feat: ✨ Scoped slots

Author: remimd

documentation/advanced-usage.md

@@ -135,7 +135,7 @@ there may be a problem with this instance. It may contain an obsolete dependency
 
 _First of all, make sure that all scripts containing injectables have been imported before executing the main function._
 
-> **Tips**
+> [!TIP]
 > * Avoid local imports
 > * Avoid singletons if not necessary
 

documentation/basic-usage.md

@@ -2,7 +2,8 @@
 
 ## Register an injectable
 
-> **Note**: If the class needs dependencies, these will be resolved when the instance is retrieved.
+> [!NOTE]
+> If the class needs dependencies, these will be resolved when the instance is retrieved.
 
 If you wish to inject a singleton, use `singleton` decorator.
 
@@ -65,7 +66,8 @@ def some_function(service_a: ServiceA):
 If `inject` decorates a class, it will be applied to the `__init__` method.
 _Especially useful for dataclasses:_
 
-> **Note**: Doesn't work with Pydantic `BaseModel` because the signature of the `__init__` method doesn't contain the
+> [!NOTE]
+> Doesn't work with Pydantic `BaseModel` because the signature of the `__init__` method doesn't contain the
 > dependencies.
 
 ```python
@@ -132,8 +134,9 @@ service_a = await lazy_service_a
 In the case of inheritance, you can use the decorator parameter `on` to link the injection to one or several other
 classes.
 
-**Warning: if the child class is in another file, make sure that file is imported before injection.**
-[_See `load_packages` function._](utils.md#load_packages)
+> [!WARNING]
+> If the child class is in another file, make sure that file is imported before injection.
+> [_See `load_packages` function._](utils.md#load_packages)
 
 _Example with one class:_
 

documentation/integrations.md

@@ -50,7 +50,7 @@ from contextlib import asynccontextmanager
 from enum import StrEnum, auto
 
 from fastapi import FastAPI, Request, Response
-from injection import adefine_scope
+from injection import adefine_scope, reserve_scoped_slot
 
 class InjectionScope(StrEnum):
     LIFESPAN = auto()
@@ -63,11 +63,14 @@ async def lifespan(_: FastAPI) -> AsyncIterator[None]:
 
 app = FastAPI(lifespan=lifespan)
 
+request_slot = 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)
         return await handler(request)
 ```

documentation/scoped-dependencies.md

@@ -96,3 +96,24 @@ def client_recipe() -> Iterator[Client]:
         # On scope close
         client.close_connection()
 ```
+
+### Scoped slots
+
+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.
+
+Example:
+
+```python
+from injection import define_scope, reserve_scoped_slot
+
+class Request: ...
+
+request_slot = reserve_scoped_slot(Request, scope_name="request")
+
+def process_request(request: Request) -> None:
+    with define_scope("request"):
+        request_slot.set(request)
+        # ...
+```

documentation/testing.md

@@ -20,7 +20,7 @@ def autouse_test_injectables():
 
 ## Register a test injectable
 
-> **Notes**
+> [!NOTE]
 > * Test injectables replace conventional injectables if they are registered on the same type.
 > * A test injectable can't depend on a conventional injectable.
 

documentation/utils.md

@@ -30,7 +30,8 @@ load_packages(package)
 `load_profile` is an injection module initialization function based on profile name.
 This is very useful when you want to use a set of dependencies based on the execution profile.
 
-> **Note:** A profile name is equivalent to an injection module name.
+> [!NOTE]
+> A profile name is equivalent to an injection module name.
 
 For example, when I'm doing my development tests, I don't really feel like sending SMS messages.
 

injection/__init__.py

@@ -2,13 +2,15 @@
 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
 
 __all__ = (
     "Injectable",
     "LazyInstance",
     "Mode",
     "Module",
     "Priority",
+    "Slot",
     "adefine_scope",
     "afind_instance",
     "aget_instance",
@@ -21,6 +23,7 @@
     "inject",
     "injectable",
     "mod",
+    "reserve_scoped_slot",
     "scoped",
     "set_constant",
     "should_be_injectable",
@@ -36,6 +39,7 @@
 get_lazy_instance = mod().get_lazy_instance
 inject = mod().inject
 injectable = mod().injectable
+reserve_scoped_slot = mod().reserve_scoped_slot
 scoped = mod().scoped
 set_constant = mod().set_constant
 should_be_injectable = mod().should_be_injectable

injection/__init__.pyi

@@ -23,6 +23,7 @@ get_instance = __MODULE.get_instance
 get_lazy_instance = __MODULE.get_lazy_instance
 inject = __MODULE.inject
 injectable = __MODULE.injectable
+reserve_scoped_slot = __MODULE.reserve_scoped_slot
 scoped = __MODULE.scoped
 set_constant = __MODULE.set_constant
 should_be_injectable = __MODULE.should_be_injectable
@@ -46,6 +47,11 @@ class Injectable[T](Protocol):
     @abstractmethod
     def get_instance(self) -> T: ...
 
+@runtime_checkable
+class Slot[T](Protocol):
+    @abstractmethod
+    def set(self, instance: T, /) -> Self: ...
+
 class LazyInstance[T]:
     def __init__(
         self,
@@ -171,6 +177,14 @@ class Module:
         that no dependencies are resolved, so the module doesn't need to be locked.
         """
 
+    def reserve_scoped_slot[T](
+        self,
+        on: _TypeInfo[T],
+        /,
+        scope_name: str,
+        *,
+        mode: Mode | ModeStr = ...,
+    ) -> Slot[T]: ...
     def make_injected_function[**P, T](
         self,
         wrapped: Callable[P, T],

injection/_core/common/type.py

@@ -2,6 +2,7 @@
     AsyncGenerator,
     AsyncIterable,
     AsyncIterator,
+    Awaitable,
     Callable,
     Generator,
     Iterable,
@@ -21,7 +22,12 @@
 
 type TypeDef[T] = type[T] | TypeAliasType | GenericAlias
 type InputType[T] = TypeDef[T] | UnionType
-type TypeInfo[T] = InputType[T] | Callable[..., T] | Iterable[TypeInfo[T]]
+type TypeInfo[T] = (
+    InputType[T]
+    | Callable[..., T]
+    | Callable[..., Awaitable[T]]
+    | Iterable[TypeInfo[T]]
+)
 
 
 def get_return_types(*args: TypeInfo[Any]) -> Iterator[InputType[Any]]:

injection/_core/injectables.py

@@ -107,25 +107,31 @@ def build(self, scope: Scope) -> T:
         raise NotImplementedError
 
     async def aget_instance(self) -> T:
-        scope = get_scope(self.scope_name)
+        scope = self.get_scope()
 
         with suppress(KeyError):
             return scope.cache[self]
 
         instance = await self.abuild(scope)
-        scope.cache[self] = instance
+        self.set_instance(instance, scope)
         return instance
 
     def get_instance(self) -> T:
-        scope = get_scope(self.scope_name)
+        scope = self.get_scope()
 
         with suppress(KeyError):
             return scope.cache[self]
 
         instance = self.build(scope)
-        scope.cache[self] = instance
+        self.set_instance(instance, scope)
         return instance
 
+    def get_scope(self) -> Scope:
+        return get_scope(self.scope_name)
+
+    def set_instance(self, instance: T, scope: Scope) -> None:
+        scope.cache[self] = instance
+
     def unlock(self) -> None:
         if self.is_locked:
             raise RuntimeError(f"To unlock, close the `{self.scope_name}` scope.")