anydi 0.41.0__py3-none-any.whl → 0.43.0__py3-none-any.whl

anydi/_container.py

@@ -4,110 +4,75 @@ from __future__ import annotations
 
 import contextlib
 import functools
-import importlib
 import inspect
 import logging
-import pkgutil
 import types
 import uuid
 from collections import defaultdict
-from collections.abc import AsyncIterator, Iterable, Iterator, Sequence
+from collections.abc import AsyncIterator, Iterable, Iterator
 from contextvars import ContextVar
-from types import ModuleType
-from typing import Annotated, Any, Callable, TypeVar, cast, overload
+from typing import Any, Callable, TypeVar, cast, overload
 
-from typing_extensions import Concatenate, ParamSpec, Self, final, get_args, get_origin
+from typing_extensions import ParamSpec, Self, get_args, get_origin
 
+from ._async import run_sync
 from ._context import InstanceContext
-from ._types import (
-    NOT_SET,
-    AnyInterface,
-    Event,
-    InjectableDecoratorArgs,
-    InstanceProxy,
+from ._decorators import is_provided
+from ._module import ModuleDef, ModuleRegistrar
+from ._provider import (
     Provider,
-    ProviderArgs,
-    ProviderDecoratorArgs,
+    ProviderDef,
     ProviderKind,
-    ScannedDependency,
-    Scope,
-    is_event_type,
-    is_marker,
 )
-from ._utils import (
-    get_full_qualname,
+from ._scan import PackageOrIterable, Scanner
+from ._scope import ALLOWED_SCOPES, Scope
+from ._typing import (
+    NOT_SET,
+    Event,
     get_typed_annotation,
     get_typed_parameters,
-    import_string,
     is_async_context_manager,
     is_builtin_type,
     is_context_manager,
+    is_event_type,
     is_iterator_type,
+    is_marker,
     is_none_type,
-    run_async,
+    type_repr,
 )
 
 T = TypeVar("T", bound=Any)
-M = TypeVar("M", bound="Module")
 P = ParamSpec("P")
 
-ALLOWED_SCOPES: dict[Scope, list[Scope]] = {
-    "singleton": ["singleton"],
-    "request": ["request", "singleton"],
-    "transient": ["transient", "request", "singleton"],
-}
-
-
-class ModuleMeta(type):
-    """A metaclass used for the Module base class."""
-
-    def __new__(cls, name: str, bases: tuple[type, ...], attrs: dict[str, Any]) -> Any:
-        attrs["providers"] = [
-            (name, getattr(value, "__provider__"))
-            for name, value in attrs.items()
-            if hasattr(value, "__provider__")
-        ]
-        return super().__new__(cls, name, bases, attrs)
-
-
-class Module(metaclass=ModuleMeta):
-    """A base class for defining AnyDI modules."""
-
-    providers: list[tuple[str, ProviderDecoratorArgs]]
 
-    def configure(self, container: Container) -> None:
-        """Configure the AnyDI container with providers and their dependencies."""
-
-
-@final
 class Container:
     """AnyDI is a dependency injection container."""
 
     def __init__(
         self,
         *,
-        providers: Sequence[ProviderArgs] | None = None,
-        modules: Sequence[Module | type[Module] | Callable[[Container], None] | str]
-        | None = None,
+        providers: Iterable[ProviderDef] | None = None,
+        modules: Iterable[ModuleDef] | None = None,
         strict: bool = False,
         default_scope: Scope = "transient",
-        testing: bool = False,
         logger: logging.Logger | None = None,
     ) -> None:
         self._providers: dict[Any, Provider] = {}
         self._strict = strict
         self._default_scope: Scope = default_scope
-        self._testing = testing
         self._logger = logger or logging.getLogger(__name__)
         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._override_instances: dict[Any, Any] = {}
         self._unresolved_interfaces: set[Any] = set()
         self._inject_cache: dict[Callable[..., Any], Callable[..., Any]] = {}
 
+        # Components
+        self._modules = ModuleRegistrar(self)
+        self._scanner = Scanner(self)
+
         # Register providers
         providers = providers or []
         for provider in providers:
@@ -136,11 +101,6 @@ class Container:
         """Get the default scope."""
         return self._default_scope
 
-    @property
-    def testing(self) -> bool:
-        """Check if testing mode is enabled."""
-        return self._testing
-
     @property
     def providers(self) -> dict[type[Any], Provider]:
         """Get the registered providers."""
@@ -258,7 +218,7 @@ class Container:
 
     def register(
         self,
-        interface: AnyInterface,
+        interface: Any,
         call: Callable[..., Any],
         *,
         scope: Scope,
@@ -267,16 +227,15 @@ class Container:
         """Register a provider for the specified interface."""
         return self._register_provider(call, scope, interface, override)
 
-    def is_registered(self, interface: AnyInterface) -> bool:
+    def is_registered(self, interface: Any) -> bool:
         """Check if a provider is registered for the specified interface."""
         return interface in self._providers
 
-    def unregister(self, interface: AnyInterface) -> None:
+    def unregister(self, interface: Any) -> None:
         """Unregister a provider by interface."""
         if not self.is_registered(interface):
             raise LookupError(
-                "The provider interface "
-                f"`{get_full_qualname(interface)}` not registered."
+                f"The provider interface `{type_repr(interface)}` not registered."
             )
 
         provider = self._get_provider(interface)
@@ -314,7 +273,7 @@ class Container:
         **defaults: Any,
     ) -> Provider:
         """Register a provider with the specified scope."""
-        name = get_full_qualname(call)
+        name = type_repr(call)
         kind = ProviderKind.from_call(call)
         detected_scope = scope
 
@@ -359,8 +318,7 @@ class Container:
         # Check for existing provider
         if interface in self._providers and not override:
             raise LookupError(
-                f"The provider interface `{get_full_qualname(interface)}` "
-                "already registered."
+                f"The provider interface `{type_repr(interface)}` already registered."
             )
 
         unresolved_parameter = None
@@ -421,7 +379,7 @@ class Container:
             else:
                 raise LookupError(
                     f"The provider `{name}` depends on `{unresolved_parameter.name}` "
-                    f"of type `{get_full_qualname(unresolved_parameter.annotation)}`, "
+                    f"of type `{type_repr(unresolved_parameter.annotation)}`, "
                     "which has not been registered or set. To resolve this, ensure "
                     f"that `{unresolved_parameter.name}` is registered before "
                     f"attempting to use it."
@@ -464,19 +422,19 @@ class Container:
                 "with a transient scope, which is not allowed."
             )
 
-    def _get_provider(self, interface: AnyInterface) -> Provider:
+    def _get_provider(self, interface: Any) -> Provider:
         """Get provider by interface."""
         try:
             return self._providers[interface]
         except KeyError as exc:
             raise LookupError(
-                f"The provider interface for `{get_full_qualname(interface)}` has "
+                f"The provider interface for `{type_repr(interface)}` has "
                 "not been registered. Please ensure that the provider interface is "
                 "properly registered before attempting to use it."
             ) from exc
 
     def _get_or_register_provider(
-        self, interface: AnyInterface, parent_scope: Scope | None, /, **defaults: Any
+        self, interface: Any, parent_scope: Scope | None, /, **defaults: Any
     ) -> Provider:
         """Get or register a provider by interface."""
         try:
@@ -484,17 +442,13 @@ class Container:
         except LookupError:
             if self.strict or interface is inspect.Parameter.empty:
                 raise
-            if get_origin(interface) is Annotated and (args := get_args(interface)):
-                call = args[0]
-            else:
-                call = interface
-            if inspect.isclass(call) and not is_builtin_type(call):
+            if inspect.isclass(interface) and not is_builtin_type(interface):
                 # Try to get defined scope
-                if hasattr(call, "__scope__"):
-                    scope = getattr(call, "__scope__")
+                if is_provided(interface):
+                    scope = interface.__provided__["scope"]
                 else:
                     scope = parent_scope
-                return self._register_provider(call, scope, interface, **defaults)
+                return self._register_provider(interface, scope, interface, **defaults)
             raise
 
     def _set_provider(self, provider: Provider) -> None:
@@ -551,7 +505,7 @@ class Container:
         """Create an instance by interface asynchronously."""
         return await self._aresolve_or_create(interface, True, **defaults)
 
-    def is_resolved(self, interface: AnyInterface) -> bool:
+    def is_resolved(self, interface: Any) -> bool:
         """Check if an instance by interface exists."""
         try:
             provider = self._get_provider(interface)
@@ -562,7 +516,7 @@ class Container:
         context = self._get_instance_context(provider.scope)
         return interface in context
 
-    def release(self, interface: AnyInterface) -> None:
+    def release(self, interface: Any) -> None:
         """Release an instance by interface."""
         provider = self._get_provider(interface)
         if provider.scope == "transient":
@@ -597,9 +551,6 @@ class Container:
                     else self._create_instance(provider, context, **defaults)
                 )
 
-        if self.testing:
-            instance = self._patch_test_resolver(provider.interface, instance)
-
         return cast(T, instance)
 
     async def _aresolve_or_create(
@@ -618,9 +569,6 @@ class Container:
                     else await self._acreate_instance(provider, context, **defaults)
                 )
 
-        if self.testing:
-            instance = self._patch_test_resolver(provider.interface, instance)
-
         return cast(T, instance)
 
     def _get_or_create_instance(
@@ -695,9 +643,9 @@ class Container:
                 cm = contextlib.contextmanager(provider.call)(**provider_kwargs)
                 return context.enter(cm)
 
-            return await run_async(_create)
+            return await run_sync(_create)
 
-        instance = await run_async(provider.call, **provider_kwargs)
+        instance = await run_sync(provider.call, **provider_kwargs)
         if (
             context is not None
             and provider.is_class
@@ -712,7 +660,7 @@ class Container:
         """Retrieve the arguments for a provider."""
         provided_kwargs = {}
         for parameter in provider.parameters:
-            instance = self._get_provider_instance(
+            instance, _ = self._get_provider_instance(
                 provider, parameter, context, **defaults
             )
             provided_kwargs[parameter.name] = instance
@@ -725,12 +673,12 @@ class Container:
         context: InstanceContext | None,
         /,
         **defaults: Any,
-    ) -> Any:
+    ) -> tuple[Any, bool]:
         """Retrieve an instance of a dependency from the scoped context."""
 
         # Try to get instance from defaults
         if parameter.name in defaults:
-            return defaults[parameter.name]
+            return defaults[parameter.name], True
 
         # Try to get instance from context
         elif context and parameter.annotation in context:
@@ -743,12 +691,8 @@ class Container:
             except LookupError:
                 if parameter.default is inspect.Parameter.empty:
                     raise
-                return parameter.default
-
-        # Wrap the instance in a proxy for testing
-        if self.testing:
-            return InstanceProxy(instance, interface=parameter.annotation)
-        return instance
+                return parameter.default, True
+        return instance, False
 
     async def _aget_provided_kwargs(
         self, provider: Provider, context: InstanceContext | None, /, **defaults: Any
@@ -756,7 +700,7 @@ class Container:
         """Asynchronously retrieve the arguments for a provider."""
         provided_kwargs = {}
         for parameter in provider.parameters:
-            instance = await self._aget_provider_instance(
+            instance, _ = await self._aget_provider_instance(
                 provider, parameter, context, **defaults
             )
             provided_kwargs[parameter.name] = instance
@@ -769,12 +713,12 @@ class Container:
         context: InstanceContext | None,
         /,
         **defaults: Any,
-    ) -> Any:
+    ) -> tuple[Any, bool]:
         """Asynchronously retrieve an instance of a dependency from the context."""
 
         # Try to get instance from defaults
         if parameter.name in defaults:
-            return defaults[parameter.name]
+            return defaults[parameter.name], True
 
         # Try to get instance from context
         elif context and parameter.annotation in context:
@@ -787,12 +731,8 @@ class Container:
             except LookupError:
                 if parameter.default is inspect.Parameter.empty:
                     raise
-                return parameter.default
-
-        # Wrap the instance in a proxy for testing
-        if self.testing:
-            return InstanceProxy(instance, interface=parameter.annotation)
-        return instance
+                return parameter.default, True
+        return instance, False
 
     def _resolve_parameter(
         self, provider: Provider, parameter: inspect.Parameter
@@ -813,83 +753,11 @@ class Container:
         if parameter.annotation in self._unresolved_interfaces:
             raise LookupError(
                 f"You are attempting to get the parameter `{parameter.name}` with the "
-                f"annotation `{get_full_qualname(parameter.annotation)}` as a "
-                f"dependency into `{get_full_qualname(provider.call)}` which is "
+                f"annotation `{type_repr(parameter.annotation)}` as a "
+                f"dependency into `{type_repr(provider.call)}` which is "
                 "not registered or set in the scoped context."
             )
 
-    @contextlib.contextmanager
-    def override(self, interface: AnyInterface, instance: Any) -> Iterator[None]:
-        """
-        Override the provider for the specified interface with a specific instance.
-        """
-        if not self.testing:
-            raise RuntimeError(
-                "The `override` method can only be used in testing mode."
-            )
-        if not self.is_registered(interface) and self.strict:
-            raise LookupError(
-                f"The provider interface `{get_full_qualname(interface)}` "
-                "not registered."
-            )
-        self._override_instances[interface] = instance
-        try:
-            yield
-        finally:
-            self._override_instances.pop(interface, None)
-
-    ############################
-    # Testing Methods
-    ############################
-
-    def _patch_test_resolver(self, interface: type[Any], instance: Any) -> Any:
-        """Patch the test resolver for the instance."""
-        if interface in self._override_instances:
-            return self._override_instances[interface]
-
-        if not hasattr(instance, "__dict__") or hasattr(
-            instance, "__resolver_getter__"
-        ):
-            return instance
-
-        wrapped = {
-            name: value.interface
-            for name, value in instance.__dict__.items()
-            if isinstance(value, InstanceProxy)
-        }
-
-        def __resolver_getter__(name: str) -> Any:
-            if name in wrapped:
-                _interface = wrapped[name]
-                # Resolve the dependency if it's wrapped
-                return self.resolve(_interface)
-            raise LookupError
-
-        # Attach the resolver getter to the instance
-        instance.__resolver_getter__ = __resolver_getter__
-
-        if not hasattr(instance.__class__, "__getattribute_patched__"):
-
-            def __getattribute__(_self: Any, name: str) -> Any:
-                # Skip the resolver getter
-                if name in {"__resolver_getter__", "__class__"}:
-                    return object.__getattribute__(_self, name)
-
-                if hasattr(_self, "__resolver_getter__"):
-                    try:
-                        return _self.__resolver_getter__(name)
-                    except LookupError:
-                        pass
-
-                # Fall back to default behavior
-                return object.__getattribute__(_self, name)
-
-            # Apply the patched resolver if wrapped attributes exist
-            instance.__class__.__getattribute__ = __getattribute__
-            instance.__class__.__getattribute_patched__ = True
-
-        return instance
-
     ############################
     # Injector Methods
     ############################
@@ -922,6 +790,9 @@ class Container:
             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):
 
@@ -933,7 +804,7 @@ class Container:
 
             self._inject_cache[call] = awrapper
 
-            return awrapper  # type: ignore[return-value]
+            return awrapper  # type: ignore
 
         @functools.wraps(call)
         def wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
@@ -956,9 +827,9 @@ class Container:
             except LookupError as exc:
                 if not self.strict:
                     self.logger.debug(
-                        f"Cannot validate the `{get_full_qualname(call)}` parameter "
+                        f"Cannot validate the `{type_repr(call)}` parameter "
                         f"`{parameter.name}` with an annotation of "
-                        f"`{get_full_qualname(parameter.annotation)} due to being "
+                        f"`{type_repr(parameter.annotation)} due to being "
                         "in non-strict mode. It will be validated at the first call."
                     )
                 else:
@@ -972,215 +843,29 @@ class Container:
         """Validate an injected parameter."""
         if parameter.annotation is inspect.Parameter.empty:
             raise TypeError(
-                f"Missing `{get_full_qualname(call)}` parameter "
-                f"`{parameter.name}` annotation."
+                f"Missing `{type_repr(call)}` parameter `{parameter.name}` annotation."
             )
 
         if not self.is_registered(parameter.annotation):
             raise LookupError(
-                f"`{get_full_qualname(call)}` has an unknown dependency parameter "
+                f"`{type_repr(call)}` has an unknown dependency parameter "
                 f"`{parameter.name}` with an annotation of "
-                f"`{get_full_qualname(parameter.annotation)}`."
+                f"`{type_repr(parameter.annotation)}`."
             )
 
     ############################
     # Module Methods
     ############################
 
-    def register_module(
-        self, module: Module | type[Module] | Callable[[Container], None] | str
-    ) -> None:
+    def register_module(self, module: ModuleDef) -> None:
         """Register a module as a callable, module type, or module instance."""
-        # Callable Module
-        if inspect.isfunction(module):
-            module(self)
-            return
-
-        # Module path
-        if isinstance(module, str):
-            module = import_string(module)
-
-        # Class based Module or Module type
-        if inspect.isclass(module) and issubclass(module, Module):
-            module = module()
-
-        if isinstance(module, Module):
-            module.configure(self)
-            for provider_name, decorator_args in module.providers:
-                obj = getattr(module, provider_name)
-                self.provider(
-                    scope=decorator_args.scope,
-                    override=decorator_args.override,
-                )(obj)
-        else:
-            raise TypeError(
-                "The module must be a callable, a module type, or a module instance."
-            )
+        self._modules.register(module)
 
     ############################
     # Scanner Methods
     ############################
 
     def scan(
-        self,
-        /,
-        packages: ModuleType | str | Iterable[ModuleType | str],
-        *,
-        tags: Iterable[str] | None = None,
+        self, /, packages: PackageOrIterable, *, tags: Iterable[str] | None = None
     ) -> None:
-        """Scan packages or modules for decorated members and inject dependencies."""
-        dependencies: list[ScannedDependency] = []
-
-        if isinstance(packages, ModuleType | str):
-            scan_packages: Iterable[ModuleType | str] = [packages]
-        else:
-            scan_packages = packages
-
-        for package in scan_packages:
-            dependencies.extend(self._scan_package(package, tags=tags))
-
-        for dependency in dependencies:
-            decorator = self.inject()(dependency.member)
-            setattr(dependency.module, dependency.member.__name__, decorator)
-
-    def _scan_package(
-        self,
-        package: ModuleType | str,
-        *,
-        tags: Iterable[str] | None = None,
-    ) -> list[ScannedDependency]:
-        """Scan a package or module for decorated members."""
-        tags = tags or []
-        if isinstance(package, str):
-            package = importlib.import_module(package)
-
-        package_path = getattr(package, "__path__", None)
-
-        if not package_path:
-            return self._scan_module(package, tags=tags)
-
-        dependencies: list[ScannedDependency] = []
-
-        for module_info in pkgutil.walk_packages(
-            path=package_path, prefix=package.__name__ + "."
-        ):
-            module = importlib.import_module(module_info.name)
-            dependencies.extend(self._scan_module(module, tags=tags))
-
-        return dependencies
-
-    def _scan_module(
-        self, module: ModuleType, *, tags: Iterable[str]
-    ) -> list[ScannedDependency]:
-        """Scan a module for decorated members."""
-        dependencies: list[ScannedDependency] = []
-
-        for _, member in inspect.getmembers(module):
-            if getattr(member, "__module__", None) != module.__name__ or not callable(
-                member
-            ):
-                continue
-
-            decorator_args: InjectableDecoratorArgs = getattr(
-                member,
-                "__injectable__",
-                InjectableDecoratorArgs(wrapped=False, tags=[]),
-            )
-
-            if tags and (
-                decorator_args.tags
-                and not set(decorator_args.tags).intersection(tags)
-                or not decorator_args.tags
-            ):
-                continue
-
-            if decorator_args.wrapped:
-                dependencies.append(
-                    self._create_scanned_dependency(member=member, module=module)
-                )
-                continue
-
-            # Get by Marker
-            for parameter in get_typed_parameters(member):
-                if is_marker(parameter.default):
-                    dependencies.append(
-                        self._create_scanned_dependency(member=member, module=module)
-                    )
-                    continue
-
-        return dependencies
-
-    def _create_scanned_dependency(
-        self, member: Any, module: ModuleType
-    ) -> ScannedDependency:
-        """Create a `Dependency` object from the scanned member and module."""
-        if hasattr(member, "__wrapped__"):
-            member = member.__wrapped__
-        return ScannedDependency(member=member, module=module)
-
-
-############################
-# Decorators
-############################
-
-
-def transient(target: T) -> T:
-    """Decorator for marking a class as transient scope."""
-    target.__scope__ = "transient"
-    return target
-
-
-def request(target: T) -> T:
-    """Decorator for marking a class as request scope."""
-    target.__scope__ = "request"
-    return target
-
-
-def singleton(target: T) -> T:
-    """Decorator for marking a class as singleton scope."""
-    target.__scope__ = "singleton"
-    return target
-
-
-def provider(
-    *, scope: Scope, override: bool = False
-) -> Callable[[Callable[Concatenate[M, P], T]], Callable[Concatenate[M, P], T]]:
-    """Decorator for marking a function or method as a provider in a AnyDI module."""
-
-    def decorator(
-        target: Callable[Concatenate[M, P], T],
-    ) -> Callable[Concatenate[M, P], T]:
-        target.__provider__ = ProviderDecoratorArgs(scope=scope, override=override)  # type: ignore
-        return target
-
-    return decorator
-
-
-@overload
-def injectable(func: Callable[P, T]) -> Callable[P, T]: ...
-
-
-@overload
-def injectable(
-    *, tags: Iterable[str] | None = None
-) -> Callable[[Callable[P, T]], Callable[P, T]]: ...
-
-
-def injectable(
-    func: Callable[P, T] | None = None,
-    tags: Iterable[str] | None = None,
-) -> Callable[[Callable[P, T]], Callable[P, T]] | Callable[P, T]:
-    """Decorator for marking a function or method as requiring dependency injection."""
-
-    def decorator(inner: Callable[P, T]) -> Callable[P, T]:
-        setattr(
-            inner,
-            "__injectable__",
-            InjectableDecoratorArgs(wrapped=True, tags=tags),
-        )
-        return inner
-
-    if func is None:
-        return decorator
-
-    return decorator(func)
+        self._scanner.scan(packages=packages, tags=tags)