anydi 0.56.0__py3-none-any.whl → 0.58.0__py3-none-any.whl

anydi/__init__.py

@@ -1,10 +1,10 @@
 """AnyDI public objects and functions."""
 
-from ._container import Container
+from ._container import Container, import_container
 from ._decorators import injectable, provided, provider, request, singleton, transient
 from ._module import Module
 from ._provider import ProviderDef as Provider
-from ._types import Inject, Scope
+from ._types import Inject, Provide, Scope
 
 # Alias for dependency auto marker
 # TODO: deprecate it
@@ -15,9 +15,11 @@ __all__ = [
     "Container",
     "Inject",
     "Module",
+    "Provide",
     "Provider",
     "Scope",
     "auto",
+    "import_container",
     "injectable",
     "provided",
     "provider",

anydi/_container.py

@@ -3,43 +3,30 @@
 from __future__ import annotations
 
 import contextlib
-import functools
+import importlib
 import inspect
 import logging
 import types
 import uuid
 from collections import defaultdict
-from collections.abc import AsyncIterator, Callable, Iterable, Iterator
+from collections.abc import AsyncIterator, Callable, Iterable, Iterator, Sequence
 from contextvars import ContextVar
-from typing import Annotated, Any, TypeVar, cast, get_args, get_origin, overload
+from typing import Any, TypeVar, get_args, get_origin, overload
 
 from typing_extensions import ParamSpec, Self, type_repr
 
 from ._context import InstanceContext
 from ._decorators import is_provided
+from ._injector import Injector
 from ._module import ModuleDef, ModuleRegistrar
 from ._provider import Provider, ProviderDef, ProviderKind, ProviderParameter
 from ._resolver import Resolver
 from ._scanner import PackageOrIterable, Scanner
-from ._types import (
-    NOT_SET,
-    Event,
-    Scope,
-    is_event_type,
-    is_inject_marker,
-    is_iterator_type,
-    is_none_type,
-)
+from ._types import NOT_SET, Event, Scope, is_event_type, is_iterator_type, is_none_type
 
 T = TypeVar("T", bound=Any)
 P = ParamSpec("P")
 
-ALLOWED_SCOPES: dict[Scope, list[Scope]] = {
-    "singleton": ["singleton"],
-    "request": ["request", "singleton"],
-    "transient": ["transient", "request", "singleton"],
-}
-
 
 class Container:
     """AnyDI is a dependency injection container."""
@@ -53,18 +40,24 @@ class Container:
     ) -> None:
         self._providers: dict[Any, Provider] = {}
         self._logger = logger or logging.getLogger(__name__)
+        self._scopes: dict[str, Sequence[str]] = {
+            "transient": ("transient", "singleton"),
+            "singleton": ("singleton",),
+        }
+
         self._resources: dict[str, list[Any]] = defaultdict(list)
         self._singleton_context = InstanceContext()
-        self._request_context_var: ContextVar[InstanceContext | None] = ContextVar(
-            "request_context", default=None
-        )
-        self._inject_cache: dict[Callable[..., Any], Callable[..., Any]] = {}
+        self._scoped_context: dict[str, ContextVar[InstanceContext]] = {}
 
         # Components
         self._resolver = Resolver(self)
+        self._injector = Injector(self)
         self._modules = ModuleRegistrar(self)
         self._scanner = Scanner(self)
 
+        # Register default scopes
+        self.register_scope("request")
+
         # Register providers
         providers = providers or []
         for provider in providers:
@@ -141,66 +134,142 @@ class Container:
         await self._singleton_context.aclose()
 
     @contextlib.contextmanager
-    def request_context(self) -> Iterator[InstanceContext]:
+    def scoped_context(self, scope: str) -> Iterator[InstanceContext]:
         """Obtain a context manager for the request-scoped context."""
-        context = InstanceContext()
+        context_var = self._get_scoped_context_var(scope)
 
-        token = self._request_context_var.set(context)
+        # Check if context already exists (re-entering same scope)
+        context = context_var.get(None)
+        if context is not None:
+            # Reuse existing context, don't create a new one
+            yield context
+            return
+
+        # Create new context
+        context = InstanceContext()
+        token = context_var.set(context)
 
         # Resolve all request resources
-        for interface in self._resources.get("request", []):
+        for interface in self._resources.get(scope, []):
             if not is_event_type(interface):
                 continue
             self.resolve(interface)
 
         with context:
             yield context
-            self._request_context_var.reset(token)
+            context_var.reset(token)
 
     @contextlib.asynccontextmanager
-    async def arequest_context(self) -> AsyncIterator[InstanceContext]:
-        """Obtain an async context manager for the request-scoped context."""
-        context = InstanceContext()
+    async def ascoped_context(self, scope: str) -> AsyncIterator[InstanceContext]:
+        """Obtain a context manager for the specified scoped context."""
+        context_var = self._get_scoped_context_var(scope)
+
+        # Check if context already exists (re-entering same scope)
+        context = context_var.get(None)
+        if context is not None:
+            # Reuse existing context, don't create a new one
+            yield context
+            return
 
-        token = self._request_context_var.set(context)
+        # Create new context
+        context = InstanceContext()
+        token = context_var.set(context)
 
-        for interface in self._resources.get("request", []):
+        # Resolve all request resources
+        for interface in self._resources.get(scope, []):
             if not is_event_type(interface):
                 continue
             await self.aresolve(interface)
 
         async with context:
             yield context
-            self._request_context_var.reset(token)
+            context_var.reset(token)
+
+    @contextlib.contextmanager
+    def request_context(self) -> Iterator[InstanceContext]:
+        """Obtain a context manager for the request-scoped context."""
+        with self.scoped_context("request") as context:
+            yield context
+
+    @contextlib.asynccontextmanager
+    async def arequest_context(self) -> AsyncIterator[InstanceContext]:
+        """Obtain an async context manager for the request-scoped context."""
+        async with self.ascoped_context("request") as context:
+            yield context
 
-    def _get_request_context(self) -> InstanceContext:
-        """Get the current request context."""
-        request_context = self._request_context_var.get()
-        if request_context is None:
+    def _get_scoped_context(self, scope: str) -> InstanceContext:
+        scoped_context_var = self._get_scoped_context_var(scope)
+        try:
+            scoped_context = scoped_context_var.get()
+        except LookupError as exc:
             raise LookupError(
-                "The request context has not been started. Please ensure that "
-                "the request context is properly initialized before attempting "
+                f"The {scope} context has not been started. Please ensure that "
+                f"the {scope} context is properly initialized before attempting "
                 "to use it."
+            ) from exc
+        return scoped_context
+
+    def _get_scoped_context_var(self, scope: str) -> ContextVar[InstanceContext]:
+        """Get the context variable for the specified scope."""
+        # Validate that scope is registered and not reserved
+        if scope in ("transient", "singleton"):
+            raise ValueError(
+                f"Cannot get context variable for reserved scope `{scope}`."
             )
-        return request_context
+        if scope not in self._scopes:
+            raise ValueError(
+                f"Cannot get context variable for not registered scope `{scope}`. "
+                f"Please register the scope first using register_scope()."
+            )
+
+        if scope not in self._scoped_context:
+            self._scoped_context[scope] = ContextVar(f"{scope}_context")
+        return self._scoped_context[scope]
 
     def _get_instance_context(self, scope: Scope) -> InstanceContext:
         """Get the instance context for the specified scope."""
         if scope == "singleton":
             return self._singleton_context
-        return self._get_request_context()
+        return self._get_scoped_context(scope)
+
+    # == Scopes == #
+
+    def register_scope(
+        self, scope: str, *, parents: Sequence[str] | None = None
+    ) -> None:
+        """Register a new scope with the specified parents."""
+        # Check if the scope is reserved
+        if scope in ("transient", "singleton"):
+            raise ValueError(
+                f"The scope `{scope}` is reserved and cannot be overridden."
+            )
+
+        # Check if the scope is already registered
+        if scope in self._scopes:
+            raise ValueError(f"The scope `{scope}` is already registered.")
+
+        # Validate parents
+        parents = parents or []
+        for parent in parents:
+            if parent not in self._scopes:
+                raise ValueError(f"The parent scope `{parent}` is not registered.")
+
+        # Register the scope
+        self._scopes[scope] = tuple({scope, "singleton"} | set(parents))
 
     # == Provider Registry ==
 
     def register(
         self,
         interface: Any,
-        call: Callable[..., Any],
+        call: Callable[..., Any] = NOT_SET,
         *,
-        scope: Scope,
+        scope: Scope = "singleton",
         override: bool = False,
     ) -> Provider:
         """Register a provider for the specified interface."""
+        if call is NOT_SET:
+            call = interface
         return self._register_provider(call, scope, interface, override)
 
     def is_registered(self, interface: Any) -> bool:
@@ -298,7 +367,7 @@ class Container:
         unresolved_parameter = None
         unresolved_exc: LookupError | None = None
         parameters: list[ProviderParameter] = []
-        scopes: dict[Scope, Provider] = {}
+        scope_provider: dict[Scope, Provider] = {}
 
         for parameter in signature.parameters.values():
             if parameter.annotation is inspect.Parameter.empty:
@@ -329,8 +398,8 @@ class Container:
                 continue
 
             # Store first provider for each scope
-            if sub_provider.scope not in scopes:
-                scopes[sub_provider.scope] = sub_provider
+            if sub_provider.scope not in scope_provider:
+                scope_provider[sub_provider.scope] = sub_provider
 
             parameters.append(
                 ProviderParameter(
@@ -343,6 +412,18 @@ class Container:
                 )
             )
 
+        # Check scope compatibility
+        # Transient scope can use any scoped dependencies
+        if scope != "transient":
+            for sub_provider in scope_provider.values():
+                if sub_provider.scope not in self._scopes.get(scope, []):
+                    raise ValueError(
+                        f"The provider `{name}` with a `{scope}` scope "
+                        f"cannot depend on `{sub_provider}` with a "
+                        f"`{sub_provider.scope}` scope. Please ensure all "
+                        "providers are registered with matching scopes."
+                    )
+
         # Check for unresolved parameters
         if unresolved_parameter:
             if scope not in ("singleton", "transient"):
@@ -356,15 +437,6 @@ class Container:
                     f"attempting to use it."
                 ) from unresolved_exc
 
-        # Check scope compatibility
-        for sub_provider in scopes.values():
-            if sub_provider.scope not in ALLOWED_SCOPES.get(scope, []):
-                raise ValueError(
-                    f"The provider `{name}` with a `{scope}` scope cannot "
-                    f"depend on `{sub_provider}` with a `{sub_provider.scope}` scope. "
-                    "Please ensure all providers are registered with matching scopes."
-                )
-
         is_coroutine = kind == ProviderKind.COROUTINE
         is_generator = kind == ProviderKind.GENERATOR
         is_async_generator = kind == ProviderKind.ASYNC_GENERATOR
@@ -387,13 +459,14 @@ class Container:
         self._set_provider(provider)
         return provider
 
-    @staticmethod
-    def _validate_provider_scope(scope: Scope, name: str, is_resource: bool) -> None:
+    def _validate_provider_scope(
+        self, scope: Scope, name: str, is_resource: bool
+    ) -> None:
         """Validate the provider scope."""
-        if scope not in ALLOWED_SCOPES:
+        if scope not in self._scopes:
             raise ValueError(
                 f"The provider `{name}` scope is invalid. Only the following "
-                f"scopes are supported: {', '.join(ALLOWED_SCOPES)}. "
+                f"scopes are supported: {', '.join(self._scopes.keys())}. "
                 "Please use one of the supported scopes when registering a provider."
             )
         if scope == "transient" and is_resource:
@@ -548,115 +621,21 @@ class Container:
         """Decorator to inject dependencies into a callable."""
 
         def decorator(call: Callable[P, T]) -> Callable[P, T]:
-            return self._inject(call)
+            return self._injector.inject(call)
 
         if func is None:
             return decorator
         return decorator(func)
 
-    def run(self, func: Callable[P, T], /, *args: P.args, **kwargs: P.kwargs) -> T:
+    def run(self, func: Callable[..., T], /, *args: Any, **kwargs: Any) -> T:
         """Run the given function with injected dependencies."""
-        return self._inject(func)(*args, **kwargs)
-
-    def _inject(self, call: Callable[P, T]) -> Callable[P, T]:
-        """Inject dependencies into a callable."""
-        if call in self._inject_cache:
-            return cast(Callable[P, T], self._inject_cache[call])
-
-        injected_params = self._get_injected_params(call)
-        if not injected_params:
-            self._inject_cache[call] = call
-            return call
-
-        if inspect.iscoroutinefunction(call):
-
-            @functools.wraps(call)
-            async def awrapper(*args: P.args, **kwargs: P.kwargs) -> T:
-                for name, annotation in injected_params.items():
-                    kwargs[name] = await self.aresolve(annotation)
-                return cast(T, await call(*args, **kwargs))
-
-            self._inject_cache[call] = awrapper
-
-            return awrapper  # type: ignore
-
-        @functools.wraps(call)
-        def wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
-            for name, annotation in injected_params.items():
-                kwargs[name] = self.resolve(annotation)
-            return call(*args, **kwargs)
-
-        self._inject_cache[call] = wrapper
-
-        return wrapper
-
-    def _get_injected_params(self, call: Callable[..., Any]) -> dict[str, Any]:
-        """Get the injected parameters of a callable object."""
-        injected_params: dict[str, Any] = {}
-        for parameter in inspect.signature(call, eval_str=True).parameters.values():
-            interface, should_inject = self.validate_injected_parameter(
-                parameter, call=call
-            )
-            if should_inject:
-                injected_params[parameter.name] = interface
-        return injected_params
-
-    @staticmethod
-    def _unwrap_injected_parameter(parameter: inspect.Parameter) -> inspect.Parameter:
-        if get_origin(parameter.annotation) is not Annotated:
-            return parameter
-
-        origin, *metadata = get_args(parameter.annotation)
-
-        if not metadata or not is_inject_marker(metadata[-1]):
-            return parameter
-
-        if is_inject_marker(parameter.default):
-            raise TypeError(
-                "Cannot specify `Inject` in `Annotated` and "
-                f"default value together for '{parameter.name}'"
-            )
-
-        if parameter.default is not inspect.Parameter.empty:
-            return parameter
-
-        marker = metadata[-1]
-        new_metadata = metadata[:-1]
-        if new_metadata:
-            if hasattr(Annotated, "__getitem__"):
-                new_annotation = Annotated.__getitem__((origin, *new_metadata))  # type: ignore
-            else:
-                new_annotation = Annotated.__class_getitem__((origin, *new_metadata))  # type: ignore
-        else:
-            new_annotation = origin
-        return parameter.replace(annotation=new_annotation, default=marker)
+        return self._injector.inject(func)(*args, **kwargs)
 
     def validate_injected_parameter(
         self, parameter: inspect.Parameter, *, call: Callable[..., Any]
     ) -> tuple[Any, bool]:
         """Validate an injected parameter."""
-        parameter = self._unwrap_injected_parameter(parameter)
-        interface = parameter.annotation
-
-        if not is_inject_marker(parameter.default):
-            return interface, False
-
-        if interface is inspect.Parameter.empty:
-            raise TypeError(
-                f"Missing `{type_repr(call)}` parameter `{parameter.name}` annotation."
-            )
-
-        # Set inject marker interface
-        parameter.default.interface = interface
-
-        if not self.has_provider_for(interface):
-            raise LookupError(
-                f"`{type_repr(call)}` has an unknown dependency parameter "
-                f"`{parameter.name}` with an annotation of "
-                f"`{type_repr(interface)}`."
-            )
-
-        return interface, True
+        return self._injector.validate_parameter(parameter, call=call)
 
     # == Module Registration ==
 
@@ -685,3 +664,48 @@ class Container:
             yield
         finally:
             self._resolver.remove_override(interface)
+
+
+def import_container(container_path: str) -> Container:
+    """Import container from a string path."""
+    # Replace colon with dot for unified processing
+    container_path = container_path.replace(":", ".")
+
+    try:
+        module_path, attr_name = container_path.rsplit(".", 1)
+    except ValueError as exc:
+        raise ImportError(
+            f"Invalid container path '{container_path}'. "
+            "Expected format: 'module.path:attribute' or 'module.path.attribute'"
+        ) from exc
+
+    try:
+        module = importlib.import_module(module_path)
+    except ImportError as exc:
+        raise ImportError(
+            f"Failed to import module '{module_path}' "
+            f"from container path '{container_path}'"
+        ) from exc
+
+    try:
+        container_or_factory = getattr(module, attr_name)
+    except AttributeError as exc:
+        raise ImportError(
+            f"Module '{module_path}' has no attribute '{attr_name}'"
+        ) from exc
+
+    # If it's a callable (factory), call it
+    if callable(container_or_factory) and not isinstance(
+        container_or_factory, Container
+    ):
+        container = container_or_factory()
+    else:
+        container = container_or_factory
+
+    if not isinstance(container, Container):
+        raise ImportError(
+            f"Expected Container instance, got {type(container).__name__} "
+            f"from '{container_path}'"
+        )
+
+    return container

anydi/_injector.py

@@ -0,0 +1,132 @@
+"""Dependency injection utilities."""
+
+from __future__ import annotations
+
+import functools
+import inspect
+from collections.abc import Callable
+from typing import (
+    TYPE_CHECKING,
+    Annotated,
+    Any,
+    TypeVar,
+    cast,
+    get_args,
+    get_origin,
+)
+
+from typing_extensions import ParamSpec, type_repr
+
+from ._types import is_provide_marker
+
+if TYPE_CHECKING:
+    from ._container import Container
+
+T = TypeVar("T", bound=Any)
+P = ParamSpec("P")
+
+
+class Injector:
+    """Handles dependency injection for callables."""
+
+    def __init__(self, container: Container) -> None:
+        self.container = container
+        self._cache: dict[Callable[..., Any], Callable[..., Any]] = {}
+
+    def inject(self, call: Callable[P, T]) -> Callable[P, T]:
+        """Inject dependencies into a callable."""
+        if call in self._cache:
+            return cast(Callable[P, T], self._cache[call])
+
+        injected_params = self._get_injected_params(call)
+        if not injected_params:
+            self._cache[call] = call
+            return call
+
+        if inspect.iscoroutinefunction(call):
+
+            @functools.wraps(call)
+            async def awrapper(*args: P.args, **kwargs: P.kwargs) -> T:
+                for name, annotation in injected_params.items():
+                    kwargs[name] = await self.container.aresolve(annotation)
+                return cast(T, await call(*args, **kwargs))
+
+            self._cache[call] = awrapper
+
+            return awrapper  # type: ignore
+
+        @functools.wraps(call)
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
+            for name, annotation in injected_params.items():
+                kwargs[name] = self.container.resolve(annotation)
+            return call(*args, **kwargs)
+
+        self._cache[call] = wrapper
+
+        return wrapper
+
+    def _get_injected_params(self, call: Callable[..., Any]) -> dict[str, Any]:
+        """Get the injected parameters of a callable object."""
+        injected_params: dict[str, Any] = {}
+        for parameter in inspect.signature(call, eval_str=True).parameters.values():
+            interface, should_inject = self.validate_parameter(parameter, call=call)
+            if should_inject:
+                injected_params[parameter.name] = interface
+        return injected_params
+
+    def validate_parameter(
+        self, parameter: inspect.Parameter, *, call: Callable[..., Any]
+    ) -> tuple[Any, bool]:
+        """Validate an injected parameter."""
+        parameter = self.unwrap_parameter(parameter)
+        interface = parameter.annotation
+
+        if not is_provide_marker(parameter.default):
+            return interface, False
+
+        if interface is inspect.Parameter.empty:
+            raise TypeError(
+                f"Missing `{type_repr(call)}` parameter `{parameter.name}` annotation."
+            )
+
+        # Set inject marker interface
+        parameter.default.interface = interface
+
+        if not self.container.has_provider_for(interface):
+            raise LookupError(
+                f"`{type_repr(call)}` has an unknown dependency parameter "
+                f"`{parameter.name}` with an annotation of "
+                f"`{type_repr(interface)}`."
+            )
+
+        return interface, True
+
+    @staticmethod
+    def unwrap_parameter(parameter: inspect.Parameter) -> inspect.Parameter:
+        if get_origin(parameter.annotation) is not Annotated:
+            return parameter
+
+        origin, *metadata = get_args(parameter.annotation)
+
+        if not metadata or not is_provide_marker(metadata[-1]):
+            return parameter
+
+        if is_provide_marker(parameter.default):
+            raise TypeError(
+                "Cannot specify `Inject` in `Annotated` and "
+                f"default value together for '{parameter.name}'"
+            )
+
+        if parameter.default is not inspect.Parameter.empty:
+            return parameter
+
+        marker = metadata[-1]
+        new_metadata = metadata[:-1]
+        if new_metadata:
+            if hasattr(Annotated, "__getitem__"):
+                new_annotation = Annotated.__getitem__((origin, *new_metadata))  # type: ignore
+            else:
+                new_annotation = Annotated.__class_getitem__((origin, *new_metadata))  # type: ignore
+        else:
+            new_annotation = origin
+        return parameter.replace(annotation=new_annotation, default=marker)