FastAPI Dependency Injection: Advanced DI Container Architecture

FastAPI, with its intuitive design and powerful features, has become a favorite for building modern web APIs in Python. One of its core strengths lies in its seamless integration with dependency injection (DI), enabling developers to create loosely coupled, testable, and maintainable applications. While FastAPI's built-in DI system is excellent for simple use cases, more complex projects often benefit from a more structured and advanced DI container architecture. This article explores various strategies for building such an architecture, providing practical examples and insights for designing robust and scalable applications.

Understanding Dependency Injection (DI) and Inversion of Control (IoC)

Before diving into advanced DI container architectures, let's clarify the fundamental concepts:

• Dependency Injection (DI): A design pattern where dependencies are provided to a component from external sources rather than created internally. This promotes loose coupling, making components easier to test and reuse.
• Inversion of Control (IoC): A broader principle where the control of object creation and management is inverted – delegated to a framework or container. DI is a specific type of IoC.

FastAPI inherently supports DI through its dependency system. You define dependencies as callable objects (functions, classes, etc.), and FastAPI automatically resolves and injects them into your endpoint functions or other dependencies.

Example (Basic FastAPI DI):

            
from fastapi import FastAPI, Depends

app = FastAPI()

# Dependency
def get_db():
    db = {"items": []}  # Simulate a database connection
    try:
        yield db
    finally:
        # Close the database connection (if needed)
        pass


# Endpoint with dependency injection
@app.get("/items/")
async def read_items(db: dict = Depends(get_db)):
    return db["items"]

            

              
                Copy
              
            
          

In this example, get_db is a dependency that provides a database connection. FastAPI automatically calls get_db and injects the result (the db dictionary) into the read_items endpoint function.

Why an Advanced DI Container?

FastAPI's built-in DI works well for simple projects, but as applications grow in complexity, a more sophisticated DI container offers several advantages:

• Centralized Dependency Management: A dedicated container provides a single source of truth for all dependencies, making it easier to manage and understand the application's dependencies.
• Configuration and Lifecycle Management: The container can handle the configuration and lifecycle of dependencies, such as creating singletons, managing connections, and disposing of resources.
• Testability: An advanced container simplifies testing by allowing you to easily override dependencies with mock objects or test doubles.
• Decoupling: Promotes greater decoupling between components, reducing dependencies and improving code maintainability.
• Extensibility: An extensible container allows you to add custom features and integrations as needed.

Strategies for Building an Advanced DI Container

There are several approaches to building an advanced DI container in FastAPI. Here are some common strategies:

1. Using a Dedicated DI Library (e.g., `injector`, `dependency_injector`)

Several powerful DI libraries are available for Python, such as injector and dependency_injector. These libraries provide a comprehensive set of features for managing dependencies, including:

• Binding: Defining how dependencies are resolved and injected.
• Scopes: Controlling the lifecycle of dependencies (e.g., singleton, transient).
• Configuration: Managing configuration settings for dependencies.
• AOP (Aspect-Oriented Programming): Intercepting method calls for cross-cutting concerns.

Example with `dependency_injector`

dependency_injector is a popular choice for building DI containers. Let's illustrate its usage with an example:

            
from dependency_injector import containers, providers
from fastapi import FastAPI, Depends

# Define dependencies
class Database:
    def __init__(self, connection_string: str):
        self.connection_string = connection_string
        # Initialize database connection
        print(f"Connecting to database: {self.connection_string}")

    def get_items(self):
        # Simulate fetching items from the database
        return [{"id": 1, "name": "Item 1"}, {"id": 2, "name": "Item 2"}]


class UserRepository:
    def __init__(self, database: Database):
        self.database = database

    def get_all_users(self):
        # Simulating database request to get all users
        return [{"id": "user1", "name": "Alice"},{"id": "user2", "name": "Bob"}]

class Settings:
    def __init__(self, database_url):
        self.database_url = database_url

# Define container
class Container(containers.DeclarativeContainer):
    config = providers.Configuration()
    settings = providers.Singleton(Settings, database_url = config.database_url)
    database = providers.Singleton(Database, connection_string=config.database_url)
    user_repository = providers.Factory(UserRepository, database=database)

# Create FastAPI app
app = FastAPI()

