hex-wiring
Use when adding a binding in `containers.py` — provider classes, binding lifetimes, the `create_container` composition root and its declaration order, and where each settings class is constructed and
SKILL.mdplugins/pyhouse-hex/skills/hex-wiring/SKILL.md
GitHubHex — Wiring
Handing objects to whoever needs them, from one composition root. Settings are among those objects:
what a settings class declares is python-settings, and this skill says where, in a hexagonal service,
it is constructed and bound — at a composition root and nowhere else (python-settings rule 13). Each
settings class is shown beside the adapter that reads it: the relational store's PostgresSettings
in hex-persistence, FooClassifierSettings in hex-capability-adapter, RedisSettings in
hex-store-repository, JwtSettings in hex-restapi-auth. The composition roots of that rule are,
in this catalogue's layout, src/myapp/containers.py (the process's container), migrations/env.py
(the migration environment, hex-project-setup) and TestInfrastructureProvider with its fixtures in
tests/integration/conftest.py (the test infrastructure, hex-test-integration-setup), which
constructs settings with explicit values (test-principles).
When to use vs. neighbours
- What a settings class declares — its namespace, defaults, secrets, derived values, validation →
python-settings. - Binding a new class in the composition root, or choosing its lifetime → this skill.
- The class being wired must already exist — a handler, repository, service, adapter →
hex-application,hex-persistence,hex-store-repository,hex-domain-service,hex-capability-adapter. - A frozen domain-shaped view of settings values the domain consults → the tunable variant in
hex-domain-model; its provider reads the single field off a settings class and passes it. - Attaching the composition root to the HTTP app, running its settings check at startup and closing it at shutdown, which runs every declared teardown →
hex-restapi-app. - Resolving a bound object inside a route →
hex-restapi-endpoint. - The token-verifier port, its adapter and the route dependencies that consume the resolved caller →
hex-restapi-auth. - Substituting a binding for a test →
hex-test-integration-setup. - Which libraries the project carries and the Alembic bootstrap →
hex-project-setup; the ruff and mypy configuration →python-toolchain. Both are laid once, not per binding. - What a settings class, its env prefix or a provider method is called →
naming. - Whether a class may be bound here at all, and which layer it belongs to →
hex-architecture; it owns the layer contract this composition root sits outside of. - The unit-of-work factory binding a multi-repository transaction needs →
hex-persistence(UNIT_OF_WORK.md); the compensating-handler shape →hex-application.
Template — dishka
src/myapp/containers.py is the only file this skill touches. Bindings are grouped into provider classes
by layer and by subdomain; create_container assembles them. Every dependency is resolved by type —
no binding is reached by its attribute name, so renaming a class cannot silently break a call site. The
template is the base a project extends — the provider classes and the handlers — and binds no
store, no optional adapter and no feature. A store's or an add-on's binding lives with what it
binds: the relational engine, session factory and repository in hex-persistence, the HTTP gateway
in hex-capability-adapter, the Redis repository in hex-store-repository, the token verifier in
hex-restapi-auth, the tunable in hex-domain-model, the unit-of-work factory in hex-persistence; a project merges the ones it has.
Read CONTAINER.md in this skill's directory before writing or extending containers.py. It
carries the base composition root — the provider classes in declaration order, create_container and
the settings check an entrypoint runs at start — and how an add-on binding merges into it; only SKILL.md is loaded automatically.
Other bindings
dependency-injector. The obligations are identical; what changes is the spelling and one extra rule. Acontainers.DeclarativeContainersubclass replaces the provider classes,providers.*replace the factories, and — the rule dishka does not need — a binding is reached at the call site by its attribute name, which must be the snake_case form of the class — the call site writes<root>.<snake_case_attribute>(). That name-based contract is unenforced: rename the class and the call site breaks at runtime. Test substitution differs in kind, and its trap ishex-test-integration-setup's.dishka dependency-injector Provider+@provideDeclarativeContainer+providers.*Scope.APPproviders.SingletonScope.REQUESTproviders.Factoryprovides=IFooRepositoryproviders.Provider[IFooRepository]annotationconstructor arguments resolved by annotation each argument passed explicitly generator factory + container.close()providers.Resource, or teardown in the entrypointFromDishka[T]at the call sitecontainer.<snake_case_attribute>()an extra provider with override=True, before the container is built.override()/.reset_override()on a built containerresolve_settingsoverSettingsProvider's declarationseach provider of the settings sub-container, walked with .traverse(), called once at startManual composition — a plain factory module. A service small enough not to want a framework writes
create_container()as a function that constructs each object and returns a frozen dataclass of them. Every rule below still holds; declaration order becomes literal statement order, teardown becomes anAsyncExitStackthe entrypoint closes, and per-operation lifetime becomes a stored factory callable rather than a stored instance. Building such a root constructs its settings, so it is its own startup check, and its construct smoke passes explicit settings rather than reading the environment.
Rules
- Settings are constructed only at a composition root and bound there by type (
python-settingsrule 13) — never in a handler, an adapter, an entrypoint module or another settings class. An adapter receives the whole settings object it reads, by type, as a constructor parameter; nothing below the root reads the environment. - Every settings class the composition root provides is built when the process starts, before it
serves or takes work (
python-settingsrule 13). Under a graph that resolves lazily every entrypoint takes that step once at start — the REST shell in its lifespan (hex-restapi-app), a consumer's launcher before its first message — as a step of its own rather than part of building the root, which a test does with no environment. A root that several entrypoint processes share makes each of them require every settings class it provides, so each is deployed with all of them. - The process's container module is the composition root. Every concrete class is bound to the protocol it satisfies there and only there. Domain and application code never instantiates a concrete type.
- Every binding declares a lifetime, and the choice is deliberate. Nothing is bound without an answer to "how long does this live".
- Anything holding a resource that must be released declares its teardown in the same place as its
construction, so construction and release cannot drift apart. The entrypoint closes the composition
root exactly once, which runs every declared teardown (
hex-restapi-app). - Bindings are reached by type, not by name. A call site names the type it needs; the composition root decides what satisfies it. Nothing outside the composition root may depend on how a binding is spelled.
- A unit of work is bound as its factory callable, never as an instance, so each call opens its own
transaction and no two callers share one.
hex-persistence'sUNIT_OF_WORK.mdshows the form it binds.
Where a settings class sits
- The module a settings class sits in →
hex-conventionsblock A. There is no central settings module. - The prefix's stem names the deployable, never a bounded context.
namingowns the prefix (MYAPP_plus the integration's segment). What only a hexagonal service adds: a deployable serves every context in it, so a context-named stem becomes wrong the moment a second context shares the store — shared settings collapse to one object (hex-conventionsblock C). Working inside one context, that context is the salient name; stem on the deployable anyway.
Lifetimes
| Lifetime | Use for | Examples |
|---|---|---|
| Process | Stateless or expensive-to-construct objects whose lifetime spans the process. | Settings (*Settings), the engine, the session factory, a token verifier, a stateless library-backed adapter, tunable value objects, a stateless factory callable. |
| Per operation | Instances meant to be fresh for each request or each job, cheap to construct. | Every *Handler, every *Repository, domain services that compose them, a stateful adapter bound to per-request state. |
Default to per-operation for application and domain artifacts. Reserve process lifetime for objects that own a connection pool, parse the environment once, or are pure-data configuration.
The pitfall: giving a repository process lifetime looks fine because it is stateless, but it freezes the session factory it was built with for the life of the process, which defeats substituting one for a test and forecloses any future per-request session. Repositories are per-operation.
Declaration order
Group bindings in dependency order and keep them in that order:
- Settings first — everything else may depend on them.
- Long-lived infrastructure — engine, session factory, verifiers.
- Cross-cutting helpers — capability adapters needed by several subdomains.
- Per-subdomain block: repository → services that use it → handlers that use them.
- Cross-subdomain dependencies come first. If subdomain A's repository is consumed by subdomain B's handlers, declare it before B's block.
Where the mechanism evaluates the composition root top to bottom, this ordering is load-bearing — a binding may only reference an earlier one. Where the mechanism resolves by type it is the reading order instead, and a binding that would have to forward-reference is the signal that it is grouped wrong. When adding a binding, find the right section and insert it after the latest declaration it depends on.
Naming and access
- Factory and attribute naming →
naming. These names are internal to the composition root.
Settings lifecycle in the composition root
- Each
*Settingsis process-lifetime, built with no arguments by a factory in the composition root's one settings group. The startup check reads that group, so a settings factory declared anywhere else escapes it; the dishka spelling is inCONTAINER.md. - A tunable value object that needs a single field gets a factory of its own, which reads the field off the settings object and passes it. Never pass raw settings fields around otherwise.
What never goes in the composition root
- No business logic. It only wires.
- No conditionals on the environment. Different environments produce different settings values; the wiring stays the same. Hide a feature flag behind a settings field inside the implementation, never behind a branch in the wiring.
- No imports from
restapi/or another entrypoint. The composition root sits below the entrypoint layer. - No mutable module-level state.
create_containerreturns a new composition root per call; a module-level singleton makes the test seam unreachable. - No instantiation of concrete domain types — entities, value objects. It builds services, not data.
Inlined typing / import rules
Settings field typing and imports →
python-settings.A factory's return annotation is the binding's type, and it is the whole contract:
-> PostgresSettingsbindsPostgresSettings,-> AsyncIterator[AsyncEngine]bindsAsyncEnginewith a teardown. Useprovides=<Protocol>when the class-attribute form binds an adapter to its port. An unannotated or loosely annotated factory binds the wrong type or fails at container construction, not at the call site.Import each class from the package that DIRECTLY re-exports it — one
from .module import *hop — never a grandparent (python-packaging). This bites the nested infrastructure layout: a repository class lives ininfrastructure/<store>/repositories/<x>.py, so import it from therepositoriessubpackage —from myapp.infrastructure.postgres.repositories import FooRepository— not from the<store>technology package. The technology-package form resolves at runtime but mypy reports[attr-defined], because the intermediaterepositories/__init__.pyhas a computed__all__mypy cannot evaluate across thefrom .repositories import *hop. A class sitting directly under the technology package — theengineorsettingsmodule, a capability adapter — is one hop away, so importing it from the technology package is correct.No
from __future__ import annotations(python-style).
Package wiring
Composition-root location → hex-architecture.
containers.py needs no package wiring at all: it is src/myapp/containers.py, a module of the
distribution's root package, and the root __init__.py does not re-export it — that file stays empty
(python-packaging's carve-out for an application's root). For the classes it imports, follow
python-packaging.
Hard stops
- Asked for an environment read, a new settings field, or a default on one → stop, use
python-settings. - Asked to add a binding whose dependency is not yet declared → stop, that dependency's own skill runs first.
- The composition root is asked to bind a store connection or transaction handle per operation, so a
repository can be injected with one outside a unit of work → stop, nothing would then own the commit;
use the standalone repository form, which opens and owns its own (
hex-persistencefor a relational store,hex-store-repositoryfor a client-style one), or a unit of work (hex-persistence). A store whose client is the connection and has nothing to commit is bound at process lifetime, not per operation.