anydi 0.38.0__py3-none-any.whl → 0.38.2rc0__py3-none-any.whl

anydi/_container.py

@@ -10,23 +10,27 @@ import logging
 import pkgutil
 import threading
 import types
+import uuid
 from collections import defaultdict
 from collections.abc import AsyncIterator, Iterable, Iterator, Sequence
 from contextvars import ContextVar
 from types import ModuleType
-from typing import Any, Callable, TypeVar, Union, cast, overload
-from weakref import WeakKeyDictionary
+from typing import Any, Callable, TypeVar, Union, cast, get_origin, overload
 
-from typing_extensions import Concatenate, ParamSpec, Self, final
+from typing_extensions import Concatenate, ParamSpec, Self, final, get_args
 
 from ._context import InstanceContext
-from ._provider import Provider
 from ._types import (
+    NOT_SET,
     AnyInterface,
-    Dependency,
+    Event,
     InjectableDecoratorArgs,
     InstanceProxy,
+    Provider,
+    ProviderArgs,
     ProviderDecoratorArgs,
+    ProviderKind,
+    ScannedDependency,
     Scope,
     is_event_type,
     is_marker,
@@ -34,6 +38,7 @@ from ._types import (
 from ._utils import (
     AsyncRLock,
     get_full_qualname,
+    get_typed_annotation,
     get_typed_parameters,
     import_string,
     is_async_context_manager,
@@ -42,6 +47,12 @@ from ._utils import (
     run_async,
 )
 
+try:
+    from types import NoneType
+except ImportError:
+    NoneType = type(None)  # type: ignore[misc]
+
+
 T = TypeVar("T", bound=Any)
 M = TypeVar("M", bound="Module")
 P = ParamSpec("P")
@@ -74,7 +85,6 @@ class Module(metaclass=ModuleMeta):
         """Configure the AnyDI container with providers and their dependencies."""
 
 
-# noinspection PyShadowingNames
 @final
 class Container:
     """AnyDI is a dependency injection container."""
@@ -82,7 +92,7 @@ class Container:
     def __init__(
         self,
         *,
-        providers: Sequence[Provider] | None = None,
+        providers: Sequence[ProviderArgs] | None = None,
         modules: Sequence[Module | type[Module] | Callable[[Container], None] | str]
         | None = None,
         strict: bool = False,
@@ -104,20 +114,27 @@ class Container:
         )
         self._override_instances: dict[type[Any], Any] = {}
         self._unresolved_interfaces: set[type[Any]] = set()
-        self._inject_cache: WeakKeyDictionary[
-            Callable[..., Any], Callable[..., Any]
-        ] = WeakKeyDictionary()
+        self._inject_cache: dict[Callable[..., Any], Callable[..., Any]] = {}
 
         # Register providers
         providers = providers or []
         for provider in providers:
-            self._register_provider(provider, False)
+            _provider = self._create_provider(
+                call=provider.call,
+                scope=provider.scope,
+                interface=provider.interface,
+            )
+            self._register_provider(_provider, False)
 
         # Register modules
         modules = modules or []
         for module in modules:
             self.register_module(module)
 
+    ############################
+    # Properties
+    ############################
+
     @property
     def strict(self) -> bool:
         """Check if strict mode is enabled."""
@@ -143,9 +160,110 @@ class Container:
         """Get the logger instance."""
         return self._logger
 
-    def is_registered(self, interface: AnyInterface) -> bool:
-        """Check if a provider is registered for the specified interface."""
-        return interface in self._providers
+    ############################
+    # Lifespan/Context Methods
+    ############################
+
+    def __enter__(self) -> Self:
+        """Enter the singleton context."""
+        self.start()
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: types.TracebackType | None,
+    ) -> Any:
+        """Exit the singleton context."""
+        return self._singleton_context.__exit__(exc_type, exc_val, exc_tb)
+
+    def start(self) -> None:
+        """Start the singleton context."""
+        # Resolve all singleton resources
+        for interface in self._resources.get("singleton", []):
+            self.resolve(interface)
+
+    def close(self) -> None:
+        """Close the singleton context."""
+        self._singleton_context.close()
+
+    async def __aenter__(self) -> Self:
+        """Enter the singleton context."""
+        await self.astart()
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: types.TracebackType | None,
+    ) -> bool:
+        """Exit the singleton context."""
+        return await self._singleton_context.__aexit__(exc_type, exc_val, exc_tb)
+
+    async def astart(self) -> None:
+        """Start the singleton context asynchronously."""
+        for interface in self._resources.get("singleton", []):
+            await self.aresolve(interface)
+
+    async def aclose(self) -> None:
+        """Close the singleton context asynchronously."""
+        await self._singleton_context.aclose()
+
+    @contextlib.contextmanager
+    def request_context(self) -> Iterator[InstanceContext]:
+        """Obtain a context manager for the request-scoped context."""
+        context = InstanceContext()
+
+        token = self._request_context_var.set(context)
+
+        # Resolve all request resources
+        for interface in self._resources.get("request", []):
+            if not is_event_type(interface):
+                continue
+            self.resolve(interface)
+
+        with context:
+            yield context
+            self._request_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()
+
+        token = self._request_context_var.set(context)
+
+        for interface in self._resources.get("request", []):
+            if not is_event_type(interface):
+                continue
+            await self.aresolve(interface)
+
+        async with context:
+            yield context
+            self._request_context_var.reset(token)
+
+    def _get_request_context(self) -> InstanceContext:
+        """Get the current request context."""
+        request_context = self._request_context_var.get()
+        if request_context is None:
+            raise LookupError(
+                "The request context has not been started. Please ensure that "
+                "the request context is properly initialized before attempting "
+                "to use it."
+            )
+        return request_context
+
+    def _get_scoped_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()
+
+    ############################
+    # Provider Methods
+    ############################
 
     def register(
         self,
@@ -156,26 +274,12 @@ class Container:
         override: bool = False,
     ) -> Provider:
         """Register a provider for the specified interface."""
-        provider = Provider(call=call, scope=scope, interface=interface)
+        provider = self._create_provider(call=call, scope=scope, interface=interface)
         return self._register_provider(provider, override)
 
-    def _register_provider(
-        self, provider: Provider, override: bool, /, **defaults: Any
-    ) -> Provider:
-        """Register a provider."""
-        if provider.interface in self._providers:
-            if override:
-                self._set_provider(provider)
-                return provider
-
-            raise LookupError(
-                f"The provider interface `{get_full_qualname(provider.interface)}` "
-                "already registered."
-            )
-
-        self._validate_sub_providers(provider, **defaults)
-        self._set_provider(provider)
-        return provider
+    def is_registered(self, interface: AnyInterface) -> bool:
+        """Check if a provider is registered for the specified interface."""
+        return interface in self._providers
 
     def unregister(self, interface: AnyInterface) -> None:
         """Unregister a provider by interface."""
@@ -199,6 +303,120 @@ class Container:
         # Cleanup provider references
         self._delete_provider(provider)
 
+    def provider(
+        self, *, scope: Scope, override: bool = False
+    ) -> Callable[[Callable[P, T]], Callable[P, T]]:
+        """Decorator to register a provider function with the specified scope."""
+
+        def decorator(call: Callable[P, T]) -> Callable[P, T]:
+            provider = self._create_provider(call=call, scope=scope)
+            self._register_provider(provider, override)
+            return call
+
+        return decorator
+
+    def _create_provider(  # noqa: C901
+        self, call: Callable[..., Any], *, scope: Scope, interface: Any = NOT_SET
+    ) -> Provider:
+        name = get_full_qualname(call)
+
+        # Detect the kind of callable provider
+        kind = ProviderKind.from_call(call)
+
+        # Validate the scope of the provider
+        if scope not in get_args(Scope):
+            raise ValueError(
+                f"The provider `{name}` scope is invalid. Only the following "
+                f"scopes are supported: {', '.join(get_args(Scope))}. "
+                "Please use one of the supported scopes when registering a provider."
+            )
+
+        # Validate the scope of the provider
+        if (
+            kind in {ProviderKind.GENERATOR, ProviderKind.ASYNC_GENERATOR}
+            and scope == "transient"
+        ):
+            raise TypeError(
+                f"The resource provider `{name}` is attempting to register "
+                "with a transient scope, which is not allowed."
+            )
+
+        # Get the signature
+        globalns = getattr(call, "__globals__", {})
+        signature = inspect.signature(call, globals=globalns)
+
+        # Detect the interface
+        if kind == ProviderKind.CLASS:
+            interface = call
+        else:
+            if interface is NOT_SET:
+                interface = signature.return_annotation
+                if interface is inspect.Signature.empty:
+                    interface = None
+                else:
+                    interface = get_typed_annotation(interface, globalns)
+
+            # If the callable is an iterator, return the actual type
+            iterator_types = {Iterator, AsyncIterator}
+            if interface in iterator_types or get_origin(interface) in iterator_types:
+                if args := get_args(interface):
+                    interface = args[0]
+                    # If the callable is a generator, return the resource type
+                    if interface in {None, NoneType}:
+                        interface = type(f"Event_{uuid.uuid4().hex}", (Event,), {})
+                else:
+                    raise TypeError(
+                        f"Cannot use `{name}` resource type annotation "
+                        "without actual type argument."
+                    )
+
+            # None interface is not allowed
+            if interface in {None, NoneType}:
+                raise TypeError(f"Missing `{name}` provider return annotation.")
+
+        # Detect the parameters
+        parameters = []
+        for parameter in signature.parameters.values():
+            if parameter.annotation is inspect.Parameter.empty:
+                raise TypeError(
+                    f"Missing provider `{name}` "
+                    f"dependency `{parameter.name}` annotation."
+                )
+            if parameter.kind == inspect.Parameter.POSITIONAL_ONLY:
+                raise TypeError(
+                    "Positional-only parameters "
+                    f"are not allowed in the provider `{name}`."
+                )
+            annotation = get_typed_annotation(parameter.annotation, globalns)
+            parameters.append(parameter.replace(annotation=annotation))
+
+        return Provider(
+            call=call,
+            scope=scope,
+            interface=interface,
+            name=name,
+            kind=kind,
+            parameters=parameters,
+        )
+
+    def _register_provider(
+        self, provider: Provider, override: bool, /, **defaults: Any
+    ) -> Provider:
+        """Register a provider."""
+        if provider.interface in self._providers:
+            if override:
+                self._set_provider(provider)
+                return provider
+
+            raise LookupError(
+                f"The provider interface `{get_full_qualname(provider.interface)}` "
+                "already registered."
+            )
+
+        self._validate_sub_providers(provider, **defaults)
+        self._set_provider(provider)
+        return provider
+
     def _get_provider(self, interface: AnyInterface) -> Provider:
         """Get provider by interface."""
         try:
@@ -227,9 +445,11 @@ class Container:
                 scope = getattr(interface, "__scope__", parent_scope)
                 # Try to detect scope
                 if scope is None:
-                    scope = self._detect_scope(interface, **defaults)
+                    scope = self._detect_provider_scope(interface, **defaults)
                 scope = scope or self.default_scope
-                provider = Provider(call=interface, scope=scope, interface=interface)
+                provider = self._create_provider(
+                    call=interface, scope=scope, interface=interface
+                )
                 return self._register_provider(provider, False, **defaults)
             raise
 
@@ -250,12 +470,6 @@ class Container:
         """Validate the sub-providers of a provider."""
 
         for parameter in provider.parameters:
-            if parameter.annotation is inspect.Parameter.empty:
-                raise TypeError(
-                    f"Missing provider `{provider}` "
-                    f"dependency `{parameter.name}` annotation."
-                )
-
             try:
                 sub_provider = self._get_or_register_provider(
                     parameter.annotation, provider.scope
@@ -282,7 +496,9 @@ class Container:
                     "Please ensure all providers are registered with matching scopes."
                 )
 
-    def _detect_scope(self, call: Callable[..., Any], **defaults: Any) -> Scope | None:
+    def _detect_provider_scope(
+        self, call: Callable[..., Any], /, **defaults: Any
+    ) -> Scope | None:
         """Detect the scope for a callable."""
         scopes = set()
 
@@ -320,122 +536,56 @@ class Container:
             not self.strict and parameter.default is not inspect.Parameter.empty
         )
 