# Configure container (from an environment variable)
container = Container()
container.config.database_url.from_env("DATABASE_URL", default="sqlite:///:memory:")
container.wire([__name__]) # enables injection of dependencies into FastAPI endpoints

# Dependency for FastAPI
def get_user_repository(user_repository: UserRepository = Depends(container.user_repository.provided)) -> UserRepository:
    return user_repository


# Endpoint using injected dependency
@app.get("/users/")
async def read_users(user_repository: UserRepository = Depends(get_user_repository)):
    return user_repository.get_all_users()

@app.on_event("startup")
async def startup_event():
    # Container initialization
    container.init_resources()

            

              
                Copy
              
            
          

Explanation:

• We define our dependencies (Database, UserRepository, Settings) as regular Python classes.
• We create a Container class that inherits from containers.DeclarativeContainer. This class defines the dependencies and their providers (e.g., providers.Singleton for singletons, providers.Factory for creating new instances each time).
• The container.wire([__name__]) line enables dependency injection into FastAPI endpoints.
• The get_user_repository function is a FastAPI dependency that uses container.user_repository.provided to retrieve the UserRepository instance from the container.
• The endpoint function read_users injects the UserRepository dependency.
• The `config` allows you to externalize the dependency configurations. It can then come from environment variables, configuration files etc.
• The `startup_event` is used to initialize the resources managed in the container

2. Implementing a Custom DI Container

For more control over the DI process, you can implement a custom DI container. This approach requires more effort but allows you to tailor the container to your specific needs.

Basic Custom DI Container Example:

            
from typing import Callable, Dict, Type, Any
from fastapi import FastAPI, Depends

class Container:
    def __init__(self):
        self.dependencies: Dict[Type[Any], Callable[..., Any]] = {}
        self.instances: Dict[Type[Any], Any] = {}

    def register(self, dependency_type: Type[Any], provider: Callable[..., Any]):
        self.dependencies[dependency_type] = provider

    def resolve(self, dependency_type: Type[Any]) -> Any:
        if dependency_type in self.instances:
            return self.instances[dependency_type]

        if dependency_type not in self.dependencies:
            raise Exception(f"Dependency {dependency_type} not registered.")

        provider = self.dependencies[dependency_type]
        instance = provider()
        return instance

    def singleton(self, dependency_type: Type[Any], provider: Callable[..., Any]):
        self.register(dependency_type, provider)
        self.instances[dependency_type] = provider()


# Example Dependencies
class PaymentGateway:
    def process_payment(self, amount: float) -> bool:
        print(f"Processing payment of ${amount}")
        return True # Simulate successful payment


class NotificationService:
    def send_notification(self, message: str):
        print(f"Sending notification: {message}")


# Example Usage
container = Container()
container.singleton(PaymentGateway, PaymentGateway)
container.singleton(NotificationService, NotificationService)

app = FastAPI()

# FastAPI Dependency
def get_payment_gateway(payment_gateway: PaymentGateway = Depends(lambda: container.resolve(PaymentGateway))):
    return payment_gateway


def get_notification_service(notification_service: NotificationService = Depends(lambda: container.resolve(NotificationService))):
    return notification_service


@app.post("/purchase/")
async def purchase_item(payment_gateway: PaymentGateway = Depends(get_payment_gateway), notification_service: NotificationService = Depends(get_notification_service)):
    if payment_gateway.process_payment(100.0):
        notification_service.send_notification("Purchase successful!")
        return {"message": "Purchase successful"}
    else:
        return {"message": "Purchase failed"}

            

              
                Copy
              
            
          

Explanation:

• The Container class manages a dictionary of dependencies and their providers.
• The register method registers a dependency with its provider.
• The resolve method resolves a dependency by calling its provider.
• The singleton method registers a dependency and creates a single instance of it.
• FastAPI dependencies are created using a lambda function to resolve dependencies from the container.

3. Using FastAPI's `Depends` with a Factory Function

Instead of a full-fledged DI container, you can use FastAPI's Depends along with factory functions to achieve some level of dependency management. This approach is simpler than implementing a custom container but still provides some benefits over directly instantiating dependencies within endpoint functions.

            
from fastapi import FastAPI, Depends
from typing import Callable

