How to Use These Docs

Choose your path based on what you want to accomplish.

“I want to try dioxide quickly”

Time: 15 minutes

Get dioxide running with a minimal example to understand the core concepts.

  1. Getting Started - Install and build your first container

  2. Choosing Between @service and @adapter - Which decorator: @service or @adapter? (decision tree)

  3. Tutorial 1: Basic Dependency Injection - See a complete working example

  4. Tutorial 2: Email Service with Profiles - Understand profile switching

“I’m evaluating dioxide for my project”

Time: 30 minutes

Understand what dioxide offers and whether it fits your needs.

  1. Why dioxide? - Philosophy, feature comparison, and honest limitations

  2. Hexagonal Architecture with dioxide - How dioxide maps to ports-and-adapters

  3. Package Scanning - How scanning works, side effects, and best practices

  4. Dioxide Testing Guide: Fakes Over Mocks - Testing philosophy (fakes over mocks)

  5. Migrating from dependency-injector - Coming from another DI framework?

“I’m integrating with a web framework”

Time: 20 minutes

Get dioxide working with your framework of choice.

FastAPI

  1. FastAPI Integration - Lifespan, dependency injection, and testing endpoints

  2. Tutorial 4: Lifecycle Management - Async startup/shutdown patterns

  3. Lifecycle Methods: Async/Sync Patterns - Understanding async lifecycle with sync resolution

Django

  1. Django and Django REST Framework Integration - Django-specific integration guide

Other Frameworks

  1. Getting Started - Core container patterns work everywhere

  2. Scoping Guide - Request scoping for web applications

  3. Lifecycle Methods: Async/Sync Patterns - Async lifecycle in sync frameworks (Flask, Django)

“I want to understand the testing philosophy”

Time: 45 minutes

Learn why dioxide prefers fakes over mocks and how to test effectively.

  1. Dioxide Testing Guide: Fakes Over Mocks - Comprehensive testing philosophy and patterns

  2. Testing with Fakes - Practical testing techniques

  3. Testing Patterns - Copy-paste test fixtures and patterns

  4. Migration from Mocks to Fakes - Transitioning from mock-heavy tests

“I need the API reference”

Jump directly to the technical documentation.

  • API Reference - Auto-generated API documentation for all public classes and functions

“I want practical recipes”

Browse the cookbook for copy-paste solutions to common problems.

Learning Path Recommendations

Your Background

Recommended Path

New to DI

Quick start, then examples 1-4 in order

Using dependency-injector

Why dioxide, then migration guide

Familiar with hexagonal architecture

Hexagonal architecture guide, then testing

Mock-heavy test suite

Testing philosophy, then migration from mocks

FastAPI developer

FastAPI cookbook, then lifecycle async patterns

Flask/Django developer

Lifecycle async patterns, then cookbook

Confused about decorators

Choosing Between @service and @adapter - visual decision tree