pyiv 0.3.0__py3-none-any.whl

pyiv/__init__.py

@@ -0,0 +1,137 @@
+"""Guice-style dependency injection for Python.
+
+pyiv provides type-based constructor injection, scopes, qualified keys, and
+built-in test doubles. Runtime has zero third-party dependencies. Python 3.8+.
+
+Key Features:
+
+- Type-based constructor injection from annotations
+- Scopes (per-injector and process-wide singletons, plus custom Scope)
+- Qualified keys and a fluent Binder API
+- Reflection to discover implementations in a package
+- Test doubles for Clock, Filesystem, Console, and DateTimeService
+- Zero runtime dependencies
+
+Quick Start:
+
+    >>> from pyiv import Config, get_injector
+    >>> class Database:
+    ...     pass
+    >>> class PostgreSQL(Database):
+    ...     pass
+    >>> class MyConfig(Config):
+    ...     def configure(self):
+    ...         self.register(Database, PostgreSQL)
+    >>> injector = get_injector(MyConfig)
+    >>> isinstance(injector.inject(Database), PostgreSQL)
+    True
+"""
+
+from pyiv.binder import Binder, BindingBuilder
+from pyiv.chain import ChainHandler, ChainType
+from pyiv.clock import Clock, RealClock, SyntheticClock, Timer
+from pyiv.config import Config
+from pyiv.console import (
+    BaseConsole,
+    Console,
+    FileConsole,
+    MemoryConsole,
+    MockConsole,
+    PTYConsole,
+    RealConsole,
+)
+from pyiv.datetime_service import DateTimeService, MockDateTimeService, PythonDateTimeService
+from pyiv.factory import BaseFactory, Factory, SimpleFactory
+from pyiv.filesystem import Filesystem, MemoryFilesystem, RealFilesystem
+from pyiv.injector import Injector, get_injector
+from pyiv.key import Key, Named, Qualifier
+from pyiv.members import InjectorMembersInjector, MembersInjector
+from pyiv.multibinder import ListMultibinder, Multibinder, SetMultibinder
+from pyiv.network import HTTPClient, HTTPSClient, NetworkClient
+from pyiv.optional import get_optional_type, is_optional_type
+from pyiv.provider import (
+    BaseProvider,
+    FactoryProvider,
+    InjectorProvider,
+    InstanceProvider,
+    Provider,
+)
+from pyiv.reflection import ReflectionConfig
+from pyiv.scope import GlobalSingletonScope, NoScope, Scope, SingletonScope
+from pyiv.serde import Base64SerDe, JSONSerDe, NoOpSerDe, PickleSerDe, SerDe, XMLSerDe, YAMLSerDe
+from pyiv.singleton import GlobalSingletonRegistry, SingletonType
+
+# Command interface (optional import)
+try:
+    from pyiv.command import CLICommand, Command, CommandRunner, ServiceCommand
+
+    _has_commands = True
+except ImportError:
+    _has_commands = False
+
+__version__ = "0.3.0"
+__all__ = [
+    "Config",
+    "ReflectionConfig",
+    "Injector",
+    "get_injector",
+    "ChainType",
+    "ChainHandler",
+    "Filesystem",
+    "RealFilesystem",
+    "MemoryFilesystem",
+    "Console",
+    "BaseConsole",
+    "RealConsole",
+    "MemoryConsole",
+    "FileConsole",
+    "PTYConsole",
+    "MockConsole",
+    "Clock",
+    "RealClock",
+    "SyntheticClock",
+    "Timer",
+    "DateTimeService",
+    "PythonDateTimeService",
+    "MockDateTimeService",
+    "Factory",
+    "BaseFactory",
+    "SimpleFactory",
+    "SerDe",
+    "JSONSerDe",
+    "Base64SerDe",
+    "XMLSerDe",
+    "YAMLSerDe",
+    "PickleSerDe",
+    "NoOpSerDe",
+    "NetworkClient",
+    "HTTPClient",
+    "HTTPSClient",
+    "SingletonType",
+    "GlobalSingletonRegistry",
+    # New interfaces
+    "Provider",
+    "BaseProvider",
+    "InjectorProvider",
+    "InstanceProvider",
+    "FactoryProvider",
+    "Scope",
+    "NoScope",
+    "SingletonScope",
+    "GlobalSingletonScope",
+    "Key",
+    "Named",
+    "Qualifier",
+    "Binder",
+    "BindingBuilder",
+    "MembersInjector",
+    "InjectorMembersInjector",
+    "Multibinder",
+    "SetMultibinder",
+    "ListMultibinder",
+    "is_optional_type",
+    "get_optional_type",
+]
+
+if _has_commands:
+    __all__.extend(["Command", "ServiceCommand", "CLICommand", "CommandRunner"])

