Skip to content

Core Reference

Agrupation

dependency.core.agrupation.entrypoint

Entrypoint(container, plugins, strategy=ResolutionStrategy())

Entrypoint for the application.

Attributes:

Name Type Description
init_time float

Time when the entrypoint was initialized.

Set up the application entrypoint.

Stores the plugin list and initializes the InjectionResolver with the given container. Resolves the structural dependency tree so that the injection hierarchy is ready before instance imports loaded. Full resolution is deferred to initialize().

Parameters:

Name Type Description Default
container Container

The application container holding configuration.

required
plugins Iterable[type[Plugin]]

List of root Plugin classes to load.

required
strategy ResolutionStrategy

Resolution strategy to use. Defaults to a standard ResolutionStrategy with default config.

ResolutionStrategy()

initialize(injectables=())

Initialize the application.

main_loop()

Main loop for the application. Waits indefinitely.

This method is intended to be called after the application has been initialized.

dependency.core.agrupation.plugin

PluginMeta

Bases: BaseModel

Metadata for the plugin.

Attributes:

Name Type Description
name str

Name of the plugin

version str

Version of the plugin

Plugin

Bases: Module

Plugin class for creating reusable components.

Attributes:

Name Type Description
meta PluginMeta

Metadata for the plugin

config BaseModel

Configuration model for the plugin

on_declaration() classmethod

Mark this plugin as a root container in the injection tree.

Called by ContainerMixin.init_injection when the @module decorator is applied. Sets is_root=True on the ContainerInjection so the Registry and FallbackPlugin do not treat it as an orphan.

on_resolution(container) classmethod

Resolve plugin configuration against the application container.

Called by ContainerMixin.inject_container when the plugin is attached to the application container during module resolution. Delegates to resolve_container to validate and populate the config attribute.

Parameters:

Name Type Description Default
container Container

The application container.

required

resolve_container(container) classmethod

Resolve the plugin configuration.

Parameters:

Name Type Description Default
container Container

The application container.

required

Raises:

Type Description
ResolutionError

If the configuration is invalid.

dependency.core.agrupation.module

Module

Bases: ContainerMixin

Base class for all structural grouping units in the framework.

A Module organizes related Components and Products under a common namespace within the injection tree. It carries no logic of its own — its only role is structural: to define scope and hierarchy for the providers registered under it.

Modules must be decorated with @module to be registered in the injection tree.

module(module=None)

Register a Module class into the injection tree.

Initializes a ContainerInjection node for the decorated class and attaches it to the parent module's injection node if one is provided. The decorated class must be a subclass of Module.

Parameters:

Name Type Description Default
module type[Module]

Parent module or plugin this module belongs to. If None, the module is registered without a parent — it will be treated as an orphan unless it is itself a Plugin root. Defaults to None.

None

Raises:

Type Description
TypeError

If the decorated class is not a subclass of Module.

Returns:

Type Description
Callable[[type[MODULE]], type[MODULE]]

Callable[[type[MODULE]], type[MODULE]]: Decorator that registers the module class and returns it unchanged.

Declaration

dependency.core.declaration.component

Component

Bases: ProviderMixin

Base class for all interface declarations in the injection framework.

A Component defines the interface (contract) that consumers depend on. It does not provide any implementation on its own — an Instance must be declared to implement it before it can be resolved and provided.

Components must be decorated with @component to be registered in the injection tree. The @component decorator initializes the ProviderInjection and Injectable, making the class available as a dependency for other providers.

component(module=None, imports=(), partial_resolution=False, strict_resolution=True, provider=None, bootstrap=False)

Register a Component class as an interface declaration in the injection tree.

Initializes a ProviderInjection node for the decorated class and registers it under the given module. Optionally assigns an inline provider, making the component self-providing without requiring a separate @instance declaration.

The decorated class must be a subclass of Component.

Parameters:

Name Type Description Default
module type[Module]

Module or Plugin this component belongs to. If None, the component is registered as an orphan and will be adopted by the FallbackPlugin at initialization time. Defaults to None.

None
imports Iterable[type[ProviderMixin]]

Components this component depends on. Must be declared for all dependencies used in the implementation to ensure correct resolution order. Defaults to ().

()
provider InstanceOrClass[Provider]

