Lifespan Events ¶

from contextlib import asynccontextmanager
from fastapi import FastAPI
def fake_answer_to_everything_ml_model(x: float):
    return x * 42
ml_models = {}
@asynccontextmanager
async def lifespan(app: FastAPI):
    # Load the ML model
    ml_models["answer_to_everything"] = fake_answer_to_everything_ml_model
    yield
    # Clean up the ML models and release the resources
    ml_models.clear()
app = FastAPI(lifespan=lifespan)
@app.get("/predict")
async def predict(x: float):
    result = ml_models["answer_to_everything"](x)
    return {"result": result}
Here we are simulating the expensive startup operation of loading the model by putting the (fake) model function in the dictionary with machine learning models before the yield. This code will be executed before the application starts taking requests, during the startup.
And then, right after the yield, we unload the model. This code will be executed after the application finishes handling requests, right before the shutdown. This could, for example, release resources like memory or a GPU.
The shutdown would happen when you are stopping the application.
Maybe you need to start a new version, or you just got tired of running it. 🤷
Lifespan function¶
The first thing to notice, is that we are defining an async function with yield. This is very similar to Dependencies with yield.
from contextlib import asynccontextmanager
from fastapi import FastAPI
def fake_answer_to_everything_ml_model(x: float):
    return x * 42
ml_models = {}
@asynccontextmanager
async def lifespan(app: FastAPI):
    # Load the ML model
    ml_models["answer_to_everything"] = fake_answer_to_everything_ml_model
    yield
    # Clean up the ML models and release the resources
    ml_models.clear()
app = FastAPI(lifespan=lifespan)
@app.get("/predict")
async def predict(x: float):
    result = ml_models["answer_to_everything"](x)
    return {"result": result}
The first part of the function, before the yield, will be executed before the application starts.
And the part after the yield will be executed after the application has finished.
Async Context Manager¶
If you check, the function is decorated with an @asynccontextmanager.
That converts the function into something called an "async context manager".
from contextlib import asynccontextmanager
from fastapi import FastAPI
def fake_answer_to_everything_ml_model(x: float):
    return x * 42
ml_models = {}
@asynccontextmanager
async def lifespan(app: FastAPI):
    # Load the ML model
    ml_models["answer_to_everything"] = fake_answer_to_everything_ml_model
    yield
    # Clean up the ML models and release the resources
    ml_models.clear()
app = FastAPI(lifespan=lifespan)
@app.get("/predict")
async def predict(x: float):
    result = ml_models["answer_to_everything"](x)
    return {"result": result}
A context manager in Python is something that you can use in a with statement, for example, open() can be used as a context manager:
with open("file.txt") as file:
    file.read()
In recent versions of Python, there's also an async context manager. You would use it with async with:
async with lifespan(app):
    await do_stuff()
When you create a context manager or an async context manager like above, what it does is that, before entering the with block, it will execute the code before the yield, and after exiting the with block, it will execute the code after the yield.
In our code example above, we don't use it directly, but we pass it to FastAPI for it to use it.
The lifespan parameter of the FastAPI app takes an async context manager, so we can pass our new lifespan async context manager to it.
from contextlib import asynccontextmanager
from fastapi import FastAPI
def fake_answer_to_everything_ml_model(x: float):
    return x * 42
ml_models = {}
@asynccontextmanager
async def lifespan(app: FastAPI):
    # Load the ML model
    ml_models["answer_to_everything"] = fake_answer_to_everything_ml_model
    yield
    # Clean up the ML models and release the resources
    ml_models.clear()
app = FastAPI(lifespan=lifespan)
@app.get("/predict")
async def predict(x: float):
    result = ml_models["answer_to_everything"](x)
    return {"result": result}
Alternative Events (deprecated)¶
Warning
The recommended way to handle the startup and shutdown is using the lifespan parameter of the FastAPI app as described above.
You can probably skip this part.
There's an alternative way to define this logic to be executed during startup and during shutdown.
You can define event handlers (functions) that need to be executed before the application starts up, or when the application is shutting down.
These functions can be declared with async def or normal def.
startup event¶
To add a function that should be run before the application starts, declare it with the event "startup":
from fastapi import FastAPI
app = FastAPI()
items = {}
@app.on_event("startup")
async def startup_event():
    items["foo"] = {"name": "Fighters"}
    items["bar"] = {"name": "Tenders"}
@app.get("/items/{item_id}")
async def read_items(item_id: str):
    return items[item_id]
In this case, the startup event handler function will initialize the items "database" (just a dict) with some values.
You can add more than one event handler function.
And your application won't start receiving requests until all the startup event handlers have completed.
shutdown event¶
To add a function that should be run when the application is shutting down, declare it with the event "shutdown":
from fastapi import FastAPI
app = FastAPI()
@app.on_event("shutdown")
def shutdown_event():
    with open("log.txt", mode="a") as log:
        log.write("Application shutdown")
@app.get("/items/")
async def read_items():
    return [{"name": "Foo"}]
Here, the shutdown event handler function will write a text line "Application shutdown" to a file log.txt.
In the open() function, the mode="a" means "append", so, the line will be added after whatever is on that file, without overwriting the previous contents.
Notice that in this case we are using a standard Python open() function that interacts with a file.
So, it involves I/O (input/output), that requires "waiting" for things to be written to disk.
But open() doesn't use async and await.
So, we declare the event handler function with standard def instead of async def.
startup and shutdown together¶
There's a high chance that the logic for your startup and shutdown is connected, you might want to start something and then finish it, acquire a resource and then release it, etc.
Doing that in separated functions that don't share logic or variables together is more difficult as you would need to store values in global variables or similar tricks.
Because of that, it's now recommended to instead use the lifespan as explained above.
Technical Details¶
Just a technical detail for the curious nerds. 🤓
Underneath, in the ASGI technical specification, this is part of the Lifespan Protocol, and it defines events called startup and shutdown.
You can read more about the Starlette lifespan handlers in Starlette's  Lifespan' docs.
Including how to handle lifespan state that can be used in other areas of your code.
Sub Applications¶
🚨 Have in mind that these lifespan events (startup and shutdown) will only be executed for the main application, not for Sub Applications - Mounts.