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)
LazyProvider(provider, modifier=None)
LazyClosing(provider, modifier=None)
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.