DEV Community: Vlad Shulcz

Fast dependency injection in Python without a provider framework

Vlad Shulcz — Tue, 09 Jun 2026 07:54:07 +0000

Python does not need a dependency injection container by default.
For small apps, direct constructor calls are clearer than any framework:

repo = UserRepository(settings.database_url)
email = EmailSender(settings.smtp_url)
use_case = RegisterUser(repo, email)

That is fine once.

The problem starts when the same object graph appears in more than one place:

FastAPI startup;
Typer commands;
background workers;
scripts;
tests.

At that point, the question is not "how do I inject everything?"

The better question is:

Where should application wiring live?

The boundary I want

For web apps, I like this split:

FastAPI owns HTTP adaptation;
Typer owns CLI adaptation;
workers own job adaptation;
the application owns service wiring.

That means repositories, gateways, and use cases should depend on normal Python types, not framework primitives.

A service should not need to know whether it was called from an HTTP request, a CLI command, a queue worker, or a test.

FastAPI Depends is not the whole composition root

FastAPI Depends is excellent at the request boundary.

It handles request data, authentication, headers, cookies, and per-request adapters.

But if the same service graph is used outside HTTP, the real composition root should live in plain Python.

A useful shape is:

def build_services(settings: Settings) -> Services:
    client = ApiClient(settings)
    repo = UserRepository(client)
    email = EmailSender(client)

    return Services(
        register_user=RegisterUser(repo, email),
    )

FastAPI can adapt that graph:

@asynccontextmanager
async def lifespan(app: FastAPI):
    app.state.services = build_services(load_settings())
    yield

def get_register_user(request: Request) -> RegisterUser:
    return request.app.state.services.register_user

Workers and CLIs can use the same builder directly:

services = build_services(load_settings())
services.register_user.execute("ada@example.com")

The rule of thumb:

FastAPI adapts HTTP. The application owns service wiring.

Start with factories

I still think plain factories are the best default.

If your graph is small, this is better than adding any container:

def build_register_user(settings: Settings) -> RegisterUser:
    client = ApiClient(settings)
    repo = UserRepository(client)
    email = EmailSender(client)

    return RegisterUser(repo, email)

A DI container becomes useful later, when the same graph starts repeating across entrypoints and tests.

Why I built Injex

I built Injex for that middle ground.

Not a full provider framework.
Not framework-specific dependency injection.
Not a replacement for FastAPI Depends.

The niche is small Python apps that want:

explicit registrations;
constructor injection from type hints;
singleton, transient, and scoped lifetimes;
test overrides;
graph validation before startup;
zero runtime dependencies.

Example:

from injex import Container


container = Container()

container.add_instance(Settings, settings)
container.add_singleton(ApiClient)
container.add_transient(UserRepository)
container.add_transient(EmailSender)
container.add_transient(RegisterUser)

container.assert_valid()

use_case = container.resolve(RegisterUser)

Application classes stay plain:

class RegisterUser:
    def __init__(self, repo: UserRepository, email: EmailSender):
        self.repo = repo
        self.email = email

No decorators required for constructor injection.
No provider DSL.
No runtime dependencies.

What changed in 1.3.0

Injex 1.3.0 focused on two things:

cleaner internals;
faster repeated resolves.

Internally, the package is now split into focused modules:

container.py;
planning.py;
registry.py;
errors.py.

For performance, Injex now caches dependency plans and uses a fast path for common constructor-injection graphs.

Benchmark

I added a reproducible benchmark for a small service graph:

singleton Settings;
singleton ApiClient(settings);
transient UserRepository(client);
transient EmailSender(client);
transient AuditLog(settings);
transient RegisterUser(repo, email, audit).

Local result

Library	Median resolve time
manual wiring	`0.265 µs/op`
Injex	`0.818 µs/op`
Wireup, same scope	`0.879 µs/op`
Wireup, scope per operation	`1.559 µs/op`
dependency-injector	`1.727 µs/op`
lagom	`9.794 µs/op`
punq	`56.795 µs/op`

This is not a universal ranking.

Different graphs, lifetimes, async resources, framework integrations, and request scope models can change results.

The benchmark exists to answer a narrower question:

Can explicit typed wiring stay small and fast?

For this graph, yes.

Reproduce it:

uv run --with punq --with lagom --with dependency-injector --with wireup \ python benchmarks/resolve_graph.py

When I would not use Injex

I would skip Injex when:

a few constructor calls are still clear;
a framework dependency system covers every entrypoint;
the app needs a large provider/configuration DSL;
the team does not want a container at all.

Manual wiring is still the baseline.

Where Injex fits

I would consider Injex when:

a service layer is reused by API, CLI, workers, and tests;
constructors already describe dependencies with type hints;
tests need temporary external-service overrides;
startup should catch missing registrations before first request/job;
the team wants explicit wiring without a large DI framework.

Links

Repo:
https://github.com/vshulcz/injex

Docs:
https://vshulcz.github.io/injex/

Performance notes:
https://vshulcz.github.io/injex/docs/performance.html

Compared to FastAPI Depends:
https://github.com/vshulcz/injex/blob/main/docs/fastapi-depends.md

When Python Manual Wiring Turns Into Copy-Paste Architecture

Vlad Shulcz — Tue, 26 May 2026 11:07:59 +0000

I usually avoid dependency injection containers in Python.

Not because dependency injection is bad. Most of us already do it when we pass objects into constructors. I avoid containers because small Python apps usually do not need one.

Manual wiring is often the right starting point:

repo = UserRepository()
email_sender = EmailSender()
register_user = RegisterUser(repo, email_sender)

That is explicit, easy to debug, and boring in a good way.

The problem starts when this code stops living in one place.

The Code Drifts

The same services need to be created across completely different entrypoints.

In api/routes.py:

register_user = RegisterUser(UserRepository(), EmailSender())

In cli/commands.py:

# Oops, forgot to update this one when dependencies changed?
register_user = RegisterUser(UserRepository(), MockEmailSender())

The code does not fail all at once. It drifts.

One entrypoint gets a new dependency:

register_user = RegisterUser(repo, email_sender, audit_log)

Another still creates the old version. A test uses a fake for one service but accidentally keeps a real client for another. A worker starts fine, then fails only when the first real job touches the missing path.

That is the kind of boring failure I wanted to avoid. It was not a big architecture disaster. It was worse in a boring way: tiny setup details repeated in enough places that forgetting one became easy.

The problem is not dependency injection

Most Python code already uses dependency injection in the boring sense:

class RegisterUser:
    def __init__(self, repo: UserRepository, email_sender: EmailSender):
        self.repo = repo
        self.email_sender = email_sender

The class is fine. It receives dependencies instead of creating them.

The mess appears around the class, when every entrypoint has to remember how to build the same graph.

Framework DI stops at the framework boundary

FastAPI Depends is useful. Framework dependency systems are good when the framework owns the entrypoint.

But application services often need to run elsewhere:

maintenance commands;
scheduled jobs;
message consumers;
tests;
local scripts.

I do not want my service layer to care whether it is being called from an API route, a CLI command, or a worker. Construction can stay at the edge. The service layer can stay plain.

I wanted something smaller than a full DI container

Python already has mature DI libraries. Some of them support provider objects, configuration systems, framework integrations, and dozens of advanced features.

That is useful if you need it. I wanted a smaller tool for the middle ground:

Normal constructor injection (no magic syntax).
Type hints as the wiring contract.
Singleton, transient, and scoped lifetimes.
Temporary overrides in tests.
Validation before startup.
Zero runtime dependencies & no decorators required on your services.

I built injex as one attempt at that middle ground.

Here is how the wiring can live in one place.

In a real app, these classes would live in separate modules. They are inline here to keep the example short:

# app/ioc.py
from abc import ABC, abstractmethod
from injex import Container

class UserRepository(ABC):
    @abstractmethod
    def save(self, email: str) -> int: ...

class SqlUserRepository(UserRepository):
    def save(self, email: str) -> int:
        return 42

class EmailSender:
    def send_welcome(self, email: str) -> None:
        print(f"Welcome, {email}")

class RegisterUser:
    def __init__(self, repo: UserRepository, email_sender: EmailSender):
        self.repo = repo
        self.email_sender = email_sender

    def execute(self, email: str) -> int:
        return self.repo.save(email)

# Centralized configuration
container = Container()

# Bind abstract interfaces to concrete implementations
container.add_singleton(UserRepository, SqlUserRepository)
container.add_singleton(EmailSender)
container.add_transient(RegisterUser)

container.assert_valid()

Now each entrypoint uses the same graph.

In your api/routes.py or cli/commands.py, you just resolve what you need:

from app.ioc import container, RegisterUser

use_case = container.resolve(RegisterUser)
use_case.execute("ada@example.com")

The service class stays plain Python. No decorators, no base class, no framework imports. The container only owns construction.

The part I care about most: validation

The most useful feature for me is not resolving objects. It is finding broken wiring before anything important runs.

If a dependency is missing, or a constructor annotation is wrong, I want to know at startup. Not after the first HTTP request. Not after the first worker job. Not in a rarely used CLI path at 3 AM.

container.assert_valid()

If you forgot to register AuditLog, startup fails immediately with a clear error:

Container validation failed with 1 error(s):
- RegisterUser: Dependency 'audit_log' is not registered: AuditLog.

Or you can collect errors explicitly in your CI/CD sanity-check script:

errors = container.validate()

if errors:
    for error in errors:
        print(error)
    raise SystemExit(1)

The crucial detail is that validation checks the dependency graph without constructing service instances. That matters when constructors open files, spin up thread pools, or establish heavy database connections.

Test overrides

Tests are where copy-pasted wiring becomes especially annoying.

You either rebuild the whole graph for each test, or you mutate shared setup and hope it gets restored correctly. I wanted replacement to be explicit and temporary:

class FakeEmailSender:
    def __init__(self):
        self.sent_to = []

    def send_welcome(self, email: str) -> None:
        self.sent_to.append(email)

fake_sender = FakeEmailSender()

# Explicit context manager for tests
with container.override(EmailSender, instance=fake_sender):
    use_case = container.resolve(RegisterUser)
    use_case.execute("test@example.com")

assert fake_sender.sent_to == ["test@example.com"]
# Outside the block, the original configuration is restored.

That keeps tests explicit without permanently mutating the production container or introducing side effects.

Scoped lifetimes

Some objects should live for one request, one job, or one message, but not for the whole lifecycle of the process.

class RequestContext:
    pass

container.add_scoped(RequestContext)

scope_a = container.create_scope()
scope_b = container.create_scope()

assert scope_a.resolve(RequestContext) is scope_a.resolve(RequestContext)
assert scope_a.resolve(RequestContext) is not scope_b.resolve(RequestContext)

This is ideal for message consumers (like Celery or RabbitMQ workers) that reuse long-lived clients but still need isolated per-job state.

Multiple implementations

Sometimes resolving one implementation is wrong. You want every handler, plugin, or pipeline step registered for the same interface.

container.add_singleton(Notifier, EmailNotifier)
container.add_singleton(Notifier, SlackNotifier)

# Resolve all registered implementations at once
for notifier in container.resolve_all(Notifier):
    notifier.notify("Deployment complete")

That is enough for simple fan-out notifications, plugin architectures, and processing pipelines.

When I would not use it

A container should pay rent. I would still skip one if:

the wiring fits in one file;
there is only one entrypoint;
tests can easily pass fakes directly via standard constructors;
the framework dependency system (like FastAPI) already covers 100% of your operational surface;
the project needs a massive provider/configuration ecosystem.

Manual wiring is still the baseline. A container should only appear when it removes repeated construction code instead of adding ceremony.

Closing

I am not trying to make Python look like Java. I still prefer manual wiring when an application is small enough.

I built injex for the awkward middle: the graph is repeated enough to hurt, but not complex enough to justify a large provider framework. It is small, type-hint driven, zero-dependency, and focused entirely on explicit app wiring.

If you have run into this problem in Python services, CLIs, workers, or tests, I would appreciate your feedback on the API and examples!

Links: