✨ Add support for lifespan async context managers (superseding startup and shutdown events)

docs/en/docs/advanced/events.md

@@ -45,3 +45,14 @@ Here, the `shutdown` event handler function will write a text line `"Application
 
 !!! info
     You can read more about these event handlers in <a href="https://www.starlette.io/events/" class="external-link" target="_blank">Starlette's  Events' docs</a>.
+
+# Lifespan
+
+You can also define a lifespan context as an asynchronous context manager, instead of using separate startup and shutdown functions.
+
+This `async` function must be declared with the `@asynccontextmanager` decorator.  This was added to `contextlib` in Python 3.7.  For earlier versions of Python,
+you can install the `contextlib2` library to get `@asynccontextmanager`.
+
+```Python hl_lines="4"
+{!../../../docs_src/events/tutorial003.py!}
+```

docs_src/events/tutorial003.py

@@ -0,0 +1,18 @@
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+
+
+@asynccontextmanager
+async def lifespan(app):
+    print("startup")
+    yield
+    print("shutdown")
+
+
+app = FastAPI(lifespan=lifespan)
+
+
+@app.get("/")
+async def hello():
+    return {"result": "hello world"}

fastapi/applications.py

@@ -1,4 +1,15 @@
-from typing import Any, Callable, Coroutine, Dict, List, Optional, Sequence, Type, Union
+from typing import (
+    Any,
+    AsyncContextManager,
+    Callable,
+    Coroutine,
+    Dict,
+    List,
+    Optional,
+    Sequence,
+    Type,
+    Union,
+)
 
 from fastapi import routing
 from fastapi.concurrency import AsyncExitStack
@@ -55,6 +66,7 @@ def __init__(
         ] = None,
         on_startup: Optional[Sequence[Callable[[], Any]]] = None,
         on_shutdown: Optional[Sequence[Callable[[], Any]]] = None,
+        lifespan: Optional[Callable[[Starlette], AsyncContextManager[Any]]] = None,
         terms_of_service: Optional[str] = None,
         contact: Optional[Dict[str, Union[str, Any]]] = None,
         license_info: Optional[Dict[str, Union[str, Any]]] = None,
@@ -74,6 +86,7 @@ def __init__(
             dependency_overrides_provider=self,
             on_startup=on_startup,
             on_shutdown=on_shutdown,
+            lifespan=lifespan,
             default_response_class=default_response_class,
             dependencies=dependencies,
             callbacks=callbacks,

fastapi/routing.py

@@ -6,6 +6,7 @@
 import json
 from typing import (
     Any,
+    AsyncContextManager,
     Callable,
     Coroutine,
     Dict,
@@ -40,6 +41,7 @@
 from pydantic.error_wrappers import ErrorWrapper, ValidationError
 from pydantic.fields import ModelField, Undefined
 from starlette import routing
+from starlette.applications import Starlette
 from starlette.concurrency import run_in_threadpool
 from starlette.exceptions import HTTPException
 from starlette.requests import Request
@@ -450,6 +452,7 @@ def __init__(
         route_class: Type[APIRoute] = APIRoute,
         on_startup: Optional[Sequence[Callable[[], Any]]] = None,
         on_shutdown: Optional[Sequence[Callable[[], Any]]] = None,
+        lifespan: Optional[Callable[[Starlette], AsyncContextManager[Any]]] = None,
         deprecated: Optional[bool] = None,
         include_in_schema: bool = True,
     ) -> None:
@@ -459,6 +462,7 @@ def __init__(
             default=default,  # type: ignore # in Starlette
             on_startup=on_startup,  # type: ignore # in Starlette
             on_shutdown=on_shutdown,  # type: ignore # in Starlette
+            lifespan=lifespan,  # type: ignore # in Starlette
         )
         if prefix:
             assert prefix.startswith("/"), "A path prefix must start with '/'"

tests/test_router_events.py

@@ -1,3 +1,4 @@
+import pytest
 from fastapi import APIRouter, FastAPI
 from fastapi.testclient import TestClient
 from pydantic import BaseModel
@@ -12,57 +13,49 @@ class State(BaseModel):
     sub_router_shutdown: bool = False
 
 
-state = State()
+@pytest.fixture
+def state():
+    return State()
 
-app = FastAPI()
 
+def test_router_events(state):
+    app = FastAPI()
 
-@app.on_event("startup")
-def app_startup():
-    state.app_startup = True
+    @app.get("/")
+    def main():
+        return {"message": "Hello World"}
 
+    @app.on_event("startup")
+    def app_startup():
+        state.app_startup = True
 
-@app.on_event("shutdown")
-def app_shutdown():
-    state.app_shutdown = True
+    @app.on_event("shutdown")
+    def app_shutdown():
+        state.app_shutdown = True
 
+    router = APIRouter()
 
-router = APIRouter()
+    @router.on_event("startup")
+    def router_startup():
+        state.router_startup = True
 
+    @router.on_event("shutdown")
+    def router_shutdown():
+        state.router_shutdown = True
 
-@router.on_event("startup")
-def router_startup():
-    state.router_startup = True
+    sub_router = APIRouter()
 
+    @sub_router.on_event("startup")
+    def sub_router_startup():
+        state.sub_router_startup = True
 
-@router.on_event("shutdown")
-def router_shutdown():
-    state.router_shutdown = True
+    @sub_router.on_event("shutdown")
+    def sub_router_shutdown():
+        state.sub_router_shutdown = True
 
+    router.include_router(sub_router)
+    app.include_router(router)
 
-sub_router = APIRouter()
-
-
-@sub_router.on_event("startup")
-def sub_router_startup():
-    state.sub_router_startup = True
-
-
-@sub_router.on_event("shutdown")
-def sub_router_shutdown():
-    state.sub_router_shutdown = True
-
-
-@sub_router.get("/")
-def main():
-    return {"message": "Hello World"}
-
-
-router.include_router(sub_router)
-app.include_router(router)
-
-
-def test_router_events():
     assert state.app_startup is False
     assert state.router_startup is False
     assert state.sub_router_startup is False
@@ -85,3 +78,32 @@ def test_router_events():
     assert state.app_shutdown is True
     assert state.router_shutdown is True
     assert state.sub_router_shutdown is True
+
+
+def test_app_lifespan_state(state):
+    class Lifespan:
+        def __init__(self, app):
+            pass
+
+        async def __aenter__(self):
+            state.app_startup = True
+
+        async def __aexit__(self, exc_type, exc_value, exc_tb):
+            state.app_shutdown = True
+
+    app = FastAPI(lifespan=Lifespan)
+
+    @app.get("/")
+    def main():
+        return {"message": "Hello World"}
+
+    assert state.app_startup is False
+    assert state.app_shutdown is False
+    with TestClient(app) as client:
+        assert state.app_startup is True
+        assert state.app_shutdown is False
+        response = client.get("/")
+        assert response.status_code == 200, response.text
+        assert response.json() == {"message": "Hello World"}
+    assert state.app_startup is True
+    assert state.app_shutdown is True