feat: ✨ Introduce MappedScope

Author: remimd

documentation/scoped-dependencies.md

@@ -41,6 +41,50 @@ def main() -> None:
         ...
 ```
 
+## MappedScope
+
+`MappedScope` allows you to open a dependency injection scope and register values annotated with `Scoped[...]` so they 
+can be retrieved by other dependencies within that scope.
+
+### How it works
+
+1. **Define bindings**: Create a class with fields annotated with `Scoped`.
+2. **Create scope**: Instantiate `MappedScope` with a scope name.
+3. **Open scope**: Use `define` or `adefine` context manager to register the scoped values.
+4. **Access dependencies**: Other dependencies can now inject these scoped values within the context.
+
+This is particularly useful for request-scoped dependencies in web applications, where you need to make request-specific
+data available throughout the request lifecycle.
+
+Example:
+
+```python
+from dataclasses import dataclass
+from injection import MappedScope, Scoped
+
+class Request: ...
+
+@dataclass
+class RequestBindings:
+    request: Scoped[Request]
+
+    scope = MappedScope("request")
+
+def process_request(request: Request) -> None:
+    with RequestBindings(request).scope.define():
+        # Dependencies can now access the scoped Request instance
+        ...
+```
+
+For asynchronous contexts, use `adefine`:
+
+```python
+async def process_request_async(request: Request) -> None:
+    async with RequestBindings(request).scope.adefine():
+        # Dependencies can now access the scoped Request instance
+        ...
+```
+
 ## Register a scoped dependencies
 
 `@scoped` works exactly like `@injectable`, it just has extra features.
@@ -99,6 +143,9 @@ def client_recipe() -> Iterator[Client]:
 
 ### Scoped slots
 
+> [!IMPORTANT]
+> It's preferable to use `MappedScope` instead.
+
 Scoped slots allow you to reserve a place for an instance within a predefined scope. This ensures that injected 
 functions can resolve dependencies efficiently without unnecessary recomputation. This is why the syntax can seem a 
 little verbose.

injection/__init__.py

@@ -1,5 +1,5 @@
 from ._core.asfunction import asfunction
-from ._core.descriptors import LazyInstance
+from ._core.descriptors import LazyInstance, MappedScope, Scoped
 from ._core.injectables import Injectable
 from ._core.module import Mode, Module, Priority, mod
 from ._core.scope import ScopeFacade as Scope
@@ -9,10 +9,12 @@
 __all__ = (
     "Injectable",
     "LazyInstance",
+    "MappedScope",
     "Mode",
     "Module",
     "Priority",
     "Scope",
+    "Scoped",
     "ScopeKind",
     "SlotKey",
     "adefine_scope",

injection/__init__.pyi

@@ -13,6 +13,7 @@ from ._core.module import InjectableFactory as _InjectableFactory
 from ._core.module import ModeStr, PriorityStr
 from ._core.scope import ScopeKindStr
 
+type Scoped[T] = T
 type _Decorator[T] = Callable[[T], T]
 
 __MODULE: Final[Module] = ...
@@ -90,6 +91,34 @@ class Scope(Protocol):
 
 class SlotKey[T]: ...
 
+class MappedScope:
+    def __init__(self, name: str, /, module: Module = ...) -> None: ...
+    @overload
+    def __get__(
+        self,
+        instance: object,
+        owner: type | None = ...,
+    ) -> _BoundMappedScope: ...
+    @overload
+    def __get__(self, instance: None = ..., owner: type | None = ...) -> Self: ...
+    def __set_name__(self, owner: type, name: str) -> None: ...
+
+class _BoundMappedScope:
+    @asynccontextmanager
+    def adefine(
+        self,
+        /,
+        kind: ScopeKind | ScopeKindStr = ...,
+        threadsafe: bool | None = ...,
+    ) -> AsyncIterator[None]: ...
+    @contextmanager
+    def define(
+        self,
+        /,
+        kind: ScopeKind | ScopeKindStr = ...,
+        threadsafe: bool | None = ...,
+    ) -> Iterator[None]: ...
+
 class LazyInstance[T]:
     def __init__(
         self,

injection/_core/descriptors.py

@@ -1,8 +1,98 @@
-from typing import Self
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Iterator, Mapping
+from contextlib import asynccontextmanager, contextmanager
+from dataclasses import dataclass
+from types import MappingProxyType
+from typing import Any, Self, get_args, get_origin, get_type_hints
 
 from injection._core.common.invertible import Invertible
 from injection._core.common.type import InputType
 from injection._core.module import Module, mod
+from injection._core.scope import ScopeKind, ScopeKindStr, adefine_scope, define_scope
+from injection._core.slots import SlotKey
+
+type Scoped[T] = T
+
+
+class MappedScope:
+    __slots__ = ("__keys", "__module", "__name", "__owner")
+
+    __keys: Mapping[str, SlotKey[Any]]
+    __module: Module
+    __name: str
+    __owner: type | None
+
+    def __init__(self, name: str, /, module: Module | None = None) -> None:
+        self.__module = module or mod()
+        self.__name = name
+        self.__owner = None
+
+    def __get__(
+        self,
+        instance: object | None = None,
+        owner: type | None = None,
+    ) -> Self | BoundMappedScope:
+        if instance is None:
+            return self
+
+        mapping = self.__mapping_from(instance)
+        return BoundMappedScope(self.__name, mapping)
+
+    def __set_name__(self, owner: type, name: str) -> None:
+        if self.__owner:
+            raise TypeError(f"`{self}` owner is already defined.")
+
+        self.__keys = MappingProxyType(dict(self.__generate_keys(owner)))
+        self.__owner = owner
+
+    def __generate_keys(self, cls: type) -> Iterator[tuple[str, SlotKey[Any]]]:
+        for name, hint in get_type_hints(cls).items():
+            if get_origin(hint) is not Scoped:
+                continue
+
+            annotation = get_args(hint)[0]
+            key = self.__module.reserve_scoped_slot(annotation, scope_name=self.__name)
+            yield name, key
+
+    def __mapping_from(self, instance: object) -> dict[SlotKey[Any], Any]:
+        return {
+            key: value
+            for name, key in self.__keys.items()
+            if (value := getattr(instance, name, None)) is not None
+        }
+
+
+@dataclass(repr=False, eq=False, frozen=True, slots=True)
+class BoundMappedScope:
+    name: str
+    mapping: Mapping[SlotKey[Any], Any]
+
+    @asynccontextmanager
+    async def adefine(
+        self,
+        /,
+        kind: ScopeKind | ScopeKindStr = ScopeKind.get_default(),
+        threadsafe: bool | None = None,
+    ) -> AsyncIterator[None]:
+        async with adefine_scope(self.name, kind, threadsafe) as scope:
+            if mapping := self.mapping:
+                scope.slot_map(mapping)
+
+            yield
+
+    @contextmanager
+    def define(
+        self,
+        /,
+        kind: ScopeKind | ScopeKindStr = ScopeKind.get_default(),
+        threadsafe: bool | None = None,
+    ) -> Iterator[None]:
+        with define_scope(self.name, kind, threadsafe) as scope:
+            if mapping := self.mapping:
+                scope.slot_map(mapping)
+
+            yield
 
 
 class LazyInstance[T]:

tests/core/test_descriptors.py

@@ -1,4 +1,58 @@
-from injection import LazyInstance, injectable
+from dataclasses import dataclass
+
+import pytest
+
+from injection import LazyInstance, MappedScope, Scoped, injectable
+
+
+class _RawData: ...
+
+
+class TestMappedScope:
+    def test_set_name_with_multiple_owner_raise_type_error(self):
+        class ContextA:
+            scope = MappedScope("some_scope")
+
+        with pytest.raises(TypeError):
+
+            class ContextB:
+                scope = ContextA.scope
+
+    async def test_aopen_with_success(self, module):
+        @dataclass
+        class ScopeContext:
+            data: Scoped[_RawData]
+
+            scope = MappedScope("some_scope", module=module)
+
+        data = _RawData()
+        context = ScopeContext(data)
+
+        assert module.get_instance(_RawData) is NotImplemented
+
+        async with context.scope.adefine():
+            assert module.get_instance(_RawData) is data
+
+        assert module.get_instance(_RawData) is NotImplemented
+
+    def test_open_with_success(self, module):
+        @dataclass
+        class ScopeContext:
+            data: Scoped[_RawData]
+            unscoped_data: int
+
+            scope = MappedScope("some_scope", module=module)
+
+        data = _RawData()
+        context = ScopeContext(data, 2)
+
+        assert module.get_instance(_RawData) is NotImplemented
+
+        with context.scope.define():
+            assert module.get_instance(_RawData) is data
+            assert module.get_instance(int) is NotImplemented
+
+        assert module.get_instance(_RawData) is NotImplemented
 
 
 class TestLazyInstance: