Cookbook¶

Practical, copy-paste-ready recipes for common dioxide patterns.

This cookbook provides working code examples for real-world scenarios. Each recipe follows a consistent format:

Quick Links¶

FastAPI Integration

Routes, dependency injection, lifecycle management, and testing endpoints.

Testing Patterns

Fixtures, fakes, test isolation, and async testing patterns.

Configuration

Pydantic Settings integration and environment-specific config.

Database Patterns

SQLAlchemy adapters, repository pattern, and transaction handling.

Library Authors

Make your library dioxide-compatible without depending on dioxide.

Recipe	Description
Basic Setup	Container + lifespan integration
Dependency Injection	Using `Depends()` with dioxide
Testing Endpoints	TestClient with fakes
Middleware Integration	Access container in middleware

Recipe	Description
Container Fixture	Fresh container per test
Typed Fake Access	IDE-friendly fixture typing
Async Testing	pytest-asyncio patterns
Error Injection	Configurable fake failures
Time Control	Fake clock for time-dependent tests

Recipe	Description
Pydantic Settings	Type-safe config with validation
Profile-Based Config	Different settings per environment
Secrets Management	Secure secret handling
Config Validation	Fail fast on missing config

Recipe	Description
SQLAlchemy Adapter	Async SQLAlchemy with lifecycle
Repository Pattern	Clean data access abstraction
In-Memory Fake	Fast fake for testing
Transaction Handling	Commit/rollback patterns

Recipe	Description
dioxide-Compatible Libraries	Optional DI with sensible defaults

These recipes follow dioxide’s core principles: