Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Document the lifespan event handler parameter #1110

Merged
merged 4 commits into from Jul 15, 2021
Merged

Document the lifespan event handler parameter #1110

Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
8873aaf
Document the lifespan event handler parameter
emilmelnikov Dec 9, 2020
e261095
Change lifespan to asynccontextmanager
emilmelnikov Jul 8, 2021
e0f77b2
Merge branch 'master' into patch-1
graingert Jul 9, 2021
7d04f65
Simplify asynccontextmanager example
emilmelnikov Jul 12, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
27 changes: 27 additions & 0 deletions docs/events.md
View file
Open in desktop
Expand Up @@ -37,6 +37,33 @@ registered startup handlers have completed.
The shutdown handlers will run once all connections have been closed, and
any in-process background tasks have completed.

A single lifespan asynccontextmanager handler can be used instead of
separate startup and shutdown handlers:

```python
import contextlib
import anyio
from starlette.applications import Starlette


@contextlib.asynccontextmanager
async def lifespan(app):
emilmelnikov marked this conversation as resolved.
Show resolved Hide resolved
# acquire async resources
async with anyio.create_task_group() as app.tg:
try:
yield
finally:
with anyio.CancelScope(shield=True):
# release async resources
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

sorry I lead you wrong here - the TaskGroup context manager will capture any CancelledError for you

Suggested change
async with anyio.create_task_group() as app.tg:
try:
yield
finally:
with anyio.CancelScope(shield=True):
# release async resources
async with anyio.create_task_group() as app.tg:
yield
# release async resources

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I do want to somehow document that yield can now throw CancelledError

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

sometimes you want to acquire/release resources inside the TaskGroup and sometimes you want to acquire/release them outside the TaskGroup and there's no specific answer as they both have different behaviours with their own pros/cons

image

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure we should have the main documentation for lifespan be setting app.tg. That could be a separate topic, but I think the initial introduction to "make a lifespan" example should be as simple as possible.

@contextlib.asynccontextmanager
async def lifespan(app):
    async with some_async_resource():
        yield

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

that's fair

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like the simple lifespan example; we can also add a link to anyio documentation on task groups and cancellation.



routes = [
...
]

app = Starlette(routes=routes, lifespan=lifespan)
```

## Running event handlers in tests

You might want to explicitly call into your event handlers in any test setup
Expand Down