doc

Author: remimd

README.md

@@ -56,6 +56,7 @@ if __name__ == "__main__":
 ## Resources
 
 * [**Basic usage**](https://github.com/100nm/python-injection/tree/prod/documentation/basic-usage.md)
+* [**Scoped dependencies**](https://github.com/100nm/python-injection/tree/prod/documentation/scoped-dependencies.md)
 * [**Testing**](https://github.com/100nm/python-injection/tree/prod/documentation/testing.md)
 * [**Advanced usage**](https://github.com/100nm/python-injection/tree/prod/documentation/advanced-usage.md)
 * [**Utils**](https://github.com/100nm/python-injection/tree/prod/documentation/utils.md)

documentation/scoped-dependencies.md

@@ -0,0 +1,96 @@
+# Scoped dependencies
+
+The scoped dependencies were created for two reasons:
+* To have dependencies that have a defined lifespan.
+* To be able to open and close things in a dependency recipe.
+
+> **Best practices:**
+> * Avoid making a singleton dependent on a scoped dependency.
+
+## Scope
+
+The scope is responsible for instance persistence and for cleaning up when it closes.
+There are two kinds of scopes:
+* **Contextual**: All threads have access to a different scope (based on [contextvars](https://docs.python.org/3.13/library/contextvars.html)).
+* **Shared**: All threads have access to the same scope.
+
+First of all, the scope must be defined:
+
+*By default, the `shared` parameter is `False`.*
+
+> Define an asynchronous scope:
+
+```python
+from injection import adefine_scope
+
+async def main() -> None:
+    async with adefine_scope("<scope-name>", shared=True):
+        ...
+```
+
+> Define a synchronous scope:
+
+```python
+from injection import define_scope
+
+
+def main() -> None:
+    with define_scope("<scope-name>", shared=True):
+        ...
+```
+
+## Register a scoped dependencies
+
+`@scoped` works exactly like `@injectable`, it just has extra features.
+
+### "contextmanager-like" recipes
+
+*Anything after the `yield` keyword will be executed when the scope is closed.*
+
+> Asynchronous (asynchronous scope required):
+
+```python
+from collections.abc import AsyncIterator
+from injection import scoped
+
+class Client:
+    async def open_connection(self) -> None: ...
+    
+    async def close_connection(self) -> None: ...
+
+@scoped("<scope-name>")
+async def client_recipe() -> AsyncIterator[Client]:
+    # On resolving dependency
+    client = Client()
+    await client.open_connection()
+    
+    try:
+        yield client
+    finally:
+        # On scope close
+        await client.close_connection()
+```
+
+> Synchronous:
+
+```python
+from collections.abc import Iterator
+from injection import scoped
+
+class Client:
+    def open_connection(self) -> None: ...
+    
+    def close_connection(self) -> None: ...
+
+@scoped("<scope-name>")
+def client_recipe() -> Iterator[Client]:
+    # On resolving dependency
+    client = Client()
+    client.open_connection()
+    
+    try:
+        yield client
+    finally:
+        # On scope close
+        client.close_connection()
+```

injection/__init__.py

@@ -1,19 +1,20 @@
 from ._core.descriptors import LazyInstance
 from ._core.injectables import Injectable
 from ._core.module import Mode, Module, Priority, mod
-from ._core.scope import async_scope, sync_scope
+from ._core.scope import adefine_scope, define_scope
 
 __all__ = (
     "Injectable",
     "LazyInstance",
     "Mode",
     "Module",
     "Priority",
+    "adefine_scope",
     "afind_instance",
     "aget_instance",
     "aget_lazy_instance",
-    "async_scope",
     "constant",
+    "define_scope",
     "find_instance",
     "get_instance",
     "get_lazy_instance",
@@ -24,7 +25,6 @@
     "set_constant",
     "should_be_injectable",
     "singleton",
-    "sync_scope",
 )
 
 afind_instance = mod().afind_instance

injection/__init__.pyi

@@ -1,19 +1,9 @@
 from abc import abstractmethod
-from collections.abc import Awaitable, Callable
-from contextlib import ContextDecorator
+from collections.abc import AsyncIterator, Awaitable, Callable, Iterator
+from contextlib import asynccontextmanager, contextmanager
 from enum import Enum
 from logging import Logger
-from typing import (
-    Any,
-    AsyncContextManager,
-    ContextManager,
-    Final,
-    Protocol,
-    Self,
-    final,
-    overload,
-    runtime_checkable,
-)
+from typing import Any, Final, Protocol, Self, final, overload, runtime_checkable
 
 from ._core.common.invertible import Invertible as _Invertible
 from ._core.common.type import InputType as _InputType
@@ -37,8 +27,10 @@ set_constant = __MODULE.set_constant
 should_be_injectable = __MODULE.should_be_injectable
 singleton = __MODULE.singleton
 
-def async_scope(name: str, *, shared: bool = ...) -> AsyncContextManager[None]: ...
-def sync_scope(name: str, *, shared: bool = ...) -> ContextManager[None]: ...
+@asynccontextmanager
+def adefine_scope(name: str, *, shared: bool = ...) -> AsyncIterator[None]: ...
+@contextmanager
+def define_scope(name: str, *, shared: bool = ...) -> Iterator[None]: ...
 def mod(name: str = ..., /) -> Module:
     """
     Short syntax for `Module.from_name`.
@@ -268,12 +260,13 @@ class Module:
         Function to remove a module in use.
         """
 
+    @contextmanager
     def use_temporarily(
         self,
         module: Module,
         *,
         priority: Priority | PriorityStr = ...,
-    ) -> ContextManager[None] | ContextDecorator:
+    ) -> Iterator[None]:
         """
         Context manager or decorator for temporary use of a module.
         """

injection/_core/scope.py

@@ -62,7 +62,7 @@ def bind_contextual_scope(self, scope: Scope) -> Iterator[None]:
 
     @contextmanager
     def bind_shared_scope(self, scope: Scope) -> Iterator[None]:
-        if self.__references:
+        if self.get_active_scopes():
             raise ScopeError(
                 "A shared scope can't be defined when one or more contextual scopes "
                 "are defined on the same name."
@@ -91,14 +91,14 @@ def get_active_scopes(self) -> tuple[Scope, ...]:
 
 
 @asynccontextmanager
-async def async_scope(name: str, *, shared: bool = False) -> AsyncIterator[None]:
+async def adefine_scope(name: str, *, shared: bool = False) -> AsyncIterator[None]:
     async with AsyncScope() as scope:
         scope.enter(_bind_scope(name, scope, shared))
         yield
 
 
 @contextmanager
-def sync_scope(name: str, *, shared: bool = False) -> Iterator[None]:
+def define_scope(name: str, *, shared: bool = False) -> Iterator[None]:
     with SyncScope() as scope:
         scope.enter(_bind_scope(name, scope, shared))
         yield
@@ -120,7 +120,7 @@ def get_scope(name: str) -> Scope:
 
 
 @contextmanager
-def _bind_scope(name: str, value: Scope, shared: bool) -> Iterator[None]:
+def _bind_scope(name: str, scope: Scope, shared: bool) -> Iterator[None]:
     state = __SCOPES[name]
 
     if state.get_scope():
@@ -129,14 +129,14 @@ def _bind_scope(name: str, value: Scope, shared: bool) -> Iterator[None]:
         )
 
     strategy = (
-        state.bind_shared_scope(value) if shared else state.bind_contextual_scope(value)
+        state.bind_shared_scope(scope) if shared else state.bind_contextual_scope(scope)
     )
 
     try:
         with strategy:
             yield
     finally:
-        value.cache.clear()
+        scope.cache.clear()
 
 
 @runtime_checkable
@@ -208,7 +208,9 @@ def __exit__(
         return self.delegate.__exit__(exc_type, exc_value, traceback)
 
     async def aenter[T](self, context_manager: AsyncContextManager[T]) -> T:
-        raise ScopeError("SyncScope doesn't support asynchronous context manager.")
+        raise ScopeError(
+            "Synchronous scope doesn't support asynchronous context manager."
+        )
 
     def enter[T](self, context_manager: ContextManager[T]) -> T:
         return self.delegate.enter_context(context_manager)

tests/core/test_module.py

@@ -2,7 +2,7 @@
 
 import pytest
 
-from injection import Module, sync_scope
+from injection import Module, define_scope
 from injection.exceptions import (
     ModuleError,
     ModuleLockError,
@@ -346,7 +346,7 @@ class Dependency: ...
 
         assert module.is_locked is False
 
-        with sync_scope("test"):
+        with define_scope("test"):
             instance_1 = module.get_instance(Dependency)
             assert module.is_locked is True
 

tests/test_scoped.py

@@ -3,12 +3,12 @@
 import pytest
 
 from injection import (
+    adefine_scope,
     afind_instance,
-    async_scope,
+    define_scope,
     find_instance,
     injectable,
     scoped,
-    sync_scope,
 )
 from injection.exceptions import ScopeError, ScopeUndefinedError
 
@@ -18,7 +18,7 @@ def test_scoped_with_success(self):
         @scoped("test")
         class SomeInjectable: ...
 
-        with sync_scope("test"):
+        with define_scope("test"):
             instance_1 = find_instance(SomeInjectable)
             instance_2 = find_instance(SomeInjectable)
 
@@ -30,7 +30,7 @@ class A: ...
         @scoped("test", on=A)
         class B(A): ...
 
-        with sync_scope("test"):
+        with define_scope("test"):
             a = find_instance(A)
             b = find_instance(B)
 
@@ -44,7 +44,7 @@ class B(A): ...
         @scoped("test", on=(A, B))
         class C(B): ...
 
-        with sync_scope("test"):
+        with define_scope("test"):
             a = find_instance(A)
             b = find_instance(B)
             c = find_instance(C)
@@ -76,7 +76,7 @@ class A: ...
         @scoped("test", on=A, mode="override")
         class B(A): ...
 
-        with sync_scope("test"):
+        with define_scope("test"):
             a = find_instance(A)
 
         assert isinstance(a, B)
@@ -91,7 +91,7 @@ class B(A): ...
         @scoped("test", on=A, mode="override")
         class C(B): ...
 
-        with sync_scope("test"):
+        with define_scope("test"):
             a = find_instance(A)
 
         assert isinstance(a, C)
@@ -103,7 +103,7 @@ class SomeInjectable: ...
         def some_injectable_recipe() -> SomeInjectable:
             return SomeInjectable()
 
-        with sync_scope("test"):
+        with define_scope("test"):
             instance_1 = find_instance(SomeInjectable)
             instance_2 = find_instance(SomeInjectable)
 
@@ -116,7 +116,7 @@ class SomeInjectable: ...
         async def some_injectable_recipe() -> SomeInjectable:
             return SomeInjectable()
 
-        with sync_scope("test"):
+        with define_scope("test"):
             instance_1 = await afind_instance(SomeInjectable)
             instance_2 = await afind_instance(SomeInjectable)
 
@@ -129,7 +129,7 @@ class SomeInjectable: ...
         def some_injectable_recipe() -> Iterator[SomeInjectable]:
             yield SomeInjectable()
 
-        with sync_scope("test"):
+        with define_scope("test"):
             instance_1 = find_instance(SomeInjectable)
             instance_2 = find_instance(SomeInjectable)
 
@@ -142,7 +142,7 @@ class SomeInjectable: ...
         def some_injectable_recipe() -> Iterator[SomeInjectable]:
             yield SomeInjectable()
 
-        async with async_scope("test"):
+        async with adefine_scope("test"):
             instance_1 = find_instance(SomeInjectable)
             instance_2 = find_instance(SomeInjectable)
 
@@ -157,7 +157,7 @@ class SomeInjectable: ...
         async def some_injectable_recipe() -> AsyncIterator[SomeInjectable]:
             yield SomeInjectable()  # pragma: no cover
 
-        with sync_scope("test"):
+        with define_scope("test"):
             with pytest.raises(ScopeError):
                 await afind_instance(SomeInjectable)
 
@@ -168,7 +168,7 @@ class SomeInjectable: ...
         async def some_injectable_recipe() -> AsyncIterator[SomeInjectable]:
             yield SomeInjectable()
 
-        async with async_scope("test"):
+        async with adefine_scope("test"):
             instance_1 = await afind_instance(SomeInjectable)
             instance_2 = await afind_instance(SomeInjectable)