-    def register_module(
-        self, module: Module | type[Module] | Callable[[Container], None] | str
-    ) -> 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)
-
-    def __enter__(self) -> Self:
-        """Enter the singleton context."""
-        self.start()
-        return self
-
-    def __exit__(
-        self,
-        exc_type: type[BaseException] | None,
-        exc_val: BaseException | None,
-        exc_tb: types.TracebackType | None,
-    ) -> Any:
-        """Exit the singleton context."""
-        return self._singleton_context.__exit__(exc_type, exc_val, exc_tb)
-
-    def start(self) -> None:
-        """Start the singleton context."""
-        # Resolve all singleton resources
-        for interface in self._resources.get("singleton", []):
-            self.resolve(interface)
-
-    def close(self) -> None:
-        """Close the singleton context."""
-        self._singleton_context.close()
-
-    @contextlib.contextmanager
-    def request_context(self) -> Iterator[InstanceContext]:
-        """Obtain a context manager for the request-scoped context."""
-        context = InstanceContext()
-
-        token = self._request_context_var.set(context)
+    ############################
+    # Instance Methods
+    ############################
 
-        # Resolve all request resources
-        for interface in self._resources.get("request", []):
-            if not is_event_type(interface):
-                continue
-            self.resolve(interface)
-
-        with context:
-            yield context
-            self._request_context_var.reset(token)
+    @overload
+    def resolve(self, interface: type[T]) -> T: ...
 
-    async def __aenter__(self) -> Self:
-        """Enter the singleton context."""
-        await self.astart()
-        return self
+    @overload
+    def resolve(self, interface: T) -> T: ...
 
-    async def __aexit__(
-        self,
-        exc_type: type[BaseException] | None,
-        exc_val: BaseException | None,
-        exc_tb: types.TracebackType | None,
-    ) -> bool:
-        """Exit the singleton context."""
-        return await self._singleton_context.__aexit__(exc_type, exc_val, exc_tb)
+    def resolve(self, interface: type[T]) -> T:
+        """Resolve an instance by interface."""
+        return self._resolve_or_create(interface, False)
 
-    async def astart(self) -> None:
-        """Start the singleton context asynchronously."""
-        for interface in self._resources.get("singleton", []):
-            await self.aresolve(interface)
+    @overload
+    async def aresolve(self, interface: type[T]) -> T: ...
 
-    async def aclose(self) -> None:
-        """Close the singleton context asynchronously."""
-        await self._singleton_context.aclose()
+    @overload
+    async def aresolve(self, interface: T) -> T: ...
 
-    @contextlib.asynccontextmanager
-    async def arequest_context(self) -> AsyncIterator[InstanceContext]:
-        """Obtain an async context manager for the request-scoped context."""
-        context = InstanceContext()
+    async def aresolve(self, interface: type[T]) -> T:
+        """Resolve an instance by interface asynchronously."""
+        return await self._aresolve_or_acreate(interface, False)
 
