dioxide 0.0.2a1__cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

dioxide/decorators.py

@@ -0,0 +1,249 @@
+"""Decorator for marking classes as DI components.
+
+The @component decorator enables automatic discovery and registration of
+classes with the dependency injection container. Decorated classes are
+found by Container.scan() and registered with their specified lifecycle
+scope (SINGLETON or FACTORY).
+"""
+
+from typing import TYPE_CHECKING, Any, TypeVar, overload
+
+from dioxide.scope import Scope
+
+T = TypeVar('T')
+
+# Global registry for @component decorated classes
+_component_registry: set[type[Any]] = set()
+
+
+@overload
+def component(cls: type[T]) -> type[T]: ...
+
+
+@overload
+def component(
+    cls: None = None,
+    *,
+    scope: Scope = Scope.SINGLETON,
+) -> Any: ...
+
+
+def component(
+    cls: type[T] | None = None,
+    *,
+    scope: Scope = Scope.SINGLETON,
+) -> type[T] | Any:
+    """Mark a class as a dependency injection component.
+
+    This decorator enables automatic discovery and registration with the
+    Container. When Container.scan() is called, all @component decorated
+    classes are registered with their dependencies automatically resolved
+    based on constructor type hints.
+
+    The decorator can be used with or without parentheses:
+
+    Usage:
+        Basic usage with default SINGLETON scope:
+            >>> from dioxide import component, Container
+            >>>
+            >>> @component
+            ... class Database:
+            ...     def connect(self):
+            ...         return 'Connected'
+
+        With explicit SINGLETON scope:
+            >>> from dioxide import component, Scope
+            >>>
+            >>> @component(scope=Scope.SINGLETON)
+            ... class ConfigService:
+            ...     def __init__(self):
+            ...         self.settings = {'debug': True}
+
+        With FACTORY scope for per-request instances (old syntax):
+            >>> @component(scope=Scope.FACTORY)
+            ... class RequestHandler:
+            ...     def __init__(self):
+            ...         self.request_id = id(self)
+
+        With FACTORY scope (MLP attribute syntax):
+            >>> @component.factory
+            ... class RequestHandler:
+            ...     def __init__(self):
+            ...         self.request_id = id(self)
+
+        With constructor-based dependency injection:
+            >>> @component
+            ... class UserService:
+            ...     def __init__(self, db: Database):
+            ...         self.db = db
+
+        Auto-discovery and resolution:
+            >>> container = Container()
+            >>> container.scan()  # Discovers all @component classes
+            >>> service = container.resolve(UserService)
+            >>> assert isinstance(service.db, Database)
+
+    Args:
+        cls: The class being decorated (provided when used without parentheses).
+        scope: Lifecycle scope controlling instance creation and caching.
+            Defaults to Scope.SINGLETON. Use Scope.FACTORY for new instances
+            on each resolve() call.
+
+    Returns:
+        The decorated class with dioxide metadata attached. The class can be
+        used normally and will be discovered by Container.scan().
+
+    Note:
+        - Dependencies are resolved from constructor (__init__) type hints
+        - Classes without __init__ or without type hints are supported
+        - The decorator does not modify class behavior, only adds metadata
+        - Manual registration takes precedence over decorator-based registration
+    """
+
+    def decorator(target_cls: type[T]) -> type[T]:
+        # Store DI metadata on the class
+        target_cls.__dioxide_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)
+
+
+# Add factory attribute for MLP API: @component.factory
+def _factory_decorator(cls: type[T]) -> type[T]:
+    """Factory scope decorator for @component.factory syntax.
+
+    This is the MLP API for creating factory-scoped components.
+    Equivalent to @component(scope=Scope.FACTORY) but more ergonomic.
+
+    Usage:
+        >>> @component.factory
+        ... class RequestHandler:
+        ...     pass
+    """
+    # Store DI metadata on the class
+    cls.__dioxide_scope__ = Scope.FACTORY  # type: ignore[attr-defined]
+    # Add to global registry for auto-discovery
+    _component_registry.add(cls)
+    return cls
+
+
+# Attach factory attribute to component function
+component.factory = _factory_decorator  # type: ignore[attr-defined]
+
+# Expose type annotation for static type checkers
+if TYPE_CHECKING:
+    # Annotate component.factory for mypy
+    component.factory = _factory_decorator  # type: ignore[attr-defined]
+
+
+def _get_registered_components() -> set[type[Any]]:
+    """Get all registered component classes.
+
+    Internal function used by Container.scan() to discover @component
+    decorated classes. Returns a copy of the registry to prevent
+    external modification.
+
+    Returns:
+        Set of all classes that have been decorated with @component.
+
+    Note:
+        This is an internal API primarily for testing. Users should
+        rely on Container.scan() for component discovery.
+    """
+    return _component_registry.copy()
+
+
+def _clear_registry() -> None:
+    """Clear the component registry.
+
+    Internal function used in test cleanup to reset the global registry
+    state between tests. Should not be used in production code.
+
+    Note:
+        This is an internal testing API. Clearing the registry does not
+        affect already-configured Container instances.
+    """
+    _component_registry.clear()
+
+
+def implements(
+    protocol_class: type[Any],
+    *,
+    scope: Scope = Scope.SINGLETON,
+) -> Any:
+    """Mark a class as implementing a protocol.
+
+    This decorator marks a concrete class as an implementation of a protocol,
+    enabling protocol-based dependency resolution. The container will register
+    the implementation so it can be resolved by the protocol type.
+
+    Usage:
+        Protocol implementation:
+            >>> from typing import Protocol
+            >>> from dioxide import component
+            >>>
+            >>> class EmailProvider(Protocol):
+            ...     async def send(self, to: str, subject: str, body: str) -> None: ...
+            >>>
+            >>> @component.implements(EmailProvider)
+            ... class SendGridEmail:
+            ...     async def send(self, to: str, subject: str, body: str) -> None:
+            ...         pass  # Implementation
+
+        Multiple implementations with profiles:
+            >>> from dioxide import profile
+            >>>
+            >>> @component.implements(EmailProvider)
+            >>> @profile.production
+            ... class SendGridEmail:
+            ...     async def send(self, to: str, subject: str, body: str) -> None:
+            ...         pass  # Real implementation
+            >>>
+            >>> @component.implements(EmailProvider)
+            >>> @profile.test
+            ... class InMemoryEmail:
+            ...     def __init__(self) -> None:
+            ...         self.sent_emails: list[dict[str, str]] = []
+            ...
+            ...     async def send(self, to: str, subject: str, body: str) -> None:
+            ...         self.sent_emails.append({'to': to, 'subject': subject, 'body': body})
+
+    Args:
+        protocol_class: The protocol class that this implementation satisfies.
+        scope: Lifecycle scope controlling instance creation and caching.
+            Defaults to Scope.SINGLETON. Use Scope.FACTORY for new instances
+            on each resolve() call.
+
+    Returns:
+        A decorator function that marks the class as implementing the protocol
+        and registers it with the container.
+
+    Note:
+        - The implementation class must satisfy the protocol's interface
+        - Multiple implementations of the same protocol are allowed
+        - Use @profile decorators to select implementations per environment
+        - The protocol itself is not registered, only the implementation
+    """
+
+    def decorator(target_cls: type[T]) -> type[T]:
+        # Store protocol metadata on the class
+        target_cls.__dioxide_implements__ = protocol_class  # type: ignore[attr-defined]
+        # Store DI scope metadata
+        target_cls.__dioxide_scope__ = scope  # type: ignore[attr-defined]
+        # Add to global registry for auto-discovery
+        _component_registry.add(target_cls)
+        return target_cls
+
+    return decorator
+
+
+# Attach implements as an attribute to component for @component.implements() syntax
+component.implements = implements  # type: ignore[attr-defined]

dioxide/profile.py

@@ -0,0 +1,206 @@
+"""Profile decorator for environment-specific component implementations.
+
+The profile system enables "fakes at the seams" testing by allowing different
+implementations of the same protocol for different environments (production, test, dev).
+
+Example:
+    >>> from typing import Protocol
+    >>> from dioxide import component, profile
+    >>>
+    >>> class EmailProvider(Protocol):
+    ...     async def send(self, to: str, subject: str, body: str) -> None: ...
+    >>>
+    >>> @component.implements(EmailProvider)
+    >>> @profile.production
+    >>> class SendGridEmail:
+    ...     async def send(self, to: str, subject: str, body: str) -> None:
+    ...         # Real SendGrid implementation
+    ...         pass
+    >>>
+    >>> @component.implements(EmailProvider)
+    >>> @profile.test
+    >>> class FakeEmail:
+    ...     def __init__(self) -> None:
+    ...         self.sent_emails: list[dict[str, str]] = []
+    ...
+    ...     async def send(self, to: str, subject: str, body: str) -> None:
+    ...         self.sent_emails.append({'to': to, 'subject': subject, 'body': body})
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, TypeVar, overload
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+T = TypeVar('T')
+
+# Attribute name for storing profiles on decorated classes
+PROFILE_ATTRIBUTE = '__dioxide_profiles__'
+
+
+class Profile:
+    """Profile decorator for marking components with environment profiles.
+
+    Supports both attribute access (@profile.production) and callable syntax
+    (@profile("prod", "staging")) for maximum flexibility.
+
+    Pre-defined profiles:
+        - production: Production environment
+        - test: Test environment
+        - development: Development environment
+
+    Custom profiles via __getattr__:
+        - @profile.staging
+        - @profile.custom_name
+
+    Multiple profiles:
+        - @profile("prod", "staging")
+
+    Attributes:
+        production: Decorator for production profile
+        test: Decorator for test profile
+        development: Decorator for development profile
+    """
+
+    def __init__(self) -> None:
+        """Initialize Profile decorator."""
+        # Pre-defined profile decorators
+        self.production = self._create_profile_decorator('production')
+        self.test = self._create_profile_decorator('test')
+        self.development = self._create_profile_decorator('development')
+
+    def __getattr__(self, name: str) -> Callable[[type[T]], type[T]]:
+        """Support custom profiles via attribute access.
+
+        Args:
+            name: Profile name (e.g., "staging")
+
+        Returns:
+            Decorator function for the custom profile
+
+        Example:
+            >>> @profile.staging
+            >>> class StagingService:
+            ...     pass
+        """
+        return self._create_profile_decorator(name)
+
+    @overload
+    def __call__(self, cls: type[T], /) -> type[T]: ...
+
+    @overload
+    def __call__(self, *profile_names: str) -> Callable[[type[T]], type[T]]: ...
+
+    def __call__(self, *args: type[T] | str) -> type[T] | Callable[[type[T]], type[T]]:
+        """Support callable syntax for multiple profiles.
+
+        Args:
+            *args: Either a single class (when used as @profile) or
+                   multiple profile names (when used as @profile("prod", "staging"))
+
+        Returns:
+            Decorated class or decorator function
+
+        Raises:
+            ValueError: If no profile names provided or empty strings
+            TypeError: If profile names are not strings
+
+        Example:
+            >>> @profile("prod", "staging")
+            >>> class SharedService:
+            ...     pass
+        """
+        # Check if called with a class directly (e.g., @profile without parens)
+        # This shouldn't happen in normal usage, but handle it gracefully
+        if len(args) == 1 and isinstance(args[0], type):
+            # Default to production if used as bare @profile
+            cls = args[0]
+            return self._create_profile_decorator('production')(cls)
+
+        # Called as @profile("name1", "name2", ...)
+        if not args:
+            raise ValueError('At least one profile name required')
+
+        # Validate all arguments are strings
+        for name in args:
+            if not isinstance(name, str):
+                raise TypeError('Profile names must be strings')
+            if not name:
+                raise ValueError('Profile names cannot be empty')
+
+        # Normalize to lowercase - all args are strings at this point
+        normalized_names = [name.lower() for name in args]  # type: ignore[union-attr]
+
+        return self._create_multi_profile_decorator(normalized_names)
+
+    def _create_profile_decorator(self, profile_name: str) -> Callable[[type[T]], type[T]]:
+        """Create a decorator for a single profile.
+
+        Args:
+            profile_name: Name of the profile
+
+        Returns:
+            Decorator function
+        """
+
+        def decorator(cls: type[T]) -> type[T]:
+            """Add profile to class metadata.
+
+            Args:
+                cls: Class to decorate
+
+            Returns:
+                Same class with profile metadata added
+            """
+            # Get existing profiles or create new set
+            existing_profiles: frozenset[str] = getattr(cls, PROFILE_ATTRIBUTE, frozenset())
+
+            # Add new profile (frozenset is immutable, so create new one)
+            new_profiles = existing_profiles | {profile_name.lower()}
+
+            # Store as frozenset (immutable)
+            setattr(cls, PROFILE_ATTRIBUTE, frozenset(new_profiles))
+
+            return cls
+
+        return decorator
+
+    def _create_multi_profile_decorator(self, profile_names: list[str]) -> Callable[[type[T]], type[T]]:
+        """Create a decorator for multiple profiles.
+
+        Args:
+            profile_names: List of profile names (already normalized)
+
+        Returns:
+            Decorator function
+        """
+
+        def decorator(cls: type[T]) -> type[T]:
+            """Add all profiles to class metadata.
+
+            Args:
+                cls: Class to decorate
+
+            Returns:
+                Same class with profile metadata added
+            """
+            # Get existing profiles or create new set
+            existing_profiles: frozenset[str] = getattr(cls, PROFILE_ATTRIBUTE, frozenset())
+
+            # Add all new profiles (deduplicated by set)
+            new_profiles = existing_profiles | set(profile_names)
+
+            # Store as frozenset (immutable)
+            setattr(cls, PROFILE_ATTRIBUTE, frozenset(new_profiles))
+
+            return cls
+
+        return decorator
+
+
+# Global singleton instance for use as decorator
+profile = Profile()
+
+__all__ = ['PROFILE_ATTRIBUTE', 'Profile', 'profile']

dioxide/scope.py

@@ -0,0 +1,77 @@
+"""Dependency injection scopes.
+
+This module defines the lifecycle scopes available for components in the
+dependency injection container.
+"""
+
+from enum import Enum
+
+
+class Scope(str, Enum):
+    """Component lifecycle scope.
+
+    Defines how instances of a component are created and cached:
+
+    - SINGLETON: One shared instance for the lifetime of the container.
+      The factory is called once and the result is cached. Subsequent
+      resolve() calls return the same instance.
+
+    - FACTORY: New instance created on each resolve() call. The factory
+      is invoked every time the component is requested, creating a fresh
+      instance.
+
+    Example:
+        >>> from dioxide import Container, component, Scope
+        >>>
+        >>> @component  # Default: SINGLETON scope
+        ... class Database:
+        ...     pass
+        >>>
+        >>> @component(scope=Scope.FACTORY)
+        ... class RequestHandler:
+        ...     request_id: int = 0
+        ...
+        ...     def __init__(self):
+        ...         RequestHandler.request_id += 1
+        ...         self.id = RequestHandler.request_id
+        >>>
+        >>> container = Container()
+        >>> container.scan()
+        >>>
+        >>> # Singleton: same instance every time
+        >>> db1 = container.resolve(Database)
+        >>> db2 = container.resolve(Database)
+        >>> assert db1 is db2
+        >>>
+        >>> # Factory: new instance every time
+        >>> handler1 = container.resolve(RequestHandler)
+        >>> handler2 = container.resolve(RequestHandler)
+        >>> assert handler1 is not handler2
+        >>> assert handler1.id != handler2.id
+    """
+
+    SINGLETON = 'singleton'
+    """One shared instance for the lifetime of the container.
+
+    The component factory is called once and the result is cached.
+    All subsequent resolve() calls return the same instance.
+
+    Use for:
+    - Database connections
+    - Configuration objects
+    - Services with shared state
+    - Expensive-to-create objects
+    """
+
+    FACTORY = 'factory'
+    """New instance created on each resolve() call.
+
+    The component factory is invoked every time the component is
+    requested, creating a fresh instance.
+
+    Use for:
+    - Request handlers
+    - Transient data objects
+    - Stateful components that shouldn't be shared
+    - Objects with per-request lifecycle
+    """