# Define Dependencies
class EmailService:
    def __init__(self, smtp_server: str):
        self.smtp_server = smtp_server

    def send_email(self, recipient: str, subject: str, body: str):
        print(f"Sending email to {recipient} via {self.smtp_server}: {subject} - {body}")


# Factory function for EmailService
def create_email_service(smtp_server: str) -> EmailService:
    return EmailService(smtp_server=smtp_server)


# FastAPI
app = FastAPI()

# FastAPI Dependency, leveraging factory function and Depends
def get_email_service(email_service: EmailService = Depends(lambda: create_email_service(smtp_server="smtp.example.com"))):
    return email_service


@app.post("/send-email/")
async def send_email(recipient: str, subject: str, body: str, email_service: EmailService = Depends(get_email_service)):
    email_service.send_email(recipient=recipient, subject=subject, body=body)
    return {"message": "Email sent!"}

            

              
                Copy
              
            
          

Explanation:

• We define a factory function (create_email_service) that creates instances of the EmailService dependency.
• The get_email_service dependency uses Depends and a lambda to call the factory function and provide an instance of EmailService.
• The endpoint function send_email injects the EmailService dependency.

Advanced Considerations

1. Scopes and Lifecycles

DI containers often provide features for managing the lifecycle of dependencies. Common scopes include:

• Singleton: A single instance of the dependency is created and reused throughout the application's lifetime. This is suitable for dependencies that are stateless or have global scope.
• Transient: A new instance of the dependency is created each time it is requested. This is suitable for dependencies that are stateful or need to be isolated from each other.
• Request: A single instance of the dependency is created for each incoming request. This is suitable for dependencies that need to maintain state within the context of a single request.

The dependency_injector library provides built-in support for scopes. For custom containers, you'll need to implement the scope management logic yourself.

2. Configuration

Dependencies often require configuration settings, such as database connection strings, API keys, and feature flags. DI containers can help manage these settings by providing a centralized way to access and inject configuration values.

In the dependency_injector example, the config provider allows configuration from environment variables. For custom containers, you can load configuration from files or environment variables and store them in the container.

3. Testing

One of the primary benefits of DI is improved testability. With a DI container, you can easily replace real dependencies with mock objects or test doubles during testing.

Example (Testing with `dependency_injector`):

            
import pytest
from unittest.mock import MagicMock
from dependency_injector import containers, providers
from fastapi import FastAPI, Depends
from fastapi.testclient import TestClient

# Define dependencies (same as before)
class Database:
    def __init__(self, connection_string: str):
        self.connection_string = connection_string

    def get_items(self):
        return [{"id": 1, "name": "Item 1"}, {"id": 2, "name": "Item 2"}]


class UserRepository:
    def __init__(self, database: Database):
        self.database = database

    def get_all_users(self):
        return [{"id": "user1", "name": "Alice"},{"id": "user2", "name": "Bob"}]

class Settings:
    def __init__(self, database_url):
        self.database_url = database_url

# Define container (same as before)
class Container(containers.DeclarativeContainer):
    config = providers.Configuration()
    settings = providers.Singleton(Settings, database_url = config.database_url)
    database = providers.Singleton(Database, connection_string=config.database_url)
    user_repository = providers.Factory(UserRepository, database=database)

# Create FastAPI app (same as before)
app = FastAPI()

# Configure container (from an environment variable)
container = Container()
container.config.database_url.from_env("DATABASE_URL", default="sqlite:///:memory:")
container.wire([__name__]) # enables injection of dependencies into FastAPI endpoints

# Dependency for FastAPI
def get_user_repository(user_repository: UserRepository = Depends(container.user_repository.provided)) -> UserRepository:
    return user_repository


# Endpoint using injected dependency (same as before)
@app.get("/users/")
async def read_users(user_repository: UserRepository = Depends(get_user_repository)):
    return user_repository.get_all_users()

@app.on_event("startup")
async def startup_event():
    # Container initialization
    container.init_resources()

# Test
@pytest.fixture
def test_client():
    # Override the database dependency with a mock
    database_mock = MagicMock(spec=Database)
    database_mock.get_items.return_value = [{"id": 3, "name": "Test Item"}]

    user_repository_mock = MagicMock(spec = UserRepository)
    user_repository_mock.get_all_users.return_value = [{"id": "test_user", "name": "Test User"}]

    # Override container with mock dependencies
    container.user_repository.override(providers.Factory(lambda: user_repository_mock))

    with TestClient(app) as client:
        yield client
    container.user_repository.reset()


