asgi-lifespan
Modular components for adding lifespan protocol support to ASGI apps and libraries.
Features
- Create a lifespan-capable ASGI app with event handler registration support using
Lifespan. - Add lifespan support to an ASGI app using
LifespanMiddleware. (TODO) - Send lifespan events to an ASGI app (e.g. for testing) using
LifespanManager. (TODO) - Support for asyncio, trio and curio (provided by anyio).
- Fully type-annotated.
- 100% test coverage.
Installation
pip install asgi-lifespan
Usage
Adding lifespan support to an ASGI app
from asgi_lifespan import Lifespan, LifespanMiddleware
# 'Lifespan' is a standalone ASGI app.
# It implements the lifespan protocol,
# and allows registering lifespan event handlers.
lifespan = Lifespan()
@lifespan.on_event("startup")
async def startup():
print("Starting up...")
@lifespan.on_event("shutdown")
async def shutdown():
print("Shutting down...")
# Sync event handlers and an imperative syntax are supported too.
def more_shutdown():
print("Bye!")
lifespan.add_event_handler("shutdown", more_shutdown)
# Example ASGI app. We're using a "Hello, world" application here,
# but any ASGI-compliant callable will do.
async def app(scope, receive, send):
assert scope["type"] == "http"
output = b"Hello, World!"
headers = [
(b"content-type", "text/plain"),
(b"content-length", str(len(output)))
]
await send(
{"type": "http.response.start", "status": 200, "headers": headers}
)
await send({"type": "http.response.body", "body": output})
# 'LifespanMiddleware' returns an ASGI app.
# It forwards lifespan requests to 'lifespan',
# and anything else goes to 'app'.
app = LifespanMiddleware(app, lifespan=lifespan)
Save this script as app.py. You can serve this application with an ASGI server such as uvicorn:
uvicorn app:app
You should get the following output:
INFO: Started server process [2407]
INFO: Waiting for application startup.
Starting up...
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
Stop the server using Ctrl+C, and you should get the following output:
INFO: Shutting down
INFO: Waiting for application shutdown.
Shutting down...
Bye!
INFO: Finished server process [2407]
Sending lifespan events
To programmatically send ASGI lifespan events to an ASGI app, use LifespanManager. This is particularly useful for testing and/or making requests using an ASGI-capable HTTP client such as HTTPX.
from asgi_lifespan import Lifespan, LifespanManager
# Example lifespan-capable ASGI app.
# (Doesn't need to be a `Lifespan` instance.
# Any ASGI app implementing the lifespan protocol will do.)
app = Lifespan()
@app.on_event("startup")
async def startup():
print("Starting up...")
@app.on_event("shutdown")
async def shutdown():
print("Shutting down...")
async def main():
async with LifespanManager(app):
print("We're in!")
# Maybe make some requests to 'app'
# using an ASGI-capable test client here?
Note: if
LifespanManagerdetects that the lifespan protocol isn't supported, aLifespanNotSupportedexception is raised. To silence this exception, useLifespanManager(app, ignore_unsupported=True).
Save this script as main.py. You can run it with any of the supported async libraries:
# Add one of these at the bottom of 'main.py'.
import asyncio
asyncio.run(main())
import trio
trio.run(main)
import curio
curio.run(main)
Run $ python main.py in your terminal, and you should get the following output:
Starting up...
We're in!
Shutting down...
API Reference
Lifespan
def __init__(self, on_startup: Callable = None, on_shutdown: Callable = None)
A standalone ASGI app that implements the lifespan protocol and supports registering event handlers.
Example
lifespan = Lifespan()
Parameters
on_startup(Callable): an optional initial startup event handler.on_shutdown(Callable): an optional initial shutdown event handler.
add_event_handler
def add_event_handler(self, event_type: str, func: Callable[[], None]) -> None
Register a callback to be called when the application starts up or shuts down.
Imperative version of .on_event().
Example
async def on_startup():
...
lifespan.add_event_handler("startup", on_startup)
Parameters
event_type(str): one of"startup"or"shutdown".func(Callable): a callback. Can be sync or async.
on_event
def on_event(self, event_type: str) -> Callable[[], None]
Register a callback to be called when the application starts up or shuts down.
Decorator version of .add_event_handler().
Example
@lifespan.on_event("startup")
async def on_startup():
...
Parameters
event_type(str): one of"startup"or"shutdown".
__call__
async def __call__(self, scope: dict, receive: Callable, send: Callable) -> None
ASGI 3 implementation.
License
MIT
Changelog
All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog.
Unreleased
0.1.0 (September 28, 2019)
Added
- Add
Lifespan, an ASGI app implementing the lifespan protocol with event handler registration support. (Pull #7)
0.0.2 (September 28, 2019)
Fixed
- Installation from PyPI used to fail due to missing
MANIFEST.in.
0.0.1 (September 28, 2019)
Added
- Empty package.
Metadata
Release files for asgi-lifespan 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| asgi-lifespan-0.1.0.tar.gz | 6.0 kB | Without provenance | Details for asgi-lifespan-0.1.0.tar.gz |
Release files / asgi-lifespan-0.1.0.tar.gz
| Download URL | asgi-lifespan-0.1.0.tar.gz |
|---|---|
| Size | 6.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0ee51a5cdee5ba3e3ad18379355b9bfc5f9e425043bf7f338e10c67b118d17c1
|
|
BLAKE2b-256 checksum How to use checksums |
cf9225f8aaf365835cbfa65980e87d1506ebb0f03f1974c2fb090dd1bc4dbe43
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/2.0.0 pkginfo/1.5.0.1 requests/2.22.0 setuptools/40.8.0 requests-toolbelt/0.9.1 tqdm/4.36.1 CPython/3.7.3
|
Security for asgi-lifespan 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.