Dependency Injection
In the Hexagonal Architecture, the application core depends only on ports, never on the adapters that implement them. Some code still has to create the adapters and hand them to the core. Dependency injection is the name for this: an object receives the objects it works with from outside instead of creating or looking them up itself. This chapter recommends a way to set up dependency injection in a service built on hexkit, and explains why we recommend plain Python over a dependency injection framework.
Why Plain Python
hexkit works with any dependency injection framework, but does not need one, and we recommend wiring a service without one. The service then wires its dependencies by hand, in ordinary functions that call constructors and pass the results on. This has the following advantages:
- Transparent: the wiring is code you can read top to bottom, with no registry, decorators or name matching.
- Debuggable: a debugger steps through it, and a wrong argument fails at the line that passes it.
- Type-checked: mypy checks every constructor call, so most wiring mistakes show before the service runs.
- No global state: everything is created inside a function call, so tests can build as many independent instances as they like.
- Lazy: each entrypoint builds only what it uses, so starting the REST API does not also start an event consumer.
The price is some verbosity. In a microservice with a handful of components, that is a few dozen lines, written once and read often.
hexkit’s providers are built for this style. Providers that hold a resource, such as a database client or a Kafka producer, are created with a construct class method that returns an async context manager. Entering it opens the connection, and leaving it closes the connection again, so setup and teardown follow the structure of the code. Providers without such a resource, such as S3ObjectStorage, are created with a plain constructor call.
Constructor Injection in the Core
The core receives every dependency through its constructor, typed as a port:
class LoanManager(LoanManagerPort):
"""Handles the lending and returning of books."""
def __init__(
self,
*,
config: LoanConfig,
book_dao: BookDaoPort,
event_publisher: EventPublisherPort,
):
self._config = config
self._book_dao = book_dao
self._event_publisher = event_publisherFollow these rules in the core:
- Type each dependency as its port, a
Protocolor abstract base class, so that any implementation can be passed in. - Make the parameters keyword-only, since the wiring code calls them by name and a reordering cannot then go unnoticed.
- Pass the config in like any other dependency instead of instantiating it, so tests can vary it per instance.
- Keep imports of hexkit providers, FastAPI and other infrastructure out of the core; only the wiring code needs them.
The same applies to the translators of the adapters: an event subscriber translator receives the inbound port of the core, and an event publisher translator receives the hexkit provider it publishes through.
The Composition Root
All wiring of a service lives in one module, conventionally named inject.py. This module, the composition root, is the only place that knows which adapter implements which port. It typically holds three kinds of functions, each an async context manager that takes the config and yields the finished object:
prepare_corebuilds the outbound adapters and the core, and yields the inbound port of the core.- One
prepare_<adapter>per inbound adapter, such asprepare_rest_apporprepare_event_subscriber, builds the adapter on top ofprepare_core. - Optionally, helpers for a provider that more than one of the above needs with the same settings, such as a persistent publisher with its topic configuration.
Preparing the Core
from collections.abc import AsyncGenerator
from contextlib import asynccontextmanager
from hexkit.providers.akafka import KafkaEventPublisher
from hexkit.providers.mongodb import MongoDbDaoFactory
from my_service.adapters.outbound.dao import get_book_dao
from my_service.adapters.outbound.event_pub import EventPubTranslator
from my_service.config import Config
from my_service.core.loans import LoanManager
from my_service.ports.inbound.loans import LoanManagerPort
@asynccontextmanager
async def prepare_core(*, config: Config) -> AsyncGenerator[LoanManagerPort]:
"""Construct the core with all its outbound dependencies."""
async with (
MongoDbDaoFactory.construct(config=config) as dao_factory,
KafkaEventPublisher.construct(config=config) as kafka_publisher,
):
book_dao = await get_book_dao(dao_factory=dao_factory)
event_publisher = EventPubTranslator(config=config, provider=kafka_publisher)
yield LoanManager(
config=config, book_dao=book_dao, event_publisher=event_publisher
)The return type is the port, not the implementation, so callers of prepare_core depend on the port as well. The resources stay open as long as the caller stays inside the async with block, and close in reverse order when it leaves, also when an exception ends the block.
Put the details of building one adapter, such as the collection name and indexes of a DAO, into a small function next to the adapter, like get_book_dao above. This keeps prepare_core a readable list of what the core is made of.
Preparing the REST API
FastAPI resolves the dependencies of a route with Depends. The routes are defined at import time, before any port implementation exists, so they depend on a placeholder that the composition root replaces once the core is built. Define the placeholders in their own module of the REST adapter:
# my_service/adapters/inbound/fastapi_/dummies.py
from typing import Annotated
from fastapi import Depends
from my_service.ports.inbound.loans import LoanManagerPort
def loan_manager_port() -> LoanManagerPort:
"""Placeholder that the composition root replaces with the real loan manager."""
raise RuntimeError("The loan manager dependency was not replaced.")
LoanManagerDummy = Annotated[LoanManagerPort, Depends(loan_manager_port)]# my_service/adapters/inbound/fastapi_/routes.py
@router.post("/loans")
async def lend_book(loan: LoanRequest, loan_manager: LoanManagerDummy):
await loan_manager.lend(book_id=loan.book_id, user_id=loan.user_id)A placeholder that raises turns a forgotten replacement into a clear error on the first request instead of a confusing one.
prepare_rest_app then maps each placeholder to the real object through FastAPI’s dependency_overrides:
@asynccontextmanager
async def prepare_rest_app(*, config: Config) -> AsyncGenerator[FastAPI]:
"""Construct the REST API app with all its dependencies."""
app = get_configured_app(config=config)
async with prepare_core(config=config) as loan_manager:
app.dependency_overrides[dummies.loan_manager_port] = lambda: loan_manager
yield appEach lambda returns the same instance on every request, so the core and its connections are shared by all requests and live as long as the app. This is the intended lifetime for hexkit providers, which manage connection pools of their own.
Preparing the Event Subscriber
An event consumer is wired the same way, with the translator in place of the routes:
@asynccontextmanager
async def prepare_event_subscriber(
*, config: Config
) -> AsyncGenerator[KafkaEventSubscriber]:
"""Construct the event subscriber with all its dependencies."""
async with prepare_core(config=config) as loan_manager:
translator = EventSubTranslator(config=config, loan_manager=loan_manager)
async with (
KafkaEventPublisher.construct(config=config) as dlq_publisher,
KafkaEventSubscriber.construct(
config=config, translator=translator, dlq_publisher=dlq_publisher
) as event_subscriber,
):
yield event_subscriberIf the service consumes several groups of topics, combine their translators with a ComboTranslator and pass that to a single subscriber.
Entrypoints
The entrypoints of the service, usually in main.py, create the config, set up logging and use exactly one prepare function each:
async def run_rest_app() -> None:
"""Run the HTTP REST API."""
config = Config()
configure_logging(config=config)
async with prepare_rest_app(config=config) as app:
await run_server(app=app, config=config)
async def consume_events(run_forever: bool = True) -> None:
"""Run an event consumer listening to the configured topics."""
config = Config()
configure_logging(config=config)
async with prepare_event_subscriber(config=config) as event_subscriber:
await event_subscriber.run(forever=run_forever)A periodic job or a command line task can use prepare_core directly and call the core in a loop.
Overriding Dependencies in Tests
Without a container, there is no central place to swap a dependency. Instead, each inbound prepare function takes an optional override for the port it builds on, so a test can run the real adapter against a mock core:
def prepare_core_with_override(
*, config: Config, loan_manager_override: LoanManagerPort | None = None
):
"""Return the given loan manager, or a context manager that builds the real one."""
return (
nullcontext(loan_manager_override)
if loan_manager_override is not None
else prepare_core(config=config)
)
@asynccontextmanager
async def prepare_rest_app(
*, config: Config, loan_manager_override: LoanManagerPort | None = None
) -> AsyncGenerator[FastAPI]:
"""Construct the REST API app, with the real core unless an override is given."""
app = get_configured_app(config=config)
async with prepare_core_with_override(
config=config, loan_manager_override=loan_manager_override
) as loan_manager:
app.dependency_overrides[dummies.loan_manager_port] = lambda: loan_manager
yield appA REST test then needs neither a database nor Kafka:
async def test_lend_unknown_book():
"""Test that lending an unknown book returns 404."""
loan_manager = AsyncMock()
loan_manager.lend.side_effect = LoanManagerPort.BookNotFoundError(book_id="b1")
async with (
prepare_rest_app(config=config, loan_manager_override=loan_manager) as app,
httpx2.AsyncClient(
transport=httpx2.ASGITransport(app=app), base_url="http://test"
) as client,
):
response = await client.post("/loans", json={"book_id": "b1", "user_id": "u1"})
assert response.status_code == 404Follow these rules for overrides:
- Override at the inbound port of the core, the boundary the adapter under test talks to. Overriding single outbound adapters through every layer makes the signatures long and the tests brittle.
- Test the core itself by calling its constructor directly with in-memory or mock adapters, such as hexkit’s testing providers; it needs no composition root.
- Test outbound adapters against real infrastructure in test containers, through hexkit’s fixtures and the regular prepare functions.
- Compare an override with
is not None, not by its truth value, since a valid implementation may define__bool__or__len__and be falsy. - If a service has several independent inbound ports, give each its own prepare function and override parameter.
If a test needs the outbound dependencies of a real core, for example to inspect the database after a call, let a separate prepare function yield a dataclass that holds the core together with them. Keep prepare_core itself yielding only the port, so production code cannot reach past it.
Summary
- Pass every dependency to the core through its constructor, typed as a port.
- Wire the service in one
inject.pywith plain functions; it is the only module that imports concrete providers. - Write one async context manager for the core and one per inbound adapter, and let each entrypoint use exactly one.
- Use
async withfor every provider that holds a resource, and share one instance within a process where adapters need the same backend. - Give inbound prepare functions an optional override of the core port for tests.