Tutorial (runnable examples)

All examples below are self-contained scripts. You can:

• run most of them in your browser (click Run in the top-right of a code block)

• copy a block into a local .py file and run it with python

The FastAPI examples are the main exception: they are not runnable in the browser.

Follow this path (easy -> hard)

This tutorial is intentionally example-first. If you want the full mental model, use Core concepts alongside the examples.

1. Basics (registration, lifetimes, constructor injection)

2. Scopes (SCOPED, generator cleanup, nested scopes)

3. Function injection (Injected marker)

4. Components (multiple implementations by name)

5. Patterns (request handlers, repositories, interfaces)

6. Async

7. FastAPI

8. Errors (what failures look like)

• Basics
  • Registration methods
  • Lifetimes (TRANSIENT vs SINGLETON)
  • Constructor injection (auto-wiring)
  • Decorator registration
  • Open generics
  • Compilation
  • Read more
• Scopes
  • Scope basics
  • SCOPED lifetime (shared per scope)
  • Nested scopes
  • Generator factories (cleanup on scope exit)
  • Read more
• Function injection
  • Injected marker (Annotated[T, Injected()])
  • Injected wrapper behavior
  • Per-call scope (ScopedInjected)
  • Read more
• Components
  • Named components
  • Read more
• Patterns
  • HTTP request handler pattern (per-request scope)
  • Repository / unit-of-work pattern
  • Class methods with container_context
  • Interface registration (Protocol/ABC -> concrete_class)
  • Read more
• Async
  • Basic async factory
  • Async generator cleanup
  • Async injected functions
  • Async scoped injection
  • Mixed sync/async + parallel resolution
  • Async error handling
  • Web frameworks
  • Read more
• FastAPI
  • Basic integration
  • Decorator-based layering
  • container_context + middleware-managed request context
  • Read more
• Errors
  • Circular dependencies
  • Missing dependencies
  • Scope mismatch
  • Scoped resolved outside scope (auto-register safety)
  • Read more