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

anydi/__init__.py

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

anydi/_container.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 import contextlib
-import functools
+import importlib
 import inspect
 import logging
 import types
@@ -11,12 +11,13 @@ import uuid
 from collections import defaultdict
 from collections.abc import AsyncIterator, Callable, Iterable, Iterator
 from contextvars import ContextVar
-from typing import Annotated, Any, TypeVar, cast, get_args, get_origin, overload
+from typing import Any, TypeVar, get_args, get_origin, overload
 
 from typing_extensions import ParamSpec, Self, type_repr
 
 from ._context import InstanceContext
 from ._decorators import is_provided
+from ._injector import Injector
 from ._module import ModuleDef, ModuleRegistrar
 from ._provider import Provider, ProviderDef, ProviderKind, ProviderParameter
 from ._resolver import Resolver
@@ -26,7 +27,6 @@ from ._types import (
     Event,
     Scope,
     is_event_type,
-    is_inject_marker,
     is_iterator_type,
     is_none_type,
 )
@@ -58,10 +58,10 @@ class Container:
         self._request_context_var: ContextVar[InstanceContext | None] = ContextVar(
             "request_context", default=None
         )
-        self._inject_cache: dict[Callable[..., Any], Callable[..., Any]] = {}
 
         # Components
         self._resolver = Resolver(self)
+        self._injector = Injector(self)
         self._modules = ModuleRegistrar(self)
         self._scanner = Scanner(self)
 
@@ -195,12 +195,14 @@ class Container:
     def register(
         self,
         interface: Any,
-        call: Callable[..., Any],
+        call: Callable[..., Any] = NOT_SET,
         *,
-        scope: Scope,
+        scope: Scope = "singleton",
         override: bool = False,
     ) -> Provider:
         """Register a provider for the specified interface."""
+        if call is NOT_SET:
+            call = interface
         return self._register_provider(call, scope, interface, override)
 
     def is_registered(self, interface: Any) -> bool:
@@ -548,115 +550,21 @@ class Container:
         """Decorator to inject dependencies into a callable."""
 
         def decorator(call: Callable[P, T]) -> Callable[P, T]:
-            return self._inject(call)
+            return self._injector.inject(call)
 
         if func is None:
             return decorator
         return decorator(func)
 
-    def run(self, func: Callable[P, T], /, *args: P.args, **kwargs: P.kwargs) -> T:
+    def run(self, func: Callable[..., T], /, *args: Any, **kwargs: Any) -> T:
         """Run the given function with injected dependencies."""
-        return self._inject(func)(*args, **kwargs)
-
-    def _inject(self, call: Callable[P, T]) -> Callable[P, T]:
-        """Inject dependencies into a callable."""
-        if call in self._inject_cache:
-            return cast(Callable[P, T], self._inject_cache[call])
-
-        injected_params = self._get_injected_params(call)
-        if not injected_params:
-            self._inject_cache[call] = call
-            return call
-
-        if inspect.iscoroutinefunction(call):
-
-            @functools.wraps(call)
-            async def awrapper(*args: P.args, **kwargs: P.kwargs) -> T:
-                for name, annotation in injected_params.items():
-                    kwargs[name] = await self.aresolve(annotation)
-                return cast(T, await call(*args, **kwargs))
-
-            self._inject_cache[call] = awrapper
-
-            return awrapper  # type: ignore
-
-        @functools.wraps(call)
-        def wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
-            for name, annotation in injected_params.items():
-                kwargs[name] = self.resolve(annotation)
-            return call(*args, **kwargs)
-
-        self._inject_cache[call] = wrapper
-
-        return wrapper
-
-    def _get_injected_params(self, call: Callable[..., Any]) -> dict[str, Any]:
-        """Get the injected parameters of a callable object."""
-        injected_params: dict[str, Any] = {}
-        for parameter in inspect.signature(call, eval_str=True).parameters.values():
-            interface, should_inject = self.validate_injected_parameter(
-                parameter, call=call
-            )
-            if should_inject:
-                injected_params[parameter.name] = interface
-        return injected_params
-
-    @staticmethod
-    def _unwrap_injected_parameter(parameter: inspect.Parameter) -> inspect.Parameter:
-        if get_origin(parameter.annotation) is not Annotated:
-            return parameter
-
-        origin, *metadata = get_args(parameter.annotation)
-
-        if not metadata or not is_inject_marker(metadata[-1]):
-            return parameter
-
-        if is_inject_marker(parameter.default):
-            raise TypeError(
-                "Cannot specify `Inject` in `Annotated` and "
-                f"default value together for '{parameter.name}'"
-            )
-
-        if parameter.default is not inspect.Parameter.empty:
-            return parameter
-
-        marker = metadata[-1]
-        new_metadata = metadata[:-1]
-        if new_metadata:
-            if hasattr(Annotated, "__getitem__"):
-                new_annotation = Annotated.__getitem__((origin, *new_metadata))  # type: ignore
-            else:
-                new_annotation = Annotated.__class_getitem__((origin, *new_metadata))  # type: ignore
-        else:
-            new_annotation = origin
-        return parameter.replace(annotation=new_annotation, default=marker)
+        return self._injector.inject(func)(*args, **kwargs)
 
     def validate_injected_parameter(
         self, parameter: inspect.Parameter, *, call: Callable[..., Any]
     ) -> tuple[Any, bool]:
         """Validate an injected parameter."""
