Allow entering scope when using @Inject. (#189)

* Updated benchmarks with logging.

* Updated benchmark.

* Enabled automatic dependency injection by type.

* Wrote tests for type based injections.

* Minor documentation fixes.

* Refactored inject method.

* Added covariant binding.

* Corrected to contravariant and added docs.

* Extended docs.

* Improved bind docstring.

* Added enter_scope to inject.

* Extended documentation.

* Adjusted migration guide.

* Removed some white space in docs.

Author: alexanderlazarev0

docs/introduction/scopes.md

@@ -144,7 +144,7 @@ def foo(...):
 ```
 
 The `@inject` wrapper will enter a new context for each injected provider that matches the specified scope.
-However, it will not enter the scope!
+However, it will not enter the scope by default!
 
 Here is a simple example:
 ```python hl_lines="5 10"
@@ -188,32 +188,30 @@ injected()
 2. Context for `Container.provider` is initialized and will exit when the function returns.
 3. This assertion will pass since the context for this provider is still the same.
 
-If you want to enter a scope for the duration of the function you can use the following pattern:
-```python hl_lines="4 10"
+This implementation might seem complex at first glance, but it providers the following advantages:
+
+- Only context for `ContextResource` providers you need is initialized. This improves performance.
+- It discourages explicit resolution via `.resolve()` or `.resolve_sync()` in the function body.
+This pattern should be avoided since defining providers in function parameters allows for overriding by just passing an argument 
+instead of having to override the provider.
+
+### Entering a scope with `@inject`
+If you want to enter a scope for the duration of the function you can set `enter_scope=True` when using `@inject`:  
+```python hl_lines="4 9"
 class Container(BaseContainer):
     default_scope = ContextScopes.INJECT
     provider = providers.ContextResource(iterator).with_config(scope=ContextScopes.INJECT)
     another_provider = providers.ContextResource(iterator).with_config(scope=ContextScopes.INJECT)
 
-@container_context(scope=ContextScopes.INJECT)
-@inject(scope=None) # (3)!
-def injected(v: int = Provide[Container.provider]) -> int: # (2)!
+@inject(scope=ContextScopes.INJECT, enter_scope=True)
+def injected(v: int = Provide[Container.provider]) -> int:
     assert get_current_scope() == ContextScopes.INJECT
     Container.another_provider.resolve_sync() # (1)!
     return v
 ```
 
 1. This will resolve since this resource has been initialized when you entered the `INJECT` scope.
-2. `Container.provider` was resolved successfully since the `INJECT` scope was entered before the function was called.
-3. `scope=None` means that the `@inject` wrapper will ignore scopes. It will not resolve `None`-scoped ContextResources!
-
-
-This implementation is complex but it providers the following advantages:
 
-- Only context for `ContextResources` you need is initialized. This improves performance.
-- It discourages explicit resolution via `.resolve()` or `.resolve_sync()` in the function body.
-This pattern should be avoided since defining providers in function parameters allows for overriding by just passing an argument 
-instead of having to override the provider.
 
 ## Implementing custom scopes
 

docs/migration/v3.md

@@ -59,14 +59,13 @@ def injected(...): ...
 ```
 
 In `3.*` the scope is only used to resolve relevant dependencies that match the provided scope.
-Thus, to achieve the same behaviour as in `2.*` you need to use the `@container_context` context manager:
-```python   
-@container_context(scope=ContextScope.REQUEST)
-@inject(scope=None) # None is required for exactly the same behaviour as in 2.*
+Thus, to achieve the same behaviour as in `2.*` you need to set `enter_scope=True`:
+```python
+@inject(scope=ContextScopes.REQUEST, enter_scope=True)
 def injected(...): ...
     assert get_current_scope() == ContextScopes.REQUEST
 ```
-This fix will work, but is not recommended, please refer to the [scopes documentation](../introduction/scopes.md#named-scopes-with-the-inject-wrapper)
+For further details, please refer to the [scopes documentation](../introduction/scopes.md#named-scopes-with-the-inject-wrapper)
 
 ---
 

tests/test_injection.py

@@ -9,7 +9,7 @@
 import pytest
 
 from tests import container
-from that_depends import BaseContainer, ContextScopes, Provide, container_context, inject, providers
+from that_depends import BaseContainer, ContextScopes, Provide, container_context, get_current_scope, inject, providers
 from that_depends.injection import ContextProviderError, StringProviderDefinition
 
 
@@ -1038,3 +1038,54 @@ async def _injected(val: float = Provide()) -> float:
 
     with pytest.raises(RuntimeError):
         await _injected()
+
+
+def test_inject_with_enter_scope_enters_scope_sync() -> None:
+    def _sync_creator() -> typing.Iterator[float]:
+        yield random.random()
+
+    class _Container(BaseContainer):
+        resource = providers.ContextResource(_sync_creator).with_config(scope=ContextScopes.INJECT)
+
+    @inject(enter_scope=True)
+    def _injected(val: float = Provide[_Container.resource]) -> float:
+        assert get_current_scope() is ContextScopes.INJECT
+        return val
+
+    assert isinstance(_injected(), float)
+
+
+async def test_inject_with_enter_scope_enters_scope_async() -> None:
+    async def _async_creator() -> typing.AsyncIterator[float]:
+        yield random.random()
+
+    class _Container(BaseContainer):
+        resource = providers.ContextResource(_async_creator).with_config(scope=ContextScopes.INJECT)
+
+    @inject(enter_scope=True)
+    async def _injected(val: float = Provide[_Container.resource]) -> float:
+        assert get_current_scope() is ContextScopes.INJECT
+        return val
+
+    assert isinstance(await _injected(), float)
+
+
+def test_inject_with_none_scope_and_enter_scope_raises() -> None:
+    with pytest.raises(ValueError, match="enter_scope cannot be used with scope=None."):
+        inject(scope=None, enter_scope=True)
+
+
+def test_enter_scope_raises_with_generator_sync() -> None:
+    with pytest.raises(ValueError, match="enter_scope cannot be used with generator functions."):
+
+        @inject(enter_scope=True)
+        def _injected(val: float = Provide["C.a"]) -> typing.Generator[float, None, None]:
+            yield val  # pragma: no cover
+
+
+async def test_enter_scope_raises_with_generator_async() -> None:
+    with pytest.raises(ValueError, match="enter_scope cannot be used with async generator functions."):
+
+        @inject(enter_scope=True)
+        async def _injected(val: float = Provide["C.a"]) -> typing.AsyncGenerator[float, None]:
+            yield val  # pragma: no cover

that_depends/injection.py

@@ -12,7 +12,7 @@
 from that_depends.exceptions import TypeNotBoundError
 from that_depends.meta import BaseContainerMeta
 from that_depends.providers import AbstractProvider, ContextResource
-from that_depends.providers.context_resources import ContextScope, ContextScopes
+from that_depends.providers.context_resources import ContextScope, ContextScopes, container_context
 from that_depends.providers.mixin import ProviderWithArguments
 
 
@@ -38,20 +38,23 @@ def inject(
     *,
     scope: ContextScope | None = ContextScopes.INJECT,
     container: BaseContainerMeta | None = None,
+    enter_scope: bool = False,
 ) -> typing.Callable[[typing.Callable[P, T]], typing.Callable[P, T]]: ...
 
 
 def inject(  # noqa: C901
     func: typing.Callable[P, T] | None = None,
     scope: ContextScope | None = ContextScopes.INJECT,
     container: BaseContainerMeta | None = None,
+    enter_scope: bool = False,
 ) -> typing.Callable[P, T] | typing.Callable[[typing.Callable[P, T]], typing.Callable[P, T]]:
     """Mark a function for dependency injection.
 
     Args:
         func: function or generator function to be wrapped.
         scope: scope to initialize ContextResources for.
         container: container from which to resolve dependencies marked with `Provide()`.
+        enter_scope: enter the provided scope.
 
     Returns:
         wrapped function.
@@ -60,13 +63,22 @@ def inject(  # noqa: C901
     if scope == ContextScopes.ANY:
         msg = f"{scope} is not allowed in inject decorator."
         raise ValueError(msg)
+    if scope is None and enter_scope:
+        msg = "enter_scope cannot be used with scope=None."
+        raise ValueError(msg)
 
     def _inject(
         func: typing.Callable[P, T],
     ) -> typing.Callable[P, T]:
         if inspect.isasyncgenfunction(func):
+            if enter_scope:
+                msg = "enter_scope cannot be used with async generator functions."
+                raise ValueError(msg)
             return typing.cast(typing.Callable[P, T], _inject_to_async_gen(func))
         if inspect.isgeneratorfunction(func):
+            if enter_scope:
+                msg = "enter_scope cannot be used with generator functions."
+                raise ValueError(msg)
             return typing.cast(typing.Callable[P, T], _inject_to_sync_gen(func))
         if inspect.iscoroutinefunction(func):
             return typing.cast(typing.Callable[P, T], _inject_to_async(func))
@@ -112,7 +124,11 @@ def _inject_to_async(
     ) -> typing.Callable[P, typing.Coroutine[typing.Any, typing.Any, T]]:
         @functools.wraps(func)
         async def inner(*args: P.args, **kwargs: P.kwargs) -> T:
-            return await _resolve_async(func, scope, container, *args, **kwargs)
+            if enter_scope:
+                async with container_context(scope=scope):
+                    return await _resolve_async(func, None, container, *args, **kwargs)
+            else:
+                return await _resolve_async(func, scope, container, *args, **kwargs)
 
         return inner
 
@@ -121,7 +137,11 @@ def _inject_to_sync(
     ) -> typing.Callable[P, T]:
         @functools.wraps(func)
         def inner(*args: P.args, **kwargs: P.kwargs) -> T:
-            return _resolve_sync(func, scope, container, *args, **kwargs)
+            if enter_scope:
+                with container_context(scope=scope):
+                    return _resolve_sync(func, None, container, *args, **kwargs)
+            else:
+                return _resolve_sync(func, scope, container, *args, **kwargs)
 
         return inner