-        token = self._request_context_var.set(context)
+    def create(self, interface: type[T], /, **defaults: Any) -> T:
+        """Create an instance by interface."""
+        return self._resolve_or_create(interface, True, **defaults)
 
-        for interface in self._resources.get("request", []):
-            if not is_event_type(interface):
-                continue
-            await self.aresolve(interface)
+    async def acreate(self, interface: type[T], /, **defaults: Any) -> T:
+        """Create an instance by interface asynchronously."""
+        return await self._aresolve_or_acreate(interface, True, **defaults)
 
-        async with context:
-            yield context
-            self._request_context_var.reset(token)
+    def is_resolved(self, interface: AnyInterface) -> bool:
+        """Check if an instance by interface exists."""
+        try:
+            provider = self._get_provider(interface)
+        except LookupError:
+            return False
+        if provider.scope == "transient":
+            return False
+        context = self._get_scoped_context(provider.scope)
+        return interface in context
 
-    def _get_request_context(self) -> InstanceContext:
-        """Get the current request context."""
-        request_context = self._request_context_var.get()
-        if request_context is None:
-            raise LookupError(
-                "The request context has not been started. Please ensure that "
-                "the request context is properly initialized before attempting "
-                "to use it."
-            )
-        return request_context
+    def release(self, interface: AnyInterface) -> None:
+        """Release an instance by interface."""
+        provider = self._get_provider(interface)
+        if provider.scope == "transient":
+            return None
+        context = self._get_scoped_context(provider.scope)
+        del context[interface]
 
     def reset(self) -> None:
         """Reset resolved instances."""
@@ -448,66 +598,38 @@ class Container:
                 continue
             del context[interface]
 
-    @overload
-    def resolve(self, interface: type[T]) -> T: ...
-
-    @overload
-    def resolve(self, interface: T) -> T: ...
-
-    def resolve(self, interface: type[T]) -> T:
-        """Resolve an instance by interface."""
-        provider = self._get_or_register_provider(interface, None)
+    def _resolve_or_create(
+        self, interface: type[T], create: bool, /, **defaults: Any
+    ) -> T:
+        """Internal method to handle instance resolution and creation."""
+        provider = self._get_or_register_provider(interface, None, **defaults)
         if provider.scope == "transient":
-            instance = self._create_instance(provider, None)
+            instance = self._create_instance(provider, None, **defaults)
         else:
             context = self._get_scoped_context(provider.scope)
             if provider.scope == "singleton":
                 with self._singleton_lock:
-                    instance = self._get_or_create_instance(provider, context)
+                    instance = (
+                        self._get_or_create_instance(provider, context)
+                        if not create
+                        else self._create_instance(provider, context, **defaults)
+                    )
             else:
-                instance = self._get_or_create_instance(provider, context)
-        if self.testing:
-            instance = self._patch_test_resolver(provider.interface, instance)
-        return cast(T, instance)
-
-    @overload
-    async def aresolve(self, interface: type[T]) -> T: ...
-
-    @overload
-    async def aresolve(self, interface: T) -> T: ...
+                instance = (
+                    self._get_or_create_instance(provider, context)
+                    if not create
+                    else self._create_instance(provider, context, **defaults)
+                )
 
-    async def aresolve(self, interface: type[T]) -> T:
-        """Resolve an instance by interface asynchronously."""
-        provider = self._get_or_register_provider(interface, None)
-        if provider.scope == "transient":
-            instance = await self._acreate_instance(provider, None)
-        else:
-            context = self._get_scoped_context(provider.scope)
-            if provider.scope == "singleton":
-                async with self._singleton_async_lock:
-                    instance = await self._aget_or_create_instance(provider, context)
-            else:
-                instance = await self._aget_or_create_instance(provider, context)
         if self.testing:
-            instance = self._patch_test_resolver(interface, instance)
-        return cast(T, instance)
+            instance = self._patch_test_resolver(provider.interface, instance)
 
-    def create(self, interface: type[T], **defaults: Any) -> T:
-        """Create an instance by interface."""
-        provider = self._get_or_register_provider(interface, None, **defaults)
-        if provider.scope == "transient":
-            instance = self._create_instance(provider, None, **defaults)
-        else:
-            context = self._get_scoped_context(provider.scope)
-            if provider.scope == "singleton":
-                with self._singleton_lock:
-                    instance = self._create_instance(provider, context, **defaults)
-            else:
-                instance = self._create_instance(provider, context, **defaults)
         return cast(T, instance)
 
-    async def acreate(self, interface: type[T], **defaults: Any) -> T:
-        """Create an instance by interface."""
+    async def _aresolve_or_acreate(
+        self, interface: type[T], create: bool, /, **defaults: Any
+    ) -> T:
+        """Internal method to handle instance resolution and creation asynchronously."""
         provider = self._get_or_register_provider(interface, None, **defaults)
         if provider.scope == "transient":
             instance = await self._acreate_instance(provider, None, **defaults)
@@ -515,11 +637,21 @@ class Container:
             context = self._get_scoped_context(provider.scope)
             if provider.scope == "singleton":
                 async with self._singleton_async_lock:
