anydi 0.57.0__tar.gz → 0.58.0__tar.gz

{anydi-0.57.0 → anydi-0.58.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: anydi
-Version: 0.57.0
+Version: 0.58.0
 Summary: Dependency Injection library
 Keywords: dependency injection,dependencies,di,async,asyncio,application
 Author: Anton Ruhlov
@@ -58,9 +58,9 @@ The key features are:
 
 * **Type-safe**: Dependency resolution is driven by type hints.
 * **Async-ready**: Works the same for sync and async providers or injections.
-* **Scoped**: Built-in singleton, transient, and request lifetimes.
+* **Scoped**: Built-in singleton, transient, and request scopes, plus custom scopes.
 * **Simple**: Small surface area keeps boilerplate low.
-* **Fast**: Resolver still adds only microseconds of overhead.
+* **Fast**: Has minimal overhead and resolves dependencies quickly.
 * **Named**: `Annotated[...]` makes multiple bindings per type simple.
 * **Managed**: Providers can open/close resources via context managers.
 * **Modular**: Compose containers or modules for large apps.
@@ -74,7 +74,7 @@ The key features are:
 pip install anydi
 ```
 
-## Comprehensive Example
+## Quick Example
 
 ### Define a Service (`app/services.py`)
 
@@ -264,3 +264,23 @@ urlpatterns = [
     path("api/", api.urls),
 ]
 ```
+
+## What's Next?
+
+Ready to learn more? Check out these resources:
+
+**Core Documentation:**
+- [Core Concepts](https://anydi.readthedocs.io/en/latest/concepts/) - Understand containers, providers, scopes, and dependency injection
+- [Providers](https://anydi.readthedocs.io/en/latest/usage/providers/) - Learn about registration, named providers, and resource management
+- [Scopes](https://anydi.readthedocs.io/en/latest/usage/scopes/) - Master lifecycle management with built-in and custom scopes
+- [Dependency Injection](https://anydi.readthedocs.io/en/latest/usage/injection/) - Explore injection patterns and techniques
+- [Testing](https://anydi.readthedocs.io/en/latest/usage/testing/) - Write testable code with provider overrides
+
+**Framework Integrations:**
+- [FastAPI](https://anydi.readthedocs.io/en/latest/extensions/fastapi/) - Build modern APIs with automatic dependency injection
+- [Django](https://anydi.readthedocs.io/en/latest/extensions/django/) - Integrate with Django and Django Ninja
+- [FastStream](https://anydi.readthedocs.io/en/latest/extensions/faststream/) - Message broker applications
+- [Pydantic Settings](https://anydi.readthedocs.io/en/latest/extensions/pydantic_settings/) - Configuration management
+
+**Full Documentation:**
+- [Read the Docs](https://anydi.readthedocs.io/) - Complete documentation with examples and guides

{anydi-0.57.0 → anydi-0.58.0}/README.md

@@ -23,9 +23,9 @@ The key features are:
 
 * **Type-safe**: Dependency resolution is driven by type hints.
 * **Async-ready**: Works the same for sync and async providers or injections.
-* **Scoped**: Built-in singleton, transient, and request lifetimes.
+* **Scoped**: Built-in singleton, transient, and request scopes, plus custom scopes.
 * **Simple**: Small surface area keeps boilerplate low.
-* **Fast**: Resolver still adds only microseconds of overhead.
+* **Fast**: Has minimal overhead and resolves dependencies quickly.
 * **Named**: `Annotated[...]` makes multiple bindings per type simple.
 * **Managed**: Providers can open/close resources via context managers.
 * **Modular**: Compose containers or modules for large apps.
@@ -39,7 +39,7 @@ The key features are:
 pip install anydi
 ```
 
-## Comprehensive Example
+## Quick Example
 
 ### Define a Service (`app/services.py`)
 
@@ -229,3 +229,23 @@ urlpatterns = [
     path("api/", api.urls),
 ]
 ```
+
+## What's Next?
+
+Ready to learn more? Check out these resources:
+
+**Core Documentation:**
+- [Core Concepts](https://anydi.readthedocs.io/en/latest/concepts/) - Understand containers, providers, scopes, and dependency injection
+- [Providers](https://anydi.readthedocs.io/en/latest/usage/providers/) - Learn about registration, named providers, and resource management
+- [Scopes](https://anydi.readthedocs.io/en/latest/usage/scopes/) - Master lifecycle management with built-in and custom scopes
+- [Dependency Injection](https://anydi.readthedocs.io/en/latest/usage/injection/) - Explore injection patterns and techniques
+- [Testing](https://anydi.readthedocs.io/en/latest/usage/testing/) - Write testable code with provider overrides
+
+**Framework Integrations:**
+- [FastAPI](https://anydi.readthedocs.io/en/latest/extensions/fastapi/) - Build modern APIs with automatic dependency injection
+- [Django](https://anydi.readthedocs.io/en/latest/extensions/django/) - Integrate with Django and Django Ninja
+- [FastStream](https://anydi.readthedocs.io/en/latest/extensions/faststream/) - Message broker applications
+- [Pydantic Settings](https://anydi.readthedocs.io/en/latest/extensions/pydantic_settings/) - Configuration management
+
+**Full Documentation:**
+- [Read the Docs](https://anydi.readthedocs.io/) - Complete documentation with examples and guides

{anydi-0.57.0 → anydi-0.58.0}/anydi/_container.py

@@ -9,7 +9,7 @@ import logging
 import types
 import uuid
 from collections import defaultdict
-from collections.abc import AsyncIterator, Callable, Iterable, Iterator
+from collections.abc import AsyncIterator, Callable, Iterable, Iterator, Sequence
 from contextvars import ContextVar
 from typing import Any, TypeVar, get_args, get_origin, overload
 
@@ -22,24 +22,11 @@ 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")
 
-ALLOWED_SCOPES: dict[Scope, list[Scope]] = {
-    "singleton": ["singleton"],
-    "request": ["request", "singleton"],
-    "transient": ["transient", "request", "singleton"],
-}
-
 
 class Container:
     """AnyDI is a dependency injection container."""
@@ -53,11 +40,14 @@ class Container:
     ) -> None:
         self._providers: dict[Any, Provider] = {}
         self._logger = logger or logging.getLogger(__name__)
+        self._scopes: dict[str, Sequence[str]] = {
+            "transient": ("transient", "singleton"),
+            "singleton": ("singleton",),
+        }
+
         self._resources: dict[str, list[Any]] = defaultdict(list)
         self._singleton_context = InstanceContext()
-        self._request_context_var: ContextVar[InstanceContext | None] = ContextVar(
-            "request_context", default=None
-        )
+        self._scoped_context: dict[str, ContextVar[InstanceContext]] = {}
 
         # Components
         self._resolver = Resolver(self)
@@ -65,6 +55,9 @@ class Container:
         self._modules = ModuleRegistrar(self)
         self._scanner = Scanner(self)
 
+        # Register default scopes
+        self.register_scope("request")
+
         # Register providers
         providers = providers or []
         for provider in providers:
@@ -141,54 +134,128 @@ class Container:
         await self._singleton_context.aclose()
 
     @contextlib.contextmanager
-    def request_context(self) -> Iterator[InstanceContext]:
+    def scoped_context(self, scope: str) -> Iterator[InstanceContext]:
         """Obtain a context manager for the request-scoped context."""
-        context = InstanceContext()
+        context_var = self._get_scoped_context_var(scope)
 
-        token = self._request_context_var.set(context)
+        # Check if context already exists (re-entering same scope)
+        context = context_var.get(None)
+        if context is not None:
+            # Reuse existing context, don't create a new one
+            yield context
+            return
+
+        # Create new context
+        context = InstanceContext()
+        token = context_var.set(context)
 
         # Resolve all request resources
-        for interface in self._resources.get("request", []):
+        for interface in self._resources.get(scope, []):
             if not is_event_type(interface):
                 continue
             self.resolve(interface)
 
         with context:
             yield context
-            self._request_context_var.reset(token)
+            context_var.reset(token)
 
     @contextlib.asynccontextmanager
-    async def arequest_context(self) -> AsyncIterator[InstanceContext]:
-        """Obtain an async context manager for the request-scoped context."""
-        context = InstanceContext()
+    async def ascoped_context(self, scope: str) -> AsyncIterator[InstanceContext]:
+        """Obtain a context manager for the specified scoped context."""
+        context_var = self._get_scoped_context_var(scope)
+
+        # Check if context already exists (re-entering same scope)
+        context = context_var.get(None)
+        if context is not None:
+            # Reuse existing context, don't create a new one
+            yield context
+            return
 
-        token = self._request_context_var.set(context)
+        # Create new context
+        context = InstanceContext()
+        token = context_var.set(context)
 
-        for interface in self._resources.get("request", []):
+        # Resolve all request resources
+        for interface in self._resources.get(scope, []):
             if not is_event_type(interface):
                 continue
             await self.aresolve(interface)
 
         async with context:
             yield context
-            self._request_context_var.reset(token)
+            context_var.reset(token)
+
+    @contextlib.contextmanager
+    def request_context(self) -> Iterator[InstanceContext]:
+        """Obtain a context manager for the request-scoped context."""
+        with self.scoped_context("request") as context:
+            yield context
+
+    @contextlib.asynccontextmanager
+    async def arequest_context(self) -> AsyncIterator[InstanceContext]:
+        """Obtain an async context manager for the request-scoped context."""
+        async with self.ascoped_context("request") as context:
+            yield context
 
-    def _get_request_context(self) -> InstanceContext:
-        """Get the current request context."""
-        request_context = self._request_context_var.get()
-        if request_context is None:
+    def _get_scoped_context(self, scope: str) -> InstanceContext:
+        scoped_context_var = self._get_scoped_context_var(scope)
+        try:
+            scoped_context = scoped_context_var.get()
+        except LookupError as exc:
             raise LookupError(
-                "The request context has not been started. Please ensure that "
-                "the request context is properly initialized before attempting "
+                f"The {scope} context has not been started. Please ensure that "
+                f"the {scope} context is properly initialized before attempting "
                 "to use it."
+            ) from exc
+        return scoped_context
+
+    def _get_scoped_context_var(self, scope: str) -> ContextVar[InstanceContext]:
+        """Get the context variable for the specified scope."""
+        # Validate that scope is registered and not reserved
+        if scope in ("transient", "singleton"):
+            raise ValueError(
+                f"Cannot get context variable for reserved scope `{scope}`."
             )
-        return request_context
+        if scope not in self._scopes:
+            raise ValueError(
+                f"Cannot get context variable for not registered scope `{scope}`. "
+                f"Please register the scope first using register_scope()."
+            )
+
+        if scope not in self._scoped_context:
+            self._scoped_context[scope] = ContextVar(f"{scope}_context")
+        return self._scoped_context[scope]
 
     def _get_instance_context(self, scope: Scope) -> InstanceContext:
         """Get the instance context for the specified scope."""
         if scope == "singleton":
             return self._singleton_context
-        return self._get_request_context()
+        return self._get_scoped_context(scope)
+
+    # == Scopes == #
+
+    def register_scope(
+        self, scope: str, *, parents: Sequence[str] | None = None
+    ) -> None:
+        """Register a new scope with the specified parents."""
+        # Check if the scope is reserved
+        if scope in ("transient", "singleton"):
+            raise ValueError(
+                f"The scope `{scope}` is reserved and cannot be overridden."
+            )
+
+        # Check if the scope is already registered
+        if scope in self._scopes:
+            raise ValueError(f"The scope `{scope}` is already registered.")
+
+        # Validate parents
+        parents = parents or []
+        for parent in parents:
+            if parent not in self._scopes:
+                raise ValueError(f"The parent scope `{parent}` is not registered.")
+
+        # Register the scope
+        self._scopes[scope] = tuple({scope, "singleton"} | set(parents))
 
     # == Provider Registry ==
 
@@ -300,7 +367,7 @@ class Container:
         unresolved_parameter = None
         unresolved_exc: LookupError | None = None
         parameters: list[ProviderParameter] = []
-        scopes: dict[Scope, Provider] = {}
+        scope_provider: dict[Scope, Provider] = {}
 
         for parameter in signature.parameters.values():
             if parameter.annotation is inspect.Parameter.empty:
@@ -331,8 +398,8 @@ class Container:
                 continue
 
             # Store first provider for each scope
-            if sub_provider.scope not in scopes:
-                scopes[sub_provider.scope] = sub_provider
+            if sub_provider.scope not in scope_provider:
+                scope_provider[sub_provider.scope] = sub_provider
 
             parameters.append(
                 ProviderParameter(
@@ -345,6 +412,18 @@ class Container:
                 )
             )
 
+        # Check scope compatibility
+        # Transient scope can use any scoped dependencies
+        if scope != "transient":
+            for sub_provider in scope_provider.values():
+                if sub_provider.scope not in self._scopes.get(scope, []):
+                    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."
+                    )
+
         # Check for unresolved parameters
         if unresolved_parameter:
             if scope not in ("singleton", "transient"):
@@ -358,15 +437,6 @@ class Container:
                     f"attempting to use it."
                 ) from unresolved_exc
 
-        # Check scope compatibility
-        for sub_provider in scopes.values():
-            if sub_provider.scope not in ALLOWED_SCOPES.get(scope, []):
-                raise ValueError(
-                    f"The provider `{name}` with a `{scope}` scope cannot "
-                    f"depend on `{sub_provider}` with a `{sub_provider.scope}` scope. "
-                    "Please ensure all providers are registered with matching scopes."
-                )
-
         is_coroutine = kind == ProviderKind.COROUTINE
         is_generator = kind == ProviderKind.GENERATOR
         is_async_generator = kind == ProviderKind.ASYNC_GENERATOR
@@ -389,13 +459,14 @@ class Container:
         self._set_provider(provider)
         return provider
 
-    @staticmethod
-    def _validate_provider_scope(scope: Scope, name: str, is_resource: bool) -> None:
+    def _validate_provider_scope(
+        self, scope: Scope, name: str, is_resource: bool
+    ) -> None:
         """Validate the provider scope."""
-        if scope not in ALLOWED_SCOPES:
+        if scope not in self._scopes:
             raise ValueError(
                 f"The provider `{name}` scope is invalid. Only the following "
-                f"scopes are supported: {', '.join(ALLOWED_SCOPES)}. "
+                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:

{anydi-0.57.0 → anydi-0.58.0}/anydi/_resolver.py

@@ -453,7 +453,7 @@ class Resolver:
                 create_lines.append("        context.enter(inst)")
 
         create_lines.append("    if context is not None and store:")
-        create_lines.append("        context.set(_interface, inst)")
+        create_lines.append("        context._instances[_interface] = inst")
 
         # Wrap instance if in override mode (only for override version)
         if with_override:
@@ -470,18 +470,28 @@ class Resolver:
             resolver_lines.append("def _resolver(container, context=None):")
 
         # Only define NOT_SET_ if we actually need it
-        needs_not_set = scope in ("singleton", "request")
+        needs_not_set = scope != "transient"
         if needs_not_set:
             resolver_lines.append("    NOT_SET_ = _NOT_SET")
 
         if scope == "singleton":
             resolver_lines.append("    if context is None:")
             resolver_lines.append("        context = container._singleton_context")
-        elif scope == "request":
-            resolver_lines.append("    if context is None:")
-            resolver_lines.append("        context = container._get_request_context()")
-        else:
+        elif scope == "transient":
             resolver_lines.append("    context = None")
+        else:
+            # Custom scopes (including "request")
+            # Inline context retrieval to avoid method call overhead
+            resolver_lines.append("    if context is None:")
+            resolver_lines.append("        try:")
+            resolver_lines.append("            context = _scoped_context_var.get()")
+            resolver_lines.append("        except LookupError:")
+            resolver_lines.append(
+                f"            raise LookupError("
+                f"'The {scope} context has not been started. "
+                f"Please ensure that the {scope} context is properly initialized "
+                f"before attempting to use it.')"
+            )
 
         if scope == "singleton":
             if with_override:
@@ -507,33 +517,36 @@ class Resolver:
                 store=True,
                 indent="        ",
             )
-        elif scope == "request":
+        elif scope == "transient":
+            # Transient scope
             if with_override:
-                self._add_override_check(resolver_lines)
-
-            # Fast path: check cached instance
-            resolver_lines.append("    inst = context.get(_interface)")
-            resolver_lines.append("    if inst is not NOT_SET_:")
-            resolver_lines.append("        return inst")
+                self._add_override_check(resolver_lines, include_not_set=True)
 
             self._add_create_call(
                 resolver_lines,
                 is_async=is_async,
                 with_override=with_override,
-                context="context",
-                store=True,
+                context="",
+                store=False,
             )
         else:
-            # Transient scope
+            # Custom scopes (including "request")
             if with_override:
-                self._add_override_check(resolver_lines, include_not_set=True)
+                self._add_override_check(resolver_lines)
+
+            # Fast path: check cached instance (inline dict access for speed)
+            resolver_lines.append(
+                "    inst = context._instances.get(_interface, NOT_SET_)"
+            )
+            resolver_lines.append("    if inst is not NOT_SET_:")
+            resolver_lines.append("        return inst")
 
             self._add_create_call(
                 resolver_lines,
                 is_async=is_async,
                 with_override=with_override,
-                context="",
-                store=False,
+                context="context",
+                store=True,
             )
 
         create_resolver_lines: list[str] = []
@@ -552,18 +565,26 @@ class Resolver:
 
         if scope == "singleton":
             create_resolver_lines.append("    context = container._singleton_context")
-        elif scope == "request":
+        elif scope == "transient":
+            create_resolver_lines.append("    context = None")
+        else:
+            # Custom scopes (including "request")
+            # Inline context retrieval to avoid method call overhead
+            create_resolver_lines.append("    try:")
+            create_resolver_lines.append("        context = _scoped_context_var.get()")
+            create_resolver_lines.append("    except LookupError:")
             create_resolver_lines.append(
-                "    context = container._get_request_context()"
+                f"        raise LookupError("
+                f"'The {scope} context has not been started. "
+                f"Please ensure that the {scope} context is properly initialized "
+                f"before attempting to use it.')"
             )
-        else:
-            create_resolver_lines.append("    context = None")
 
         if with_override:
             self._add_override_check(create_resolver_lines, include_not_set=True)
 
         # Determine context for create call
-        context_arg = "context" if scope in ("singleton", "request") else ""
+        context_arg = "context" if scope != "transient" else ""
 
         self._add_create_call(
             create_resolver_lines,
@@ -603,6 +624,12 @@ class Resolver:
             "resolver": self,
         }
 
+        # For custom scopes, cache the ContextVar to avoid dictionary lookups
+        if scope not in ("singleton", "transient"):
+            ns["_scoped_context_var"] = self._container._get_scoped_context_var(  # type: ignore[reportPrivateUsage]
+                scope
+            )
+
         # Add async-specific namespace entries
         if is_async:
             ns["_asynccontextmanager"] = contextlib.asynccontextmanager

{anydi-0.57.0 → anydi-0.58.0}/anydi/_types.py

@@ -11,7 +11,7 @@ from typing_extensions import Sentinel
 
 T = TypeVar("T")
 
-Scope = Literal["transient", "singleton", "request"]
+Scope = Literal["transient", "singleton", "request"] | str
 
 NOT_SET = Sentinel("NOT_SET")
 

{anydi-0.57.0 → anydi-0.58.0}/anydi/ext/fastapi.py

@@ -11,8 +11,8 @@ from fastapi.dependencies.models import Dependant
 from fastapi.routing import APIRoute
 from starlette.requests import Request
 
-from anydi import Container
-from anydi._types import Inject, ProvideMarker, set_provide_factory
+from anydi import Container, Inject
+from anydi._types import ProvideMarker, set_provide_factory
 
 from .starlette.middleware import RequestScopedMiddleware
 

{anydi-0.57.0 → anydi-0.58.0}/anydi/ext/starlette/middleware.py

@@ -5,7 +5,7 @@ from starlette.requests import Request
 from starlette.responses import Response
 from starlette.types import ASGIApp
 
-from anydi._container import Container
+from anydi import Container
 
 
 class RequestScopedMiddleware(BaseHTTPMiddleware):

{anydi-0.57.0 → anydi-0.58.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "anydi"
-version = "0.57.0"
+version = "0.58.0"
 description = "Dependency Injection library"
 authors = [{ name = "Anton Ruhlov", email = "antonruhlov@gmail.com" }]
 requires-python = ">=3.10.0, <3.15"