-        parameter = self._unwrap_injected_parameter(parameter)
-        interface = parameter.annotation
-
-        if not is_inject_marker(parameter.default):
-            return interface, False
-
-        if interface is inspect.Parameter.empty:
-            raise TypeError(
-                f"Missing `{type_repr(call)}` parameter `{parameter.name}` annotation."
-            )
-
-        # Set inject marker interface
-        parameter.default.interface = interface
-
-        if not self.has_provider_for(interface):
-            raise LookupError(
-                f"`{type_repr(call)}` has an unknown dependency parameter "
-                f"`{parameter.name}` with an annotation of "
-                f"`{type_repr(interface)}`."
-            )
-
-        return interface, True
+        return self._injector.validate_parameter(parameter, call=call)
 
     # == Module Registration ==
 
@@ -685,3 +593,48 @@ class Container:
             yield
         finally:
             self._resolver.remove_override(interface)
+
+
+def import_container(container_path: str) -> Container:
+    """Import container from a string path."""
+    # Replace colon with dot for unified processing
+    container_path = container_path.replace(":", ".")
+
+    try:
+        module_path, attr_name = container_path.rsplit(".", 1)
+    except ValueError as exc:
+        raise ImportError(
+            f"Invalid container path '{container_path}'. "
+            "Expected format: 'module.path:attribute' or 'module.path.attribute'"
+        ) from exc
+
+    try:
+        module = importlib.import_module(module_path)
+    except ImportError as exc:
+        raise ImportError(
+            f"Failed to import module '{module_path}' "
+            f"from container path '{container_path}'"
+        ) from exc
+
+    try:
+        container_or_factory = getattr(module, attr_name)
+    except AttributeError as exc:
+        raise ImportError(
+            f"Module '{module_path}' has no attribute '{attr_name}'"
+        ) from exc
+
+    # If it's a callable (factory), call it
+    if callable(container_or_factory) and not isinstance(
+        container_or_factory, Container
+    ):
+        container = container_or_factory()
+    else:
+        container = container_or_factory
+
+    if not isinstance(container, Container):
+        raise ImportError(
+            f"Expected Container instance, got {type(container).__name__} "
+            f"from '{container_path}'"
+        )
+
+    return container

anydi/_injector.py

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

anydi/_scanner.py

@@ -3,13 +3,12 @@ from __future__ import annotations
 import importlib
 import inspect
 import pkgutil
-from collections.abc import Callable, Iterable
+from collections.abc import Callable, Iterable, Iterator
 from dataclasses import dataclass
 from types import ModuleType
 from typing import TYPE_CHECKING, Any
 
-from ._decorators import is_injectable
-from ._types import is_inject_marker
+from ._decorators import Provided, is_injectable, is_provided
 
 if TYPE_CHECKING:
     from ._container import Container
@@ -38,45 +37,64 @@ class Scanner:
     ) -> None:
         """Scan packages or modules for decorated members and inject dependencies."""
         if isinstance(packages, (ModuleType, str)):
-            scan_packages: Iterable[Package] = [packages]
-        else:
-            scan_packages = packages
-
-        dependencies = [
-            dependency
-            for package in scan_packages
-            for dependency in self._scan_package(package, tags=tags)
-        ]
-
-        for dependency in dependencies:
+            packages = [packages]
+
+        tags_list = list(tags) if tags else []
+        provided_classes: list[type[Provided]] = []
+        injectable_dependencies: list[ScannedDependency] = []
+
+        # Single pass: collect both @provided classes and @injectable functions
+        for module in self._iter_modules(packages):
+            provided_classes.extend(self._scan_module_for_provided(module))
+            injectable_dependencies.extend(
+                self._scan_module_for_injectable(module, tags=tags_list)
+            )
+
+        # First: register @provided classes
+        for cls in provided_classes:
+            if not self._container.is_registered(cls):
+                scope = cls.__provided__["scope"]
+                self._container.register(cls, scope=scope)
+
+        # Second: inject @injectable functions
+        for dependency in injectable_dependencies:
             decorated = self._container.inject()(dependency.member)
             setattr(dependency.module, dependency.member.__name__, decorated)
 
-    def _scan_package(
-        self, package: Package, *, tags: Iterable[str] | None = None
-    ) -> list[ScannedDependency]:
-        """Scan a package or module for decorated members."""
-        tags = list(tags) if tags else []
+    def _iter_modules(self, packages: Iterable[Package]) -> Iterator[ModuleType]:
+        """Iterate over all modules in the given packages."""
+        for package in packages:
+            if isinstance(package, str):
+                package = importlib.import_module(package)
 
-        if isinstance(package, str):
-            package = importlib.import_module(package)
+            # Single module (not a package)
+            if not hasattr(package, "__path__"):
+                yield package
+                continue
 
-        if not hasattr(package, "__path__"):
-            return self._scan_module(package, tags=tags)
+            # Package - walk all submodules
+            for module_info in pkgutil.walk_packages(
+                package.__path__, prefix=package.__name__ + "."
+            ):
+                yield importlib.import_module(module_info.name)
 
-        dependencies: list[ScannedDependency] = []
-        for module_info in pkgutil.walk_packages(
-            package.__path__, prefix=package.__name__ + "."
-        ):
-            module = importlib.import_module(module_info.name)
-            dependencies.extend(self._scan_module(module, tags=tags))
+    def _scan_module_for_provided(self, module: ModuleType) -> list[type[Provided]]:
+        """Scan a module for @provided classes."""
+        provided_classes: list[type[Provided]] = []
 
-        return dependencies
+        for _, member in inspect.getmembers(module, predicate=inspect.isclass):
+            if getattr(member, "__module__", None) != module.__name__:
+                continue
+
+            if is_provided(member):
+                provided_classes.append(member)
 
-    def _scan_module(
-        self, module: ModuleType, *, tags: Iterable[str]
+        return provided_classes
+
+    def _scan_module_for_injectable(
+        self, module: ModuleType, *, tags: list[str]
     ) -> list[ScannedDependency]:
-        """Scan a module for decorated members."""
+        """Scan a module for @injectable functions."""
         dependencies: list[ScannedDependency] = []
 
         for _, member in inspect.getmembers(module, predicate=callable):
@@ -89,22 +107,12 @@ class Scanner:
         return dependencies
 
     @staticmethod
-    def _should_include_member(
-        member: Callable[..., Any], *, tags: Iterable[str]
-    ) -> bool:
+    def _should_include_member(member: Callable[..., Any], *, tags: list[str]) -> bool:
         """Determine if a member should be included based on tags or marker defaults."""
-
         if is_injectable(member):
             member_tags = set(member.__injectable__["tags"] or [])
             if tags:
                 return bool(set(tags) & member_tags)
             return True  # No tags passed → include all injectables
 
-        # If no tags are passed and not explicitly injectable,
-        # check for parameter markers
-        if not tags:
-            for parameter in inspect.signature(member).parameters.values():
-                if is_inject_marker(parameter.default):
-                    return True
-
         return False

anydi/_types.py

@@ -3,19 +3,21 @@
 from __future__ import annotations
 
 import inspect
-from collections.abc import AsyncIterator, Iterator
+from collections.abc import AsyncIterator, Callable, Iterator
 from types import NoneType
-from typing import Any, Literal
+from typing import TYPE_CHECKING, Annotated, Any, Literal, TypeVar
 
 from typing_extensions import Sentinel
 
+T = TypeVar("T")
+
 Scope = Literal["transient", "singleton", "request"]
 
 NOT_SET = Sentinel("NOT_SET")
 
 
-class InjectMarker:
-    """A marker object for declaring injectable dependencies."""
+class ProvideMarker:
+    """A marker object for declaring dependency."""
 
     __slots__ = ("_interface",)
 
@@ -32,13 +34,52 @@ class InjectMarker:
     def interface(self, interface: Any) -> None:
         self._interface = interface
 
+    def __class_getitem__(cls, item: Any) -> Any:
+        return Annotated[item, cls()]
+
+
+_provide_factory: Callable[[], Any] = ProvideMarker
+
+
+def set_provide_factory(factory: Callable[[], Any]) -> Callable[[], Any]:
+    """Set the global factory used by Inject() and Provide."""
+    global _provide_factory
+    previous = _provide_factory
+    _provide_factory = factory
+    return previous
+
+
+def is_provide_marker(obj: Any) -> bool:
+    return isinstance(obj, ProvideMarker)
+
 
-def is_inject_marker(obj: Any) -> bool:
-    return isinstance(obj, InjectMarker)
+class _ProvideMeta(type):
+    """Metaclass for Provide that delegates __class_getitem__ to the current factory."""
+
+    def __getitem__(cls, item: Any) -> Any:
+        # Use the current factory's __class_getitem__ if available
+        factory = _provide_factory
+        if hasattr(factory, "__class_getitem__"):
+            return factory.__class_getitem__(item)  # type: ignore[attr-defined]
+        # Fallback to creating Annotated with factory instance
+        return Annotated[item, factory()]
+
+
+if TYPE_CHECKING:
+    Provide = Annotated[T, ProvideMarker()]
+
+else:
+
+    class Provide(metaclass=_ProvideMeta):
+        pass
 
 
 def Inject() -> Any:
-    return InjectMarker()
+    return _provide_factory()
+
+
+# Alias from backward compatibility
+is_inject_marker = is_provide_marker
 
 
 class Event: