Dependency Injection

Execution Workflow

1. Choose the contract to inject first: settings object, service, repository, session, current user, or request-derived value.
2. Pick the narrowest scope that should own it: app, router, controller, or handler.
3. Implement the provider as a callable wrapped in Provide, choosing async, sync, or generator form based on lifecycle needs.
4. Keep the dependency key identical to the injected parameter name.
5. Use overrides intentionally at lower scopes and in tests.
6. Mark special cases with Dependency(...) when validation, defaults, or OpenAPI behavior need to be explicit.
7. Verify cleanup behavior for generator dependencies and startup-time failure for missing explicit dependencies.

Core Rules

• Register dependencies at the narrowest scope that matches their reuse boundary.
• Keep dependency keys stable and descriptive: settings, db_session, current_user, tenant, clock.
• Keep injected annotations runtime-importable. Avoid hiding injected types behind TYPE_CHECKING unless you also provide a working runtime signature namespace.
• Accept keyword arguments and self in providers, never positional-only runtime arguments.
• Match the provider key and the consumer parameter name exactly.