feat: ⚡️ Scoped slot rework

Author: remimd

documentation/integrations.md

@@ -58,19 +58,19 @@ class InjectionScope(StrEnum):
 
 @asynccontextmanager
 async def lifespan(_: FastAPI) -> AsyncIterator[None]:
-    async with adefine_scope(InjectionScope.LIFESPAN, shared=True):
+    async with adefine_scope(InjectionScope.LIFESPAN, kind="shared"):
         yield
 
 app = FastAPI(lifespan=lifespan)
 
-request_slot = reserve_scoped_slot(Request, InjectionScope.REQUEST)
+request_slot_key = reserve_scoped_slot(Request, InjectionScope.REQUEST)
 
 @app.middleware("http")
 async def define_request_scope_middleware(
     request: Request,
     handler: Callable[[Request], Awaitable[Response]],
 ) -> Response:
-    async with adefine_scope(InjectionScope.REQUEST):
-        request_slot.set(request)
+    async with adefine_scope(InjectionScope.REQUEST) as scope:
+        scope.set_slot(request_slot_key, request)
         return await handler(request)
 ```

documentation/scoped-dependencies.md

@@ -19,15 +19,15 @@ There are two kinds of scopes:
 
 First of all, the scope must be defined:
 
-_By default, the `shared` parameter is `False`._
+_By default, the `kind` parameter is `"contextual"`._
 
 > Define an asynchronous scope:
 
 ```python
 from injection import adefine_scope
 
 async def main() -> None:
-    async with adefine_scope("<scope-name>", shared=True):
+    async with adefine_scope("<scope-name>"):
         ...
 ```
 
@@ -37,7 +37,7 @@ async def main() -> None:
 from injection import define_scope
 
 def main() -> None:
-    with define_scope("<scope-name>", shared=True):
+    with define_scope("<scope-name>"):
         ...
 ```
 
@@ -110,10 +110,13 @@ from injection import define_scope, reserve_scoped_slot
 
 class Request: ...
 
-request_slot = reserve_scoped_slot(Request, scope_name="request")
+request_slot_key = reserve_scoped_slot(Request, scope_name="request")
 
 def process_request(request: Request) -> None:
-    with define_scope("request"):
-        request_slot.set(request)
+    with define_scope("request") as scope:
+        scope.set_slot(request_slot_key, request)
         # ...
 ```
+
+> [!NOTE]
+> You can set several slots at once with the `slot_map` method.

injection/__init__.py

@@ -1,16 +1,19 @@
 from ._core.descriptors import LazyInstance
 from ._core.injectables import Injectable
 from ._core.module import Mode, Module, Priority, mod
-from ._core.scope import adefine_scope, define_scope
-from ._core.slots import Slot
+from ._core.scope import ScopeFacade as Scope
+from ._core.scope import ScopeKind, adefine_scope, define_scope
+from ._core.slots import SlotKey
 
 __all__ = (
     "Injectable",
     "LazyInstance",
     "Mode",
     "Module",
     "Priority",
-    "Slot",
+    "Scope",
+    "ScopeKind",
+    "SlotKey",
     "adefine_scope",
     "afind_instance",
     "aget_instance",

injection/__init__.pyi

@@ -1,5 +1,5 @@
 from abc import abstractmethod
-from collections.abc import AsyncIterator, Awaitable, Callable, Iterator
+from collections.abc import AsyncIterator, Awaitable, Callable, Iterator, Mapping
 from contextlib import asynccontextmanager, contextmanager
 from enum import Enum
 from logging import Logger
@@ -11,6 +11,7 @@ from ._core.common.type import TypeInfo as _TypeInfo
 from ._core.module import InjectableFactory as _InjectableFactory
 from ._core.module import ModeStr, PriorityStr
 from ._core.module import Recipe as _Recipe
+from ._core.scope import ScopeKindStr
 
 __MODULE: Final[Module] = ...
 
@@ -30,9 +31,17 @@ should_be_injectable = __MODULE.should_be_injectable
 singleton = __MODULE.singleton
 
 @asynccontextmanager
-def adefine_scope(name: str, *, shared: bool = ...) -> AsyncIterator[None]: ...
+def adefine_scope(
+    name: str,
+    /,
+    kind: ScopeKind | ScopeKindStr = ...,
+) -> AsyncIterator[Scope]: ...
 @contextmanager
-def define_scope(name: str, *, shared: bool = ...) -> Iterator[None]: ...
+def define_scope(
+    name: str,
+    /,
+    kind: ScopeKind | ScopeKindStr = ...,
+) -> Iterator[Scope]: ...
 def mod(name: str = ..., /) -> Module:
     """
     Short syntax for `Module.from_name`.
@@ -47,10 +56,19 @@ class Injectable[T](Protocol):
     @abstractmethod
     def get_instance(self) -> T: ...
 
+@final
+class ScopeKind(Enum):
+    CONTEXTUAL = ...
+    SHARED = ...
+
 @runtime_checkable
-class Slot[T](Protocol):
+class Scope(Protocol):
     @abstractmethod
-    def set(self, instance: T, /) -> None: ...
+    def set_slot[T](self, key: SlotKey[T], value: T) -> Self: ...
+    @abstractmethod
+    def slot_map(self, mapping: Mapping[SlotKey[Any], Any], /) -> Self: ...
+
+class SlotKey[T]: ...
 
 class LazyInstance[T]:
     def __init__(
@@ -179,12 +197,12 @@ class Module:
 
     def reserve_scoped_slot[T](
         self,
-        on: _TypeInfo[T],
+        cls: type[T],
         /,
         scope_name: str,
         *,
         mode: Mode | ModeStr = ...,
-    ) -> Slot[T]: ...
+    ) -> SlotKey[T]: ...
     def make_injected_function[**P, T](
         self,
         wrapped: Callable[P, T],

injection/_core/injectables.py

@@ -17,8 +17,14 @@
 from injection._core.common.asynchronous import (
     create_semaphore as _create_async_semaphore,
 )
-from injection._core.scope import Scope, get_active_scopes, get_scope
-from injection.exceptions import InjectionError
+from injection._core.scope import (
+    Scope,
+    get_scope,
+    in_scope_cache,
+    remove_scoped_values,
+)
+from injection._core.slots import SlotKey
+from injection.exceptions import EmptySlotError, InjectionError
 
 
 @runtime_checkable
@@ -123,7 +129,7 @@ class ScopedInjectable[R, T](Injectable[T], ABC):
 
     @property
     def is_locked(self) -> bool:
-        return any(self in scope.cache for scope in get_active_scopes(self.scope_name))
+        return in_scope_cache(self, self.scope_name)
 
     @abstractmethod
     async def abuild(self, scope: Scope) -> T:
@@ -143,10 +149,6 @@ def get_instance(self) -> T:
         factory = partial(self.build, scope)
         return self.logic.get_or_create(scope.cache, self, factory)
 
-    def setdefault(self, instance: T) -> T:
-        scope = self.__get_scope()
-        return self.logic.get_or_create(scope.cache, self, lambda: instance)
-
     def unlock(self) -> None:
         if self.is_locked:
             raise RuntimeError(f"To unlock, close the `{self.scope_name}` scope.")
@@ -188,8 +190,35 @@ def build(self, scope: Scope) -> T:
         return self.factory.call()
 
     def unlock(self) -> None:
-        for scope in get_active_scopes(self.scope_name):
-            scope.cache.pop(self, None)
+        remove_scoped_values(self, self.scope_name)
+
+
+@dataclass(repr=False, eq=False, frozen=True, slots=True)
+class ScopedSlotInjectable[T](Injectable[T]):
+    cls: type[T]
+    scope_name: str
+    key: SlotKey[T] = field(default_factory=SlotKey)
+
+    @property
+    def is_locked(self) -> bool:
+        return in_scope_cache(self.key, self.scope_name)
+
+    async def aget_instance(self) -> T:
+        return self.get_instance()
+
+    def get_instance(self) -> T:
+        scope_name = self.scope_name
+        scope = get_scope(scope_name)
+
+        try:
+            return scope.cache[self.key]
+        except KeyError as exc:
+            raise EmptySlotError(
+                f"The slot for `{self.cls}` isn't set in the current `{scope_name}` scope."
+            ) from exc
+
+    def unlock(self) -> None:
+        remove_scoped_values(self.key, self.scope_name)
 
 
 @dataclass(repr=False, eq=False, frozen=True, slots=True)

injection/_core/module.py

@@ -64,14 +64,14 @@
     CMScopedInjectable,
     Injectable,
     ScopedInjectable,
+    ScopedSlotInjectable,
     ShouldBeInjectable,
     SimpleInjectable,
     SimpleScopedInjectable,
     SingletonInjectable,
 )
-from injection._core.slots import ScopedSlot, Slot
+from injection._core.slots import SlotKey
 from injection.exceptions import (
-    EmptySlotError,
     ModuleError,
     ModuleLockError,
     ModuleNotUsedError,
@@ -492,11 +492,8 @@ def decorator(
 
     def should_be_injectable[T](self, wrapped: type[T] | None = None, /) -> Any:
         def decorator(wp: type[T]) -> type[T]:
-            updater = Updater(
-                classes=(wp,),
-                injectable=ShouldBeInjectable(wp),
-                mode=Mode.FALLBACK,
-            )
+            injectable = ShouldBeInjectable(wp)
+            updater = Updater.with_basics(wp, injectable, Mode.FALLBACK)
             self.update(updater)
             return wp
 
@@ -543,21 +540,16 @@ def set_constant[T](
 
     def reserve_scoped_slot[T](
         self,
-        on: TypeInfo[T],
+        cls: type[T],
         /,
         scope_name: str,
         *,
         mode: Mode | ModeStr = Mode.get_default(),
-    ) -> Slot[T]:
-        def when_empty() -> T:
-            raise EmptySlotError(
-                f"The slot for `{on}` isn't set in the current `{scope_name}` scope."
-            )
-
-        injectable = SimpleScopedInjectable(SyncCaller(when_empty), scope_name)
-        updater = Updater.with_basics(on, injectable, mode)
+    ) -> SlotKey[T]:
+        injectable = ScopedSlotInjectable(cls, scope_name)
+        updater = Updater.with_basics(cls, injectable, mode)
         self.update(updater)
-        return ScopedSlot(injectable)
+        return injectable.key
 
     def inject[**P, T](
         self,