philiprehberger-di

Lightweight dependency injection container for Python.

Installation

pip install philiprehberger-di

Usage

from philiprehberger_di import Container

container = Container()
container.register(Logger)
logger = container.resolve(Logger)

Singletons

container.register(Database, singleton=True)

a = container.resolve(Database)
b = container.resolve(Database)
assert a is b

Custom Factories

container.register(Cache, factory=lambda: Cache(max_size=256))
cache = container.resolve(Cache)

Recursive Resolution

class Service:
    def __init__(self, db: Database, logger: Logger) -> None:
        self.db = db
        self.logger = logger

container.register(Database)
container.register(Logger)
container.register(Service)
service = container.resolve(Service)  # db and logger are injected automatically

Inject Decorator

from philiprehberger_di import Container, inject

container = Container()
container.register(Logger, singleton=True)

@inject(container)
def handle_request(logger: Logger) -> str:
    logger.log("request handled")
    return "ok"

handle_request()  # logger is resolved and injected automatically

Lifecycle Hooks

container.register(
    Database,
    singleton=True,
    on_create=lambda db: db.connect(),
    on_destroy=lambda db: db.disconnect(),
)

db = container.resolve(Database)  # on_create called after creation
container.reset()                 # on_destroy called before clearing singletons

Circular Dependency Detection

The container detects circular dependencies during resolution and raises a CircularDependencyError with the full dependency chain:

from philiprehberger_di import CircularDependencyError

class A:
    def __init__(self, b: B) -> None: ...

class B:
    def __init__(self, a: A) -> None: ...

container.register(A)
container.register(B)

try:
    container.resolve(A)
except CircularDependencyError as e:
    print(e)  # Circular dependency detected: A -> B -> A
    print(e.chain)  # [A, B, A]

Scoped Lifetime

Services registered with Lifetime.SCOPED are singletons within a scope but differ across scopes:

from philiprehberger_di import Container, Lifetime

container = Container()
container.register(RequestContext, lifetime=Lifetime.SCOPED)
container.register(Logger, lifetime=Lifetime.SINGLETON)

with container.create_scope() as scope:
    ctx1 = scope.resolve(RequestContext)
    ctx2 = scope.resolve(RequestContext)
    assert ctx1 is ctx2  # same within the scope

# on_destroy hooks are called when the scope exits

Lazy Resolution

Defer construction of an expensive service until first use:

from philiprehberger_di import Container, Lifetime

container = Container()
container.register(ExpensiveClient, lifetime=Lifetime.SINGLETON)

proxy = container.lazy(ExpensiveClient)
# ExpensiveClient is NOT yet constructed

result = proxy.do_thing()  # constructed on first access, cached afterwards

Introspection

Check whether a type is registered, or remove it. Useful when wiring up tests:

container.is_registered(Database)  # True / False

container.register(Database, singleton=True)
container.unregister(Database)     # also clears cached singleton + calls on_destroy

Introspection and full clear

List every type registered in the container, or wipe it clean:

container.register(Logger)
container.register(Database, singleton=True)

container.registered_types()  # [Logger, Database] — snapshot, in insertion order

container.clear()  # removes ALL registrations and cached singletons
                   # (calls on_destroy first for any cached singletons)

Unlike reset(), which only clears the singleton cache and keeps registrations intact, clear() empties the container entirely.

API

Development

pip install -e .
python -m pytest tests/ -v

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT