dioxide

dioxide is a fast and efficient dependency injection framework for Python that integrates Rust's performance and a declarative approach for defining dependencies. This framework enables developers to write cleaner and more maintainable code while adhering to the Dependency Inversion Principle. The key features include:

• Declarative Python API: Utilize simple decorators and type hints to define your dependencies clearly.
• Rust-backed Performance: Significant speed improvements for graph construction and resolution through PyO3.
• Type Safety: Full support for type checkers like mypy ensures correctness during development.
• Clean Architecture: Promotes loose coupling and enhances testability.

Overview

Key Features

• Type-safe Dependency Injection: Ensures that the wiring of components is correct if mypy passes.
• Profile-based Implementations: Easily switch between different implementations (e.g., swap between PostgreSQL and in-memory database) with minimal changes.
• Testing without Mocks: Facilitates fast fakes at the seams instead of mock behavior, streamlining the testing process.
• Lifecycle Management: Controlled initialization and cleanup of services and adapters to manage resource usage effectively.

Quick Start

Dioxide employs a hexagonal architecture to facilitate clean and testable code through a straightforward implementation process. A typical usage example is:

from typing import Protocol
from dioxide import Container, Profile, adapter, service

# Define a protocol for email sending
class EmailPort(Protocol):
    async def send(self, to: str, subject: str, body: str) -> None: ...

# Create an adapter for production environment
@adapter.for_(EmailPort, profile=Profile.PRODUCTION)
class SendGridAdapter:
    async def send(self, to: str, subject: str, body: str) -> None:
        print(f"📧 Sending via SendGrid to {to}: {subject}")

# Service that uses the EmailPort
@service
class UserService:
    def __init__(self, email: EmailPort):
        self.email = email

    async def register_user(self, email_addr: str, name: str):
        await self.email.send(
            to=email_addr,
            subject="Welcome!",
            body=f"Hello {name}, thanks for signing up!"
        )

# Using the container to resolve dependencies
container = Container()
container.scan(profile=Profile.PRODUCTION)
user_service = container.resolve(UserService)
await user_service.register_user("user@example.com", "Alice")

Environment Support

Dioxide supports multiple platforms and Python versions across:

• Linux, macOS (M1/M2/M3), and Windows.
• Compatible with Python versions 3.11, 3.12, and up.

Lifecycle Management

Dioxide also provides lifecycle management capabilities for components that require initialization and cleanup. The @lifecycle decorator allows efficient management of component lifetimes, ensuring a structured approach to setting up and tearing down resources.

Function Injection

The framework supports function injection for flexibility, enabling dependency injection into standalone functions, making it ideal for web frameworks like FastAPI and background job systems.

Stability and Future Plans

dioxide is marked as stable, with the current API frozen to prevent breaking changes until v2.0. Future features will enhance the framework's capabilities, including request scoping and property injection.

For detailed insights into the architecture and other advanced usage patterns, please refer to the comprehensive documentation available within the repository.