-                    instance = await self._acreate_instance(
-                        provider, context, **defaults
+                    instance = (
+                        await self._aget_or_create_instance(provider, context)
+                        if not create
+                        else await self._acreate_instance(provider, context, **defaults)
                     )
             else:
-                instance = await self._acreate_instance(provider, context, **defaults)
+                instance = (
+                    await self._aget_or_create_instance(provider, context)
+                    if not create
+                    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(
@@ -696,26 +828,48 @@ class Container:
     def _resolve_parameter(
         self, provider: Provider, parameter: inspect.Parameter
     ) -> Any:
-        self._validate_resolvable_parameter(parameter, call=provider.call)
+        self._validate_resolvable_parameter(provider, parameter)
         return self.resolve(parameter.annotation)
 
     async def _aresolve_parameter(
         self, provider: Provider, parameter: inspect.Parameter
     ) -> Any:
-        self._validate_resolvable_parameter(parameter, call=provider.call)
+        self._validate_resolvable_parameter(provider, parameter)
         return await self.aresolve(parameter.annotation)
 
     def _validate_resolvable_parameter(
-        self, parameter: inspect.Parameter, call: Callable[..., Any]
+        self, provider: Provider, parameter: inspect.Parameter
     ) -> None:
         """Ensure that the specified interface is resolved."""
         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(call)}` which is not registered "
-                "or set in the scoped context."
+                f"dependency into `{get_full_qualname(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
+        yield
+        del self._override_instances[interface]
+
+    ############################
+    # Testing Methods
+    ############################
 
     def _patch_test_resolver(self, interface: type[Any], instance: Any) -> Any:
         """Patch the test resolver for the instance."""
@@ -765,60 +919,9 @@ class Container:
 
         return instance
 
-    def is_resolved(self, interface: AnyInterface) -> bool:
-        """Check if an instance by interface exists."""
-        try:
-            provider = self._get_provider(interface)
-        except LookupError:
-            return False
-        if provider.scope == "transient":
-            return False
-        context = self._get_scoped_context(provider.scope)
-        return interface in context
-
-    def release(self, interface: AnyInterface) -> None:
-        """Release an instance by interface."""
-        provider = self._get_provider(interface)
-        if provider.scope == "transient":
-            return None
-        context = self._get_scoped_context(provider.scope)
-        del context[interface]
-
-    def _get_scoped_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()
-
-    @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
-        yield
-        del self._override_instances[interface]
-
-    def provider(
-        self, *, scope: Scope, override: bool = False
-    ) -> Callable[[Callable[P, T]], Callable[P, T]]:
-        """Decorator to register a provider function with the specified scope."""
-
-        def decorator(call: Callable[P, T]) -> Callable[P, T]:
-            provider = Provider(call=call, scope=scope)
-            self._register_provider(provider, override)
-            return call
-
-        return decorator
+    ############################
+    # Injector Methods
+    ############################
 
     @overload
     def inject(self, func: Callable[P, T]) -> Callable[P, T]: ...
@@ -838,6 +941,10 @@ class Container:
             return decorator
         return decorator(func)
 
+    def run(self, func: Callable[P, T], /, *args: P.args, **kwargs: P.kwargs) -> 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:
@@ -905,9 +1012,39 @@ class Container:
                 f"`{get_full_qualname(parameter.annotation)}`."
             )
 
-    def run(self, func: Callable[P, T], /, *args: P.args, **kwargs: P.kwargs) -> T:
-        """Run the given function with injected dependencies."""
-        return self._inject(func)(*args, **kwargs)
+    ############################
+    # Module Methods
+    ############################
+
+    def register_module(
+        self, module: Module | type[Module] | Callable[[Container], None] | str
+    ) -> 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)
+
+    ############################
+    # Scanner Methods
+    ############################
 
     def scan(
         self,
@@ -917,7 +1054,7 @@ class Container:
         tags: Iterable[str] | None = None,
     ) -> None:
         """Scan packages or modules for decorated members and inject dependencies."""
-        dependencies: list[Dependency] = []
+        dependencies: list[ScannedDependency] = []
 
         if isinstance(packages, Iterable) and not isinstance(packages, str):
             scan_packages: Iterable[ModuleType | str] = packages
@@ -936,7 +1073,7 @@ class Container:
         package: ModuleType | str,
         *,
         tags: Iterable[str] | None = None,
-    ) -> list[Dependency]:
+    ) -> list[ScannedDependency]:
         """Scan a package or module for decorated members."""
         tags = tags or []
         if isinstance(package, str):
@@ -947,7 +1084,7 @@ class Container:
         if not package_path:
             return self._scan_module(package, tags=tags)
 
-        dependencies: list[Dependency] = []
+        dependencies: list[ScannedDependency] = []
 
         for module_info in pkgutil.walk_packages(
             path=package_path, prefix=package.__name__ + "."
@@ -959,9 +1096,9 @@ class Container:
 
     def _scan_module(
         self, module: ModuleType, *, tags: Iterable[str]
-    ) -> list[Dependency]:
+    ) -> list[ScannedDependency]:
         """Scan a module for decorated members."""
-        dependencies: list[Dependency] = []
+        dependencies: list[ScannedDependency] = []
 
         for _, member in inspect.getmembers(module):
             if getattr(member, "__module__", None) != module.__name__ or not callable(
@@ -984,7 +1121,7 @@ class Container:
 
             if decorator_args.wrapped:
                 dependencies.append(
-                    self._create_dependency(member=member, module=module)
+                    self._create_scanned_dependency(member=member, module=module)
                 )
                 continue
 
@@ -992,17 +1129,24 @@ class Container:
             for parameter in get_typed_parameters(member):
                 if is_marker(parameter.default):
                     dependencies.append(
-                        self._create_dependency(member=member, module=module)
+                        self._create_scanned_dependency(member=member, module=module)
                     )
                     continue
 
         return dependencies
 
-    def _create_dependency(self, member: Any, module: ModuleType) -> Dependency:
+    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 Dependency(member=member, module=module)
+        return ScannedDependency(member=member, module=module)
+
+
+############################
+# Decorators
+############################
 
 
 def transient(target: T) -> T: