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

anydi/_context.py

@@ -15,22 +15,22 @@ from ._types import NOT_SET
 class InstanceContext:
     """A context to store instances."""
 
-    __slots__ = ("_instances", "_stack", "_async_stack", "_lock", "_async_lock")
+    __slots__ = ("_items", "_stack", "_async_stack", "_lock", "_async_lock")
 
     def __init__(self) -> None:
-        self._instances: dict[Any, Any] = {}
+        self._items: dict[Any, Any] = {}
         self._stack: contextlib.ExitStack | None = None
         self._async_stack: contextlib.AsyncExitStack | None = None
         self._lock: threading.RLock | None = None
         self._async_lock: AsyncRLock | None = None
 
-    def get(self, interface: Any, default: Any = NOT_SET) -> Any:
+    def get(self, key: Any, default: Any = NOT_SET) -> Any:
         """Get an instance from the context."""
-        return self._instances.get(interface, default)
+        return self._items.get(key, default)
 
-    def set(self, interface: Any, value: Any) -> None:
+    def set(self, key: Any, value: Any) -> None:
         """Set an instance in the context."""
-        self._instances[interface] = value
+        self._items[key] = value
 
     def enter(self, cm: contextlib.AbstractContextManager[Any]) -> Any:
         """Enter the context."""
@@ -44,17 +44,17 @@ class InstanceContext:
             self._async_stack = contextlib.AsyncExitStack()
         return await self._async_stack.enter_async_context(cm)
 
-    def __setitem__(self, interface: Any, value: Any) -> None:
-        self._instances[interface] = value
+    def __setitem__(self, key: Any, value: Any) -> None:
+        self._items[key] = value
 
-    def __getitem__(self, interface: Any) -> Any:
-        return self._instances[interface]
+    def __getitem__(self, key: Any) -> Any:
+        return self._items[key]
 
-    def __contains__(self, interface: Any) -> bool:
-        return interface in self._instances
+    def __contains__(self, key: Any) -> bool:
+        return key in self._items
 
-    def __delitem__(self, interface: Any) -> None:
-        self._instances.pop(interface, None)
+    def __delitem__(self, key: Any) -> None:
+        self._items.pop(key, None)
 
     def __enter__(self) -> Self:
         """Enter the context."""

anydi/_decorators.py

@@ -11,11 +11,13 @@ from typing import (
     overload,
 )
 
+from typing_extensions import NotRequired
+
 if TYPE_CHECKING:
     from ._module import Module
 
 
-from ._types import Scope
+from ._types import NOT_SET, Scope
 
 T = TypeVar("T")
 P = ParamSpec("P")
@@ -27,23 +29,128 @@ ModuleT = TypeVar("ModuleT", bound="Module")
 class ProvidedMetadata(TypedDict):
     """Metadata for classes marked as provided by AnyDI."""
 
+    dependency_type: NotRequired[Any]
     scope: Scope
+    from_context: NotRequired[bool]
+
+
+@overload
+def provided(
+    dependency_type: Any, /, *, scope: Scope, from_context: bool = False
+) -> Callable[[ClassT], ClassT]: ...
+
+
+@overload
+def provided(
+    *, scope: Scope, from_context: bool = False
+) -> Callable[[ClassT], ClassT]: ...
 
 
-def provided(*, scope: Scope) -> Callable[[ClassT], ClassT]:
+def provided(
+    dependency_type: Any = NOT_SET, /, *, scope: Scope, from_context: bool = False
+) -> Callable[[ClassT], ClassT]:
     """Decorator for marking a class as provided by AnyDI with a specific scope."""
 
     def decorator(cls: ClassT) -> ClassT:
-        cls.__provided__ = ProvidedMetadata(scope=scope)
+        metadata: ProvidedMetadata = {"scope": scope}
+        if dependency_type is not NOT_SET:
+            metadata["dependency_type"] = dependency_type
+        if from_context:
+            metadata["from_context"] = from_context
+        cls.__provided__ = metadata  # type: ignore[attr-defined]
         return cls
 
     return decorator
 
 
-# Scoped decorators for class-level providers
-transient = provided(scope="transient")
-request = provided(scope="request")
-singleton = provided(scope="singleton")
+@overload
+def singleton(cls: ClassT, /) -> ClassT: ...
+
+
+@overload
+def singleton(
+    cls: None = None, /, *, dependency_type: Any = NOT_SET
+) -> Callable[[ClassT], ClassT]: ...
+
+
+def singleton(
+    cls: ClassT | None = None, /, *, dependency_type: Any = NOT_SET
+) -> Callable[[ClassT], ClassT] | ClassT:
+    """Decorator for marking a class as a singleton dependency."""
+
+    def decorator(c: ClassT) -> ClassT:
+        metadata: ProvidedMetadata = {"scope": "singleton"}
+        if dependency_type is not NOT_SET:
+            metadata["dependency_type"] = dependency_type
+        c.__provided__ = metadata  # type: ignore[attr-defined]
+        return c
+
+    if cls is None:
+        return decorator
+
+    return decorator(cls)
+
+
+@overload
+def transient(cls: ClassT, /) -> ClassT: ...
+
+
+@overload
+def transient(
+    cls: None = None, /, *, dependency_type: Any = NOT_SET
+) -> Callable[[ClassT], ClassT]: ...
+
+
+def transient(
+    cls: ClassT | None = None, /, *, dependency_type: Any = NOT_SET
+) -> Callable[[ClassT], ClassT] | ClassT:
+    """Decorator for marking a class as a transient dependency."""
+
+    def decorator(c: ClassT) -> ClassT:
+        metadata: ProvidedMetadata = {"scope": "transient"}
+        if dependency_type is not NOT_SET:
+            metadata["dependency_type"] = dependency_type
+        c.__provided__ = metadata  # type: ignore[attr-defined]
+        return c
+
+    if cls is None:
+        return decorator
+
+    return decorator(cls)
+
+
+@overload
+def request(cls: ClassT, /, *, from_context: bool = False) -> ClassT: ...
+
+
+@overload
+def request(
+    cls: None = None, /, *, dependency_type: Any = NOT_SET, from_context: bool = False
+) -> Callable[[ClassT], ClassT]: ...
+
+
+def request(
+    cls: ClassT | None = None,
+    /,
+    *,
+    dependency_type: Any = NOT_SET,
+    from_context: bool = False,
+) -> Callable[[ClassT], ClassT] | ClassT:
+    """Decorator for marking a class as a request-scoped dependency."""
+
+    def decorator(c: ClassT) -> ClassT:
+        metadata: ProvidedMetadata = {"scope": "request"}
+        if dependency_type is not NOT_SET:
+            metadata["dependency_type"] = dependency_type
+        if from_context:
+            metadata["from_context"] = from_context
+        c.__provided__ = metadata  # type: ignore[attr-defined]
+        return c
+
+    if cls is None:
+        return decorator
+
+    return decorator(cls)
 
 
 class Provided(Protocol):
@@ -51,7 +158,7 @@ class Provided(Protocol):
 
 
 def is_provided(cls: Any) -> TypeGuard[type[Provided]]:
-    return hasattr(cls, "__provided__")
+    return hasattr(cls, "__provided__") and "scope" in cls.__provided__
 
 
 class ProviderMetadata(TypedDict):

anydi/_graph.py

@@ -0,0 +1,217 @@
+"""Graph generation for AnyDI."""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any, Literal
+
+from typing_extensions import type_repr
+
+from ._provider import Provider
+
+if TYPE_CHECKING:
+    from ._container import Container
+
+
+class Graph:
+    """Graph generator for the dependency container."""
+
+    def __init__(self, container: Container) -> None:
+        self._container = container
+
+    def draw(
+        self,
+        output_format: Literal["tree", "mermaid", "dot", "json"] = "tree",
+        *,
+        full_path: bool = False,
+        **kwargs: Any,
+    ) -> str:
+        """Draw the dependency graph."""
+        if output_format == "mermaid":
+            return self._mermaid(full_path=full_path)
+        if output_format == "dot":
+            return self._dot(full_path=full_path)
+        if output_format == "json":
+            return self._json(full_path=full_path, ident=kwargs.get("ident", 2))
+        return self._tree(full_path=full_path)
+
+    def _mermaid(self, full_path: bool) -> str:
+        """Generate mermaid format dependency graph."""
+        lines: list[str] = ["graph TD"]
+        seen_nodes: set[str] = set()
+
+        for provider in self._container.providers.values():
+            dependency_repr = self._get_name(provider, full_path)
+            scope_label = self._get_scope_label(provider.scope, provider.from_context)
+            node_id = dependency_repr.replace(".", "_")
+
+            if node_id not in seen_nodes:
+                seen_nodes.add(node_id)
+
+            for param in provider.parameters:
+                if param.provider is None:
+                    continue
+
+                dep_name = self._get_name(param.provider, full_path)
+                dep_scope = self._get_scope_label(
+                    param.provider.scope, param.provider.from_context
+                )
+                dep_node_id = dep_name.replace(".", "_")
+
+                if dep_node_id not in seen_nodes:
+                    seen_nodes.add(dep_node_id)
+
+                # Use dashed line for from_context dependencies
+                if param.provider.from_context:
+                    arrow = "-.->"
+                else:
+                    arrow = "-->"
+
+                lines.append(
+                    f'    {node_id}["{dependency_repr} ({scope_label})"] '
+                    f"{arrow}|{param.name}| "
+                    f'{dep_node_id}["{dep_name} ({dep_scope})"]'
+                )
+
+        return "\n".join(lines)
+
+    def _dot(self, full_path: bool) -> str:
+        """Generate DOT format dependency graph."""
+        lines: list[str] = ["digraph G {"]
+        lines.append("    node [shape=box];")
+        seen_edges: set[tuple[str, str]] = set()
+
+        for provider in self._container.providers.values():
+            provider_name = self._get_name(provider, full_path)
+            scope_label = self._get_scope_label(provider.scope, provider.from_context)
+            node_id = f'"{provider_name} ({scope_label})"'
+
+            for param in provider.parameters:
+                if param.provider is None:
+                    continue
+
+                dep_name = self._get_name(param.provider, full_path)
+                dep_scope = self._get_scope_label(
+                    param.provider.scope, param.provider.from_context
+                )
+                dep_node_id = f'"{dep_name} ({dep_scope})"'
+
+                if (node_id, dep_node_id) not in seen_edges:
+                    style = " [style=dashed]" if param.provider.from_context else ""
+                    lines.append(
+                        f'    {node_id} -> {dep_node_id} [label="{param.name}"]{style};'
+                    )
+                    seen_edges.add((node_id, dep_node_id))
+
+        lines.append("}")
+        return "\n".join(lines)
+
+    def _json(self, full_path: bool, ident: int) -> str:
+        """Generate JSON format dependency graph."""
+        container_type = type(self._container)
+        providers: list[dict[str, Any]] = []
+
+        for provider in self._container.providers.values():
+            # Exclude Container itself
+            if provider.dependency_type is container_type:
+                continue
+
+            dependencies: list[dict[str, str]] = []
+            for param in provider.parameters:
+                if param.provider is None:
+                    continue
+                dependencies.append(
+                    {
+                        "name": param.name,
+                        "type": self._get_name(param.provider, full_path),
+                    }
+                )
+
+            providers.append(
+                {
+                    "type": self._get_name(provider, full_path),
+                    "scope": provider.scope,
+                    "from_context": provider.from_context,
+                    "dependencies": dependencies,
+                }
+            )
+
+        return json.dumps({"providers": providers}, indent=ident)
+
+    def _tree(self, full_path: bool) -> str:
+        """Generate tree format dependency graph."""
+        lines: list[str] = []
+
+        # Find all dependency types (providers that are dependencies of others)
+        all_deps: set[Any] = set()
+        for provider in self._container.providers.values():
+            for param in provider.parameters:
+                if param.provider is not None:
+                    all_deps.add(param.provider.dependency_type)
+
+        # Root providers: not a dependency of any other provider
+        # Exclude Container itself (internal implementation detail)
+        container_type = type(self._container)
+        root_providers = [
+            p
+            for p in self._container.providers.values()
+            if p.dependency_type not in all_deps
+            and p.dependency_type is not container_type
+        ]
+
+        for i, provider in enumerate(root_providers):
+            if i > 0:
+                lines.append("")
+            lines.append(self._format_tree_node(provider, full_path))
+            self._render_tree_children(provider, "", set(), lines, full_path)
+
+        return "\n".join(lines)
+
+    @classmethod
+    def _format_tree_node(
+        cls, provider: Provider, full_path: bool, param_name: str | None = None
+    ) -> str:
+        name = cls._get_name(provider, full_path)
+        scope_label = Graph._get_scope_label(provider.scope, provider.from_context)
+        context_marker = " [context]" if provider.from_context else ""
+        if param_name:
+            return f"{param_name}: {name} ({scope_label}){context_marker}"
+        return f"{name} ({scope_label}){context_marker}"
+
+    @staticmethod
+    def _render_tree_children(
+        provider: Provider,
+        prefix: str,
+        visited: set[Any],
+        lines: list[str],
+        full_path: bool,
+    ) -> None:
+        if provider.dependency_type in visited:
+            return
+        visited = visited | {provider.dependency_type}
+
+        deps = [p for p in provider.parameters if p.provider is not None]
+        for i, param in enumerate(deps):
+            dep_provider = param.provider
+            if dep_provider is None:
+                continue
+            is_last = i == len(deps) - 1
+            connector = "└── " if is_last else "├── "
+            node_text = Graph._format_tree_node(dep_provider, full_path, param.name)
+            lines.append(f"{prefix}{connector}{node_text}")
+            extension = "    " if is_last else "│   "
+            Graph._render_tree_children(
+                dep_provider, prefix + extension, visited, lines, full_path
+            )
+
+    @staticmethod
+    def _get_name(provider: Provider, full_path: bool) -> str:
+        if full_path:
+            return type_repr(provider.dependency_type)
+        return type_repr(provider.dependency_type).rsplit(".", 1)[-1]
+
+    @staticmethod
+    def _get_scope_label(scope: str, from_context: bool) -> str:
+        if from_context:
+            return f"{scope}/context"
+        return scope

