hdmi 0.1.0__tar.gz

hdmi-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Romain Dorgueil
+
+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.

hdmi-0.1.0/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.3
+Name: hdmi
+Version: 0.1.0
+Summary: A dependency injection framework for Python with dynamic late-binding resolution
+Author: Romain Dorgueil
+Author-email: Romain Dorgueil <romain@makersquad.fr>
+License: MIT License
+         
+         Copyright (c) 2025 Romain Dorgueil
+         
+         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.
+Requires-Dist: anyio>=4.0.0
+Requires-Dist: pytest>=8.0.0 ; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1.0 ; extra == 'dev'
+Requires-Dist: ruff>=0.8.0 ; extra == 'dev'
+Requires-Dist: basedpyright>=1.21.0 ; extra == 'dev'
+Requires-Dist: sphinx>=8.0.0 ; extra == 'dev'
+Requires-Dist: sphinx-autobuild>=2024.0.0 ; extra == 'dev'
+Requires-Dist: furo>=2024.0.0 ; extra == 'dev'
+Requires-Dist: sphinxcontrib-mermaid>=1.0.0 ; extra == 'dev'
+Requires-Dist: twine>=6.0.0 ; extra == 'dev'
+Requires-Python: >=3.13
+Provides-Extra: dev
+Description-Content-Type: text/markdown
+
+# hdmi - Dependency Management Interface
+
+A lightweight dependency injection framework for Python 3.13+ with:
+
+- **Type-driven dependency discovery** - Uses Python's standard type annotations
+- **Scope-aware validation** - Prevents lifetime bugs at build time
+- **Lazy instantiation** - Services created just-in-time
+- **Early error detection** - Configuration errors caught at build time
+
+## Quick Example
+
+### Simple Example (Singleton Services)
+
+```python
+from hdmi import ContainerBuilder
+
+# Define your services
+class DatabaseConnection:
+    def __init__(self):
+        self.connected = True
+
+class UserRepository:
+    def __init__(self, db: DatabaseConnection):
+        self.db = db
+
+class UserService:
+    def __init__(self, repo: UserRepository):
+        self.repo = repo
+
+# Configure the container (all singletons by default)
+builder = ContainerBuilder()
+builder.register(DatabaseConnection)
+builder.register(UserRepository)
+builder.register(UserService)
+
+# Build validates the dependency graph
+container = builder.build()
+
+# Resolve services lazily - dependencies are auto-wired!
+user_service = container.get(UserService)
+```
+
+### Using Scoped Services
+
+```python
+# For request-scoped services (e.g., web requests)
+builder = ContainerBuilder()
+builder.register(DatabaseConnection)  # singleton (default)
+builder.register(UserRepository, scoped=True)  # One per request
+builder.register(UserService, transient=True)   # New each time
+
+container = builder.build()
+
+# Scoped services must be resolved within a scope context
+with container.scope() as scoped:
+    user_service = scoped.get(UserService)
+    # All scoped dependencies share the same instance within this scope
+```
+
+## Key Features
+
+### Two-Phase Architecture
+
+1. **ContainerBuilder** (Configuration): Register services and define scopes
+2. **Container** (Runtime): Validated, immutable graph for lazy resolution
+
+### Scope Safety
+
+Services have four lifecycles that are validated at build time:
+
+- **Singleton** (default): One instance per container
+- **Scoped**: One instance per scope (e.g., per request)
+- **Transient**: New instance every time
+- **Scoped Transient**: New instance every time, requires scope
+
+**Validation Rules (Simplified):**
+The only invalid dependency is when a non-scoped service (singleton or transient) depends on a scoped service.
+
+```python
+#  Valid: Scoped � Singleton
+builder = ContainerBuilder()
+builder.register(DatabaseConnection)  # singleton (default)
+builder.register(UserRepository, scoped=True)
+
+# L Invalid: Singleton � Scoped (raises ScopeViolationError)
+builder = ContainerBuilder()
+builder.register(RequestHandler, scoped=True)
+builder.register(SingletonService)  # singleton depends on scoped!
+container = builder.build()  # ScopeViolationError!
+```
+
+### Type-Driven Dependencies
+
+Dependencies are automatically discovered from type annotations:
+
+```python
+class ServiceA:
+    def __init__(self, dep: DependencyType):
+        self.dep = dep
+```
+
+No decorators or manual wiring required!
+
+## Installation
+
+```bash
+pip install hdmi  # Coming soon
+```
+
+## Development
+
+This project uses [uv](https://github.com/astral-sh/uv) for dependency management and follows strict TDD methodology.
+
+```bash
+# Run all checks (linting, type checking, tests)
+make test
+
+# Build documentation
+make docs
+
+# See all available commands
+make help
+```
+
+## License
+
+MIT License - see LICENSE file for details.

hdmi-0.1.0/README.md

@@ -0,0 +1,127 @@
+# hdmi - Dependency Management Interface
+
+A lightweight dependency injection framework for Python 3.13+ with:
+
+- **Type-driven dependency discovery** - Uses Python's standard type annotations
+- **Scope-aware validation** - Prevents lifetime bugs at build time
+- **Lazy instantiation** - Services created just-in-time
+- **Early error detection** - Configuration errors caught at build time
+
+## Quick Example
+
+### Simple Example (Singleton Services)
+
+```python
+from hdmi import ContainerBuilder
+
+# Define your services
+class DatabaseConnection:
+    def __init__(self):
+        self.connected = True
+
+class UserRepository:
+    def __init__(self, db: DatabaseConnection):
+        self.db = db
+
+class UserService:
+    def __init__(self, repo: UserRepository):
+        self.repo = repo
+
+# Configure the container (all singletons by default)
+builder = ContainerBuilder()
+builder.register(DatabaseConnection)
+builder.register(UserRepository)
+builder.register(UserService)
+
+# Build validates the dependency graph
+container = builder.build()
+
+# Resolve services lazily - dependencies are auto-wired!
+user_service = container.get(UserService)
+```
+
+### Using Scoped Services
+
+```python
+# For request-scoped services (e.g., web requests)
+builder = ContainerBuilder()
+builder.register(DatabaseConnection)  # singleton (default)
+builder.register(UserRepository, scoped=True)  # One per request
+builder.register(UserService, transient=True)   # New each time
+
+container = builder.build()
+
+# Scoped services must be resolved within a scope context
+with container.scope() as scoped:
+    user_service = scoped.get(UserService)
+    # All scoped dependencies share the same instance within this scope
+```
+
+## Key Features
+
+### Two-Phase Architecture
+
+1. **ContainerBuilder** (Configuration): Register services and define scopes
+2. **Container** (Runtime): Validated, immutable graph for lazy resolution
+
+### Scope Safety
+
+Services have four lifecycles that are validated at build time:
+
+- **Singleton** (default): One instance per container
+- **Scoped**: One instance per scope (e.g., per request)
+- **Transient**: New instance every time
+- **Scoped Transient**: New instance every time, requires scope
+
+**Validation Rules (Simplified):**
+The only invalid dependency is when a non-scoped service (singleton or transient) depends on a scoped service.
+
+```python
+#  Valid: Scoped � Singleton
+builder = ContainerBuilder()
+builder.register(DatabaseConnection)  # singleton (default)
+builder.register(UserRepository, scoped=True)
+
+# L Invalid: Singleton � Scoped (raises ScopeViolationError)
+builder = ContainerBuilder()
+builder.register(RequestHandler, scoped=True)
+builder.register(SingletonService)  # singleton depends on scoped!
+container = builder.build()  # ScopeViolationError!
+```
+
+### Type-Driven Dependencies
+
+Dependencies are automatically discovered from type annotations:
+
+```python
+class ServiceA:
+    def __init__(self, dep: DependencyType):
+        self.dep = dep
+```
+
+No decorators or manual wiring required!
+
+## Installation
+
+```bash
+pip install hdmi  # Coming soon
+```
+
+## Development
+
+This project uses [uv](https://github.com/astral-sh/uv) for dependency management and follows strict TDD methodology.
+
+```bash
+# Run all checks (linting, type checking, tests)
+make test
+
+# Build documentation
+make docs
+
+# See all available commands
+make help
+```
+
+## License
+
+MIT License - see LICENSE file for details.

hdmi-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[project]
+name = "hdmi"
+version = "0.1.0"
+description = "A dependency injection framework for Python with dynamic late-binding resolution"
+readme = "README.md"
+license = { file = "LICENSE" }
+authors = [
+    { name = "Romain Dorgueil", email = "romain@makersquad.fr" }
+]
+requires-python = ">=3.13"
+dependencies = [
+    "anyio>=4.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=4.1.0",
+    "ruff>=0.8.0",
+    "basedpyright>=1.21.0",
+    "sphinx>=8.0.0",
+    "sphinx-autobuild>=2024.0.0",
+    "furo>=2024.0.0",
+    "sphinxcontrib-mermaid>=1.0.0",
+    "twine>=6.0.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.7,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 120
+indent-width = 4
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+[tool.basedpyright]
+# Standard type checking mode - stricter than basic, not as strict as strict
+typeCheckingMode = "standard"
+pythonVersion = "3.13"
+
+# Include source code and tests
+include = ["src", "tests"]
+
+# Report missing type stubs for third-party libraries as information, not errors
+reportMissingTypeStubs = "information"
+
+# Note: Planning to migrate to Astral's 'ty' when it reaches production readiness (late 2025)
+# https://github.com/astral-sh/ty

hdmi-0.1.0/src/hdmi/__init__.py

@@ -0,0 +1,31 @@
+"""hdmi - Dynamic Dependency Injection for Python.
+
+A lightweight dependency injection framework with:
+- Type-driven dependency discovery
+- Scope-aware validation
+- Lazy instantiation
+- Early error detection
+"""
+
+from hdmi.builders import ContainerBuilder
+from hdmi.containers import Container, ScopedContainer
+from hdmi.types import IContainer, ServiceDefinition
+from hdmi.exceptions import (
+    CircularDependencyError,
+    HDMIError,
+    ScopeViolationError,
+    UnresolvableDependencyError,
+)
+
+__all__ = [
+    "CircularDependencyError",
+    "Container",
+    "ContainerBuilder",
+    "HDMIError",
+    "IContainer",
+    "IContainer",
+    "ScopeViolationError",
+    "ScopedContainer",
+    "ServiceDefinition",
+    "UnresolvableDependencyError",
+]

hdmi-0.1.0/src/hdmi/builders/__init__.py

@@ -0,0 +1,11 @@
+"""hdmi.builders - Container builder implementations.
+
+This package provides builder classes for configuring dependency injection:
+- ContainerBuilder: Builder for creating and validating containers
+"""
+
+from hdmi.builders.default import ContainerBuilder
+
+__all__ = [
+    "ContainerBuilder",
+]

hdmi-0.1.0/src/hdmi/builders/default.py

@@ -0,0 +1,187 @@
+"""ContainerBuilder - Configuration phase for dependency injection.
+
+The ContainerBuilder accumulates service registrations and produces
+a validated, immutable Container when build() is called.
+"""
+
+import inspect
+from typing import TYPE_CHECKING, Any, Awaitable, Callable, Type, get_type_hints
+
+from hdmi.utils.typing import extract_type_from_optional
+from hdmi.types.definitions import ServiceDefinition
+from hdmi.exceptions import ScopeViolationError
+
+if TYPE_CHECKING:
+    from hdmi.containers import Container
+
+# Removed - no longer using scope hierarchy with boolean flags
+
+
+class ContainerBuilder:
+    """Mutable builder for configuring dependency injection services.
+
+    The ContainerBuilder is responsible for:
+    - Accumulating service registrations
+    - Validating the dependency graph when build() is called
+    - Producing an immutable, validated Container
+    """
+
+    def __init__(self):
+        self._definitions: dict[Type, ServiceDefinition] = {}
+
+    def register(
+        self,
+        service_type: Type,
+        /,
+        *,
+        scoped: bool = False,
+        transient: bool = False,
+        name: str | None = None,
+        factory: Callable[..., Any] | Callable[..., Awaitable[Any]] | None = None,
+        autowire: bool = True,
+        initializer: Callable[[Any], None] | Callable[[Any], Awaitable[None]] | None = None,
+        finalizer: Callable[[Any], None] | Callable[[Any], Awaitable[None]] | None = None,
+    ) -> None:
+        """Register a service type with the container.
+
+        Args:
+            service_type: The class to register as a service
+            scoped: False (default) = available from Container, True = requires ScopedContainer
+            transient: False (default) = cached, True = new instance per request
+            name: Optional name for the service
+            factory: Optional factory function to create the service (sync or async)
+            autowire: Whether to auto-inject this service into optional dependencies (defaults to True)
+            initializer: Optional initialization function called after service creation (sync or async)
+            finalizer: Optional cleanup function called when service is disposed (sync or async)
+        """
+        definition = ServiceDefinition(
+            service_type,
+            scoped=scoped,
+            transient=transient,
+            name=name,
+            factory=factory,
+            autowire=autowire,
+            initializer=initializer,
+            finalizer=finalizer,
+        )
+        self._definitions[service_type] = definition
+
+    def build(self) -> "Container":
+        """Build and validate the Container.
+
+        This method:
+        1. Validates the dependency graph
+        2. Checks for circular dependencies
+        3. Validates scope hierarchy
+        4. Produces an immutable Container
+
+        Returns:
+            An immutable, validated Container ready for runtime use
+
+        Raises:
+            CircularDependencyError: If circular dependencies are detected
+            UnresolvableDependencyError: If a dependency cannot be resolved
+            ScopeViolationError: If scope hierarchy is violated
+        """
+        from hdmi.containers import Container
+
+        # Validate scope hierarchy for all registrations
+        self._validate_scopes()
+
+        # Create and return the validated Container
+        return Container(self._definitions)
+
+    def _validate_scopes(self) -> None:
+        """Validate that scope rules are respected.
+
+        Validation rule:
+        - Non-scoped services (scoped=False) cannot depend on scoped services (scoped=True)
+
+        This is because non-scoped services are available from Container, but scoped
+        services only exist within a ScopedContainer context.
+
+        Raises:
+            ScopeViolationError: If a non-scoped service depends on a scoped service
+        """
+        for service_type, definition in self._definitions.items():
+            # Get dependencies from type annotations
+            dependencies = self._get_dependencies(service_type)
+
+            # Check each dependency's scope
+            for dep_name, dep_type in dependencies.items():
+                if dep_type not in self._definitions:
+                    # Will be caught later by unresolvable dependency check
+                    continue
+
+                dep_definition = self._definitions[dep_type]
+
+                # Validate scope compatibility
+                # The only unsafe dependency is: non-scoped -> scoped
+                # (non-scoped service needs a scoped instance that only exists within a scope)
+                if not definition.scoped and dep_definition.scoped:
+                    service_type_str = (
+                        f"{service_type.__name__} (scoped={definition.scoped}, transient={definition.transient})"
+                    )
+                    dep_type_str = (
+                        f"{dep_type.__name__} (scoped={dep_definition.scoped}, transient={dep_definition.transient})"
+                    )
+                    raise ScopeViolationError(
+                        f"{service_type_str} cannot depend on {dep_type_str}. "
+                        f"Non-scoped services cannot depend on scoped services because "
+                        f"scoped services only exist within a scope context."
+                    )
+
+    def _get_dependencies(self, service_type: Type) -> dict[str, Type]:
+        """Get dependencies that will actually be injected.
+
+        Only returns dependencies that will be injected at runtime, respecting:
+        - Optional dependencies not registered are skipped
+        - Optional dependencies with autowire=False are skipped
+        - Required dependencies are always included
+
+        Args:
+            service_type: The service type to analyze
+
+        Returns:
+            Dictionary mapping parameter name to dependency type (only dependencies that will be injected)
+        """
+        try:
+            sig = inspect.signature(service_type.__init__)
+            hints = get_type_hints(service_type.__init__)
+        except Exception:
+            return {}
+
+        dependencies = {}
+        for param_name, param in sig.parameters.items():
+            if param_name == "self":
+                continue
+
+            if param_name not in hints:
+                continue
+
+            type_hint = hints[param_name]
+            has_default = param.default is not inspect.Parameter.empty
+
+            # Extract actual type from Optional/Union types (e.g., Config | None -> Config)
+            dependency_type = extract_type_from_optional(type_hint)
+            if dependency_type is None:
+                # Can't determine single type (e.g., Union[A, B] or just None)
+                continue
+
+            # Check if dependency is registered
+            is_registered = dependency_type in self._definitions
+
+            if has_default:
+                # Optional dependency - only include if registered AND autowire=True
+                if is_registered:
+                    dep_definition = self._definitions[dependency_type]
+                    if dep_definition.autowire:
+                        # Will be injected - include in dependencies
+                        dependencies[param_name] = dependency_type
+                    # else: skip (autowire=False, won't be injected)
+                # else: skip (not registered, won't be injected)
+            else:
+                # Required dependency - always include (will always be injected)
+                dependencies[param_name] = dependency_type
+
+        return dependencies

hdmi-0.1.0/src/hdmi/containers/__init__.py

@@ -0,0 +1,14 @@
+"""hdmi.containers - Dependency injection container implementations.
+
+This package provides the runtime containers for dependency injection:
+- Container: Root container for singleton and transient services
+- ScopedContainer: Scoped container for scoped service resolution
+"""
+
+from hdmi.containers.default import Container
+from hdmi.containers.scoped import ScopedContainer
+
+__all__ = [
+    "Container",
+    "ScopedContainer",
+]

hdmi-0.1.0/src/hdmi/containers/default.py

@@ -0,0 +1,250 @@
+"""Container - Root container for dependency injection.
+
+The Container is an immutable, validated dependency graph that resolves
+service instances lazily (just-in-time) when requested.
+"""
+
+import asyncio
+import inspect
+from contextlib import AsyncExitStack
+from typing import TYPE_CHECKING, Type, TypeVar, get_type_hints
+
+from anyio import to_thread
+
+from hdmi.utils.typing import extract_type_from_optional
+
+if TYPE_CHECKING:
+    from hdmi.types.definitions import ServiceDefinition
+    from hdmi.containers.scoped import ScopedContainer
+
+T = TypeVar("T")
+
+
+class Container:
+    """Immutable root container for resolving service instances at runtime.
+
+    The Container is produced by ContainerBuilder.build() and is:
+    - Immutable: cannot be modified after creation
+    - Pre-validated: all configuration errors caught during build
+    - Lazy: services instantiated only when first requested via get()
+    - Async: all resolution and lifecycle management is async
+
+    Implements IContainer protocol to provide a consistent interface with
+    ScopedContainer.
+    """
+
+    def __init__(self, definitions: dict[Type, "ServiceDefinition"]):
+        """Initialize Container with validated service definitions.
+
+        This should only be called by ContainerBuilder.build().
+
+        Args:
+            definitions: Validated service definitions from builder
+        """
+        self._definitions = definitions
+        self._singletons: dict[Type, object] = {}
+        self._pending_tasks: dict[Type, asyncio.Task] = {}
+        self._exit_stack: AsyncExitStack | None = None
+
+    async def __aenter__(self) -> "Container":
+        """Enter the async context manager.
+
+        Returns:
+            Self to enable 'async with builder.build() as container:' syntax
+        """
+        self._exit_stack = AsyncExitStack()
+        await self._exit_stack.__aenter__()
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
+        """Exit the async context manager and cleanup all managed services.
+
+        This triggers all registered finalizers and closes all async context managers.
+        """
+        if self._exit_stack is not None:
+            await self._exit_stack.__aexit__(exc_type, exc_val, exc_tb)
+            self._exit_stack = None
+
+    def scope(self) -> "ScopedContainer":
+        """Create a new scoped container for resolving scoped services.
+
+        Returns:
+            A new ScopedContainer instance
+        """
+        from hdmi.containers.scoped import ScopedContainer
+
+        return ScopedContainer(self)
+
+    async def get(self, service_type: Type[T]) -> T:
+        """Resolve a service instance (lazy instantiation).
+
+        Args:
+            service_type: The service type to resolve
+
+        Returns:
+            An instance of the service type
+
+        Raises:
+            UnresolvableDependencyError: If the service type is not registered
+            ScopeViolationError: If trying to resolve a scoped service outside a scope
+        """
+        from hdmi.exceptions import ScopeViolationError, UnresolvableDependencyError
+
+        try:
+            definition = self._definitions[service_type]
+        except KeyError:
+            raise UnresolvableDependencyError(
+                f"{service_type.__name__} is not registered in the container. "
+                f"Use ContainerBuilder.register({service_type.__name__}) to register it."
+            ) from None
+
+        # Scoped services cannot be resolved directly from Container
+        if definition.scoped:
+            raise ScopeViolationError(
+                f"{service_type.__name__} is a scoped service (scoped=True) and cannot be resolved "
+                f"directly from Container. Use Container.scope() to create a scoped context."
+            )
+
+        # Handle non-scoped services
+        if definition.transient:
+            # Transient (scoped=False, transient=True): new instance every time, no task sharing
+            return await self._create_instance(service_type)  # type: ignore
+        else:
+            # Singleton (scoped=False, transient=False): cached with task sharing
+            # Check if already cached
+            if service_type in self._singletons:
+                return self._singletons[service_type]  # type: ignore
+
+            # Check if task is already pending (task sharing)
+            if service_type in self._pending_tasks:
+                # Reuse existing task
+                return await self._pending_tasks[service_type]  # type: ignore
+
+            # Create new task and store it
+            task = asyncio.create_task(self._create_instance(service_type))
+            self._pending_tasks[service_type] = task
+
+            try:
+                # Await the task
+                instance = await task
+                # Cache the result
+                self._singletons[service_type] = instance
+                return instance  # type: ignore
+            finally:
+                # Remove from pending tasks (cleanup)
+                self._pending_tasks.pop(service_type, None)
+
+    async def _create_instance(self, service_type: Type[T]) -> T:
+        """Create an instance of a service, resolving dependencies and managing lifecycle.
+
+        Args:
+            service_type: The service type to instantiate
+
+        Returns:
+            An instance with all dependencies resolved and lifecycle hooks executed
+        """
+        # Get the __init__ signature
+        try:
+            sig = inspect.signature(service_type.__init__)
+        except ValueError:
+            # If we can't get signature, try without parameters
+            instance = service_type()  # type: ignore
+            await self._manage_lifecycle(service_type, instance)
+            return instance
+
+        # Get type hints for the __init__ method
+        try:
+            hints = get_type_hints(service_type.__init__)
+        except Exception:
+            hints = {}
+
+        # Collect dependencies to resolve concurrently
+        dependency_tasks: dict[str, asyncio.Task] = {}
+
+        for param_name, param in sig.parameters.items():
+            if param_name == "self":
+                continue
+
+            # Get the type annotation for this parameter
+            if param_name not in hints:
+                continue
+
+            type_hint = hints[param_name]
+            has_default = param.default is not inspect.Parameter.empty
+
+            # Extract actual type from Optional/Union types (e.g., Config | None -> Config)
+            dependency_type = extract_type_from_optional(type_hint)
+            if dependency_type is None:
+                # Can't determine single type (e.g., Union[A, B] or just None)
+                continue
+
+            # Check if dependency is registered
+            is_registered = dependency_type in self._definitions
+
+            if has_default:
+                # Optional dependency - only inject if registered AND autowire=True
+                if is_registered:
+                    dep_definition = self._definitions[dependency_type]
+                    if dep_definition.autowire:
+                        # Create task for concurrent resolution
+                        dependency_tasks[param_name] = asyncio.create_task(self.get(dependency_type))
+                    # else: skip (autowire=False, let class use default)
+                # else: skip (not registered, let class use default)
+            else:
+                # Required dependency - create task for concurrent resolution
+                dependency_tasks[param_name] = asyncio.create_task(self.get(dependency_type))
+
+        # Resolve all dependencies concurrently
+        if dependency_tasks:
+            # Wait for all dependency tasks to complete
+            await asyncio.gather(*dependency_tasks.values())
+
+            # Collect results into kwargs
+            kwargs = {param_name: task.result() for param_name, task in dependency_tasks.items()}
+        else:
+            kwargs = {}
+
+        instance = service_type(**kwargs)  # type: ignore
+
+        # Manage lifecycle (initializer, context manager, finalizer)
+        await self._manage_lifecycle(service_type, instance)
+
+        return instance
+
+    async def _manage_lifecycle(self, service_type: Type[T], instance: T) -> None:
+        """Manage the lifecycle of a service instance.
+
+        This includes:
+        - Calling initializer (if provided)
+        - Registering finalizer with exit stack (if provided)
+
+        Note: Services that are context managers are NOT automatically entered.
+        The user is responsible for managing their context themselves.
+
+        Args:
+            service_type: The service type
+            instance: The service instance
+        """
+        definition = self._definitions[service_type]
+
+        # Call initializer if provided
+        if definition.initializer is not None:
+            if inspect.iscoroutinefunction(definition.initializer):
+                await definition.initializer(instance)
+            else:
+                # Run sync initializer in thread pool
+                await to_thread.run_sync(definition.initializer, instance)
+
+        # Register finalizer with exit stack if provided
+        if definition.finalizer is not None and self._exit_stack is not None:
+            if inspect.iscoroutinefunction(definition.finalizer):
+                # Async finalizer
+                self._exit_stack.push_async_callback(definition.finalizer, instance)
+            else:
+                # Sync finalizer - wrap in async callback that runs in thread pool
+                finalizer = definition.finalizer  # Capture to satisfy type checker
+
+                async def _run_sync_finalizer():
+                    await to_thread.run_sync(finalizer, instance)
+
+                self._exit_stack.push_async_callback(_run_sync_finalizer)

hdmi-0.1.0/src/hdmi/containers/scoped.py

@@ -0,0 +1,117 @@
+"""ScopedContainer - Scoped container for dependency injection.
+
+ScopedContainer follows the decorator pattern, extending Container to provide
+scoped service resolution within a specific scope context.
+"""
+
+import asyncio
+from contextlib import AsyncExitStack
+from typing import TYPE_CHECKING, Type, TypeVar
+
+from hdmi.containers.default import Container
+
+if TYPE_CHECKING:
+    pass
+
+T = TypeVar("T")
+
+
+class ScopedContainer(Container):
+    """Scoped container for resolving scoped services within a scope context.
+
+    ScopedContainer extends Container, following the decorator pattern to delegate
+    to its parent Container for non-scoped services while maintaining its own
+    cache for scoped instances.
+
+    Implements IContainer protocol to provide a consistent interface with Container.
+    """
+
+    def __init__(self, parent: Container):
+        """Initialize ScopedContainer with a parent Container.
+
+        Args:
+            parent: The parent Container to delegate to
+        """
+        # Don't call super().__init__ - we use parent's definitions
+        self._parent = parent
+        self._definitions = parent._definitions
+        self._scoped_instances: dict[Type, object] = {}
+        self._pending_tasks: dict[Type, asyncio.Task] = {}  # For scoped services only
+        self._exit_stack: AsyncExitStack | None = None
+        # Note: we don't initialize _singletons as we delegate to parent
+
+    async def __aenter__(self) -> "ScopedContainer":
+        """Enter the async scope context.
+
+        Returns:
+            Self to enable 'async with container.scope() as scoped:' syntax
+        """
+        self._exit_stack = AsyncExitStack()
+        await self._exit_stack.__aenter__()
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
+        """Exit the async scope context and cleanup all scoped services.
+
+        This triggers finalizers and closes async context managers for scoped services.
+        """
+        if self._exit_stack is not None:
+            await self._exit_stack.__aexit__(exc_type, exc_val, exc_tb)
+            self._exit_stack = None
+        self._scoped_instances.clear()
+
+    async def get(self, service_type: Type[T]) -> T:
+        """Resolve a service instance within the scope.
+
+        Args:
+            service_type: The service type to resolve
+
+        Returns:
+            An instance of the service type
+
+        Raises:
+            UnresolvableDependencyError: If the service type is not registered
+        """
+        from hdmi.exceptions import UnresolvableDependencyError
+
+        try:
+            definition = self._definitions[service_type]
+        except KeyError:
+            raise UnresolvableDependencyError(
+                f"{service_type.__name__} is not registered in the container. "
+                f"Use ContainerBuilder.register({service_type.__name__}) to register it."
+            ) from None
+
+        # Handle based on scope flags
+        if not definition.scoped:
+            # Non-scoped services (singleton or transient) - delegate to parent
+            return await self._parent.get(service_type)  # type: ignore
+
+        # Scoped services (scoped=True)
+        if definition.transient:
+            # Scoped Transient (scoped=True, transient=True): new instance every time, no task sharing
+            return await self._create_instance(service_type)  # type: ignore
+        else:
+            # Scoped (scoped=True, transient=False): cached with task sharing
+            # Check if already cached
+            if service_type in self._scoped_instances:
+                return self._scoped_instances[service_type]  # type: ignore
+
+            # Check if task is already pending (task sharing)
+            if service_type in self._pending_tasks:
+                # Reuse existing task
+                return await self._pending_tasks[service_type]  # type: ignore
+
+            # Create new task and store it
+            task = asyncio.create_task(self._create_instance(service_type))
+            self._pending_tasks[service_type] = task
+
+            try:
+                # Await the task
+                instance = await task
+                # Cache the result
+                self._scoped_instances[service_type] = instance
+                return instance  # type: ignore
+            finally:
+                # Remove from pending tasks (cleanup)
+                self._pending_tasks.pop(service_type, None)

hdmi-0.1.0/src/hdmi/exceptions.py

@@ -0,0 +1,46 @@
+"""Exceptions for hdmi dependency injection framework."""
+
+
+class HDMIError(Exception):
+    """Base exception for all hdmi errors."""
+
+    pass
+
+
+class ScopeViolationError(HDMIError):
+    """Raised when a service depends on a service with incompatible scope.
+
+    The only invalid dependency pattern is when a non-scoped service
+    (singleton or transient) attempts to depend on a scoped service.
+
+    Valid patterns:
+    - Any service can depend on singleton services
+    - Any service can depend on transient services
+    - Scoped services can depend on any service type
+
+    Invalid patterns:
+    - Singleton (scoped=False) depending on Scoped (scoped=True)
+    - Transient (scoped=False) depending on Scoped (scoped=True)
+
+    Note: Transient dependencies are created once during their dependent's
+    construction and live for the dependent's lifetime, making them safe
+    dependencies for any service type.
+    """
+
+    pass
+
+
+class CircularDependencyError(HDMIError):
+    """Raised when circular dependencies are detected."""
+
+    pass
+
+
+class UnresolvableDependencyError(HDMIError, KeyError):
+    """Raised when a required dependency cannot be resolved.
+
+    This exception extends both HDMIError and KeyError for compatibility
+    with code that catches KeyError.
+    """
+
+    pass

hdmi-0.1.0/src/hdmi/types/__init__.py

@@ -0,0 +1,7 @@
+from .containers import IContainer
+from .definitions import ServiceDefinition
+
+__all__ = [
+    "IContainer",
+    "ServiceDefinition",
+]

hdmi-0.1.0/src/hdmi/types/containers.py

@@ -0,0 +1,30 @@
+"""Container protocols - Interface definitions for dependency injection containers."""
+
+from typing import TypeVar, Protocol, Type
+
+T = TypeVar("T")
+
+
+class IContainer(Protocol):
+    """Protocol defining the interface for dependency injection containers.
+
+    This protocol is implemented by both Container (root container) and
+    ScopedContainer (scoped container), ensuring they provide a consistent
+    interface for resolving service instances.
+    """
+
+    def get(self, service_type: Type[T]) -> T:
+        """Resolve a service instance.
+
+        Args:
+            service_type: The service type to resolve
+
+        Returns:
+            An instance of the service type
+
+        Raises:
+            KeyError: If the service type is not registered
+            ScopeViolationError: If trying to resolve a scoped service
+                outside a scope (for root container only)
+        """
+        ...

hdmi-0.1.0/src/hdmi/types/definitions.py

@@ -0,0 +1,45 @@
+from typing import Type, Callable, Any, Awaitable
+
+
+class ServiceDefinition:
+    """Describes everything to know about a service.
+
+    Service lifetime is defined by two boolean flags:
+    - scoped: False (default) = available from Container, True = requires ScopedContainer
+    - transient: False (default) = cached, True = new instance per request
+
+    Four service types:
+    1. Singleton (scoped=False, transient=False): cached in Container
+    2. Scoped (scoped=True, transient=False): cached in ScopedContainer
+    3. Transient (scoped=False, transient=True): not cached, no scope required
+    4. Scoped Transient (scoped=True, transient=True): not cached, requires scope
+    """
+
+    def __init__(
+        self,
+        service_type: Type,
+        /,
+        *,
+        scoped: bool = False,
+        transient: bool = False,
+        name: str | None = None,
+        factory: Callable[..., Any] | Callable[..., Awaitable[Any]] | None = None,
+        autowire: bool = True,
+        initializer: Callable[[Any], None] | Callable[[Any], Awaitable[None]] | None = None,
+        finalizer: Callable[[Any], None] | Callable[[Any], Awaitable[None]] | None = None,
+    ):
+        if factory is not None and not callable(factory):
+            raise ValueError("factory must be callable")
+        if initializer is not None and not callable(initializer):
+            raise ValueError("initializer must be callable")
+        if finalizer is not None and not callable(finalizer):
+            raise ValueError("finalizer must be callable")
+
+        self.service_type = service_type
+        self.scoped = scoped
+        self.transient = transient
+        self.name = name
+        self.factory = factory
+        self.autowire = autowire
+        self.initializer = initializer
+        self.finalizer = finalizer

hdmi-0.1.0/src/hdmi/utils/typing.py

@@ -0,0 +1,38 @@
+from typing import Any, Type, get_origin, get_args
+
+
+def extract_type_from_optional(type_hint: Any) -> Type | None:
+    """Extract the actual type from an Optional/Union type hint.
+
+    Args:
+        type_hint: The type hint to analyze (e.g., Config | None, Optional[Config])
+
+    Returns:
+        The extracted type if it's an Optional/Union, or the original type if not.
+        Returns None if the union contains only None or multiple non-None types.
+
+    Examples:
+        >>> extract_type_from_optional(str | None)
+        <class 'str'>
+        >>> extract_type_from_optional(int)
+        <class 'int'>
+        >>> extract_type_from_optional(str | int)  # Multiple non-None types
+        None
+    """
+    # Check if it's a Union type (including Optional which is Union[T, None])
+    origin = get_origin(type_hint)
+    if origin is not None:
+        # It's a generic type, check if it's a Union
+        args = get_args(type_hint)
+        if args:
+            # Filter out NoneType from the union
+            non_none_types = [arg for arg in args if arg is not type(None)]
+
+            # If there's exactly one non-None type, return it
+            if len(non_none_types) == 1:
+                return non_none_types[0]
+            # Multiple non-None types or all None - can't determine single type
+            return None
+
+    # Not a union type, return as-is
+    return type_hint