anydi 0.38.1__py3-none-any.whl → 0.38.2rc1__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 Annotated, Any, Callable, TypeVar, Union, cast, overload
 
-from typing_extensions import Concatenate, ParamSpec, Self, final
+from typing_extensions import Concatenate, ParamSpec, Self, final, get_args, get_origin
 
 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,26 @@ 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)
+            self._register_provider(
+                provider.call,
+                provider.scope,
+                provider.interface,
+            )
 
         # 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 +159,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 +273,11 @@ class Container:
         override: bool = False,
     ) -> Provider:
         """Register a provider for the specified interface."""
-        provider = Provider(call=call, scope=scope, interface=interface)
-        return self._register_provider(provider, override)
+        return self._register_provider(call, scope, interface, 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,254 +301,233 @@ class Container:
         # Cleanup provider references
         self._delete_provider(provider)
 
-    def _get_provider(self, interface: AnyInterface) -> 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 "
-                "not been registered. Please ensure that the provider interface is "
-                "properly registered before attempting to use it."
-            ) from exc
+    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 _get_or_register_provider(
-        self, interface: AnyInterface, parent_scope: Scope | None, /, **defaults: Any
+        def decorator(call: Callable[P, T]) -> Callable[P, T]:
+            self._register_provider(call, scope, NOT_SET, override)
+            return call
+
+        return decorator
+
+    def _register_provider(  # noqa: C901
+        self,
+        call: Callable[..., Any],
+        scope: Scope | None,
+        interface: Any = NOT_SET,
+        override: bool = False,
+        /,
+        **defaults: Any,
     ) -> Provider:
-        """Get or register a provider by interface."""
-        try:
-            return self._get_provider(interface)
-        except LookupError:
-            if (
-                not self.strict
-                and inspect.isclass(interface)
-                and not is_builtin_type(interface)
-                and interface is not inspect.Parameter.empty
-            ):
-                # Try to get defined scope
-                scope = getattr(interface, "__scope__", parent_scope)
-                # Try to detect scope
-                if scope is None:
-                    scope = self._detect_scope(interface, **defaults)
-                scope = scope or self.default_scope
-                provider = Provider(call=interface, scope=scope, interface=interface)
-                return self._register_provider(provider, False, **defaults)
-            raise
+        """Register a provider with the specified scope."""
+        name = get_full_qualname(call)
+        kind = ProviderKind.from_call(call)
+        detected_scope = scope
+
+        # Validate scope if it provided
+        if scope:
+            self._validate_provider_scope(scope, name, kind)
+
+        # Get the signature
+        globalns = getattr(call, "__globals__", {})
+        module = getattr(call, "__module__", None)
+        signature = inspect.signature(call, globals=globalns)
+
+        # Detect the interface
+        if interface is NOT_SET:
+            if kind == ProviderKind.CLASS:
+                interface = call
+            else:
+                interface = signature.return_annotation
+                if interface is inspect.Signature.empty:
+                    interface = None
+                else:
+                    interface = get_typed_annotation(interface, globalns, module)
+
+        # 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."
+                )
 
-    def _set_provider(self, provider: Provider) -> None:
-        """Set a provider by interface."""
-        self._providers[provider.interface] = provider
-        if provider.is_resource:
-            self._resources[provider.scope].append(provider.interface)
+        # None interface is not allowed
+        if interface in {None, NoneType}:
+            raise TypeError(f"Missing `{name}` provider return annotation.")
 
-    def _delete_provider(self, provider: Provider) -> None:
-        """Delete a provider."""
-        if provider.interface in self._providers:
-            del self._providers[provider.interface]
-        if provider.is_resource:
-            self._resources[provider.scope].remove(provider.interface)
+        # Check for existing provider
+        if interface in self._providers and not override:
+            raise LookupError(
+                f"The provider interface `{get_full_qualname(interface)}` "
+                "already registered."
+            )
 
-    def _validate_sub_providers(self, provider: Provider, /, **defaults: Any) -> None:
-        """Validate the sub-providers of a provider."""
+        unresolved_parameter = None
+        parameters = []
+        scopes = {}
 
-        for parameter in provider.parameters:
+        for parameter in signature.parameters.values():
             if parameter.annotation is inspect.Parameter.empty:
                 raise TypeError(
-                    f"Missing provider `{provider}` "
+                    f"Missing provider `{name}` "
                     f"dependency `{parameter.name}` annotation."
                 )
-
-            try:
-                sub_provider = self._get_or_register_provider(
-                    parameter.annotation, provider.scope
-                )
-            except LookupError:
-                if self._parameter_has_default(parameter, **defaults):
-                    continue
-
-                if provider.scope not in {"singleton", "transient"}:
-                    self._unresolved_interfaces.add(provider.interface)
-                    continue
-                raise ValueError(
-                    f"The provider `{provider}` depends on `{parameter.name}` of type "
-                    f"`{get_full_qualname(parameter.annotation)}`, which "
-                    "has not been registered or set. To resolve this, ensure that "
-                    f"`{parameter.name}` is registered before attempting to use it."
-                ) from None
-
-            # Check scope compatibility
-            if sub_provider.scope not in ALLOWED_SCOPES.get(provider.scope, []):
-                raise ValueError(
-                    f"The provider `{provider}` with a `{provider.scope}` scope cannot "
-                    f"depend on `{sub_provider}` with a `{sub_provider.scope}` scope. "
-                    "Please ensure all providers are registered with matching scopes."
+            if parameter.kind == inspect.Parameter.POSITIONAL_ONLY:
+                raise TypeError(
+                    "Positional-only parameters "
+                    f"are not allowed in the provider `{name}`."
                 )
 
-    def _detect_scope(self, call: Callable[..., Any], **defaults: Any) -> Scope | None:
-        """Detect the scope for a callable."""
-        scopes = set()
+            parameter = parameter.replace(
+                annotation=get_typed_annotation(parameter.annotation, globalns, module)
+            )
 
-        for parameter in get_typed_parameters(call):
             try:
                 sub_provider = self._get_or_register_provider(
-                    parameter.annotation, None
+                    parameter.annotation, scope
                 )
             except LookupError:
                 if self._parameter_has_default(parameter, **defaults):
                     continue
-                raise
-            scope = sub_provider.scope
-
-            if scope == "transient":
-                return "transient"
-            scopes.add(scope)
-
-            # If all scopes are found, we can return based on priority order
-            if {"transient", "request", "singleton"}.issubset(scopes):
-                break  # pragma: no cover
-
-        # Determine scope based on priority
-        if "request" in scopes:
-            return "request"
-        if "singleton" in scopes:
-            return "singleton"
-
-        return None
-
-    def _parameter_has_default(
-        self, parameter: inspect.Parameter, /, **defaults: Any
-    ) -> bool:
-        return (defaults and parameter.name in defaults) or (
-            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)
-
-        # Resolve all request resources
-        for interface in self._resources.get("request", []):
-            if not is_event_type(interface):
+                unresolved_parameter = parameter
                 continue
-            self.resolve(interface)
 
-        with context:
-            yield context
-            self._request_context_var.reset(token)
+            # Store first provider for each scope
+            if sub_provider.scope not in scopes:
+                scopes[sub_provider.scope] = sub_provider
 
-    async def __aenter__(self) -> Self:
-        """Enter the singleton context."""
-        await self.astart()
-        return self
+            parameters.append(parameter)
 
-    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)
+        # Set detected scope
+        if detected_scope is None:
+            if "transient" in scopes:
+                detected_scope = "transient"
+            elif "request" in scopes:
+                detected_scope = "request"
+            elif "singleton" in scopes:
+                detected_scope = "singleton"
+            else:
+                detected_scope = self.default_scope
 
-    async def astart(self) -> None:
-        """Start the singleton context asynchronously."""
-        for interface in self._resources.get("singleton", []):
-            await self.aresolve(interface)
+        # Validate the provider scope after detection
+        if scope is None:
+            self._validate_provider_scope(detected_scope, name, kind)
 
-    async def aclose(self) -> None:
-        """Close the singleton context asynchronously."""
-        await self._singleton_context.aclose()
+        # Check for unresolved parameters
+        if unresolved_parameter:
+            if detected_scope not in {"singleton", "transient"}:
+                self._unresolved_interfaces.add(interface)
+            else:
+                raise LookupError(
+                    f"The provider `{name}` depends on `{unresolved_parameter.name}` "
+                    f"of type `{get_full_qualname(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."
+                ) from None
 
-    @contextlib.asynccontextmanager
-    async def arequest_context(self) -> AsyncIterator[InstanceContext]:
-        """Obtain an async context manager for the request-scoped context."""
-        context = InstanceContext()
+        # Check scope compatibility
+        for sub_provider in scopes.values():
+            if sub_provider.scope not in ALLOWED_SCOPES.get(detected_scope, []):
+                raise ValueError(
+                    f"The provider `{name}` with a `{detected_scope}` scope cannot "
+                    f"depend on `{sub_provider}` with a `{sub_provider.scope}` scope. "
+                    "Please ensure all providers are registered with matching scopes."
+                )
 
-        token = self._request_context_var.set(context)
+        provider = Provider(
+            call=call,
+            scope=detected_scope,
+            interface=interface,
+            name=name,
+            kind=kind,
+            parameters=parameters,
+        )
 
-        for interface in self._resources.get("request", []):
-            if not is_event_type(interface):
-                continue
-            await self.aresolve(interface)
+        self._set_provider(provider)
+        return provider
 
-        async with context:
-            yield context
-            self._request_context_var.reset(token)
+    def _validate_provider_scope(
+        self, scope: Scope, name: str, kind: ProviderKind
+    ) -> None:
+        """Validate the provider scope."""
+        if scope not in (allowed_scopes := get_args(Scope)):
+            raise ValueError(
+                f"The provider `{name}` scope is invalid. Only the following "
+                f"scopes are supported: {', '.join(allowed_scopes)}. "
+                "Please use one of the supported scopes when registering a 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."
+            )
 
-    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_provider(self, interface: AnyInterface) -> Provider:
+        """Get provider by interface."""
+        try:
+            return self._providers[interface]
+        except KeyError as exc:
             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
+                f"The provider interface for `{get_full_qualname(interface)}` has "
+                "not been registered. Please ensure that the provider interface is "
+                "properly registered before attempting to use it."
+            ) from exc
 
-    def reset(self) -> None:
-        """Reset resolved instances."""
-        for interface, provider in self._providers.items():
-            if provider.scope == "transient":
-                continue
-            try:
-                context = self._get_scoped_context(provider.scope)
-            except LookupError:
-                continue
-            del context[interface]
+    def _get_or_register_provider(
+        self, interface: AnyInterface, parent_scope: Scope | None, /, **defaults: Any
+    ) -> Provider:
+        """Get or register a provider by interface."""
+        try:
+            return self._get_provider(interface)
+        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):
+                # Try to get defined scope
+                scope = getattr(interface, "__scope__", parent_scope)
+                return self._register_provider(call, scope, interface, **defaults)
+            raise
+
+    def _set_provider(self, provider: Provider) -> None:
+        """Set a provider by interface."""
+        self._providers[provider.interface] = provider
+        if provider.is_resource:
+            self._resources[provider.scope].append(provider.interface)
+
+    def _delete_provider(self, provider: Provider) -> None:
+        """Delete a provider."""
+        if provider.interface in self._providers:
+            del self._providers[provider.interface]
+        if provider.is_resource:
+            self._resources[provider.scope].remove(provider.interface)
+
+    def _parameter_has_default(
+        self, parameter: inspect.Parameter, /, **defaults: Any
+    ) -> bool:
+        return (defaults and parameter.name in defaults) or (
+            not self.strict and parameter.default is not inspect.Parameter.empty
+        )
+
+    ############################
+    # Instance Methods
+    ############################
 
     @overload
     def resolve(self, interface: type[T]) -> T: ...
@@ -456,19 +537,7 @@ class Container:
 
     def resolve(self, interface: type[T]) -> T:
         """Resolve an instance by interface."""
-        provider = self._get_or_register_provider(interface, None)
-        if provider.scope == "transient":
-            instance = self._create_instance(provider, None)
-        else:
-            context = self._get_scoped_context(provider.scope)
-            if provider.scope == "singleton":
-                with self._singleton_lock:
-                    instance = self._get_or_create_instance(provider, context)
-            else:
-                instance = self._get_or_create_instance(provider, context)
-        if self.testing:
-            instance = self._patch_test_resolver(provider.interface, instance)
-        return cast(T, instance)
+        return self._resolve_or_create(interface, False)
 
     @overload
     async def aresolve(self, interface: type[T]) -> T: ...
@@ -478,22 +547,50 @@ class Container:
 
     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)
+        return await self._aresolve_or_acreate(interface, False)
 
-    def create(self, interface: type[T], **defaults: Any) -> T:
+    def create(self, interface: type[T], /, **defaults: Any) -> T:
         """Create an instance by interface."""
+        return self._resolve_or_create(interface, True, **defaults)
+
+    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)
+
+    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 reset(self) -> None:
+        """Reset resolved instances."""
+        for interface, provider in self._providers.items():
+            if provider.scope == "transient":
+                continue
+            try:
+                context = self._get_scoped_context(provider.scope)
+            except LookupError:
+                continue
+            del context[interface]
+
+    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, **defaults)
@@ -501,15 +598,27 @@ class Container:
             context = self._get_scoped_context(provider.scope)
             if provider.scope == "singleton":
                 with self._singleton_lock:
-                    instance = self._create_instance(provider, context, **defaults)
+                    instance = (
+                        self._get_or_create_instance(provider, context)
+                        if not create
+                        else self._create_instance(provider, context, **defaults)
+                    )
             else:
-                instance = self._create_instance(provider, context, **defaults)
+                instance = (
+                    self._get_or_create_instance(provider, context)
+                    if not create
+                    else self._create_instance(provider, context, **defaults)
+                )
+
         if self.testing:
             instance = self._patch_test_resolver(provider.interface, instance)
+
         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)
@@ -517,13 +626,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(
@@ -700,26 +817,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."""
@@ -769,60 +908,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]: ...
@@ -842,6 +930,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:
@@ -909,9 +1001,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,
@@ -921,7 +1043,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
@@ -940,7 +1062,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):
@@ -951,7 +1073,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__ + "."
@@ -963,9 +1085,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(
@@ -988,7 +1110,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
 
@@ -996,17 +1118,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: