anydi 0.67.1__py3-none-any.whl → 0.68.0__py3-none-any.whl

anydi/_container.py

@@ -8,29 +8,24 @@ import inspect
 import logging
 import types
 import uuid
+import warnings
 from collections import defaultdict
 from collections.abc import AsyncIterator, Callable, Iterable, Iterator, Sequence
 from contextvars import ContextVar
-from typing import Any, TypeVar, get_args, get_origin, overload
+from typing import Any, Literal, TypeVar, get_args, get_origin, overload
 
 from typing_extensions import ParamSpec, Self, type_repr
 
 from ._context import InstanceContext
 from ._decorators import is_provided
+from ._graph import Graph
 from ._injector import Injector
 from ._marker import Marker
 from ._module import ModuleDef, ModuleRegistrar
 from ._provider import Provider, ProviderDef, ProviderKind, ProviderParameter
 from ._resolver import Resolver
 from ._scanner import PackageOrIterable, Scanner
-from ._types import (
-    NOT_SET,
-    Event,
-    Scope,
-    is_event_type,
-    is_iterator_type,
-    is_none_type,
-)
+from ._types import NOT_SET, Event, Scope, is_event_type, is_iterator_type, is_none_type
 
 T = TypeVar("T", bound=Any)
 P = ParamSpec("P")
@@ -62,24 +57,30 @@ class Container:
         self._injector = Injector(self)
         self._modules = ModuleRegistrar(self)
         self._scanner = Scanner(self)
+        self._graph = Graph(self)
+
+        # Build state
+        self._ready = False
+
+        # Test mode (enables override support for all resolutions)
+        self._test_mode = False
 
         # Register default scopes
         self.register_scope("request")
 
         # Register self as provider
-        self._register_provider(
-            lambda: self,
-            "singleton",
-            Container,
-        )
+        self.register(Container, lambda: self, scope="singleton")
 
         # Register providers
         providers = providers or []
         for provider in providers:
             self._register_provider(
-                provider.call,
+                provider.dependency_type,
+                provider.factory,
                 provider.scope,
-                provider.interface,
+                provider.from_context,
+                False,
+                None,
             )
 
         # Register modules
@@ -94,6 +95,11 @@ class Container:
         """Get the registered providers."""
         return self._providers
 
+    @property
+    def ready(self) -> bool:
+        """Check if the container is ready."""
+        return self._ready
+
     @property
     def logger(self) -> logging.Logger:
         """Get the logger instance."""
@@ -118,8 +124,8 @@ class Container:
     def start(self) -> None:
         """Start the singleton context."""
         # Resolve all singleton resources
-        for interface in self._resources.get("singleton", []):
-            self.resolve(interface)
+        for dependency_type in self._resources.get("singleton", []):
+            self.resolve(dependency_type)
 
     def close(self) -> None:
         """Close the singleton context."""
@@ -141,8 +147,8 @@ class Container:
 
     async def astart(self) -> None:
         """Start the singleton context asynchronously."""
-        for interface in self._resources.get("singleton", []):
-            await self.aresolve(interface)
+        for dependency_type in self._resources.get("singleton", []):
+            await self.aresolve(dependency_type)
 
     async def aclose(self) -> None:
         """Close the singleton context asynchronously."""
@@ -165,10 +171,10 @@ class Container:
         token = context_var.set(context)
 
         # Resolve all request resources
-        for interface in self._resources.get(scope, []):
-            if not is_event_type(interface):
+        for dependency_type in self._resources.get(scope, []):
+            if not is_event_type(dependency_type):
                 continue
-            self.resolve(interface)
+            self.resolve(dependency_type)
 
         with context:
             yield context
@@ -191,10 +197,10 @@ class Container:
         token = context_var.set(context)
 
         # Resolve all request resources
-        for interface in self._resources.get(scope, []):
-            if not is_event_type(interface):
+        for dependency_type in self._resources.get(scope, []):
+            if not is_event_type(dependency_type):
                 continue
-            await self.aresolve(interface)
+            await self.aresolve(dependency_type)
 
         async with context:
             yield context
@@ -327,33 +333,59 @@ class Container:
 
     def register(
         self,
-        interface: Any,
-        call: Callable[..., Any] = NOT_SET,
+        dependency_type: Any = NOT_SET,
+        factory: Callable[..., Any] = NOT_SET,
         *,
         scope: Scope = "singleton",
+        from_context: bool = False,
         override: bool = False,
+        interface: Any = NOT_SET,
+        call: Callable[..., Any] = NOT_SET,
     ) -> Provider:
