version: "1.0.0" name: specx-diwire-composition description: Wire dependency injection for a specx Python service with diwire. Use when adding ioc/container.py, explicit dependency registrations for capabilities, repositories, gateways, UoW managers, clients, settings, or factories, Injected[...] constructor fields, FastAPI app factory/lifecycle composition, test overrides, or rules that keep containers out of core use cases and services.

specx Diwire Composition

Use this skill whenever object graphs, factories, controllers, adapters, or test overrides need diwire. Read references/diwire.md before writing DI code.

Rules

• Application classes receive dependencies through constructor fields typed as

Injected[DependencyType].

• Keep injection constructor-based. Do not hide dependency resolution in

application functions with resolver_context.inject.

• Capabilities are normal injectable collaborators. Register only capability

abstractions or existing instances that auto-wiring cannot infer.

• Only ioc/, top-level delivery __main__.py/factory/lifecycle modules, and

tests create or use diwire.Container.

• Do not inject Container except in FastAPILifecycle, where it is used only

to call container.aclose() during app shutdown.

• Do not inject logging.Logger or register loggers in the container. Runtime

logging is configured once by a top-level infrastructure configurator; classes that log create local stdlib loggers.

• Do not call container.resolve() inside core use cases or services.
• Let diwire auto-wire concrete project classes.
• Let diwire auto-register BaseRuntimeSettings subclasses as root-scoped

singleton factories. Register a settings instance only for an intentional test override or an explicitly prebuilt configuration object.

• Register only abstractions, external adapter bindings, gateway

implementations, factories, and instances that auto-wiring cannot infer. Keep registration in private _register_dependencies(...) inside ioc/container.py.

• Register the container instance itself with provides=Container only for the

FastAPI lifecycle shutdown dependency.

• Register concrete gateway implementations for their core BaseGateway ports.
• Register health readiness gateway implementations, such as

SQLAlchemyReadinessCheckGateway, for ReadinessCheckGateway when /readyz needs infrastructure checks.

• Register unit-of-work managers for UoW abstractions. Persistence use cases

inject the manager and open the active UoW inside execute(...); they do not inject repositories, active UoWs, providers, SQLAlchemy sessions, engines, session factories, or concrete infrastructure adapters directly.

• Unit tests receive a fresh native pytest container fixture built by the

project's real get_container(). Put project-wide test overrides in that fixture and register scenario-specific overrides directly in the test before resolving the target.

• Integration tests receive the transactional real-app container fixture.

They must use the real internal graph; do not mock internal use cases, services, or capabilities.

• Use container.resolve(...) for normal synchronous graph construction, even

for targets with async methods; use await container.aresolve(...) only when DI construction itself has async providers.

• One-off class-based test doubles live in the test_*.py module that uses

them. Reused unit-test doubles may live in mirrored tests/unit/core/<scope>/{capabilities,gateways,repositories}/fake_<source_module>.py modules.

• Inline MagicMock or AsyncMock in the test function when only one behavior

needs to change.

• Do not create DI-backed test factories, target harnesses, harness.py,

tests/_support/fakes, tests/**/_fakes.py, or fake modules outside those mirrored unit port/capability packages.

• Keep tests on native pytest fixtures. Do not enable

diwire.integrations.pytest_plugin, and do not use Injected[...] parameters in test functions.

• FastAPI async test helpers must enter LifespanManager and pass the yielded

manager's state-aware manager.app to the HTTPX2 ASGITransport.

Code Style

Use blank lines as logical separators in all code. Keep related statements together, but separate independent setup, action, assertion, response, branch, and transformation groups so long blocks stay readable.

References

• references/diwire.md - container code, registration examples, controller

composition, and test override patterns.