pyiv/binder.py

@@ -0,0 +1,203 @@
+"""Binder interface for fluent configuration API.
+
+This module provides the Binder interface for configuring dependency bindings
+in a fluent, decoupled way. The Binder separates the configuration API from
+the implementation, making Config more testable and enabling programmatic
+configuration.
+
+**What Problem Does This Solve?**
+
+Binders solve the configuration API design problem:
+
+- **Fluent API**: Method chaining for readable, expressive configuration
+- **Separation of Concerns**: Configuration API separated from implementation
+- **Testability**: Mock binders for testing configuration logic
+- **Programmatic Configuration**: Build configurations dynamically
+- **Better Readability**: ``binder.bind(X).to(Y).in_scope(Z)`` is clearer than nested calls
+
+**Real-World Use Cases:**
+
+- **Dynamic Configuration**: Build configurations based on environment variables
+- **Configuration Testing**: Mock binders to test configuration logic
+- **Modular Configuration**: Compose configurations from multiple sources
+- **Framework Integration**: Provide fluent APIs for framework-specific configuration
+
+Architecture:
+    - Binder: Protocol defining the binder interface
+    - BindingBuilder: Fluent builder for configuring bindings
+    - ConfigBinder: Concrete binder implementation used by Config
+
+Usage Examples:
+
+    Basic Fluent Configuration:
+        >>> from pyiv.binder import Binder
+        >>> from pyiv.scope import SingletonScope
+        >>> from pyiv import Config, get_injector
+        >>>
+        >>> class Database:
+        ...     pass
+        >>>
+        >>> class PostgreSQL(Database):
+        ...     pass
+        >>>
+        >>> class Logger:
+        ...     pass
+        >>>
+        >>> class FileLogger(Logger):
+        ...     pass
+        >>>
+        >>> class MyConfig(Config):
+        ...     def configure(self):
+        ...         binder = self.get_binder()
+        ...         # Fluent API - easy to read and chain
+        ...         binder.bind(Database).to(PostgreSQL)
+        ...         binder.bind(Logger).to(FileLogger).in_scope(SingletonScope())
+        >>>
+        >>> injector = get_injector(MyConfig)
+        >>> db = injector.inject(Database)
+        >>> isinstance(db, PostgreSQL)
+        True
+
+    Binding to Instances:
+        >>> from pyiv import Config, get_injector
+        >>>
+        >>> class Cache:
+        ...     def __init__(self):
+        ...         self.data = {}
+        >>>
+        >>> cache = Cache()
+        >>> class InstanceConfig(Config):
+        ...     def configure(self):
+        ...         self.get_binder().bind_instance(Cache, cache)
+        >>>
+        >>> injector = get_injector(InstanceConfig)
+        >>> injector.inject(Cache) is cache
+        True
+"""
+
+from typing import Any, Generic, Protocol, Type, TypeVar
+
+from pyiv.key import Key
+from pyiv.provider import Provider
+from pyiv.scope import Scope
+
+T = TypeVar("T")
+
+
+class BindingBuilder(Protocol, Generic[T]):
+    """Fluent builder for configuring bindings.
+
+    This builder provides a fluent API for configuring how a type should
+    be bound. It supports chaining methods to configure the binding.
+
+    Example:
+        >>> from pyiv import Config, get_injector
+        >>> from pyiv.scope import SingletonScope
+        >>> class Database:
+        ...     pass
+        >>> class PostgreSQL(Database):
+        ...     pass
+        >>> class MyConfig(Config):
+        ...     def configure(self):
+        ...         self.get_binder().bind(Database).to(PostgreSQL).in_scope(SingletonScope())
+        >>> isinstance(get_injector(MyConfig).inject(Database), PostgreSQL)
+        True
+    """
+
+    def to(self, implementation: Type[T]) -> "BindingBuilder[T]":
+        """Bind to a concrete implementation.
+
+        Args:
+            implementation: The concrete class to bind to
+
+        Returns:
+            Self for method chaining
+        """
+        ...
+
+    def to_instance(self, instance: T) -> "BindingBuilder[T]":
+        """Bind to a pre-created instance.
+
+        Args:
+            instance: The instance to bind to
+
+        Returns:
+            Self for method chaining
+        """
+        ...
+
+    def to_provider(self, provider: Provider[T]) -> "BindingBuilder[T]":
+        """Bind to a provider.
+
+        Args:
+            provider: The provider to use for instance creation
+
+        Returns:
+            Self for method chaining
+        """
+        ...
+
+    def in_scope(self, scope: Scope) -> "BindingBuilder[T]":
+        """Set the scope for this binding.
+
+        Args:
+            scope: The scope to use
+
+        Returns:
+            Self for method chaining
+        """
+        ...
+
+
+class Binder(Protocol):
+    """Protocol for binder implementations.
+
+    Binders provide a fluent API for configuring dependency bindings.
+    They separate the configuration API from the implementation, making
+    Config more testable and enabling programmatic configuration.
+
+    Example::
+
+        class MyBinder(Binder):
+            def bind(self, abstract):
+                return BindingBuilder(...)
+    """
+
+    def bind(self, abstract: Type[T]) -> BindingBuilder[T]:
+        """Start a binding configuration.
+
+        Args:
+            abstract: The abstract type to bind
+
+        Returns:
+            A binding builder for fluent configuration
+        """
+        ...
+
+    def bind_key(self, key: Key[T]) -> BindingBuilder[T]:
+        """Start a binding configuration with a qualified key.
+
+        Args:
+            key: The qualified key to bind
+
+        Returns:
+            A binding builder for fluent configuration
+        """
+        ...
+
+    def bind_instance(self, abstract: Type[T], instance: T) -> None:
+        """Bind to a pre-created instance.
+
+        Args:
+            abstract: The abstract type
+            instance: The pre-created instance
+        """
+        ...
+
+    def install(self, config: Any) -> None:
+        """Install another configuration module.
+
+        Args:
+            config: Another Config instance to install
+        """
+        ...

pyiv/binder_impl.py

@@ -0,0 +1,178 @@
+"""Concrete Binder implementation for Config.
+
+This module provides the ConfigBinder implementation that works with Config
+to provide a fluent configuration API.
+"""
+
+from typing import Any, Generic, List, Optional, Type, TypeVar
+
+from pyiv.binder import Binder, BindingBuilder
+from pyiv.config import Config
+from pyiv.key import Key
+from pyiv.provider import InjectorProvider, InstanceProvider, Provider
+from pyiv.scope import NoScope, Scope
+
+T = TypeVar("T")
+
+
+class ConfigBindingBuilder(BindingBuilder[T]):
+    """Binding builder implementation for Config."""
+
+    def __init__(self, config: Config, abstract: Type[T]):
+        """Initialize binding builder.
+
+        Args:
+            config: The config to register bindings with
+            abstract: The abstract type being bound
+        """
+        self._config = config
+        self._abstract = abstract
+        self._implementation: Optional[Type[T]] = None
+        self._instance: Optional[T] = None
+        self._provider: Optional[Provider[T]] = None
+        self._scope: Optional[Scope] = None
+
+    def to(self, implementation: Type[T]) -> "ConfigBindingBuilder[T]":
+        """Bind to a concrete implementation.
+
+        Args:
+            implementation: The concrete class to bind to
+
+        Returns:
+            Self for method chaining
+        """
+        self._implementation = implementation
+        self._finalize()
+        return self
+
+    def to_instance(self, instance: T) -> "ConfigBindingBuilder[T]":
+        """Bind to a pre-created instance.
+
+        Args:
+            instance: The instance to bind to
+
+        Returns:
+            Self for method chaining
+        """
+        self._instance = instance
+        self._finalize()
+        return self
+
+    def to_provider(self, provider: Provider[T]) -> "ConfigBindingBuilder[T]":
+        """Bind to a provider.
+
+        Args:
+            provider: The provider to use for instance creation
+
+        Returns:
+            Self for method chaining
+        """
+        self._provider = provider
+        self._finalize()
+        return self
+
+    def in_scope(self, scope: Scope) -> "ConfigBindingBuilder[T]":
+        """Set the scope for this binding.
+
+        Args:
+            scope: The scope to use
+
+        Returns:
+            Self for method chaining
+        """
+        self._scope = scope
+        # Update scope if already finalized
+        if hasattr(self, "_finalized") and getattr(self, "_finalized", False):
+            self._config._scopes[self._abstract] = scope
+        return self
+
+    def _finalize(self) -> None:
+        """Finalize the binding registration."""
+        if hasattr(self, "_finalized") and getattr(self, "_finalized", False):
+            return
+
+        if self._instance is not None:
+            self._config.register_instance(self._abstract, self._instance)
+            if self._scope is not None:
+                self._config._scopes[self._abstract] = self._scope
+        elif self._provider is not None:
+            self._config.register_provider(self._abstract, self._provider)
+            if self._scope is not None:
+                self._config._scopes[self._abstract] = self._scope
+        elif self._implementation is not None:
+            self._config.register(
+                self._abstract,
+                self._implementation,
+                scope=self._scope if self._scope is not None else NoScope(),
+            )
+        else:
+            # Don't raise error - allow chaining
+            return
+
+        self._finalized = True
+
+
+class ConfigBinder(Binder):
+    """Concrete Binder implementation for Config."""
+
+    def __init__(self, config: Config):
+        """Initialize binder.
+
+        Args:
+            config: The config to register bindings with
+        """
+        self._config = config
+        self._builders: List[ConfigBindingBuilder[Any]] = []
+
+    def bind(self, abstract: Type[T]) -> BindingBuilder[T]:
+        """Start a binding configuration.
+
+        Args:
+            abstract: The abstract type to bind
+
+        Returns:
+            A binding builder for fluent configuration
+        """
+        builder = ConfigBindingBuilder(self._config, abstract)
+        self._builders.append(builder)
+        return builder
+
+    def bind_key(self, key: Key[T]) -> BindingBuilder[T]:
+        """Start a binding configuration with a qualified key.
+
+        Args:
+            key: The qualified key to bind
+
+        Returns:
+            A binding builder for fluent configuration
+        """
+        # For qualified keys, we need a special builder
+        builder: ConfigBindingBuilder[Any] = ConfigBindingBuilder(self._config, key.type)  # type: ignore[arg-type]
+        builder._key = key  # type: ignore[attr-defined]  # Store the key
+        self._builders.append(builder)
+        return builder
+
+    def bind_instance(self, abstract: Type[T], instance: T) -> None:
+        """Bind to a pre-created instance.
+
+        Args:
+            abstract: The abstract type
+            instance: The pre-created instance
+        """
+        self._config.register_instance(abstract, instance)
+
+    def install(self, config: Any) -> None:
+        """Install another configuration module.
+
+        Args:
+            config: Another Config instance to install
+        """
+        # This would require merging configs, which is complex
+        # For now, we'll raise NotImplementedError
+        raise NotImplementedError("Config installation not yet implemented")
+
+    def finalize(self) -> None:
+        """Finalize all pending bindings."""
+        for builder in self._builders:
+            builder._finalize()
+        self._builders.clear()

pyiv/chain.py

@@ -0,0 +1,79 @@
+"""Chain of Responsibility pattern for pyiv.
+
+This module provides a general chain of responsibility system that can be used
+for various purposes: encoding, hashing, sorting, etc. Each chain type has its
+own interface and implementations.
+"""
+
+from abc import ABC, abstractmethod
+from enum import Enum
+from typing import Any, TypeVar
+
+T = TypeVar("T")
+
+
+class ChainType(Enum):
+    """Types of chain of responsibility handlers.
+
+    Each chain type represents a different category of handlers:
+    - ENCODING: Serialization/deserialization (SerDe)
+    - HASHING: Hash function implementations
+    - SORTING: Sorting algorithm implementations
+    - NETWORK_CLIENT: Network protocol clients (HTTP, HTTPS, etc.)
+    - etc.
+    """
+
+    ENCODING = "encoding"
+    HASHING = "hashing"
+    SORTING = "sorting"
+    NETWORK_CLIENT = "network_client"
+
+
+class ChainHandler(ABC):
+    """Abstract base class for chain of responsibility handlers.
+
+    Chain handlers process requests in a chain. Each handler can either:
+    - Handle the request and return a result
+    - Pass the request to the next handler in the chain
+    - Reject the request
+
+    Subclasses must implement:
+        - chain_type: The type of chain this handler belongs to
+        - handler_type: The specific handler type identifier (e.g., "json", "md5", "quicksort")
+        - handle(): Process the request
+    """
+
+    @property
+    @abstractmethod
+    def chain_type(self) -> ChainType:
+        """Return the chain type this handler belongs to.
+
+        Returns:
+            The ChainType enum value
+        """
+        pass
+
+    @property
+    @abstractmethod
+    def handler_type(self) -> str:
+        """Return the handler type identifier.
+
+        This identifies the specific implementation (e.g., "json", "md5", "quicksort").
+
+        Returns:
+            A string identifying the handler type
+        """
+        pass
+
+    @abstractmethod
+    def handle(self, request: Any, **kwargs) -> Any:
+        """Handle a request.
+
+        Args:
+            request: The request to handle
+            **kwargs: Additional keyword arguments
+
+        Returns:
+            The result of handling the request
+        """
+        pass