Python Dependency Injection

Dependency Injection (DI) is a design pattern where a class receives its dependencies from an external source rather than constructing them internally. This decouples components, improves testability, and enables flexible configuration without modifying production code.

Core Concept: Inversion of Control

Inversion of Control (IoC) shifts responsibility for creating and managing dependencies from the dependent class to an external orchestrator (a container or the caller). The class declares what it needs; something else provides it.

Tight coupling (avoid):

python

class UserNotifier:
    def __init__(self):
        self.email = EmailService()  # hard-coded, untestable

    def notify(self, msg):
        self.email.send(msg)

Loose coupling via DI (prefer):

python

class UserNotifier:
    def __init__(self, email_service: EmailService):
        self.email_service = email_service  # injected, swappable

    def notify(self, msg):
        self.email_service.send(msg)

notifier = UserNotifier(EmailService())

Injection Styles

Style	How	When to use
Constructor	Pass via `__init__`	Default; dependencies are required
Setter	Assign via method after construction	Optional dependencies
Method	Pass directly to the method call	One-off or per-call dependencies

Constructor injection is the preferred style. It makes all dependencies explicit and visible at object creation time.

The

dependency-injector

Library

For production applications, use the

dependency-injector

package (v4.x, BSD licensed, Python ≥ 3.8):

bash

pip install dependency-injector

Container-Provider Architecture

The framework organizes everything around two primitives:

Container — the central registry; declares all dependencies and how they are built
Provider — defines how a single dependency instance is created

python

from dependency_injector import containers, providers

class Container(containers.DeclarativeContainer):
    config = providers.Configuration()

    api_client = providers.Singleton(
        ApiClient,
        api_key=config.api_key,
        timeout=config.timeout,
    )

    service = providers.Factory(
        Service,
        api_client=api_client,
    )

Provider Types

Provider	Behavior	Use case
`Singleton`	Single shared instance for entire app lifetime	DB connections, API clients, caches
`Factory`	New instance on every call	Request handlers, per-operation objects
`Configuration`	Reads from env vars, YAML, JSON, ini	App settings
`Resource`	Managed lifecycle with setup/teardown	DB sessions, file handles
`Callable`	Wraps any callable	Functions, class methods
`Object`	Provides a fixed value	Constants, pre-built objects
`Selector`	Selects a provider based on config	Environment-based switching

Configuration Provider

Load settings from multiple sources:

python

class Container(containers.DeclarativeContainer):
    config = providers.Configuration()

container = Container()
container.config.api_key.from_env("API_KEY", required=True)
container.config.timeout.from_env("TIMEOUT", as_=int, default=5)
# Also supports: .from_yaml(), .from_ini(), .from_dict(), .from_pydantic()

Wiring: Auto-inject into Functions

Wiring eliminates manual dependency passing in function calls. Decorate a function with

@inject

, mark parameters with

Provide[...]

, then call

container.wire()

python

from dependency_injector.wiring import inject, Provide

@inject
def main(service: Service = Provide[Container.service]) -> None:
    service.do_work()

if __name__ == "__main__":
    container = Container()
    container.config.from_env(...)
    container.wire(modules=[__name__])
    main()  # service is injected automatically

Wire entire packages at once:

container.wire(packages=["myapp"])

Overriding for Tests

Override any provider without modifying application code:

python

# In tests
with container.api_client.override(mock.Mock()):
    main()  # the mock is injected instead

Or using the

dependency-injector

testing helpers:

python

def test_service_behavior():
    container = Container()
    container.db.override(providers.Factory(FakeDB))

    service = container.service()
    assert service.get_data() == "expected"

FastAPI equivalent via

dependency_overrides

python

app.dependency_overrides[get_db_session] = lambda: FakeDBSession()

Resource Provider: Managed Lifecycle

Use

Resource

for dependencies that require explicit setup and teardown:

python

from dependency_injector import resources

class DatabaseResource(resources.Resource):
    def init(self) -> Database:
        db = Database(url=self.config.db_url())
        db.connect()
        return db

    def shutdown(self, db: Database) -> None:
        db.disconnect()

class Container(containers.DeclarativeContainer):
    config = providers.Configuration()
    db = providers.Resource(DatabaseResource, config=config)

# Usage
container = Container()
container.init_resources()
# ... use container.db() ...
container.shutdown_resources()

Async Injection

The framework supports async resources and FastAPI's native

Depends()

python

# dependency-injector async resource
class AsyncDBResource(resources.AsyncResource):
    async def init(self) -> AsyncDB:
        db = AsyncDB()
        await db.connect()
        return db

    async def shutdown(self, db: AsyncDB) -> None:
        await db.disconnect()

# FastAPI native async dependency
async def get_db() -> AsyncGenerator[AsyncSession, None]:
    async with async_session() as session:
        yield session

@app.get("/items")
async def read_items(db: AsyncSession = Depends(get_db)):
    ...

Best Practices

Program to abstractions:

python

from abc import ABC, abstractmethod

class MessageSender(ABC):
    @abstractmethod
    def send(self, message: str) -> None: ...

class EmailSender(MessageSender):
    def send(self, message: str) -> None:
        print(f"Email: {message}")

class SMSSender(MessageSender):
    def send(self, message: str) -> None:
        print(f"SMS: {message}")

# Container switches implementation without changing consumer
class Container(containers.DeclarativeContainer):
    sender = providers.Factory(EmailSender)  # swap to SMSSender anytime

Centralize dependency configuration — define all providers in one container module, not scattered across the codebase.

Avoid circular dependencies — if A depends on B and B depends on A, restructure or use a factory provider to delay instantiation.

Use the right scope —

Singleton

for stateless shared resources;

Factory

for stateful per-request objects. Mismatched scopes cause subtle state leakage bugs.

Lock dependency versions — pin exact versions in a lock file (

poetry.lock

, pip-compile output) to avoid dependency confusion attacks.

Anti-Patterns to Avoid

Anti-pattern	Problem	Fix
Service Locator	`container.get(Service)` inside business logic hides dependencies	Inject explicitly via constructor or `@inject`
Over-injection	10+ constructor params	Split into smaller, focused classes
Tight coupling	`self.dep = ConcreteClass()` inside `__init__`	Accept dependency as parameter
Scope mismanagement	`Singleton` wrapping a stateful request-scoped object	Use `Factory` or `Resource` with correct scope
Monkey-patching in tests	`module.SomeClass = MockClass`	Use `container.override()` or `dependency_overrides`

Quick Reference

bash

pip install dependency-injector          # base
pip install "dependency-injector[yaml]"  # + YAML config support
pip install "dependency-injector[pydantic2]"  # + Pydantic v2 settings

python

# Minimal working container
from dependency_injector import containers, providers
from dependency_injector.wiring import inject, Provide

class Container(containers.DeclarativeContainer):
    config  = providers.Configuration()
    service = providers.Factory(MyService, setting=config.setting)

@inject
def handler(svc: MyService = Provide[Container.service]):
    svc.run()

container = Container()
container.config.from_dict({"setting": "value"})
container.wire(modules=[__name__])
handler()

Additional Resources

For detailed coverage of advanced topics, consult:

references/patterns.md
— Scoped dependencies, multiple containers, selector providers, and testing patterns
references/framework-integration.md
— Step-by-step integration with Flask, Django, and FastAPI including wiring setup

python-dependency-injection

NPX Install

Tags

SKILL.md Content

Python Dependency Injection

Core Concept: Inversion of Control

Injection Styles

The
`dependency-injector`
Library

Container-Provider Architecture

Provider Types

Configuration Provider

Wiring: Auto-inject into Functions

Overriding for Tests

Resource Provider: Managed Lifecycle

Async Injection

Best Practices

Anti-Patterns to Avoid

Quick Reference

Additional Resources