-        """Register a provider for the specified interface."""
-        if call is NOT_SET:
-            call = interface
-        return self._register_provider(call, scope, interface, override)
-
-    def is_registered(self, interface: Any) -> bool:
-        """Check if a provider is registered for the specified interface."""
-        return interface in self._providers
-
-    def has_provider_for(self, interface: Any) -> bool:
-        """Check if a provider exists for the specified interface."""
-        return self.is_registered(interface) or is_provided(interface)
-
-    def unregister(self, interface: Any) -> None:
-        """Unregister a provider by interface."""
-        if not self.is_registered(interface):
+        """Register a provider for the specified dependency type."""
+        if self.ready and not override:
+            raise RuntimeError(
+                "Cannot register providers after build() has been called. "
+                "All providers must be registered before building the container."
+            )
+
+        if interface is not NOT_SET:
+            warnings.warn(
+                "The `interface` is deprecated. Use `dependency_type` instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        if call is not NOT_SET:
+            warnings.warn(
+                "The `call` is deprecated. Use `factory` instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+
+        if dependency_type is NOT_SET:
+            dependency_type = interface
+        if factory is NOT_SET:
+            factory = call if call is not NOT_SET else dependency_type
+        return self._register_provider(
+            dependency_type, factory, scope, from_context, override, None
+        )
+
+    def is_registered(self, dependency_type: Any, /) -> bool:
+        """Check if a provider is registered for the specified dependency type."""
+        return dependency_type in self._providers
+
+    def has_provider_for(self, dependency_type: Any, /) -> bool:
+        """Check if a provider exists for the specified dependency type."""
+        return self.is_registered(dependency_type) or is_provided(dependency_type)
+
+    def unregister(self, dependency_type: Any, /) -> None:
+        """Unregister a provider by dependency type."""
+        if not self.is_registered(dependency_type):
             raise LookupError(
-                f"The provider interface `{type_repr(interface)}` not registered."
+                f"The provider `{type_repr(dependency_type)}` is not registered."
             )
 
-        provider = self._get_provider(interface)
+        provider = self._get_provider(dependency_type)
 
         # Cleanup instance context
         if provider.scope != "transient":
@@ -362,7 +394,7 @@ class Container:
             except LookupError:
                 pass
             else:
-                del context[interface]
+                del context[dependency_type]
 
         # Cleanup provider references
         self._delete_provider(provider)
@@ -373,334 +405,461 @@ class Container:
         """Decorator to register a provider function with the specified scope."""
 
         def decorator(call: Callable[P, T]) -> Callable[P, T]:
-            self._register_provider(call, scope, NOT_SET, override)
+            self._register_provider(NOT_SET, call, scope, False, override, None)
             return call
 
         return decorator
 
     def _register_provider(  # noqa: C901
         self,
-        call: Callable[..., Any],
+        dependency_type: Any,
+        factory: Callable[..., Any],
         scope: Scope,
-        interface: Any = NOT_SET,
-        override: bool = False,
-        defaults: dict[str, Any] | None = None,
+        from_context: bool,
+        override: bool,
+        defaults: dict[str, Any] | None,
     ) -> Provider:
         """Register a provider with the specified scope."""
-        name = type_repr(call)
-        kind = ProviderKind.from_call(call)
-        is_class = kind == ProviderKind.CLASS
-        is_coroutine = kind == ProviderKind.COROUTINE
-        is_generator = kind == ProviderKind.GENERATOR
-        is_async_generator = kind == ProviderKind.ASYNC_GENERATOR
-        is_resource = is_generator or is_async_generator
-
-        # Validate scope
-        self._validate_provider_scope(scope, name, is_resource)
-
-        # Get signature and detect interface
-        signature = inspect.signature(call, eval_str=True)
-
-        if interface is NOT_SET:
-            interface = call if is_class else signature.return_annotation
-            if interface is inspect.Signature.empty:
-                interface = None
-
-        # Handle iterator types for resources
-        interface_origin = get_origin(interface)
-        if is_iterator_type(interface) or is_iterator_type(interface_origin):
-            if args := get_args(interface):
-                interface = args[0]
-                if is_none_type(interface):
-                    interface = type(f"Event_{uuid.uuid4().hex}", (Event,), {})
-            else:
-                raise TypeError(
-                    f"Cannot use `{name}` resource type annotation "
-                    "without actual type argument."
-                )
-
-        # Validate interface
-        if is_none_type(interface):
-            raise TypeError(f"Missing `{name}` provider return annotation.")
-
-        if interface in self._providers and not override:
-            raise LookupError(
-                f"The provider interface `{type_repr(interface)}` already registered."
+        # Validate scope is registered
+        if scope not in self._scopes:
+            raise ValueError(
+                f"The scope `{scope}` is not registered. "
+                "Please register the scope first using register_scope()."
             )
 
-        # Process parameters
-        parameters: list[ProviderParameter] = []
-        scope_provider: dict[Scope, Provider] = {}
-        unresolved_parameter = None
-        unresolved_exc: LookupError | None = None
-        is_scoped = scope not in ("singleton", "transient")
-        scope_hierarchy = self._scopes.get(scope, ()) if scope != "transient" else ()
+        # Default factory to dependency_type if not set
+        if not from_context and factory is NOT_SET:
+            factory = dependency_type
 
-        for parameter in signature.parameters.values():
-            if parameter.annotation is inspect.Parameter.empty:
+        # Handle from_context providers (context-provided dependencies)
+        if from_context:
+            if scope in ("singleton", "transient"):
+                raise ValueError(
+                    f"The `from_context=True` option cannot be used with "
+                    f"`{scope}` scope. Use a scoped context like 'request' instead."
+                )
+            if dependency_type is NOT_SET:
                 raise TypeError(
-                    f"Missing provider `{name}` "
-                    f"dependency `{parameter.name}` annotation."
+                    "The `dependency_type` parameter is required when using "
+                    "`from_context=True`."
                 )
-            if parameter.kind == inspect.Parameter.POSITIONAL_ONLY:
+            if dependency_type in self._providers and not override:
+                raise LookupError(
+                    f"The provider `{type_repr(dependency_type)}` is already "
+                    "registered."
+                )
+
+            provider = Provider(
+                dependency_type=dependency_type,
+                factory=lambda: None,
+                scope=scope,
+                from_context=True,
+                parameters=(),
+                is_class=False,
+                is_coroutine=False,
+                is_generator=False,
+                is_async_generator=False,
+                is_async=False,
+                is_resource=False,
+            )
+        else:
+            # Regular provider registration
+            name = type_repr(factory)
+            kind = ProviderKind.from_call(factory)
+            is_class = kind == ProviderKind.CLASS
+            is_coroutine = kind == ProviderKind.COROUTINE
+            is_generator = kind == ProviderKind.GENERATOR
+            is_async_generator = kind == ProviderKind.ASYNC_GENERATOR
+            is_resource = is_generator or is_async_generator
+
+            if scope == "transient" and is_resource:
                 raise TypeError(
-                    "Positional-only parameters "
-                    f"are not allowed in the provider `{name}`."
+                    f"The resource provider `{name}` is attempting to register "
+                    "with a transient scope, which is not allowed."
                 )
 
-            has_default = parameter.default is not inspect.Parameter.empty
-            default = parameter.default if has_default else NOT_SET
+            signature = inspect.signature(factory, eval_str=True)
+
+            # Detect dependency_type from factory or return annotation
+            if dependency_type is NOT_SET:
+                dependency_type = factory if is_class else signature.return_annotation
+                if dependency_type is inspect.Signature.empty:
+                    dependency_type = None
+
+            # Unwrap iterator types for resources
+            type_origin = get_origin(dependency_type)
+            if is_iterator_type(dependency_type) or is_iterator_type(type_origin):
+                args = get_args(dependency_type)
+                if not args:
+                    raise TypeError(
+                        f"Cannot use `{name}` resource type annotation "
+                        "without actual type argument."
+                    )
+                dependency_type = args[0]
+                if is_none_type(dependency_type):
+                    dependency_type = type(f"Event_{uuid.uuid4().hex}", (Event,), {})
 
-            try:
-                sub_provider = self._get_or_register_provider(parameter.annotation)
-            except LookupError as exc:
-                if (defaults and parameter.name in defaults) or has_default:
-                    continue
-                # For scoped dependencies, allow unresolved parameters via context.set()
-                if is_scoped:
-                    self._resolver.add_unresolved(parameter.annotation)
-                    parameters.append(
-                        ProviderParameter(
-                            name=parameter.name,
-                            annotation=parameter.annotation,
-                            default=default,
-                            has_default=has_default,
-                            provider=None,
-                            shared_scope=True,
-                        )
+            if is_none_type(dependency_type):
+                raise TypeError(f"Missing `{name}` provider return annotation.")
+
+            if dependency_type in self._providers and not override:
+                raise LookupError(
+                    f"The provider `{type_repr(dependency_type)}` is already "
+                    "registered."
+                )
+
+            # Process parameters (lazy - store without resolving dependencies)
+            parameters: list[ProviderParameter] = []
+
+            for param in signature.parameters.values():
+                if param.annotation is inspect.Parameter.empty:
+                    raise TypeError(
+                        f"Missing provider `{name}` "
+                        f"dependency `{param.name}` annotation."
                     )
+                if param.kind == inspect.Parameter.POSITIONAL_ONLY:
+                    raise TypeError(
+                        f"Positional-only parameters "
+                        f"are not allowed in the provider `{name}`."
+                    )
+
+                has_default = param.default is not inspect.Parameter.empty
+                # Markers are injection markers, not real defaults
+                if has_default and isinstance(param.default, Marker):
+                    has_default = False
+                default = param.default if has_default else NOT_SET
+
+                # Skip parameters provided via defaults (for create() method)
+                if defaults and param.name in defaults:
                     continue
-                unresolved_parameter = parameter
-                unresolved_exc = exc
-                continue
 
-            # Track scope providers for validation
-            scope_provider.setdefault(sub_provider.scope, sub_provider)
-
-            # For scoped dependencies with same scope having unresolved params,
-            # defer to context.set() instead
-            if (
-                is_scoped
-                and sub_provider.scope == scope
-                and any(p.provider is None for p in sub_provider.parameters)
-            ):
-                self._resolver.add_unresolved(parameter.annotation)
+                # Lazy registration: Store parameter without resolving dependencies
                 parameters.append(
                     ProviderParameter(
-                        name=parameter.name,
-                        annotation=parameter.annotation,
+                        dependency_type=param.annotation,
+                        name=param.name,
                         default=default,
                         has_default=has_default,
-                        provider=None,
-                        shared_scope=True,
+                        provider=None,  # Lazy - will be resolved in build()
+                        shared_scope=False,  # Lazy - will be computed in build()
                     )
                 )
-                continue
-
-            # Validate scope compatibility inline
-            if scope_hierarchy and sub_provider.scope not in scope_hierarchy:
-                raise ValueError(
-                    f"The provider `{name}` with a `{scope}` scope "
-                    f"cannot depend on `{sub_provider}` with a "
-                    f"`{sub_provider.scope}` scope. Please ensure all "
-                    "providers are registered with matching scopes."
-                )
 
-            parameters.append(
-                ProviderParameter(
-                    name=parameter.name,
-                    annotation=parameter.annotation,
-                    default=default,
-                    has_default=has_default,
-                    provider=sub_provider,
-                    shared_scope=sub_provider.scope == scope and scope != "transient",
-                )
+            provider = Provider(
+                dependency_type=dependency_type,
+                factory=factory,
+                scope=scope,
+                from_context=False,
+                parameters=tuple(parameters),
+                is_class=is_class,
+                is_coroutine=is_coroutine,
+                is_generator=is_generator,
+                is_async_generator=is_async_generator,
+                is_async=is_coroutine or is_async_generator,
+                is_resource=is_resource,
             )
 
-        # Handle unresolved parameters
-        if unresolved_parameter:
-            if is_scoped:  # pragma: no cover
-                # Note: This branch is currently unreachable because
-                # unresolved_parameter is only set when is_scoped=False
-                self._resolver.add_unresolved(interface)
-            else:
-                raise LookupError(
-                    f"The provider `{name}` depends on `{unresolved_parameter.name}` "
-                    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."
-                ) from unresolved_exc
-
-        # Create and register provider
-        provider = Provider(
-            call=call,
-            scope=scope,
-            interface=interface,
-            name=name,
-            parameters=tuple(parameters),
-            is_class=is_class,
-            is_coroutine=is_coroutine,
-            is_generator=is_generator,
-            is_async_generator=is_async_generator,
-            is_async=is_coroutine or is_async_generator,
-            is_resource=is_resource,
-        )
-
         self._set_provider(provider)
-
         if override:
             self._resolver.clear_caches()
 
-        return provider
+        # Resolve dependencies for providers registered after build()
+        if self.ready:
+            provider = self._ensure_provider_resolved(provider, set())
 
-    def _validate_provider_scope(
-        self, scope: Scope, name: str, is_resource: bool
-    ) -> None:
-        """Validate the provider scope."""
-        if scope not in self._scopes:
-            raise ValueError(
-                f"The provider `{name}` scope is invalid. Only the following "
-                f"scopes are supported: {', '.join(self._scopes.keys())}. "
-                "Please use one of the supported scopes when registering a provider."
-            )
-        if scope == "transient" and is_resource:
-            raise TypeError(
-                f"The resource provider `{name}` is attempting to register "
-                "with a transient scope, which is not allowed."
-            )
+        return provider
 
-    def _get_provider(self, interface: Any) -> Provider:
-        """Get provider by interface."""
+    def _get_provider(self, dependency_type: Any) -> Provider:
+        """Get provider by dependency type."""
         try:
-            return self._providers[interface]
-        except KeyError as exc:
+            return self._providers[dependency_type]
+        except KeyError:
             raise LookupError(
-                f"The provider interface for `{type_repr(interface)}` has "
-                "not been registered. Please ensure that the provider interface is "
+                f"The provider for `{type_repr(dependency_type)}` has "
+                "not been registered. Please ensure that the provider is "
                 "properly registered before attempting to use it."
-            ) from exc
+            ) from None
 
     def _get_or_register_provider(
-        self, interface: Any, defaults: dict[str, Any] | None = None
+        self, dependency_type: Any, defaults: dict[str, Any] | None = None
     ) -> Provider:
-        """Get or register a provider by interface."""
+        """Get or register a provider by dependency type."""
+        registered = False
         try:
-            return self._providers[interface]
-        except KeyError:
-            if inspect.isclass(interface) and is_provided(interface):
-                return self._register_provider(
-                    interface,
-                    interface.__provided__["scope"],
-                    NOT_SET,
+            provider = self._get_provider(dependency_type)
+        except LookupError:
+            if inspect.isclass(dependency_type) and is_provided(dependency_type):
+                provider = self._register_provider(
+                    dependency_type,
+                    dependency_type,
+                    dependency_type.__provided__.get("scope", "singleton"),
+                    dependency_type.__provided__.get("from_context", False),
                     False,
                     defaults,
                 )
-            raise LookupError(
-                f"The provider interface `{type_repr(interface)}` is either not "
-                "registered, not provided, or not set in the scoped context. "
-                "Please ensure that the provider interface is properly registered and "
-                "that the class is decorated with a scope before attempting to use it."
-            ) from None
+                registered = True
+            else:
+                raise LookupError(
+                    f"The provider `{type_repr(dependency_type)}` is either not "
+                    "registered, not provided, or not set in the scoped context. "
+                    "Please ensure that the provider is properly registered and "
+                    "that the class is decorated with a scope before attempting to "
+                    "use it."
+                ) from None
+
+        # Resolve dependencies:
+        # - For existing providers: only if container is not built yet
+        # - For newly auto-registered providers: always (even after build)
+        if registered or not self.ready:
+            provider = self._ensure_provider_resolved(provider, set())
+
+        return provider
+
+    def _ensure_provider_resolved(  # noqa: C901
+        self, provider: Provider, resolving: set[Any]
+    ) -> Provider:
+        """Ensure dependencies are resolved, resolving on-the-fly if needed."""
+        # Check if we're already resolving this provider (circular dependency)
+        if provider.dependency_type in resolving:
+            return provider
+
+        # Check if already resolved by examining parameters
+        # A provider is resolved if all its parameters either:
+        # 1. Have a provider set (provider is not None), OR
+        # 2. Have a default value, OR
+        # 3. Are marked for context.set() (provider=None but in unresolved list)
+        all_resolved = all(
+            param.provider is not None
+            or param.has_default
+            or (
+                param.provider is None and param.shared_scope
+            )  # Unresolved for context.set()
+            for param in provider.parameters
+        )
+        if all_resolved:
+            return provider
+
+        # Mark as currently being resolved
+        resolving = resolving | {provider.dependency_type}
+
+        # Resolve dependencies for this provider
+        resolved_params: list[ProviderParameter] = []
+
+        for param in provider.parameters:
+            if param.provider is not None:
+                # Already resolved
+                resolved_params.append(param)
+                continue
+
+            dependency_type = param.dependency_type
+
+            # Try to resolve the dependency
+            # First check if this would create a circular dependency
+            if dependency_type in resolving:
+                raise ValueError(
+                    f"Circular dependency detected: {provider} depends on "
+                    f"{type_repr(dependency_type)}"
+                )
+
+            try:
+                dep_provider = self._get_provider(dependency_type)
+            except LookupError:
+                # Check if it's a @provided class
+                if inspect.isclass(dependency_type) and is_provided(dependency_type):
+                    provided_scope = dependency_type.__provided__["scope"]
+
+                    # Auto-register @provided class
+                    dep_provider = self._register_provider(
+                        dependency_type,
+                        dependency_type,
+                        provided_scope,
+                        False,
+                        False,
+                        None,
+                    )
+                    # Recursively ensure the @provided class is resolved
+                    dep_provider = self._ensure_provider_resolved(
+                        dep_provider, resolving
+                    )
+                elif param.has_default:
+                    # Has default, can be missing
+                    resolved_params.append(param)
+                    continue
+                else:
+                    # Required dependency is missing
+                    raise LookupError(
+                        f"The provider `{provider}` depends on `{param.name}` of type "
+                        f"`{type_repr(dependency_type)}`, which has not been "
+                        f"registered or set. To resolve this, ensure that "
+                        f"`{param.name}` is registered before resolving, "
+                        f"or register it with `from_context=True` if it should be "
+                        f"provided via scoped context."
+                    ) from None
+
+            # If the dependency is a from_context provider, mark it appropriately
+            if dep_provider.from_context:
+                resolved_params.append(
+                    ProviderParameter(
+                        name=param.name,
+                        dependency_type=dependency_type,
+                        default=param.default,
+                        has_default=param.has_default,
+                        provider=dep_provider,
+                        shared_scope=True,
+                    )
+                )
+                continue
+
+            # Ensure dependency is also resolved
+            dep_provider = self._ensure_provider_resolved(dep_provider, resolving)
+
+            # Validate scope compatibility
+            scope_hierarchy = (
+                self._scopes.get(provider.scope, ())
+                if provider.scope != "transient"
+                else ()
+            )
+            if scope_hierarchy and dep_provider.scope not in scope_hierarchy:
+                raise ValueError(
+                    f"The provider `{provider}` with a `{provider.scope}` scope "
+                    f"cannot depend on `{dep_provider}` with a "
+                    f"`{dep_provider.scope}` scope. Please ensure all providers are "
+                    f"registered with matching scopes."
+                )
+
+            # Calculate shared_scope
+            shared_scope = (
+                dep_provider.scope == provider.scope and provider.scope != "transient"
+            )
+
+            # Create resolved parameter (use unwrapped annotation)
+            resolved_params.append(
+                ProviderParameter(
+                    name=param.name,
+                    dependency_type=dependency_type,
+                    default=param.default,
+                    has_default=param.has_default,
+                    provider=dep_provider,
+                    shared_scope=shared_scope,
+                )
+            )
+
+        # Replace provider with resolved version
+        resolved_provider = Provider(
+            factory=provider.factory,
+            scope=provider.scope,
+            dependency_type=provider.dependency_type,
+            parameters=tuple(resolved_params),
+            is_class=provider.is_class,
+            is_coroutine=provider.is_coroutine,
+            is_generator=provider.is_generator,
+            is_async_generator=provider.is_async_generator,
+            is_async=provider.is_async,
+            is_resource=provider.is_resource,
+            from_context=provider.from_context,
+        )
+        self._providers[provider.dependency_type] = resolved_provider
+
+        return resolved_provider
 
     def _set_provider(self, provider: Provider) -> None:
-        """Set a provider by interface."""
-        self._providers[provider.interface] = provider
+        """Set a provider by dependency type."""
+        self._providers[provider.dependency_type] = provider
         if provider.is_resource:
-            self._resources[provider.scope].append(provider.interface)
+            self._resources[provider.scope].append(provider.dependency_type)
 
     def _delete_provider(self, provider: Provider) -> None:
         """Delete a provider."""
-        if provider.interface in self._providers:
-            del self._providers[provider.interface]
+        if provider.dependency_type in self._providers:
+            del self._providers[provider.dependency_type]
         if provider.is_resource:
-            self._resources[provider.scope].remove(provider.interface)
+            self._resources[provider.scope].remove(provider.dependency_type)
 
     # == Instance Resolution ==
 
     @overload
-    def resolve(self, interface: type[T]) -> T: ...
+    def resolve(self, dependency_type: type[T], /) -> T: ...
 
     @overload
-    def resolve(self, interface: T) -> T: ...  # type: ignore
+    def resolve(self, dependency_type: T, /) -> T: ...  # type: ignore
 
-    def resolve(self, interface: type[T]) -> T:
-        """Resolve an instance by interface using compiled sync resolver."""
-        cached = self._resolver.get_cached(interface, is_async=False)
+    def resolve(self, dependency_type: type[T], /) -> T:
+        """Resolve an instance by dependency type using compiled sync resolver."""
+        cached = self._resolver.get_cached(dependency_type, is_async=False)
         if cached is not None:
             return cached.resolve(self)
 
-        provider = self._get_or_register_provider(interface)
+        provider = self._get_or_register_provider(dependency_type)
         compiled = self._resolver.compile(provider, is_async=False)
         return compiled.resolve(self)
 
     @overload
-    async def aresolve(self, interface: type[T]) -> T: ...
+    async def aresolve(self, dependency_type: type[T], /) -> T: ...
 
     @overload
-    async def aresolve(self, interface: T) -> T: ...
+    async def aresolve(self, dependency_type: T, /) -> T: ...
 
-    async def aresolve(self, interface: type[T]) -> T:
-        """Resolve an instance by interface asynchronously."""
-        cached = self._resolver.get_cached(interface, is_async=True)
+    async def aresolve(self, dependency_type: type[T], /) -> T:
+        """Resolve an instance by dependency type asynchronously."""
+        cached = self._resolver.get_cached(dependency_type, is_async=True)
         if cached is not None:
             return await cached.resolve(self)
 
-        provider = self._get_or_register_provider(interface)
+        provider = self._get_or_register_provider(dependency_type)
         compiled = self._resolver.compile(provider, is_async=True)
         return await compiled.resolve(self)
 
-    def create(self, interface: type[T], /, **defaults: Any) -> T:
-        """Create an instance by interface."""
+    def create(self, dependency_type: type[T], /, **defaults: Any) -> T:
+        """Create an instance by dependency type."""
         if not defaults:
-            cached = self._resolver.get_cached(interface, is_async=False)
+            cached = self._resolver.get_cached(dependency_type, is_async=False)
             if cached is not None:
                 return cached.create(self, None)
 
-        provider = self._get_or_register_provider(interface, defaults)
+        provider = self._get_or_register_provider(dependency_type, defaults)
         compiled = self._resolver.compile(provider, is_async=False)
         return compiled.create(self, defaults or None)
 
-    async def acreate(self, interface: type[T], /, **defaults: Any) -> T:
-        """Create an instance by interface asynchronously."""
+    async def acreate(self, dependency_type: type[T], /, **defaults: Any) -> T:
+        """Create an instance by dependency type asynchronously."""
         if not defaults:
-            cached = self._resolver.get_cached(interface, is_async=True)
+            cached = self._resolver.get_cached(dependency_type, is_async=True)
             if cached is not None:
                 return await cached.create(self, None)
 
-        provider = self._get_or_register_provider(interface, defaults)
+        provider = self._get_or_register_provider(dependency_type, defaults)
         compiled = self._resolver.compile(provider, is_async=True)
         return await compiled.create(self, defaults or None)
 
-    def is_resolved(self, interface: Any) -> bool:
-        """Check if an instance by interface exists."""
+    def is_resolved(self, dependency_type: Any, /) -> bool:
+        """Check if an instance for the dependency type exists."""
         try:
-            provider = self._get_provider(interface)
+            provider = self._get_provider(dependency_type)
         except LookupError:
             return False
         if provider.scope == "transient":
             return False
         context = self._get_instance_context(provider.scope)
-        return interface in context
+        return dependency_type in context
 
-    def release(self, interface: Any) -> None:
-        """Release an instance by interface."""
-        provider = self._get_provider(interface)
+    def release(self, dependency_type: Any, /) -> None:
+        """Release an instance by dependency type."""
+        provider = self._get_provider(dependency_type)
         if provider.scope == "transient":
             return None
         context = self._get_instance_context(provider.scope)
-        del context[interface]
+        del context[dependency_type]
 
     def reset(self) -> None:
         """Reset resolved instances."""
-        for interface, provider in self._providers.items():
+        for dependency_type, provider in self._providers.items():
             if provider.scope == "transient":
                 continue
             try:
                 context = self._get_instance_context(provider.scope)
             except LookupError:
                 continue
-            del context[interface]
+            del context[dependency_type]
 
     # == Injection Utilities ==
 
@@ -741,24 +900,294 @@ class Container:
     # == Package Scanning ==
 
     def scan(
-        self, /, packages: PackageOrIterable, *, tags: Iterable[str] | None = None
+        self,
+        /,
+        packages: PackageOrIterable,
+        *,
+        tags: Iterable[str] | None = None,
+        ignore: PackageOrIterable | None = None,
     ) -> None:
-        self._scanner.scan(packages=packages, tags=tags)
+        self._scanner.scan(packages=packages, tags=tags, ignore=ignore)
+
+    # == Build ==
+
+    def build(self) -> None:
+        """Build the container by validating the complete dependency graph."""
+        if self.ready:
+            raise RuntimeError("Container has already been built")
+
+        self._resolve_provider_dependencies()
+        self._detect_circular_dependencies()
+        self._validate_scope_compatibility()
+
+        self._ready = True
+
+    def rebuild(self) -> None:
+        """Rebuild the container by re-validating the complete dependency graph."""
+        if self._ready:
+            self._ready = False
+            self._resolver.clear_caches()
+        self.build()
+
+    def graph(
+        self,
+        output_format: Literal["tree", "mermaid", "dot", "json"] = "tree",
+        *,
+        full_path: bool = False,
+        **kwargs: Any,
+    ) -> str:
+        """Draw the dependency graph."""
+        if not self.ready:
+            self.build()
+        return self._graph.draw(
+            output_format=output_format,
+            full_path=full_path,
+            **kwargs,
+        )
+
+    def _resolve_provider_dependencies(self) -> None:
+        """Resolve all provider dependencies by filling in provider references."""
+        for dependency_type, provider in list(self._providers.items()):
+            resolved_params: list[ProviderParameter] = []
+
+            for param in provider.parameters:
+                if param.provider is not None:
+                    # Already resolved
+                    resolved_params.append(param)
+                    continue
+
+                param_dependency_type = param.dependency_type
+
+                # Try to resolve the dependency
+                try:
+                    dep_provider = self._get_provider(param_dependency_type)
+                except LookupError:
+                    # Check if it's a @provided class
+                    if inspect.isclass(param_dependency_type) and is_provided(
+                        param_dependency_type
+                    ):
+                        provided_scope = param_dependency_type.__provided__["scope"]
+
+                        # Auto-register @provided class
+                        dep_provider = self._register_provider(
+                            param_dependency_type,
+                            param_dependency_type,
+                            provided_scope,
+                            False,
+                            False,
+                            None,
+                        )
+                    elif param.has_default:
+                        # Has default, can be missing
+                        resolved_params.append(param)
+                        continue
+                    else:
+                        # Required dependency is missing
+                        raise LookupError(
+                            f"The provider `{provider}` depends on "
+                            f"`{param.name}` of type "
+                            f"`{type_repr(param_dependency_type)}`, which has not been "
+                            f"registered or set. To resolve this, ensure that "
+                            f"`{param.name}` is registered before calling build(), "
+                            f"or register it with `from_context=True` if it should be "
+                            f"provided via scoped context."
+                        ) from None
+
+                # If the dependency is a from_context provider, mark it appropriately
+                if dep_provider.from_context:
+                    resolved_params.append(
+                        ProviderParameter(
+                            name=param.name,
+                            dependency_type=param_dependency_type,
+                            default=param.default,
+                            has_default=param.has_default,
+                            provider=dep_provider,
+                            shared_scope=True,
+                        )
+                    )
+                    continue
+
+                # Calculate shared_scope
+                shared_scope = (
+                    dep_provider.scope == provider.scope
+                    and provider.scope != "transient"
+                )
+
+                # Create resolved parameter
+                resolved_params.append(
+                    ProviderParameter(
+                        name=param.name,
+                        dependency_type=param_dependency_type,
+                        default=param.default,
+                        has_default=param.has_default,
+                        provider=dep_provider,
+                        shared_scope=shared_scope,
+                    )
+                )
+
+            # Replace provider with resolved version
+            resolved_provider = Provider(
+                factory=provider.factory,
+                scope=provider.scope,
+                dependency_type=provider.dependency_type,
+                parameters=tuple(resolved_params),
+                is_class=provider.is_class,
+                is_coroutine=provider.is_coroutine,
+                is_generator=provider.is_generator,
+                is_async_generator=provider.is_async_generator,
+                is_async=provider.is_async,
+                is_resource=provider.is_resource,
+                from_context=provider.from_context,
+            )
+            self._providers[dependency_type] = resolved_provider
+
+    def _detect_circular_dependencies(self) -> None:
+        """Detect circular dependencies in the provider graph."""
+
+        def visit(
+            dependency_type: Any,
+            provider: Provider,
+            path: list[str],
+            visited: set[Any],
+            in_path: set[Any],
+        ) -> None:
+            """DFS traversal to detect cycles."""
+            if dependency_type in in_path:
+                # Found a cycle!
+                cycle_start = next(
+                    i for i, name in enumerate(path) if name == str(provider)
+                )
+                cycle_path = " -> ".join(path[cycle_start:] + [str(provider)])
+                raise ValueError(
+                    f"Circular dependency detected: {cycle_path}. "
+                    f"Please restructure your dependencies to break the cycle."
+                )
+
+            if dependency_type in visited:
+                return
+
+            visited.add(dependency_type)
+            in_path.add(dependency_type)
+            path.append(str(provider))
+
+            # Visit dependencies
+            for param in provider.parameters:
+                # Look up the dependency provider from self._providers instead of
+                # using param.provider, which might be stale/unresolved
+                if param.dependency_type in self._providers:
+                    dep_provider = self._providers[param.dependency_type]
+                    visit(
+                        param.dependency_type,
+                        dep_provider,
+                        path,
+                        visited,
+                        in_path,
+                    )
+
+            path.pop()
+            in_path.remove(dependency_type)
+
+        visited: set[Any] = set()
+
+        for dependency_type, provider in self._providers.items():
+            if dependency_type not in visited:
+                visit(dependency_type, provider, [], visited, set())
+
+    def _validate_scope_compatibility(self) -> None:
+        """Validate that all dependencies have compatible scopes."""
+        for provider in self._providers.values():
+            scope = provider.scope
+
+            # Skip validation for transient (can depend on anything)
+            if scope == "transient":
+                continue
+
+            # Get scope hierarchy for this provider
+            scope_hierarchy = (
+                self._scopes.get(scope, ()) if scope != "transient" else ()
+            )
+
+            # Check each dependency
+            for param in provider.parameters:
+                if param.provider is None:
+                    # Unresolved (allowed for scoped providers)
+                    continue
+
+                dep_scope = param.provider.scope
+
+                # Validate scope compatibility
+                if scope_hierarchy and dep_scope not in scope_hierarchy:
+                    raise ValueError(
+                        f"The provider `{provider}` with a `{scope}` scope "
+                        f"cannot depend on `{param.provider}` with a "
+                        f"`{dep_scope}` scope. Please ensure all providers are "
+                        f"registered with matching scopes."
+                    )
 
     # == Testing / Override Support ==
 
+    def enable_test_mode(self) -> None:
+        """Enable test mode for override support on all resolutions."""
+        self._test_mode = True
+
+    def disable_test_mode(self) -> None:
+        """Disable test mode for override support on all resolutions."""
+        self._test_mode = False
+
+    @contextlib.contextmanager
+    def test_mode(self) -> Iterator[None]:
+        if self._test_mode:
+            yield
+            return
+
+        self._test_mode = True
+        try:
+            yield
+        finally:
+            self._test_mode = False
+
     @contextlib.contextmanager
-    def override(self, interface: Any, instance: Any) -> Iterator[None]:
+    def override(
+        self,
+        dependency_type: Any = NOT_SET,
+        /,
+        instance: Any = NOT_SET,
+        *,
+        interface: Any = NOT_SET,
+    ) -> Iterator[None]:
         """Override a dependency with a specific instance for testing."""
-        if not self.has_provider_for(interface):
+        if not self._test_mode:
+            warnings.warn(
+                "Using override() without enabling test mode. "
+                "Consider using `with container.test_mode():` for consistent behavior.",
+                UserWarning,
+                stacklevel=2,
+            )
+
+        if interface is not NOT_SET:
+            warnings.warn(
+                "The `interface` is deprecated. Use `dependency_type` instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            if dependency_type is NOT_SET:
+                dependency_type = interface
+
+        if dependency_type is NOT_SET:
+            raise TypeError("override() missing required argument: 'dependency_type'")
+
+        if instance is NOT_SET:
+            raise TypeError("override() missing required argument: 'instance'")
+
+        if not self.has_provider_for(dependency_type):
             raise LookupError(
-                f"The provider interface `{type_repr(interface)}` not registered."
+                f"The provider `{type_repr(dependency_type)}` is not registered."
             )
-        self._resolver.add_override(interface, instance)
+        self._resolver.add_override(dependency_type, instance)
         try:
             yield
         finally:
-            self._resolver.remove_override(interface)
+            self._resolver.remove_override(dependency_type)
 
 
 def import_container(container_path: str) -> Container: