dioxide 0.1.0__cp311-abi3-macosx_11_0_arm64.whl

dioxide/__init__.py

@@ -0,0 +1,14 @@
+"""dioxide: Fast, Rust-backed declarative dependency injection for Python."""
+
+from .container import Container
+from .decorators import _clear_registry, _get_registered_components, component
+from .scope import Scope
+
+__version__ = '0.1.0'
+__all__ = [
+    'Container',
+    'Scope',
+    '_clear_registry',
+    '_get_registered_components',
+    'component',
+]

dioxide/_rivet_core.pyi

@@ -0,0 +1,17 @@
+"""Type stubs for Rust core module."""
+
+from collections.abc import Callable
+from typing import TypeVar
+
+T = TypeVar('T')
+
+class Container:
+    """Rust-backed container implementation."""
+
+    def __init__(self) -> None: ...
+    def register_instance(self, py_type: type[T], instance: T) -> None: ...
+    def register_class(self, py_type: type[T], implementation: type[T]) -> None: ...
+    def register_factory(self, py_type: type[T], factory: Callable[[], T]) -> None: ...
+    def resolve(self, py_type: type[T]) -> T: ...
+    def is_empty(self) -> bool: ...
+    def __len__(self) -> int: ...

dioxide/container.py

@@ -0,0 +1,171 @@
+"""Dependency injection container."""
+
+import inspect
+from collections.abc import Callable
+from typing import Any, TypeVar, get_type_hints
+
+from dioxide._dioxide_core import Container as RustContainer
+
+T = TypeVar('T')
+
+
+class Container:
+    """
+    Dependency injection container.
+
+    The container builds a dependency graph from registered components
+    and resolves dependencies using the Rust-backed core.
+    """
+
+    def __init__(self) -> None:
+        """Initialize the container."""
+        self._rust_core = RustContainer()
+
+    def register_instance(self, component_type: type[T], instance: T) -> None:
+        """
+        Register a pre-created instance for a given type.
+
+        Args:
+            component_type: Type to register
+            instance: Pre-created instance to return for this type
+
+        Raises:
+            KeyError: If type is already registered
+        """
+        self._rust_core.register_instance(component_type, instance)
+
+    def register_class(self, component_type: type[T], implementation: type[T]) -> None:
+        """
+        Register a class to instantiate for a given type.
+
+        Args:
+            component_type: Type to register
+            implementation: Class to instantiate (calls __init__ with no args)
+
+        Raises:
+            KeyError: If type is already registered
+        """
+        self._rust_core.register_class(component_type, implementation)
+
+    def register_factory(self, component_type: type[T], factory: Callable[[], T]) -> None:
+        """
+        Register a factory function for a given type.
+
+        Args:
+            component_type: Type to register
+            factory: Callable that returns an instance (called with no args)
+
+        Raises:
+            KeyError: If type is already registered
+        """
+        self._rust_core.register_factory(component_type, factory)
+
+    def resolve(self, component_type: type[T]) -> T:
+        """
+        Resolve a component instance.
+
+        Args:
+            component_type: Type to resolve
+
+        Returns:
+            Instance of the requested type
+
+        Raises:
+            KeyError: If type is not registered
+        """
+        return self._rust_core.resolve(component_type)
+
+    def is_empty(self) -> bool:
+        """
+        Check if container has no registered providers.
+
+        Returns:
+            True if container is empty, False otherwise
+        """
+        return self._rust_core.is_empty()
+
+    def __len__(self) -> int:
+        """
+        Get count of registered providers.
+
+        Returns:
+            Number of registered providers
+        """
+        return len(self._rust_core)
+
+    def scan(self) -> None:
+        """
+        Discover and register all @component decorated classes.
+
+        This method finds all classes marked with the @component decorator
+        and registers them with the container, automatically setting up
+        dependency injection based on type hints.
+
+        Components are registered as singletons by default.
+        """
+        from dioxide.decorators import _get_registered_components
+        from dioxide.scope import Scope
+
+        for component_class in _get_registered_components():
+            # Create a factory that auto-injects dependencies
+            factory = self._create_auto_injecting_factory(component_class)
+
+            # Check the scope
+            scope = getattr(component_class, '__rivet_scope__', Scope.SINGLETON)
+
+            if scope == Scope.SINGLETON:
+                # Wrap the factory in a singleton wrapper
+                singleton_factory = self._create_singleton_factory(factory)
+                self.register_factory(component_class, singleton_factory)
+            else:
+                # For non-singletons, just register the factory
+                self.register_factory(component_class, factory)
+
+    def _create_singleton_factory(self, factory: Callable[[], T]) -> Callable[[], T]:
+        """
+        Wrap a factory function to return the same instance each time.
+
+        Args:
+            factory: The factory function to wrap
+
+        Returns:
+            A factory that caches the first instance and returns it on subsequent calls
+        """
+        instance_holder: list[T] = []  # Use list to avoid closure issues
+
+        def singleton_wrapper() -> T:
+            if not instance_holder:
+                instance_holder.append(factory())
+            return instance_holder[0]
+
+        return singleton_wrapper
+
+    def _create_auto_injecting_factory(self, cls: type[T]) -> Callable[[], T]:
+        """
+        Create a factory function that auto-injects dependencies from type hints.
+
+        Args:
+            cls: The class to create a factory for
+
+        Returns:
+            A factory function that resolves dependencies and instantiates the class
+        """
+        try:
+            init_signature = inspect.signature(cls.__init__)
+            type_hints = get_type_hints(cls.__init__)
+        except (ValueError, AttributeError):
+            # No __init__ or no type hints - just instantiate directly
+            return cls
+
+        # Build factory that resolves dependencies
+        def factory() -> T:
+            kwargs: dict[str, Any] = {}
+            for param_name in init_signature.parameters:
+                if param_name == 'self':
+                    continue
+                if param_name in type_hints:
+                    dependency_type = type_hints[param_name]
+                    kwargs[param_name] = self.resolve(dependency_type)
+            return cls(**kwargs)
+
+        return factory

dioxide/decorators.py

@@ -0,0 +1,61 @@
+"""Decorator for marking classes as DI components."""
+
+from typing import Any, TypeVar
+
+from dioxide.scope import Scope
+
+T = TypeVar('T')
+
+# Global registry for @component decorated classes
+_component_registry: set[type[Any]] = set()
+
+
+def component(
+    cls: type[T] | None = None,
+    *,
+    scope: Scope = Scope.SINGLETON,
+) -> type[T] | Any:
+    """
+    Mark a class as a dependency injection component.
+
+    Can be used with or without arguments:
+        @component
+        class Service:
+            pass
+
+        @component(scope=Scope.FACTORY)
+        class Factory:
+            pass
+
+    Args:
+        cls: The class being decorated (when used without parentheses)
+        scope: Lifecycle scope (SINGLETON or FACTORY), defaults to SINGLETON
+
+    Returns:
+        Decorated class with DI metadata
+    """
+
+    def decorator(target_cls: type[T]) -> type[T]:
+        # Store DI metadata on the class
+        target_cls.__rivet_scope__ = scope  # type: ignore[attr-defined]
+        # Add to global registry for auto-discovery
+        _component_registry.add(target_cls)
+        return target_cls
+
+    # Support both @component and @component()
+    if cls is None:
+        # Called with arguments: @component(scope=...)
+        return decorator
+    else:
+        # Called without arguments: @component
+        return decorator(cls)
+
+
+def _get_registered_components() -> set[type[Any]]:
+    """Internal: Get all registered component classes."""
+    return _component_registry.copy()
+
+
+def _clear_registry() -> None:
+    """Internal: Clear the component registry (for testing)."""
+    _component_registry.clear()

dioxide/scope.py

@@ -0,0 +1,10 @@
+"""Dependency injection scopes."""
+
+from enum import Enum
+
+
+class Scope(str, Enum):
+    """Component lifecycle scope."""
+
+    SINGLETON = 'singleton'
+    FACTORY = 'factory'

dioxide-0.1.0.dist-info/METADATA

@@ -0,0 +1,243 @@
+Metadata-Version: 2.4
+Name: dioxide
+Version: 0.1.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Rust
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Dist: pytest>=8.0 ; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1 ; extra == 'dev'
+Requires-Dist: behave>=1.2.6 ; extra == 'dev'
+Requires-Dist: mypy>=1.8 ; extra == 'dev'
+Requires-Dist: ruff>=0.1 ; extra == 'dev'
+Requires-Dist: isort>=5.13 ; extra == 'dev'
+Requires-Dist: tox>=4.0 ; extra == 'dev'
+Requires-Dist: pre-commit>=3.0 ; extra == 'dev'
+Requires-Dist: mutmut>=2.4 ; extra == 'dev'
+Provides-Extra: dev
+License-File: LICENSE
+Summary: Fast, Rust-backed declarative dependency injection for Python
+Keywords: dependency-injection,di,ioc,rust,container
+Author-email: Mike Lane <mikelane@gmail.com>
+License: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Homepage, https://github.com/mikelane/dioxide
+Project-URL: Repository, https://github.com/mikelane/dioxide
+Project-URL: Issues, https://github.com/mikelane/dioxide/issues
+
+# dioxide
+
+**Fast, Rust-backed declarative dependency injection for Python**
+
+[![CI](https://github.com/mikelane/dioxide/workflows/CI/badge.svg)](https://github.com/mikelane/dioxide/actions)
+[![Python Version](https://img.shields.io/pypi/pyversions/dioxide)](https://pypi.org/project/dioxide/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## Overview
+
+`dioxide` is a dependency injection framework for Python that combines:
+
+- **Declarative Python API** - Simple decorators and type hints
+- **Rust-backed performance** - Fast graph construction and resolution via PyO3
+- **Type safety** - Full support for mypy and type checkers
+- **Clean architecture** - Encourages loose coupling and testability
+
+## Status
+
+🚧 **Work in Progress** - Currently implementing the v0.1 Walking Skeleton.
+
+See [Issues](https://github.com/mikelane/dioxide/issues) and [Milestones](https://github.com/mikelane/dioxide/milestones) for current progress.
+
+## Vision
+
+Traditional Python DI frameworks like `dependency-injector` are feature-rich but can be slow with large dependency graphs. `dioxide` aims to provide:
+
+1. **Fast graph construction** using Rust's `petgraph`
+2. **Type-based resolution** via Python's `__annotations__`
+3. **Lifecycle management** with proper shutdown ordering
+4. **Clear error messages** for missing dependencies and cycles
+
+## Quick Start (Planned API)
+
+```python
+from dioxide import Container, Scope, component
+
+@component(scope=Scope.SINGLETON)
+class DatabaseConnection:
+    def __init__(self, connection_string: str):
+        self.connection_string = connection_string
+
+@component(scope=Scope.SINGLETON)
+class UserRepository:
+    def __init__(self, db: DatabaseConnection):
+        self.db = db
+
+# Create container and register components
+container = Container()
+container.register_value('connection_string', 'postgresql://localhost/mydb')
+container.register(DatabaseConnection)
+container.register(UserRepository)
+
+# Resolve dependencies
+repo = container.resolve(UserRepository)
+# repo.db is automatically injected
+
+# Clean shutdown
+container.shutdown()
+```
+
+## Features
+
+### v0.1 Walking Skeleton (In Progress)
+- [x] Basic project structure
+- [ ] Type-based dependency resolution
+- [ ] Singleton and factory scopes
+- [ ] Value injection by parameter name
+- [ ] Duplicate registration prevention
+- [ ] Clear error messages
+
+### v0.2 Core Features (Planned)
+- [ ] Named tokens for disambiguation
+- [ ] Circular dependency detection
+- [ ] Graceful shutdown with reverse ordering
+- [ ] Comprehensive test coverage (>95%)
+- [ ] Mutation testing with `mutmut`
+
+### Future Enhancements (Backlog)
+- [ ] Conditional registration
+- [ ] Provider functions
+- [ ] Property injection
+- [ ] Performance benchmarks vs. `dependency-injector`
+- [ ] Documentation site
+
+## Development
+
+### Prerequisites
+
+- Python 3.11+
+- Rust 1.70+
+- [uv](https://github.com/astral-sh/uv) for Python package management
+- [maturin](https://github.com/PyO3/maturin) for building Rust extensions
+
+### Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/mikelane/dioxide.git
+cd dioxide
+
+# Install dependencies with uv
+uv venv
+source .venv/bin/activate  # or `.venv\Scripts\activate` on Windows
+uv pip install -e ".[dev]"
+
+# Build the Rust extension
+maturin develop
+
+# Run tests
+pytest
+
+# Run all quality checks
+tox
+```
+
+### Development Workflow
+
+```bash
+# Format code
+tox -e format
+
+# Lint
+tox -e lint
+
+# Type check
+tox -e type
+
+# Run tests for all Python versions
+tox
+
+# Run tests with coverage
+tox -e cov
+
+# Mutation testing
+tox -e mutate
+```
+
+### Pre-commit Hooks
+
+Install pre-commit hooks to ensure code quality:
+
+```bash
+pre-commit install
+```
+
+## Architecture
+
+```
+dioxide/
+├── python/dioxide/       # Python API
+│   ├── __init__.py
+│   ├── container.py       # Main Container class
+│   ├── decorators.py      # @component decorator
+│   └── scope.py           # Scope enum
+├── rust/src/              # Rust core
+│   └── lib.rs             # PyO3 bindings and graph logic
+├── tests/                 # Python tests
+└── pyproject.toml         # Project configuration
+```
+
+### Key Design Decisions
+
+1. **Rust for graph operations** - Dependency graphs can get complex; Rust's performance and safety help scale
+2. **Python-first API** - Developers work in pure Python; Rust is an implementation detail
+3. **Type hints as the contract** - Leverage Python's type system for DI metadata
+4. **Explicit over implicit** - Registration is manual to avoid surprises
+5. **Test-driven development** - Every feature starts with failing tests
+
+## Comparison to Other Frameworks
+
+| Feature | dioxide | dependency-injector | injector |
+|---------|----------|---------------------|----------|
+| Type-based DI | ✅ | ✅ | ✅ |
+| Rust-backed | ✅ | ❌ | ❌ |
+| Scopes | ✅ | ✅ | ✅ |
+| Lifecycle | ✅ | ✅ | ❌ |
+| Cycle detection | ✅ (planned) | ❌ | ❌ |
+| Performance* | 🚀 (goal) | ⚡ | ⚡ |
+
+*Benchmarks coming in v0.2
+
+## Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+### Roadmap
+
+- v0.1: Walking skeleton with basic DI
+- v0.2: Production-ready core features
+- v0.3: Performance optimization and benchmarks
+- v1.0: Stable API
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Acknowledgments
+
+- Inspired by [dependency-injector](https://github.com/ets-labs/python-dependency-injector) and Spring Framework
+- Built with [PyO3](https://github.com/PyO3/pyo3) and [maturin](https://github.com/PyO3/maturin)
+- Graph algorithms powered by [petgraph](https://github.com/petgraph/petgraph)
+
+---
+
+**Note**: This project is under active development. APIs may change before v1.0.
+

dioxide-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+dioxide-0.1.0.dist-info/METADATA,sha256=udsDz2a8K_cgarNh_Txl_u1jm_wiU_xXf-K258wPctI,7212
+dioxide-0.1.0.dist-info/WHEEL,sha256=kelVgS1CONjYuT6OEIC92ofaP9Aiw74EQCpLzMjs2Gg,103
+dioxide-0.1.0.dist-info/licenses/LICENSE,sha256=JpEmJvRYOTIUt0UjgvpDrd3U94Wnbt_Grr5z-xU2jtk,1066
+dioxide/__init__.py,sha256=YULuPVqRmnBmFFRx9vMM7MAV4LKJmertLobbhFc7utA,357
+dioxide/_dioxide_core.abi3.so,sha256=treUgOU1PvwrtEHBdMRNz-wsk6DOvnEwYsjbdHA4Nd0,472912
+dioxide/_rivet_core.pyi,sha256=duJvzENpwRtl9HZIjLYrVIbCkMZscCKeVvIgEaAgnQk,594
+dioxide/container.py,sha256=dU3d0nhjiHTPT08z0kYkNujEcLq2WvO9-Gqjdzr8xh0,5549
+dioxide/decorators.py,sha256=EAxMn_HbudrH6V1bREb-dFOzkcRMBK9MlLPww9uALT4,1616
+dioxide/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dioxide/scope.py,sha256=C6pAAVwNu04CSwUyIphCwOlec9DPAMWT8Q4Js48HGkE,174
+dioxide-0.1.0.dist-info/RECORD,,

dioxide-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: maturin (1.9.6)
+Root-Is-Purelib: false
+Tag: cp311-abi3-macosx_11_0_arm64

dioxide-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Mike Lane
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.