Skip to content

Integrations

FastIoC-Enhanced FastAPI Integration

This module provides extended versions of FastAPI and APIRouter with automatic FastIoC dependency injection support. It allows:

  • Management of global dependencies via a built-in FastIoC Container.
  • Developer-friendly DX helpers for registering singleton, request-scoped, and transient dependencies.
  • Seamless integration with existing FastAPI routes and APIRouters without requiring manual injection setup.

APIRouter

Bases: APIRouter, Injectified

Extended APIRouter class with automatic FastIoC integration.

Features
  • Supports global dependencies via an internal FastIoC Container. A default container is created automatically, but it can be replaced via the container property.
  • Lazy injection of dependencies into route endpoints.
  • Developer-friendly DX sugar:
    • add_singleton, add_scoped, add_transient to register dependencies in the container.
  • Global and route-level dependencies are automatically processed.

FastAPI

Bases: FastAPI, Injectified

Extended FastAPI class with automatic FastIoC integration.

Features
  • Supports global dependencies via an internal FastIoC Container. A default container is created automatically, but it can be replaced via the container property.
  • Lazy injection of dependencies into route endpoints.
  • Developer-friendly DX sugar:
    • add_singleton, add_scoped, add_transient to register dependencies in the container.
  • Global and route-level dependencies are automatically processed.

Injectified

Base class providing shared FastIoC integration functionality.

container: Container property writable

Get the FastIoC container.

Returns:

Name Type Description
Container Container

The container instance used for dependency injection.

add_scoped(protocol: type, implementation: FastIoCConcrete)

Register a request-scoped dependency into the internal container.

A new instance is created for each HTTP request and reused throughout that request.

Parameters:

Name Type Description Default
protocol type

The interface or protocol type that acts as the key for resolving this dependency.

required
implementation FastIoCConcrete

The actual implementation to be provided when the protocol is resolved.

required

Raises:

Type Description
ProtocolNotRegisteredError

If a nested dependency is not registered.

add_singleton(protocol: type, implementation: FastIoCConcrete)

Register a singleton dependency into the internal container.

One single shared instance will be used throughout the entire process/worker.

Parameters:

Name Type Description Default
protocol type

The interface or protocol type that acts as the key for resolving this dependency.

required
implementation FastIoCConcrete

The actual implementation to be provided when the protocol is resolved.

required

Raises:

Type Description
SingletonGeneratorNotAllowedError

If 'implementation' is a generator or async generator.

ProtocolNotRegisteredError

If a nested dependency is not registered.

add_transient(protocol: type, implementation: FastIoCConcrete)

Register a transient dependency into the internal container.

A new instance is created each time the dependency is resolved.

Parameters:

Name Type Description Default
protocol type

The interface or protocol type that acts as the key for resolving this dependency.

required
implementation FastIoCConcrete

The actual implementation to be provided when the protocol is resolved.

required

Raises:

Type Description
ProtocolNotRegisteredError

If a nested dependency is not registered.

dispose() async

Dispose all registered singleton dependencies.

This method calls the disposal function of each singleton that was registered in the container. Both synchronous and asynchronous disposal functions are supported. If a disposal function raises an exception, it will be caught and logged, and the disposal process will continue for the remaining singletons.

Logging format

'Error disposing "ClassName": exception'

Notes
  • Async disposal functions will be awaited.
  • Errors during disposal do not prevent other singletons from being disposed.

override_dependencies(dependencies: dict[Callable[..., Any], Callable[..., Any]] = {}, container: Optional[Container] = None)

Override dependencies in a FastAPI app using the integrated FastIoC container.

This method merges user-provided overrides with the container’s registered dependencies and directly updates the app’s dependency_overrides. The original lifetime of each dependency is preserved.

Parameters:

Name Type Description Default
dependencies dict[Callable[..., Any], Callable[..., Any]]

Mapping from original dependency callables or protocol types to override callables.

{}
container Optional[Container]

An optional secondary container (e.g., for testing or mocking). Only protocols registered in the main container are considered.

None
Note

The lifetime of each dependency should follow the main container, unless you know exactly what you are doing.

  • For SCOPED or FACTORY dependencies in the main container, the original lifetime is always preserved regardless of what is registered in the secondary container (except SINGLETON).
  • For SINGLETON dependencies in the main container: if the main container has SINGLETON and the secondary container has a different lifetime, the resulting lifetime will be SCOPED;
  • If the main container has a non-SINGLETON lifetime and the secondary container registers it as SINGLETON, the resulting lifetime will be SINGLETON.

Examples:

from fastioc import FastAPI
app = FastAPI()
app.add_scoped(IService, Service)
overrides = {
    IService: MockService,
    some_dependency: custom_callable
}
app.override_dependencies(overrides)