def test_read_users(test_client: TestClient):
    response = test_client.get("/users/")
    assert response.status_code == 200
    assert response.json() ==  [{"id": "test_user", "name": "Test User"}]

            

              
                Copy
              
            
          

Explanation:

• We create a mock object for the Database dependency using MagicMock.
• We override the database provider in the container with the mock object using container.database.override().
• The test function test_read_items now uses the mock database dependency.
• After test execution, it resets the container's overridden dependency.

4. Asynchronous Dependencies

FastAPI is built on top of asynchronous programming (async/await). When working with asynchronous dependencies (e.g., asynchronous database connections), ensure that your DI container and dependency providers support asynchronous operations.

Example (Asynchronous Dependency with `dependency_injector`):

            
import asyncio
from dependency_injector import containers, providers
from fastapi import FastAPI, Depends

# Define asynchronous dependency
class AsyncDatabase:
    def __init__(self, connection_string: str):
        self.connection_string = connection_string

    async def connect(self):
        print(f"Connecting to database: {self.connection_string}")
        await asyncio.sleep(0.1) # Simulate connection time

    async def fetch_data(self):
        await asyncio.sleep(0.1) # Simulate database query
        return [{"id": 1, "name": "Async Item 1"}]

# Define container
class Container(containers.DeclarativeContainer):
    config = providers.Configuration()
    database = providers.Singleton(AsyncDatabase, connection_string=config.database_url)

# Create FastAPI app
app = FastAPI()

# Configure container
container = Container()
container.config.database_url.from_env("DATABASE_URL", default="sqlite:///:memory:")
container.wire([__name__])

# Dependency for FastAPI
async def get_async_database(database: AsyncDatabase = Depends(container.database.provided)) -> AsyncDatabase:
    await database.connect()
    return database


# Endpoint using injected dependency
@app.get("/async-items/")
async def read_async_items(database: AsyncDatabase = Depends(get_async_database)):
    data = await database.fetch_data()
    return data


@app.on_event("startup")
async def startup_event():
    # Container initialization
    container.init_resources()

            

              
                Copy
              
            
          

Explanation:

• The AsyncDatabase class defines asynchronous methods using async and await.
• The get_async_database dependency is also defined as an asynchronous function.
• The endpoint function read_async_items is marked as async and awaits the result of database.fetch_data().

Choosing the Right Approach

The best approach for building an advanced DI container depends on the complexity of your application and your specific requirements:

• For small to medium-sized projects: FastAPI's built-in DI or a factory function approach with Depends may be sufficient.
• For larger, more complex projects: A dedicated DI library like dependency_injector provides a comprehensive set of features for managing dependencies.
• For projects that require fine-grained control over the DI process: Implementing a custom DI container may be the best option.

Conclusion

Dependency injection is a powerful technique for building scalable, maintainable, and testable applications. While FastAPI's built-in DI system is excellent for simple use cases, an advanced DI container architecture can provide significant benefits for more complex projects. By choosing the right approach and leveraging the features of DI libraries or implementing a custom container, you can create a robust and flexible dependency management system that improves the overall quality and maintainability of your FastAPI applications.

Global Considerations

When designing DI containers for global applications, it's important to consider the following:

• Localization: Dependencies related to localization (e.g., language settings, date formats) should be managed by the DI container to ensure consistency across different regions.
• Time Zones: Dependencies that handle time zone conversions should be injected to avoid hardcoding time zone information.
• Currency: Dependencies for currency conversion and formatting should be managed by the container to support different currencies.
• Regional Settings: Other regional settings, such as number formats and address formats, should also be managed by the DI container.
• Multi-tenancy: For multi-tenant applications, the DI container should be able to provide different dependencies for different tenants. This can be achieved by using scopes or custom dependency resolution logic.
• Compliance and Security: Ensure your dependency management strategy complies with relevant data privacy regulations (e.g., GDPR, CCPA) and security best practices in various regions. Handle sensitive credentials and configurations securely within the container.

By considering these global factors, you can create DI containers that are well-suited for building applications that operate in a global environment.