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)