Provider instance or class to assign directly to this component, making it self-providing without a separate @instance. Accepts Singleton, Factory, or Resource. Defaults to None.

None
partial_resolution bool

If True, imports that are outside the current provider set are not required to be resolved. Use for components that depend on optional or externally-provided dependencies. Defaults to False.

False
strict_resolution bool

If False, resolution proceeds even when no implementation has been assigned to this component. Use for optional interface declarations that may or may not have a concrete implementation. Defaults to True.

True
bootstrap bool

If True, the provider is eagerly instantiated during the initialization phase by calling .provide() after wiring. Defaults to False.

False

Raises:

Type Description
TypeError

If the decorated class is not a subclass of Component.

Returns:

Type Description
Callable[[type[COMPONENT]], type[COMPONENT]]

Callable[[type[COMPONENT]], type[COMPONENT]]: Decorator that registers the component class and returns it unchanged.

dependency.core.declaration.instance

instance(imports=(), provider=providers.Singleton, partial_resolution=False, strict_resolution=True, bootstrap=False)

Register a class as the concrete implementation of a Component.

Takes ownership of the parent Component's Injectable by calling init_implementation, which assigns this class as the implementation and creates the provider. If another @instance was already applied to the same Component, a warning is logged and this one replaces it.

The decorated class must be a subclass of the Component it implements.

Parameters:

Name Type Description Default
imports Iterable[type[ProviderMixin]]

Components this instance depends on. Must be declared for all dependencies used in init or injected methods to ensure correct resolution order. Defaults to ().

()
provider type[Provider]

Provider class to use. Accepts Singleton, Factory, or Resource. Defaults to providers.Singleton.

Singleton
partial_resolution bool

If True, imports that are outside the current provider set are not required to be resolved. Use for instances that depend on optional or externally-provided dependencies. Defaults to False.

False
strict_resolution bool

If False, resolution proceeds even when this instance has no implementation assigned. Rarely needed on @instance since the decorated class itself is the implementation. Defaults to True.

True
bootstrap bool

If True, the provider is eagerly instantiated during the initialization phase by calling .provide() after wiring, triggering init immediately at startup. Defaults to False.

False

Raises:

Type Description
TypeError

If the decorated class is not a subclass of its parent Component.

Returns:

Type Description
Callable[[type[COMPONENT]], type[COMPONENT]]

Callable[[type[COMPONENT]], type[COMPONENT]]: Decorator that registers the instance class and returns it unchanged.

dependency.core.declaration.product

Product

Bases: Component

Base class for on-demand dependency units.

A Product is semantically distinct from a Component in that it represents an object meant to be instantiated on demand (typically via providers.Factory), rather than a long-lived service. Products are usually created by factories or services as part of their operation, not consumed directly as injected services.

Functionally, Product is equivalent to Component with provider=providers.Factory as the default. This class exists for semantic clarity and legacy compatibility.

Products must be decorated with @product to be registered in the injection tree.

product(module=None, imports=(), provider=providers.Factory, partial_resolution=False, bootstrap=False)

Register a Product class into the injection tree.

Convenience wrapper around @component that sets providers.Factory as the default provider, reflecting the semantic intent of Products as on-demand objects rather than long-lived services.

Behaves identically to @component in all other respects. The decorated class must be a subclass of Component (typically also of Product for semantic clarity).

Parameters:

Name Type Description Default
module type[Module]

Module or Plugin this product belongs to. If None, the product is registered as an orphan. Defaults to None.

None
imports Iterable[type[ProviderMixin]]

Components this product depends on. Defaults to ().

()
provider type[Provider]

Provider class to use. Defaults to providers.Factory.

Factory
partial_resolution bool

If True, imports outside the current provider set are not required to be resolved. Defaults to False.

False
bootstrap bool

If True, the provider is eagerly instantiated during the initialization phase. Defaults to False.

False

Raises:

Type Description
TypeError

If the decorated class is not a subclass of Component.

Returns:

Type Description
Callable[[type[COMPONENT]], type[COMPONENT]]

Callable[[type[COMPONENT]], type[COMPONENT]]: Decorator that registers the product class and returns it unchanged.

Injection

dependency.core.injection.mixin

ContainerMixin

Mixin class for structural units in the injection tree (Module, Plugin).

Provides class-level methods to initialize, attach, and resolve a ContainerInjection node. All structural classes (Module, Plugin) inherit from this mixin to participate in the injection hierarchy.

Attributes:

Name Type Description
injection ContainerInjection

The injection node for this container.

on_declaration() classmethod

Hook method called upon declaration of the container.

on_resolution(container) classmethod

Hook method called upon resolution of the container.

Parameters:

Name Type Description Default
container Container

The application container.

required

init_injection(parent) classmethod

Initialize the injection for the container.

Parameters:

Name Type Description Default
parent Optional[ContainerInjection]

Parent container injection instance.

required

change_parent(parent=None) classmethod

Change the parent injection of this mixin.

Parameters:

Name Type Description Default
parent ContainerMixin

The new parent container.

None

inject_container(container) classmethod

Inject the module into the application container.

Parameters:

Name Type Description Default
container Container

The application container.

required

resolve_providers(container=None) classmethod

Resolve all child providers into this container's DynamicContainer.

Delegates to ContainerInjection.resolve_providers, which recursively attaches each child ProviderInjection to the appropriate sub-container.

Parameters:

Name Type Description Default
container Container

If provided, also attaches this container as an attribute of the given parent container.

None

resolve_injectables() classmethod

Yield all Injectable objects registered under this container.

Walks the ContainerInjection tree and yields every Injectable found in child ProviderInjection nodes. Used during Phase 2 of resolution to collect the full set of providers to resolve.

Returns:

Type Description
None

Generator[Injectable, None, None]: A generator of injectables.

ProviderMixin

Bases: WiringMixin

Mixin class for providable units in the injection tree (Component, Product).

Provides class-level methods to initialize a ProviderInjection node, assign an implementation, manage dependencies, and expose the underlying provider. All providable classes (Component, Product) inherit from this mixin.

Attributes:

Name Type Description
injection ProviderInjection

The injection node for this provider.

injectable Injectable

The injectable tracking implementation and imports.

on_declaration() classmethod

Hook method called upon declaration of the provider.

init_injection(parent) classmethod

Initialize the injection for the provider.

Parameters:

Name Type Description Default
parent Optional[ContainerInjection]

Parent container injection instance.

required

init_implementation(modules_cls, provider, bootstrap) classmethod

Initialize the injectable for the provider.

Parameters:

Name Type Description Default
modules_cls Iterable[type]

List of modules that need to be wired for the provider.

required
provider Provider[Any]

Provider instance to be used for the injectable.

required
bootstrap Optional[Callable[[], Any]]

Whether the provider should be bootstrapped.

required

Raises:

Type Description
TypeError

If the class is not a subclass of the interface class.

change_parent(parent=None) classmethod

Change the parent injection of this mixin.

update_dependencies(imports=(), partial_resolution=None, strict_resolution=None) classmethod

Register dependency imports and update resolution flags for this provider.

Translates the list of ProviderMixin classes into their underlying Injectable objects and delegates to Injectable.update_dependencies.

Parameters:

Name Type Description Default
imports Iterable[type[ProviderMixin]]

Provider classes this provider depends on.

()
partial_resolution bool

If True, imports outside the current provider set are not required to be resolved.

None
strict_resolution bool

If False, resolution proceeds even when no implementation has been assigned.

None

discard_dependencies(imports=()) classmethod

Remove dependencies from the provider.

Parameters:

Name Type Description Default
imports Iterable[type[ProviderMixin]]

List of components to remove from imports.

()

reference() classmethod

Return the reference name of the Injectable.

provider() classmethod

Return the provider instance of the Injectable.

provide(*args, **kwargs) classmethod

Provide an instance of the Injectable.

dependency.core.injection.injectable

Injectable(interface_cls, implementation=None)

Injectable Class represents a implementation of some kind that can be injected as a dependency.

Attributes:

Name Type Description
interface_cls T

The interface class that this injectable implements.

weight()

Calculate the weight of this injectable for graph visualization.

The weight is defined as the number of imports plus twice the number of dependents. This heuristic emphasizes providers that are more central in the dependency graph, as they have more dependents relying on them.

Returns:

Name Type Description
int int

The calculated weight of this injectable.

