Skip to main content

Programmatic startup/shutdown of ASGI apps.

Project description


Build Status Coverage Package version

Programmatically send startup/shutdown lifespan events into ASGI applications. When used in combination with an ASGI-capable HTTP client such as HTTPX, this allows mocking or testing ASGI applications without having to spin up an ASGI server.


  • Send lifespan events to an ASGI app using LifespanManager.
  • Support for asyncio and trio.
  • Fully type-annotated.
  • 100% test coverage.


pip install 'asgi-lifespan==1.*'


asgi-lifespan provides a LifespanManager to programmatically send ASGI lifespan events into an ASGI app. This can be used to programmatically startup/shutdown an ASGI app without having to spin up an ASGI server.

LifespanManager can run on either asyncio or trio, and will auto-detect the async library in use.

Basic usage

from asgi_lifespan import LifespanManager
from starlette.applications import Starlette

# Example lifespan-capable ASGI app. Any ASGI app that supports
# the lifespan protocol will do, e.g. FastAPI, Quart, Responder, ...
app = Starlette(
    on_startup=[lambda: print("Starting up!")],
    on_shutdown=[lambda: print("Shutting down!")],

async def main():
    async with LifespanManager(app):
        print("We're in!")

# On asyncio:
import asyncio;

# On trio:
# import trio;


$ python
Starting up!
We're in!
Shutting down!

Sending lifespan events for testing

The example below demonstrates how to use asgi-lifespan in conjunction with HTTPX and pytest in order to send test requests into an ASGI app.

  • Install dependencies:
pip install asgi-lifespan httpx starlette pytest pytest-asyncio
  • Test script:
import httpx
import pytest
from asgi_lifespan import LifespanManager
from starlette.applications import Starlette
from starlette.responses import PlainTextResponse
from starlette.routing import Route

async def app():
    async def startup():
        print("Starting up")

    async def shutdown():
        print("Shutting down")

    async def home(request):
        return PlainTextResponse("Hello, world!")

    app = Starlette(
        routes=[Route("/", home)],

    async with LifespanManager(app):
        print("We're in!")
        yield app

async def client(app):
    async with httpx.AsyncClient(app=app, base_url="") as client:
        print("Client is ready")
        yield client

async def test_home(client):
    response = await client.get("/")
    assert response.status_code == 200
    assert response.text == "Hello, world!"
  • Run the test suite:
$ pytest -s
======================= test session starts ======================= Starting up
We're in!
Client is ready
.Shutting down

======================= 1 passed in 0.88s =======================

API Reference


def __init__(
    app: Callable,
    startup_timeout: Optional[float] = 5,
    shutdown_timeout: Optional[float] = 5,

An asynchronous context manager that starts up an ASGI app on enter and shuts it down on exit.

More precisely:

  • On enter, start a lifespan request to app in the background, then send the lifespan.startup event and wait for the application to send lifespan.startup.complete.
  • On exit, send the lifespan.shutdown event and wait for the application to send lifespan.shutdown.complete.
  • If an exception occurs during startup, shutdown, or in the body of the async with block, it bubbles up and no shutdown is performed.


async with LifespanManager(app):
    # 'app' was started up.

# 'app' was shut down.


  • app (Callable): an ASGI application.
  • startup_timeout (Optional[float], defaults to 5): maximum number of seconds to wait for the application to startup. Use None for no timeout.
  • shutdown_timeout (Optional[float], defaults to 5): maximum number of seconds to wait for the application to shutdown. Use None for no timeout.


  • LifespanNotSupported: if the application does not seem to support the lifespan protocol. Based on the rationale that if the app supported the lifespan protocol then it would successfully receive the lifespan.startup ASGI event, unsupported lifespan protocol is detected in two situations:
    • The application called send() before calling receive() for the first time.
    • The application raised an exception during startup before making its first call to receive(). For example, this may be because the application failed on a statement such as assert scope["type"] == "http".
  • TimeoutError: if startup or shutdown timed out.
  • Exception: any exception raised by the application (during startup, shutdown, or within the async with body) that does not indicate it does not support the lifespan protocol.




All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog.

1.0.1 (June 8, 2020)


  • Update development status to 5 - Production/Stable. (Pull #32)

1.0.0 (February 2, 2020)


  • Drop Lifespan and LifespanMiddleware. Please use Starlette's built-in lifespan capabilities instead. (Pull #27)


  • Use sniffio for auto-detecting the async environment. (Pull #28)

  • Enforce 100% test coverage on CI. (Pull #29)


  • Enforce importing from the top-level package by switching to private internal modules. (Pull #26)

0.6.0 (November 29, 2019)


  • Move Lifespan to the lifespan module. (Pull #21)
  • Refactor LifespanManager to drop dependency on asynccontextmanager on 3.6. (Pull #20)

0.5.0 (November 29, 2019)

  • Enter Beta development status.


  • Remove curio support. (Pull #18)


  • Ship binary distributions (wheels) alongside source distributions.


  • Use custom concurrency backends instead of anyio for asyncio and trio support. (Pull #18)

0.4.2 (October 6, 2019)


  • Ensure py.typed is bundled with the package so that type checkers can detect type annotations. (Pull #16)

0.4.1 (September 29, 2019)


  • Improve error handling in LifespanManager (Pull #11):
    • Exceptions raised in the context manager body or during shutdown are now properly propagated.
    • Unsupported lifespan is now also detected when the app calls send() before calling having called receive() at least once.

0.4.0 (September 29, 2019)

  • Enter Alpha development status.

0.3.1 (September 29, 2019)


  • Add configurable timeouts to LifespanManager. (Pull #10)

0.3.0 (September 29, 2019)


  • Add LifespanManager for sending lifespan events into an ASGI app. (Pull #5)

0.2.0 (September 28, 2019)


  • Add LifespanMiddleware, an ASGI middleware to add lifespan support to an ASGI app. (Pull #9)

0.1.0 (September 28, 2019)


  • Add Lifespan, an ASGI app implementing the lifespan protocol with event handler registration support. (Pull #7)

0.0.2 (September 28, 2019)


  • Installation from PyPI used to fail due to missing

0.0.1 (September 28, 2019)


  • Empty package.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

asgi-lifespan-1.0.1.tar.gz (12.4 kB view hashes)

Uploaded source

Built Distribution

asgi_lifespan-1.0.1-py3-none-any.whl (10.7 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page