repository·master·Indexed 23 days ago
https://github.com/python-injector/injectorA Python dependency injection framework inspired by Google Guice. It automates transitive dependency provision using modules, providers, and scopes to encourage decoupled, modular code. The framework avoids global state, requiring explicit use of an Injector instance via methods like .get() or .create_object(), and is designed for compatibility with static type checkers like mypy.
A Provider is a mechanism for providing an instance of a type. Injector includes several built-in providers:
ClassProvider: Creates a new instance from a class.InstanceProvider: Returns an existing instance directly.CallableProvider: Provides an instance by calling a function.To create a custom provider, subclass injector.Provider and override the get method.
mypy. The Injector.get() method is typed such that injector.get(SomeType) is statically declared to return an instance of SomeType, allowing for type-safe dependency retrieval.Using @inject or scope decorators on your classes does not change how they are constructed manually. These decorators do not modify global state and do not allow dependencies to be injected automatically when you instantiate a class without the Injector instance.
To ensure that dependencies defined in your bindings are actually provided, you must obtain the instance through the Injector (either by injecting the class into another component or by using Injector.get()).
class X:
@inject
def __init__(self, s: str):
self.s = s
# This will FAIL with a TypeError because @inject cannot find bindings without an Injector instance
x = X()A child injector inherits bindings from a parent injector but can override specific bindings without affecting the parent. This allows for localized configuration.
Warning: If a binding key is already in a parent injector's scope (like singleton), the provider saved in the parent may take precedence when overriding in the child. This behavior is subject to change.
from injector import Injector
def configure_parent(binder):
binder.bind(str, to='asd')
binder.bind(int, to=42)
def configure_child(binder):
binder.bind(str, to='qwe')
parent = Injector(configure_parent)
child = parent.create_child_injector(configure_child)
print(parent.get(str)) # 'asd'
print(child.get(str)) # 'qwe'
print(child.get(int)) # 42When defining Module classes, avoid using @inject in their __init__ or configure methods to acquire dependencies. Doing so makes the injection process dependent on the order in which modules are passed to the Injector instance, which is fragile and error-prone.
If ModuleA requires a dependency provided by ModuleC, but ModuleA is passed to the Injector before ModuleC, an error will occur because the dependency is unbound at the time ModuleA is processed.
A = Key('A')
B = Key('B')
class ModuleA(Module):
@inject(a=A)
def configure(self, binder, a):
pass
class ModuleB(Module):
@inject(b=B)
def __init__(self, b):
pass
class ModuleC(Module):
def configure(self, binder):
binder.bind(A, to='a')
binder.bind(B, to='b')
# This will fail if ModuleA or ModuleB appear before ModuleC in the list
Injector([ModuleA, ModuleC])Unlike some frameworks, Injector does not use global state. You cannot simply decorate a constructor with @inject and instantiate the class manually if that class requires dependencies; there is no global Injector instance to resolve them automatically.
To resolve dependencies, you must be explicit by using one of the following methods on an Injector instance:
Injector.get()Injector.create_object()Injector.This design ensures that classes remain standard Python classes that can still be instantiated manually without the framework if desired.
Injector is designed around several key principles:
Injector instance via injector.get() or injector.create_object(). This allows multiple independent injectors with different configurations to coexist.mypy. For example, injector.get(SomeType) is typed to return an instance of SomeType.@inject, @Inject, and @NoInject are simple markers. Your classes can often be instantiated manually without an injector if needed.Injector and its related classes use a lock to ensure thread safety. This means only one thread can perform dependency injection at a time.
Warning: Performing blocking IO (especially without timeouts) inside Module code or @provider methods can lead to application-wide deadlocks. Always avoid performing IO inside these components.
class BadModule(Module):
@provider
def provide_suba(self) -> SubA:
# DO NOT DO THIS: Blocking calls/IO inside providers can deadlock the app
while True:
sleep(1)
return SubA()For complex dependency graphs, Injector uses several key abstractions:
Module used to group bindings and providers.@provider that define how to construct a specific type.@singleton ensures that the same instance is returned every time the type is requested within that Injector instance.This allows you to decouple configuration (e.g., connection strings) from implementation (e.g., database connection logic).
import sqlite3
from injector import Module, provider, Injector, inject, singleton
class Configuration:
def __init__(self, connection_string):
self.connection_string = connection_string
# 1. Using a configuration function with a binder
def configure_for_testing(binder):
configuration = Configuration(':memory:')
binder.bind(Configuration, to=configuration, scope=singleton)
# 2. Using a Module with @provider and @singleton
class DatabaseModule(Module):
@singleton
@provider
def provide_sqlite_connection(self, configuration: Configuration) -> sqlite3.Connection:
conn = sqlite3.connect(configuration.connection_string)
return conn
class RequestHandler:
@inject
def __init__(self, db: sqlite3.Connection):
self._db = db
# 3. Initializing the Injector with modules
injector = Injector([configure_for_testing, DatabaseModule()])
handler = injector.get(RequestHandler)By default, providers are executed every time an instance is required (NoScope). Scopes allow you to customize this behavior:
SingletonScope: (Typically used via the @singleton decorator) ensures the same instance is always provided.Note: Default scopes are bound only to the root injector. Manually binding them to child injectors can result in unexpected behavior.
For scopes that require a transient lifetime tied to a specific context (such as an HTTP request), implement a thread-local or greenlet-local cache inside your Scope implementation.
To manage the lifecycle, call a method on your scope instance in low-level code to "enter" the scope (creating the cache) and call another method to "leave" the scope (clearing the cache) once the request is complete.
When using Injector, be aware of the following thread safety guarantees:
Thread-safe operations:
Injector.get to retrieve an instance.@inject decorator.Non-thread-safe operations:
Injector instance are not thread safe unless explicitly stated otherwise.@inject decorator itself is thread safe for performing injection, it does not guarantee the thread safety of the function it decorates.