Implementing Lifespan Events

What are Lifespan Events?

Every web application has a life of its own. It's born when you run the server, it lives while it serves requests, and it dies when you stop the server. Lifespan events allow you to hook into the moments of birth and death.

• Startup: Code that runs once before the application starts receiving any requests.
• Shutdown: Code that runs once after the application has finished handling all its requests and is about to stop.

The following article provides a fantastic analogy that distinguishes the application's lifespan from the lifecycle of a single request.

As the article explains, you don't want to perform expensive setup (like turning on the ovens) for every customer. You do it once when the restaurant opens. Common use cases for lifespan events include:

• Initializing a database connection pool.
• Loading a large machine learning model into memory.
• Setting up a connection to a caching service like Redis.
• Warming up a cache with initial data.

The Modern Approach: lifespan and asynccontextmanager

FastAPI provides a clean, modern way to manage lifespan events using Python's built-in asynccontextmanager. You define a single asynchronous function that handles both startup and shutdown, then pass it to the FastAPI application instance using the lifespan parameter.

The structure is simple and elegant:

1. Decorate an async function with @asynccontextmanager from the contextlib module.
2. Write your startup logic before a yield statement.
3. Write your shutdown logic after the yield statement.

FastAPI takes care of running the code before the yield during startup and the code after the yield during shutdown.

Let's see this in action. The official documentation provides a clear, practical example.

Let's Write Some Code

Let's modify our main.py from the previous lesson to include a simple lifespan event. We'll simulate loading a large configuration file or model into memory on startup and logging a message on shutdown.

# main.py

from contextlib import asynccontextmanager
from fastapi import FastAPI
import time




# A dictionary to store items that are "loaded" during startup
# In a real app, this could be a database connection pool, a ML model, etc.
app_state = {}

@asynccontextmanager
async def lifespan(app: FastAPI):



    # Code to run on startup
    print("Startup: Simulating loading a large model...")



    # Simulate a slow startup task, like loading a model from disk
    time.sleep(2) 
    app_state["model"] = "MyAwesomeMLModel_v1"
    print("Startup: Model loaded successfully!")
    
    yield
    



    # Code to run on shutdown
    print("Shutdown: Cleaning up resources...")
    app_state.clear()
    print("Shutdown: Resources cleaned up.")

app = FastAPI(lifespan=lifespan)

@app.get("/")
async def root():
    return {"message": f"Hello! The loaded model is: {app_state.get('model', 'Not loaded')}"}

Now, run your application:
uvicorn main:app --reload

You will immediately see the startup messages in your terminal and notice a 2-second delay before Uvicorn reports that the application startup is complete.

INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
Startup: Simulating loading a large model...
Startup: Model loaded successfully!
INFO:     Application startup complete.

If you access http://127.0.0.1:8000, you'll see the message with the model name.

Now, stop the server by pressing CTRL+C in your terminal. You will see the shutdown messages appear before the process exits.

...
INFO:     Shutting down
Shutdown: Cleaning up resources...
Shutdown: Resources cleaned up.
INFO:     Waiting for application shutdown.
INFO:     Application shutdown complete.

The following video provides an excellent summary of this modern approach and explains the underlying ASGI protocol, which is great for your deeper architectural understanding.

Sharing State: A Cleaner Alternative to Globals

In our example, we used a global app_state dictionary. While this works, it can become messy. The lifespan protocol offers a cleaner way to create state during startup and make it accessible to your requests. The lifespan function can yield a dictionary of objects. FastAPI then makes this state available on the request.state object.

This pattern is highly recommended as it avoids polluting the global namespace and makes dependencies more explicit. We will explore this more when we discuss dependency injection in a later module.

The Deprecated Way: on_event

Before the lifespan parameter was introduced, FastAPI used decorators: @app.on_event("startup") and @app.on_event("shutdown").

# The old, deprecated way
# from fastapi import FastAPI




# app = FastAPI()




# @app.on_event("startup")
# async def startup_event():
#     print("Application has started")




# @app.on_event("shutdown")
# def shutdown_event():
#     print("Application is shutting down")

While you may see this in older codebases, the official documentation now deprecates it in favor of the lifespan context manager. The primary reason is that lifespan keeps connected logic (like creating and closing a connection pool) within a single, self-contained function, which is cleaner and less error-prone than managing it across two separate functions that might rely on global variables.

Conclusion

You've now learned how to manage the lifecycle of your entire FastAPI application. This is the last of the core foundational concepts before we start building out more complex API functionality.

Key Takeaways:

• Lifespan Events run code once at application startup and once at shutdown.
• They are ideal for managing shared resources like database connection pools, ML models, and caches.
• The modern and recommended approach is to use an asynccontextmanager passed to the lifespan parameter of the FastAPI instance.
• In a lifespan function, code before yield runs on startup, and code after yield runs on shutdown.
• The older @app.on_event() decorators are deprecated and should be avoided in new projects.

With this, we conclude our first module! You've gone from zero to running a basic FastAPI app, understanding its async nature, using type hints for validation, and now managing its lifecycle.

In our next lesson, we will begin Module 2: Routing and Request Handling. We'll dive into how to define different API endpoints, extract parameters from the URL, and organize your routes effectively, drawing clear comparisons to Django's URL patterns and DRF's ViewSets.