has_implementation()

Check if the implementation of this injectable is valid.

Returns:

Name Type Description
bool bool

True if the implementation is valid, False otherwise.

resolve_if_posible(providers)

Attempt to mark this injectable as resolved.

Checks whether all imports are satisfied according to the resolution mode. In normal mode, all imports must already be resolved. In partial_resolution mode, an import is considered satisfied if it is resolved, also uses partial resolution, or is not part of the current provider set.

If all imports are satisfied and an implementation is assigned, sets is_resolved=True as a side effect and returns True.

Parameters:

Name Type Description Default
providers set[Injectable]

The full set of injectables being resolved in the current resolution pass.

required

Returns:

Name Type Description
bool bool

True if this injectable is now resolved, False otherwise.

update_dependencies(imports, partial_resolution=None, strict_resolution=None)

Add imports and update resolution flags.

Registers the given injectables as dependencies of this injectable and records the reverse relationship (self as a dependent of each import). Resolution flags are updated only if explicitly provided (not None).

Parameters:

Name Type Description Default
imports Iterable[Injectable]

Injectables this injectable depends on.

required
partial_resolution bool

If True, imports outside the current provider set are not required to be resolved.

None
strict_resolution bool

If False, resolution proceeds even when no implementation has been assigned.

None

discard_dependencies(imports)

Remove imports from this injectable's dependency set.

Removes the reverse dependent relationship from each discarded import as well. Useful when reconfiguring the dependency graph between resolution passes, for example in tests or dynamic reconfiguration scenarios.

Parameters:

Name Type Description Default
imports Iterable[Injectable]

Injectables to remove from imports.

required

set_implementation(implementation, modules_cls, bootstrap=None)

Assign a concrete implementation to this injectable.

Sets the implementation class, adds its module to the wiring set, and optionally sets a bootstrap callable. If an implementation was already assigned, logs a warning before overwriting — the last @instance decorator applied to a given Component wins.

Parameters:

Name Type Description Default
implementation type

The concrete class implementing the interface.

required
modules_cls Iterable[type]

Modules to include in wiring for this implementation (typically the implementation class itself).

required
bootstrap Callable[[], Any]

Callable invoked during the initialization phase if bootstrap=True was set on the decorator.

None

dependency.core.injection.injection

BaseInjection(name, parent=None)

Bases: ABC

Base class for all nodes in the injection tree.

Holds the node's name, its optional parent ContainerInjection, and the dot-separated reference path used by dependency-injector for wiring. Subclassed by ContainerInjection (for structural units) and ProviderInjection (for providable units).

Attributes:

Name Type Description
is_root bool

True if this node is a root (Plugin), meaning it has no parent by design and should not be treated as orphan.

name str

The class name of the decorated unit.

parent ContainerInjection

The parent node in the tree.

reference property

Return the reference for dependency injection.

change_parent(parent=None)

Change the parent injection of this injection.

Parameters:

Name Type Description Default
parent ContainerInjection

The new parent injection.

None

resolve_providers(container=None) abstractmethod

Resolve the injection context.

resolve_injectables() abstractmethod

Inject all children into the current injection context.

ContainerInjection(name, parent=None)

Bases: BaseInjection

Container Injection Class

resolve_providers(container=None)

Recursively attach all child providers to this container's DynamicContainer.

If a parent container is provided, also registers this node's DynamicContainer as an attribute on it, building the nested container structure that dependency-injector uses for reference-based wiring.

Parameters:

Name Type Description Default
container Container

The parent container to attach this node's DynamicContainer to, if any.

None

resolve_injectables()

Inject all children into the current container.

ProviderInjection(name, injectable, parent=None, provider=None)

Bases: BaseInjection

Injection node for a providable unit (Component or Product).

Holds the ProviderInjection's Injectable and the underlying dependency-injector Provider instance. Participates in the injection tree as a leaf node — it has a parent ContainerInjection but no children.

Attributes:

Name Type Description
_injectable Injectable

Tracks the implementation, imports, and resolution state for this provider.

_provider Provider

The dependency-injector provider instance (Singleton, Factory, or Resource).

injectable property

Return the injectable instance for this provider.

reference property

Return the reference for dependency injection.

provider property

Return the provider instance for this injectable.

set_provider(provider)

Set the provider instance for this injectable.

Parameters:

Name Type Description Default
provider Provider[Any]

The provider instance to set.

required

resolve_providers(container=None)

Return the provider instance.

resolve_injectables()

Inject all imports into the current injectable.

dependency.core.injection.wiring

WiringMixin

Base class for wiring mixins.

reference() abstractmethod classmethod

Return the reference name of the Injectable.

LazyWiring(provider, modifier=None)

Bases: _Marker

Base Lazy Class for deferred provider resolution.

Initialize the lazy wiring marker.

Accepts either a WiringMixin subclass (e.g. a Component class) or a plain callable returning a reference string or provider. If a WiringMixin class is given, its .reference classmethod is used as the deferred callable, ensuring the reference string is only resolved at injection time rather than at import time.

Parameters:

Name Type Description Default
provider Union[type[WiringMixin], Callable[[], Union[Provider[Any], Container, str]]]

A WiringMixin subclass or a callable returning a provider, container, or dot-separated reference string.

required
modifier Modifier

Optional wiring modifier from dependency-injector.

None

provider property

Return the provider instance.

Returns:

Type Description
Union[Provider[Any], Container, str]

The provider instance returned by the provider callable.

LazyProvide(provider, modifier=None)

Bases: LazyWiring, Provide

Lazy Provide Class for deferred provider resolution.

LazyProvider(provider, modifier=None)

Bases: LazyWiring, Provider

Lazy Provider Class for deferred provider resolution.

LazyClosing(provider, modifier=None)

Bases: LazyWiring, Closing

Lazy Closing Class for deferred provider resolution.

Resolution

dependency.core.resolution.resolver

InjectionResolver(container)

Injection Resolver Class

Initialize the resolver with the application container.

Parameters:

Name Type Description Default
container Container

The root application container that providers will be injected into and wired against.

required

resolve_dependencies(modules, strategy=ResolutionStrategy())

Resolve dependencies for a list of modules.

Parameters:

Name Type Description Default
modules Iterable[type[ContainerMixin]]

The list of module classes to resolve.

required
strategy type[ResolutionStrategy]

The resolution strategy to use.

ResolutionStrategy()

Returns:

Type Description
set[Injectable]

set[Injectable]: List of resolved injectables.

resolve_modules(modules)

Resolve all modules and initialize them.

Parameters:

Name Type Description Default
modules Iterable[type[ContainerMixin]]

The set of module classes to resolve.

required

resolve_injectables(modules)

Resolve all injectables from a set of modules.

Parameters:

Name Type Description Default
modules Iterable[type[ContainerMixin]]

The set of module classes to resolve.

required

Returns: set[Injectable]: Set of resolved injectables.

resolve_providers(providers, strategy=ResolutionStrategy())

Resolve all dependencies and initialize them.

Parameters:

Name Type Description Default
providers Iterable[Injectable]

The set of providers to resolve.

required
strategy type[ResolutionStrategy]

The resolution strategy to use.

ResolutionStrategy()

Returns:

Type Description
set[Injectable]

set[Injectable]: Set of resolved injectables.

dependency.core.resolution.strategy

ResolutionConfig

Bases: BaseModel

Configuration for the Resolution Strategy.

ResolutionStrategy(config=None)

Defines the strategy for resolving dependencies.

Initialize the strategy with an optional configuration.

Parameters:

Name Type Description Default
config ResolutionConfig

Configuration for the resolution process. Defaults to a ResolutionConfig with all defaults.

None

resolution(providers, container)

Resolve all dependencies and initialize them.

Parameters:

Name Type Description Default
providers list[Injectable]

List of providers to resolve.

required
container Container

The container to wire the injectables with.

required

Returns:

Type Description
set[Injectable]

list[Injectable]: List of resolved injectables.

expand(providers)

Expand the list of providers by adding all their imports.

Parameters:

Name Type Description Default
providers list[Injectable]

List of providers to expand.

required

Returns:

Type Description
set[Injectable]

list[Injectable]: List of expanded providers.

injection(providers)

Resolve all injectables in layers.

Parameters:

Name Type Description Default
providers list[Injectable]

List of injectables to resolve.

required

Returns:

Type Description
None

list[Injectable]: List of unresolved injectables.

wiring(providers, container)

Wire a list of providers with the given container.

Parameters:

Name Type Description Default
providers list[Injectable]

List of providers to wire.

required
container Container

The container to wire the providers with.

required

initialize(providers)

Start all implementations by executing their init functions.

Parameters:

Name Type Description Default
providers list[Injectable]

List of providers to start.

required

dependency.core.resolution.registry

Registry

Global store for all injection nodes created at decoration time.

The Registry is populated when @module, @component, @instance, and @product decorators are applied — before any resolution happens. It tracks every ContainerInjection and ProviderInjection ever created in the process, allowing cross-cutting validation and the FallbackPlugin to discover orphan providers.

This is class-level (shared) state. In test environments, the sets should be cleared between test runs to avoid state leaking across tests.

Attributes:

Name Type Description
containers set[ContainerInjection]

All registered container injection nodes.

providers set[ProviderInjection]

All registered provider injection nodes.

register_container(container) classmethod

Add a ContainerInjection node to the global registry.

Called by ContainerMixin.init_injection when a @module or @plugin decorator is applied.

Parameters:

Name Type Description Default
container ContainerInjection

The container node to register.

required

register_provider(provider) classmethod

Add a ProviderInjection node to the global registry.

Called by ProviderMixin.init_injection when a @component or @product decorator is applied.

Parameters:

Name Type Description Default
provider ProviderInjection

The provider node to register.

required

validation() classmethod

Warn about orphan containers and providers in the registry.

An orphan is any injection node with no parent and is_root=False — meaning it was declared without being registered under any module or plugin. Orphan providers will be adopted by the FallbackPlugin during initialization, but this is a fallback mechanism and not the intended usage.

This method only logs warnings; it does not raise exceptions.

dependency.core.resolution.container

Container

Bases: DynamicContainer

Container Class extending DynamicContainer with additional methods.

Attributes:

Name Type Description
config Configuration

Configuration provider for the container.

from_dict(config, required=False) staticmethod

Create a Container instance from a dictionary configuration.

Parameters:

Name Type Description Default
config dict[str, Any]

Configuration dictionary.

required
required bool

Whether the configuration is required. Defaults to False.

False

Returns:

Name Type Description
Container Container

A new Container instance configured with the provided dictionary.

from_json(file, required=False, envs_required=False) staticmethod

Create a Container instance from a JSON file configuration.

Parameters:

Name Type Description Default
file str

Path to the JSON configuration file.

required
required bool

Whether the configuration is required. Defaults to False.

False
envs_required bool

Whether environment variables are required. Defaults to False.

False

Returns:

Name Type Description
Container Container

A new Container instance configured with the provided JSON file.

dependency.core.resolution.errors

raise_circular_error(providers)

Raise an error if circular dependencies are detected.

Parameters:

Name Type Description Default
providers Iterable[Injectable]

The set of injectables to check for cycles.

required

Returns:

Name Type Description
bool bool

True if cycles were detected and errors were raised, False otherwise.

raise_dependency_error(unresolved)

Raise an error when unresolved dependencies are detected.

Parameters:

Name Type Description Default
unresolved Iterable[Injectable]

The set of unresolved injectables.

required

Returns:

Name Type Description
bool bool

True if unresolved dependencies were detected and errors were raised, False otherwise.

raise_resolution_error(providers, unresolved)

Raise an error if unresolved provider imports are detected.

Parameters:

Name Type Description Default
providers Iterable[Injectable]

The set of injectables to check.

required
unresolved Iterable[Injectable]

The set of resolved providers to check against.

required

Raises:

Type Description
ResolutionError

If unresolved dependencies or cycles are detected.

Exceptions

dependency.core.exceptions

DependencyError

Bases: Exception

Base class for all dependency-related errors.

DeclarationError

Bases: DependencyError

Exception raised for errors in the declaration of dependencies.

ResolutionError

Bases: DependencyError

Exception raised for errors during the resolution of dependencies.

ProvisionError

Bases: DependencyError

Exception raised for errors in the provision of dependencies.

InitializationError

Bases: DependencyError

Exception raised for errors during the initialization of components.

CancelInitialization

Bases: DependencyError

Exception to cancel the initialization of a component.