anydi/_injector.py

@@ -69,9 +69,11 @@ class Injector:
         """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)
+            dependency_type, should_inject, _ = self.validate_parameter(
+                parameter, call=call
+            )
             if should_inject:
-                injected_params[parameter.name] = interface
+                injected_params[parameter.name] = dependency_type
         return injected_params
 
     def validate_parameter(
@@ -79,28 +81,28 @@ class Injector:
     ) -> tuple[Any, bool, Marker | None]:
         """Validate an injected parameter."""
         parameter = self.unwrap_parameter(parameter)
-        interface = parameter.annotation
+        dependency_type = parameter.annotation
 
         marker = parameter.default
         if not is_marker(marker):
-            return interface, False, None
+            return dependency_type, False, None
 
-        if interface is inspect.Parameter.empty:
+        if dependency_type is inspect.Parameter.empty:
             raise TypeError(
                 f"Missing `{type_repr(call)}` parameter `{parameter.name}` annotation."
             )
 
-        # Set inject marker interface
-        parameter.default.interface = interface
+        # Set inject marker dependency type
+        parameter.default.dependency_type = dependency_type
 
-        if not self.container.has_provider_for(interface):
+        if not self.container.has_provider_for(dependency_type):
             raise LookupError(
                 f"`{type_repr(call)}` has an unknown dependency parameter "
                 f"`{parameter.name}` with an annotation of "
-                f"`{type_repr(interface)}`."
+                f"`{type_repr(dependency_type)}`."
             )
 
-        return interface, True, marker
+        return dependency_type, True, marker
 
     @staticmethod
     def unwrap_parameter(parameter: inspect.Parameter) -> inspect.Parameter:

anydi/_marker.py

@@ -12,18 +12,18 @@ T = TypeVar("T")
 class Marker:
     """Marker stored in annotations or defaults to request injection."""
 
-    __slots__ = ("_interface", "_attrs", "_preferred_owner", "_current_owner")
+    __slots__ = ("_dependency_type", "_attrs", "_preferred_owner", "_current_owner")
 
     _FRAMEWORK_ATTRS = frozenset({"dependency", "use_cache", "cast", "cast_result"})
 
-    def __init__(self, interface: Any = NOT_SET) -> None:
+    def __init__(self, dependency_type: Any = NOT_SET) -> None:
         # Avoid reinitializing attributes when mixins call __init__ multiple times
         if not hasattr(self, "_attrs"):
             super().__init__()
             self._attrs: dict[str, dict[str, Any]] = {}
             self._preferred_owner = "fastapi"
             self._current_owner: str | None = None
-        self._interface = interface
+        self._dependency_type = dependency_type
 
     def set_owner(self, owner: str) -> None:
         self._preferred_owner = owner
@@ -53,14 +53,14 @@ class Marker:
         raise AttributeError(name)
 
     @property
-    def interface(self) -> Any:
-        if self._interface is NOT_SET:
-            raise TypeError("Interface is not set.")
-        return self._interface
+    def dependency_type(self) -> Any:
+        if self._dependency_type is NOT_SET:
+            raise TypeError("Dependency type is not set.")
+        return self._dependency_type
 
-    @interface.setter
-    def interface(self, interface: Any) -> None:
-        self._interface = interface
+    @dependency_type.setter
+    def dependency_type(self, dependency_type: Any) -> None:
+        self._dependency_type = dependency_type
 
     def __class_getitem__(cls, item: Any) -> Any:
         return Annotated[item, cls()]
@@ -98,9 +98,7 @@ class _ProvideMeta(type):
     """Metaclass for Provide that delegates __class_getitem__ to the active marker."""
 
     def __getitem__(cls, item: Any) -> Any:
-        if hasattr(_marker_cls, "__class_getitem__"):
-            return _marker_cls.__class_getitem__(item)  # type: ignore
-        return Annotated[item, _marker_cls()]
+        return _marker_cls.__class_getitem__(item)
 
 
 if TYPE_CHECKING:

anydi/_provider.py

@@ -2,10 +2,13 @@ from __future__ import annotations
 
 import enum
 import inspect
+import warnings
 from collections.abc import Callable
-from dataclasses import dataclass
+from dataclasses import KW_ONLY, dataclass
 from typing import Any
 
+from typing_extensions import type_repr
+
 from ._types import NOT_SET, Scope
 
 
@@ -35,8 +38,8 @@ class ProviderKind(enum.IntEnum):
 
 @dataclass(frozen=True, slots=True)
 class ProviderParameter:
+    dependency_type: Any
     name: str
-    annotation: Any
     default: Any
     has_default: bool
     provider: Provider | None = None
@@ -45,10 +48,10 @@ class ProviderParameter:
 
 @dataclass(frozen=True, slots=True)
 class Provider:
-    call: Callable[..., Any]
+    dependency_type: Any
+    factory: Callable[..., Any]
     scope: Scope
-    interface: Any
-    name: str
+    from_context: bool
     parameters: tuple[ProviderParameter, ...]
     is_class: bool
     is_coroutine: bool
@@ -57,9 +60,44 @@ class Provider:
     is_async: bool
     is_resource: bool
 
+    def __repr__(self) -> str:
+        dep_repr = type_repr(self.dependency_type)
+        # For class providers, factory == dependency_type, so just show the type
+        if self.is_class:
+            return dep_repr
+        # For factory providers, include the factory path
+        factory_repr = type_repr(self.factory)
+        return f"{dep_repr} (via {factory_repr})"
 
-@dataclass(frozen=True, slots=True)
+
+@dataclass(slots=True)
 class ProviderDef:
-    call: Callable[..., Any]
-    scope: Scope
+    dependency_type: Any = NOT_SET
+    factory: Callable[..., Any] = NOT_SET
+    _: KW_ONLY
+    from_context: bool = False
+    scope: Scope = "singleton"
     interface: Any = NOT_SET
+    call: Callable[..., Any] = NOT_SET
+
+    def __post_init__(self) -> None:
+        if self.interface is not NOT_SET:
+            warnings.warn(
+                "The `interface` is deprecated. Use `dependency_type` instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        if self.call is not NOT_SET:
+            warnings.warn(
+                "The `call` is deprecated. Use `factory` instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+
+        if self.dependency_type is NOT_SET:
+            self.dependency_type = self.interface
+        if self.factory is NOT_SET:
+            self.factory = self.call
+
+        self.interface = self.dependency_type
+        self.call = self.factory