hdmi 0.1.0rc3__py3-none-any.whl → 0.2.0__py3-none-any.whl

hdmi/builders/default.py

@@ -9,13 +9,11 @@ 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
+from hdmi.exceptions import ScopeViolationError, CircularDependencyError
 
 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.
@@ -85,12 +83,53 @@ class ContainerBuilder:
         """
         from hdmi.containers import Container
 
+        # Check for circular dependencies
+        self._check_circular_dependencies()
+
         # Validate scope hierarchy for all registrations
         self._validate_scopes()
 
         # Create and return the validated Container
         return Container(self._definitions)
 
+    def _check_circular_dependencies(self) -> None:
+        """Check for circular dependencies in the dependency graph.
+
+        Uses depth-first search to detect cycles. Fails fast on the first cycle found.
+
+        Raises:
+            CircularDependencyError: If a circular dependency is detected
+        """
+        visited = set()
+        path = []
+
+        def visit(service_type: Type) -> None:
+            if service_type in path:
+                # Found a cycle - build the cycle path
+                cycle_start = path.index(service_type)
+                cycle_path = path[cycle_start:] + [service_type]
+                path_str = " → ".join(cls.__name__ for cls in cycle_path)
+                raise CircularDependencyError(f"Circular dependency detected: {path_str}")
+
+            if service_type in visited:
+                return
+
+            path.append(service_type)
+
+            # Get dependencies that will be injected
+            dependencies = self._get_dependencies(service_type)
+
+            for dep_type in dependencies.values():
+                if dep_type in self._definitions:
+                    visit(dep_type)
+
+            path.pop()
+            visited.add(service_type)
+
+        # Visit all registered services
+        for service_type in self._definitions:
+            visit(service_type)
+
     def _validate_scopes(self) -> None:
         """Validate that scope rules are respected.
 
@@ -104,32 +143,57 @@ class ContainerBuilder:
             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:
+            for dependency_name, dependency_type in dependencies.items():
+                if dependency_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."
-                    )
+                self._validate_scope_compatibility(
+                    service_type, definition, dependency_type, self._definitions[dependency_type]
+                )
+
+    def _validate_scope_compatibility(
+        self,
+        service_type: Type,
+        service_definition: ServiceDefinition,
+        dependency_type: Type,
+        dependency_definition: ServiceDefinition,
+    ) -> None:
+        """Validate that a service's scope is compatible with its dependency's scope.
+
+        Args:
+            service_type: The type of the service being validated
+            service_definition: The definition of the service
+            dependency_type: The type of the dependency
+            dependency_definition: The definition of the dependency
+
+        Raises:
+            ScopeViolationError: If a non-scoped service depends on a scoped service
+        """
+        # Non-scoped services cannot depend on scoped services
+        if not service_definition.scoped and dependency_definition.scoped:
+            service_description = self._format_service_description(service_type, service_definition)
+            dependency_description = self._format_service_description(dependency_type, dependency_definition)
+
+            raise ScopeViolationError(
+                f"{service_description} cannot depend on {dependency_description}. "
+                f"Non-scoped services cannot depend on scoped services because "
+                f"scoped services only exist within a scope context."
+            )
+
+    def _format_service_description(self, service_type: Type, definition: ServiceDefinition) -> str:
+        """Format a service type and definition for error messages.
+
+        Args:
+            service_type: The service type
+            definition: The service definition
+
+        Returns:
+            A formatted string describing the service and its scope
+        """
+        return f"{service_type.__name__} (scoped={definition.scoped}, transient={definition.transient})"
 
     def _get_dependencies(self, service_type: Type) -> dict[str, Type]:
         """Get dependencies that will actually be injected.
@@ -159,29 +223,46 @@ class ContainerBuilder:
             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)
+            dependency_type = self._extract_dependency_type(hints[param_name])
             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)
+            if self._should_inject_dependency(dependency_type, param.default is not inspect.Parameter.empty):
                 dependencies[param_name] = dependency_type
 
         return dependencies
+
+    def _extract_dependency_type(self, type_hint: Type) -> Type | None:
+        """Extract the concrete type from a type hint.
+
+        Handles Optional types by extracting the non-None type.
+        Returns None if no single concrete type can be determined.
+
+        Args:
+            type_hint: The type annotation to process
+
+        Returns:
+            The extracted concrete type, or None if not determinable
+        """
+        return extract_type_from_optional(type_hint)
+
+    def _should_inject_dependency(self, dependency_type: Type, is_optional: bool) -> bool:
+        """Determine if a dependency should be injected.
+
+        Args:
+            dependency_type: The type of the dependency
+            is_optional: Whether the parameter has a default value
+
+        Returns:
+            True if the dependency should be injected, False otherwise
+        """
+        if not is_optional:
+            # Required dependencies are always injected
+            return True
+
+        # Optional dependencies need to be registered AND have autowire=True
+        if dependency_type not in self._definitions:
+            return False
+
+        definition = self._definitions[dependency_type]
+        return definition.autowire

{hdmi-0.1.0rc3.dist-info → hdmi-0.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: hdmi
-Version: 0.1.0rc3
+Version: 0.2.0
 Summary: A dependency injection framework for Python with dynamic late-binding resolution
 Author: Romain Dorgueil
 Author-email: Romain Dorgueil <romain@makersquad.fr>
@@ -41,6 +41,11 @@ Description-Content-Type: text/markdown
 
 # hdmi - Dependency Management Interface
 
+> **Warning: Pre-Alpha Software**
+>
+> hdmi is experimental software in active development. Breaking changes may occur
+> until version 1.0. Use with care in production environments.
+
 A lightweight dependency injection framework for Python 3.13+ with:
 
 - **Type-driven dependency discovery** - Uses Python's standard type annotations
@@ -53,6 +58,7 @@ A lightweight dependency injection framework for Python 3.13+ with:
 ### Simple Example (Singleton Services)
 
 ```python
+import asyncio
 from hdmi import ContainerBuilder
 
 # Define your services
@@ -68,34 +74,43 @@ 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)
+async def main():
+    # 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()
+    # Build validates the dependency graph
+    container = builder.build()
 
-# Resolve services lazily - dependencies are auto-wired!
-user_service = container.get(UserService)
+    # Resolve services lazily - dependencies are auto-wired!
+    user_service = await container.get(UserService)
+
+asyncio.run(main())
 ```
 
 ### 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
+import asyncio
+from hdmi import ContainerBuilder
+
+async def main():
+    # 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()
 
-container = builder.build()
+    # Scoped services must be resolved within a scope context
+    async with container.scope() as scoped:
+        user_service = await scoped.get(UserService)
+        # All scoped dependencies share the same instance within this scope
 
-# 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
+asyncio.run(main())
 ```
 
 ## Key Features
@@ -118,12 +133,12 @@ Services have four lifecycles that are validated at build time:
 The only invalid dependency is when a non-scoped service (singleton or transient) depends on a scoped service.
 
 ```python
-#  Valid: Scoped � Singleton
+# Valid: Scoped -> Singleton
 builder = ContainerBuilder()
 builder.register(DatabaseConnection)  # singleton (default)
 builder.register(UserRepository, scoped=True)
 
-# L Invalid: Singleton � Scoped (raises ScopeViolationError)
+# Invalid: Singleton -> Scoped (raises ScopeViolationError)
 builder = ContainerBuilder()
 builder.register(RequestHandler, scoped=True)
 builder.register(SingletonService)  # singleton depends on scoped!

{hdmi-0.1.0rc3.dist-info → hdmi-0.2.0.dist-info}/RECORD

@@ -1,6 +1,6 @@
 hdmi/__init__.py,sha256=bUVZmkoCG1PgkbS7XrwwXylowF56s7aS_mCA-yHDWu4,748
 hdmi/builders/__init__.py,sha256=uN2EzCY9iFzmcxWrqikw5WDFvr_HuD2PxxYV3C43eKs,293
-hdmi/builders/default.py,sha256=DXxqDtMw3E2XyrfuDq7OALhkAb-ENn_hnvRTczFPcLk,7570
+hdmi/builders/default.py,sha256=Oyiz23IZs0Ks1rLYDZw2D6Sl-pQVxkJpcTwThIu7qHQ,10140
 hdmi/containers/__init__.py,sha256=TD8ReZks3E8CRaThWUzbZmZ4TleSmfMok_5njgNmyew,429
 hdmi/containers/default.py,sha256=jGbOU7a11p2NkWVja6tgBPb_Ngd3DOV-TP0GzhSs7Ds,9782
 hdmi/containers/scoped.py,sha256=c8OlWzQ2oiUxB1fQoB3kcSrGBX8pOw7l_Cg8QfaWzto,4415
@@ -11,6 +11,6 @@ hdmi/types/containers.py,sha256=pdEdu1QynRUDYhYz7h5EyGpB0H2FD8eCP0dXTKaLu5c,906
 hdmi/types/definitions.py,sha256=gqyhBneTex1efrAdBzn7R3bBU8YrOtoZE15cdmQFMTE,1802
 hdmi/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 hdmi/utils/typing.py,sha256=1JdUYZoE0SdX1jci0iGQLJkvBYodImoCQV8S_JcJvyw,1384
-hdmi-0.1.0rc3.dist-info/WHEEL,sha256=w4ZtLaDgMAZW2MMZZwtH8zENekoQYBCeullI-zsXJQk,78
-hdmi-0.1.0rc3.dist-info/METADATA,sha256=wku5qh1Eu0m7JNe-kp1NVpJHqkCK55G6t8gV3T55m8g,5448
-hdmi-0.1.0rc3.dist-info/RECORD,,
+hdmi-0.2.0.dist-info/WHEEL,sha256=iHtWm8nRfs0VRdCYVXocAWFW8ppjHL-uTJkAdZJKOBM,80
+hdmi-0.2.0.dist-info/METADATA,sha256=jOpv684i50C6OMUwvvvUlhdjcwHefvDCWktafcZyA-0,5858
+hdmi-0.2.0.dist-info/RECORD,,

{hdmi-0.1.0rc3.dist-info → hdmi-0.2.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: uv 0.9.9
+Generator: uv 0.9.30
 Root-Is-Purelib: true
-Tag: py3-none-any
+Tag: py3-none-any