python-injection 0.12.3__py3-none-any.whl → 0.13.1__py3-none-any.whl

injection/__init__.py

@@ -1,6 +1,7 @@
 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
 
 __all__ = (
     "Injectable",
@@ -8,16 +9,19 @@ __all__ = (
     "Mode",
     "Module",
     "Priority",
+    "adefine_scope",
     "afind_instance",
     "aget_instance",
     "aget_lazy_instance",
     "constant",
+    "define_scope",
     "find_instance",
     "get_instance",
     "get_lazy_instance",
     "inject",
     "injectable",
     "mod",
+    "scoped",
     "set_constant",
     "should_be_injectable",
     "singleton",
@@ -32,6 +36,7 @@ get_instance = mod().get_instance
 get_lazy_instance = mod().get_lazy_instance
 inject = mod().inject
 injectable = mod().injectable
+scoped = mod().scoped
 set_constant = mod().set_constant
 should_be_injectable = mod().should_be_injectable
 singleton = mod().singleton

injection/__init__.pyi

@@ -1,17 +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,
-    ContextManager,
-    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
@@ -19,27 +11,53 @@ from ._core.common.type import TypeInfo as _TypeInfo
 from ._core.module import InjectableFactory as _InjectableFactory
 from ._core.module import ModeStr, PriorityStr
 
-_: Module = ...
+__MODULE: Final[Module] = ...
 
-afind_instance = _.afind_instance
-aget_instance = _.aget_instance
-aget_lazy_instance = _.aget_lazy_instance
-constant = _.constant
-find_instance = _.find_instance
-get_instance = _.get_instance
-get_lazy_instance = _.get_lazy_instance
-inject = _.inject
-injectable = _.injectable
-set_constant = _.set_constant
-should_be_injectable = _.should_be_injectable
-singleton = _.singleton
-
-del _
+afind_instance = __MODULE.afind_instance
+aget_instance = __MODULE.aget_instance
+aget_lazy_instance = __MODULE.aget_lazy_instance
+constant = __MODULE.constant
+find_instance = __MODULE.find_instance
+get_instance = __MODULE.get_instance
+get_lazy_instance = __MODULE.get_lazy_instance
+inject = __MODULE.inject
+injectable = __MODULE.injectable
+scoped = __MODULE.scoped
+set_constant = __MODULE.set_constant
+should_be_injectable = __MODULE.should_be_injectable
+singleton = __MODULE.singleton
 
+@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`.
     """
+@runtime_checkable
+class Injectable[T](Protocol):
+    @property
+    def is_locked(self) -> bool: ...
+    def unlock(self) -> None: ...
+    @abstractmethod
+    async def aget_instance(self) -> T: ...
+    @abstractmethod
+    def get_instance(self) -> T: ...
+
+class LazyInstance[T]:
+    def __init__(
+        self,
+        cls: _InputType[T],
+        /,
+        default: T = ...,
+        module: Module = ...,
+    ) -> None: ...
+    @overload
+    def __get__(self, instance: object, owner: type | None = ...) -> T: ...
+    @overload
+    def __get__(self, instance: None = ..., owner: type | None = ...) -> Self: ...
+
 @final
 class Module:
     """
@@ -94,6 +112,21 @@ class Module:
         always be the same.
         """
 
+    def scoped[**P, T](
+        self,
+        scope_name: str,
+        /,
+        *,
+        inject: bool = ...,
+        on: _TypeInfo[T] = (),
+        mode: Mode | ModeStr = ...,
+    ) -> Any:
+        """
+        Decorator applicable to a class or function or generator function. It is used
+        to indicate how the scoped instance will be constructed. At injection time, the
+        injected instance is retrieved from the scope.
+        """
+
     def should_be_injectable[T](self, wrapped: type[T] = ..., /) -> Any:
         """
         Decorator applicable to a class. It is used to specify whether an injectable
@@ -233,12 +266,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.
         """
@@ -275,30 +309,13 @@ class Module:
         Class method for getting the default module.
         """
 
-@final
-class Priority(Enum):
-    LOW = ...
-    HIGH = ...
-
-@runtime_checkable
-class Injectable[T](Protocol):
-    @property
-    def is_locked(self) -> bool: ...
-    def unlock(self) -> None: ...
-    @abstractmethod
-    async def aget_instance(self) -> T: ...
-    @abstractmethod
-    def get_instance(self) -> T: ...
-
 @final
 class Mode(Enum):
     FALLBACK = ...
     NORMAL = ...
     OVERRIDE = ...
 
-class LazyInstance[T]:
-    def __init__(self, cls: _InputType[T], module: Module = ...) -> None: ...
-    @overload
-    def __get__(self, instance: object, owner: type | None = ...) -> T: ...
-    @overload
-    def __get__(self, instance: None = ..., owner: type | None = ...) -> Self: ...
+@final
+class Priority(Enum):
+    LOW = ...
+    HIGH = ...

injection/_core/common/asynchronous.py

@@ -1,10 +1,19 @@
 import asyncio
 from abc import abstractmethod
-from collections.abc import Awaitable, Callable, Generator
+from collections.abc import Awaitable, Callable, Coroutine, Generator
 from dataclasses import dataclass
 from typing import Any, Protocol, runtime_checkable
 
 
+def run_sync[T](coroutine: Coroutine[Any, Any, T]) -> T:
+    loop = asyncio.get_event_loop()
+
+    try:
+        return loop.run_until_complete(coroutine)
+    finally:
+        coroutine.close()
+
+
 @dataclass(repr=False, eq=False, frozen=True, slots=True)
 class SimpleAwaitable[T](Awaitable[T]):
     callable: Callable[..., Awaitable[T]]
@@ -28,21 +37,13 @@ class Caller[**P, T](Protocol):
 
 @dataclass(repr=False, eq=False, frozen=True, slots=True)
 class AsyncCaller[**P, T](Caller[P, T]):
-    callable: Callable[P, Awaitable[T]]
+    callable: Callable[P, Coroutine[Any, Any, T]]
 
     async def acall(self, /, *args: P.args, **kwargs: P.kwargs) -> T:
         return await self.callable(*args, **kwargs)
 
     def call(self, /, *args: P.args, **kwargs: P.kwargs) -> T:
-        loop = asyncio.get_event_loop()
-
-        if loop.is_running():
-            raise RuntimeError(
-                "Can't call an asynchronous function in a synchronous context."
-            )
-
-        coroutine = self.callable(*args, **kwargs)
-        return loop.run_until_complete(coroutine)
+        return run_sync(self.callable(*args, **kwargs))
 
 
 @dataclass(repr=False, eq=False, frozen=True, slots=True)

injection/_core/common/event.py

@@ -25,7 +25,7 @@ class EventChannel:
     @contextmanager
     def dispatch(self, event: Event) -> Iterator[None]:
         with ExitStack() as stack:
-            for listener in tuple(self.__listeners):
+            for listener in self.__listeners:
                 context_manager = listener.on_event(event)
 
                 if context_manager is None:

injection/_core/common/key.py

@@ -0,0 +1,5 @@
+from uuid import uuid4
+
+
+def new_short_key() -> str:
+    return uuid4().hex[:7]

injection/_core/common/type.py

@@ -1,4 +1,12 @@
-from collections.abc import Callable, Iterable, Iterator
+from collections.abc import (
+    AsyncGenerator,
+    AsyncIterable,
+    AsyncIterator,
+    Callable,
+    Generator,
+    Iterable,
+    Iterator,
+)
 from inspect import isfunction
 from types import GenericAlias, UnionType
 from typing import (
@@ -23,7 +31,7 @@ def get_return_types(*args: TypeInfo[Any]) -> Iterator[InputType[Any]]:
         ):
             inner_args = arg
 
-        elif isfunction(arg) and (return_type := get_type_hints(arg).get("return")):
+        elif isfunction(arg) and (return_type := get_return_hint(arg)):
             inner_args = (return_type,)
 
         else:
@@ -33,6 +41,29 @@ def get_return_types(*args: TypeInfo[Any]) -> Iterator[InputType[Any]]:
         yield from get_return_types(*inner_args)
 
 
+def get_return_hint[T](function: Callable[..., T]) -> InputType[T] | None:
+    return get_type_hints(function).get("return")
+
+
+def get_yield_hint[T](
+    function: Callable[..., Iterator[T]] | Callable[..., AsyncIterator[T]],
+) -> InputType[T] | None:
+    return_type = get_return_hint(function)
+
+    if get_origin(return_type) not in {
+        AsyncGenerator,
+        AsyncIterable,
+        AsyncIterator,
+        Generator,
+        Iterable,
+        Iterator,
+    }:
+        return None
+
+    args = get_args(return_type)
+    return next(iter(args), None)
+
+
 def standardize_types(
     *types: InputType[Any],
     with_origin: bool = False,

injection/_core/descriptors.py

@@ -10,9 +10,15 @@ class LazyInstance[T]:
 
     __value: Invertible[T]
 
-    def __init__(self, cls: InputType[T], module: Module | None = None) -> None:
+    def __init__(
+        self,
+        cls: InputType[T],
+        /,
+        default: T = NotImplemented,
+        module: Module | None = None,
+    ) -> None:
         module = module or mod()
-        self.__value = module.get_lazy_instance(cls, default=NotImplemented)
+        self.__value = module.get_lazy_instance(cls, default)
 
     def __get__(
         self,

injection/_core/injectables.py

@@ -2,10 +2,18 @@ from abc import ABC, abstractmethod
 from collections.abc import MutableMapping
 from contextlib import suppress
 from dataclasses import dataclass
-from typing import Any, ClassVar, NoReturn, Protocol, runtime_checkable
-
-from injection._core.common.asynchronous import Caller
-from injection._core.common.threading import synchronized
+from typing import (
+    Any,
+    AsyncContextManager,
+    ClassVar,
+    ContextManager,
+    NoReturn,
+    Protocol,
+    runtime_checkable,
+)
+
+from injection._core.common.asynchronous import Caller, run_sync
+from injection._core.scope import Scope, get_active_scopes, get_scope
 from injection.exceptions import InjectionError
 
 
@@ -50,41 +58,114 @@ class SingletonInjectable[T](BaseInjectable[T]):
     __key: ClassVar[str] = "$instance"
 
     @property
-    def cache(self) -> MutableMapping[str, Any]:
+    def is_locked(self) -> bool:
+        return self.__key in self.__cache
+
+    @property
+    def __cache(self) -> MutableMapping[str, Any]:
         return self.__dict__
 
+    async def aget_instance(self) -> T:
+        cache = self.__cache
+
+        with suppress(KeyError):
+            return cache[self.__key]
+
+        instance = await self.factory.acall()
+        cache[self.__key] = instance
+        return instance
+
+    def get_instance(self) -> T:
+        cache = self.__cache
+
+        with suppress(KeyError):
+            return cache[self.__key]
+
+        instance = self.factory.call()
+        cache[self.__key] = instance
+        return instance
+
+    def unlock(self) -> None:
+        self.__cache.pop(self.__key, None)
+
+
+@dataclass(repr=False, eq=False, frozen=True, slots=True)
+class ScopedInjectable[R, T](Injectable[T], ABC):
+    factory: Caller[..., R]
+    scope_name: str
+
     @property
     def is_locked(self) -> bool:
-        return self.__key in self.cache
+        return any(self in scope.cache for scope in get_active_scopes(self.scope_name))
 
-    def unlock(self) -> None:
-        self.cache.clear()
+    @abstractmethod
+    async def abuild(self, scope: Scope) -> T:
+        raise NotImplementedError
+
+    @abstractmethod
+    def build(self, scope: Scope) -> T:
+        raise NotImplementedError
 
     async def aget_instance(self) -> T:
-        with suppress(KeyError):
-            return self.__check_instance()
+        scope = get_scope(self.scope_name)
 
-        with synchronized():
-            instance = await self.factory.acall()
-            self.__set_instance(instance)
+        with suppress(KeyError):
+            return scope.cache[self]
 
+        instance = await self.abuild(scope)
+        scope.cache[self] = instance
         return instance
 
     def get_instance(self) -> T:
-        with suppress(KeyError):
-            return self.__check_instance()
+        scope = get_scope(self.scope_name)
 
-        with synchronized():
-            instance = self.factory.call()
-            self.__set_instance(instance)
+        with suppress(KeyError):
+            return scope.cache[self]
 
+        instance = self.build(scope)
+        scope.cache[self] = instance
         return instance
 
-    def __check_instance(self) -> T:
-        return self.cache[self.__key]
+    def unlock(self) -> None:
+        if self.is_locked:
+            raise RuntimeError(f"To unlock, close the `{self.scope_name}` scope.")
+
+
+class AsyncCMScopedInjectable[T](ScopedInjectable[AsyncContextManager[T], T]):
+    __slots__ = ()
+
+    async def abuild(self, scope: Scope) -> T:
+        cm = await self.factory.acall()
+        return await scope.aenter(cm)
+
+    def build(self, scope: Scope) -> T:
+        return run_sync(self.abuild(scope))
+
 
-    def __set_instance(self, value: T) -> None:
-        self.cache[self.__key] = value
+class CMScopedInjectable[T](ScopedInjectable[ContextManager[T], T]):
+    __slots__ = ()
+
+    async def abuild(self, scope: Scope) -> T:
+        cm = await self.factory.acall()
+        return scope.enter(cm)
+
+    def build(self, scope: Scope) -> T:
+        cm = self.factory.call()
+        return scope.enter(cm)
+
+
+class SimpleScopedInjectable[T](ScopedInjectable[T, T]):
+    __slots__ = ()
+
+    async def abuild(self, scope: Scope) -> T:
+        return await self.factory.acall()
+
+    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)
 
 
 @dataclass(repr=False, frozen=True, slots=True)

injection/_core/module.py

@@ -12,17 +12,25 @@ from collections.abc import (
     Iterator,
     Mapping,
 )
-from contextlib import contextmanager, suppress
+from contextlib import asynccontextmanager, contextmanager, suppress
 from dataclasses import dataclass, field
 from enum import StrEnum
 from functools import partialmethod, singledispatchmethod, update_wrapper
-from inspect import Signature, isclass, iscoroutinefunction, markcoroutinefunction
+from inspect import (
+    Signature,
+    isasyncgenfunction,
+    isclass,
+    iscoroutinefunction,
+    isgeneratorfunction,
+    markcoroutinefunction,
+)
 from inspect import signature as inspect_signature
 from logging import Logger, getLogger
 from queue import Empty, Queue
 from types import MethodType
 from typing import (
     Any,
+    AsyncContextManager,
     ClassVar,
     ContextManager,
     Literal,
@@ -32,7 +40,6 @@ from typing import (
     overload,
     runtime_checkable,
 )
-from uuid import uuid4
 
 from injection._core.common.asynchronous import (
     AsyncCaller,
@@ -42,14 +49,22 @@ from injection._core.common.asynchronous import (
 )
 from injection._core.common.event import Event, EventChannel, EventListener
 from injection._core.common.invertible import Invertible, SimpleInvertible
+from injection._core.common.key import new_short_key
 from injection._core.common.lazy import Lazy, LazyMapping
-from injection._core.common.threading import synchronized
-from injection._core.common.type import InputType, TypeInfo, get_return_types
+from injection._core.common.type import (
+    InputType,
+    TypeInfo,
+    get_return_types,
+    get_yield_hint,
+)
 from injection._core.hook import Hook, apply_hooks
 from injection._core.injectables import (
+    AsyncCMScopedInjectable,
+    CMScopedInjectable,
     Injectable,
     ShouldBeInjectable,
     SimpleInjectable,
+    SimpleScopedInjectable,
     SingletonInjectable,
 )
 from injection.exceptions import (
@@ -198,14 +213,12 @@ class Record[T](NamedTuple):
 
 @dataclass(repr=False, eq=False, kw_only=True, slots=True)
 class Updater[T]:
-    factory: Caller[..., T]
     classes: Iterable[InputType[T]]
-    injectable_factory: InjectableFactory[T]
+    injectable: Injectable[T]
     mode: Mode
 
     def make_record(self) -> Record[T]:
-        injectable = self.injectable_factory(self.factory)
-        return Record(injectable, self.mode)
+        return Record(self.injectable, self.mode)
 
 
 @dataclass(repr=False, eq=False, frozen=True, slots=True)
@@ -262,7 +275,6 @@ class Locator(Broker):
     def __injectables(self) -> frozenset[Injectable[Any]]:
         return frozenset(record.injectable for record in self.__records.values())
 
-    @synchronized()
     def update[T](self, updater: Updater[T]) -> Self:
         updater = self.__update_preprocessing(updater)
         record = updater.make_record()
@@ -276,7 +288,6 @@ class Locator(Broker):
 
         return self
 
-    @synchronized()
     def unlock(self) -> Self:
         for injectable in self.__injectables:
             injectable.unlock()
@@ -350,7 +361,7 @@ type PriorityStr = Literal["low", "high"]
 
 @dataclass(eq=False, frozen=True, slots=True)
 class Module(Broker, EventListener):
-    name: str = field(default_factory=lambda: f"anonymous@{uuid4().hex[:7]}")
+    name: str = field(default_factory=lambda: f"anonymous@{new_short_key()}")
     __channel: EventChannel = field(
         default_factory=EventChannel,
         init=False,
@@ -393,7 +404,7 @@ class Module(Broker, EventListener):
 
     @property
     def __brokers(self) -> Iterator[Broker]:
-        yield from tuple(self.__modules)
+        yield from self.__modules
         yield self.__locator
 
     def injectable[**P, T](
@@ -402,6 +413,7 @@ class Module(Broker, EventListener):
         /,
         *,
         cls: InjectableFactory[T] = SimpleInjectable,
+        ignore_type_hint: bool = False,
         inject: bool = True,
         on: TypeInfo[T] = (),
         mode: Mode | ModeStr = Mode.get_default(),
@@ -409,12 +421,11 @@ class Module(Broker, EventListener):
         def decorator(
             wp: Callable[P, T] | Callable[P, Awaitable[T]],
         ) -> Callable[P, T] | Callable[P, Awaitable[T]]:
-            factory = _get_caller(self.make_injected_function(wp) if inject else wp)
-            classes = get_return_types(wp, on)
+            factory = extract_caller(self.make_injected_function(wp) if inject else wp)
+            hints = on if ignore_type_hint else (wp, on)
             updater = Updater(
-                factory=factory,
-                classes=classes,
-                injectable_factory=cls,
+                classes=get_return_types(hints),
+                injectable=cls(factory),  # type: ignore[arg-type]
                 mode=Mode(mode),
             )
             self.update(updater)
@@ -424,12 +435,66 @@ class Module(Broker, EventListener):
 
     singleton = partialmethod(injectable, cls=SingletonInjectable)
 
+    def scoped[**P, T](
+        self,
+        scope_name: str,
+        /,
+        *,
+        inject: bool = True,
+        on: TypeInfo[T] = (),
+        mode: Mode | ModeStr = Mode.get_default(),
+    ) -> Any:
+        def decorator(
+            wrapped: Callable[P, T]
+            | Callable[P, Awaitable[T]]
+            | Callable[P, Iterator[T]]
+            | Callable[P, AsyncIterator[T]],
+        ) -> (
+            Callable[P, T]
+            | Callable[P, Awaitable[T]]
+            | Callable[P, Iterator[T]]
+            | Callable[P, AsyncIterator[T]]
+        ):
+            injectable_class: Callable[[Caller[P, Any], str], Injectable[T]]
+            wrapper: (
+                Callable[P, T]
+                | Callable[P, Awaitable[T]]
+                | Callable[P, ContextManager[T]]
+                | Callable[P, AsyncContextManager[T]]
+            )
+
+            if isasyncgenfunction(wrapped):
+                hint = get_yield_hint(wrapped)
+                injectable_class = AsyncCMScopedInjectable
+                wrapper = asynccontextmanager(wrapped)
+
+            elif isgeneratorfunction(wrapped):
+                hint = get_yield_hint(wrapped)
+                injectable_class = CMScopedInjectable
+                wrapper = contextmanager(wrapped)
+
+            else:
+                injectable_class = SimpleScopedInjectable
+                hint = wrapper = wrapped  # type: ignore[assignment]
+
+            hints = on if hint is None else (hint, on)
+            self.injectable(
+                wrapper,
+                cls=lambda factory: injectable_class(factory, scope_name),
+                ignore_type_hint=True,
+                inject=inject,
+                on=hints,
+                mode=mode,
+            )
+            return wrapped
+
+        return decorator
+
     def should_be_injectable[T](self, wrapped: type[T] | None = None, /) -> Any:
         def decorator(wp: type[T]) -> type[T]:
             updater = Updater(
-                factory=SyncCaller(wp),
                 classes=(wp,),
-                injectable_factory=lambda _: ShouldBeInjectable(wp),
+                injectable=ShouldBeInjectable(wp),
                 mode=Mode.FALLBACK,
             )
             self.update(updater)
@@ -449,6 +514,7 @@ class Module(Broker, EventListener):
             lazy_instance = Lazy(wp)
             self.injectable(
                 lambda: ~lazy_instance,
+                ignore_type_hint=True,
                 inject=False,
                 on=(wp, on),
                 mode=mode,
@@ -465,14 +531,12 @@ class Module(Broker, EventListener):
         alias: bool = False,
         mode: Mode | ModeStr = Mode.get_default(),
     ) -> Self:
-        if not alias:
-            cls = type(instance)
-            on = (cls, on)
-
+        hints = on if alias else (type(instance), on)
         self.injectable(
             lambda: instance,
+            ignore_type_hint=True,
             inject=False,
-            on=on,
+            on=hints,
             mode=mode,
         )
         return self
@@ -670,8 +734,11 @@ class Module(Broker, EventListener):
         priority: Priority | PriorityStr = Priority.get_default(),
     ) -> Iterator[None]:
         self.use(module, priority=priority)
-        yield
-        self.stop_using(module)
+
+        try:
+            yield
+        finally:
+            self.stop_using(module)
 
     def change_priority(self, module: Module, priority: Priority | PriorityStr) -> Self:
         priority = Priority(priority)
@@ -682,7 +749,6 @@ class Module(Broker, EventListener):
 
         return self
 
-    @synchronized()
     def unlock(self) -> Self:
         for broker in self.__brokers:
             broker.unlock()
@@ -714,12 +780,14 @@ class Module(Broker, EventListener):
         self.__check_locking()
 
         with self.__channel.dispatch(event):
-            yield
-            message = str(event)
-            self.__debug(message)
+            try:
+                yield
+            finally:
+                message = str(event)
+                self.__debug(message)
 
     def __debug(self, message: object) -> None:
-        for logger in tuple(self.__loggers):
+        for logger in self.__loggers:
             logger.debug(message)
 
     def __check_locking(self) -> None:
@@ -741,10 +809,8 @@ class Module(Broker, EventListener):
         with suppress(KeyError):
             return cls.__instances[name]
 
-        with synchronized():
-            instance = cls(name)
-            cls.__instances[name] = instance
-
+        instance = cls(name)
+        cls.__instances[name] = instance
         return instance
 
     @classmethod
@@ -873,10 +939,8 @@ class InjectMetadata[**P, T](Caller[P, T], EventListener):
         with suppress(AttributeError):
             return self.__signature
 
-        with synchronized():
-            signature = inspect_signature(self.wrapped, eval_str=True)
-            self.__signature = signature
-
+        signature = inspect_signature(self.wrapped, eval_str=True)
+        self.__signature = signature
         return signature
 
     @property
@@ -921,7 +985,6 @@ class InjectMetadata[**P, T](Caller[P, T], EventListener):
         self.__owner = owner
         return self
 
-    @synchronized()
     def update(self, module: Module) -> Self:
         self.__dependencies = Dependencies.resolve(self.signature, module, self.__owner)
         return self
@@ -968,9 +1031,7 @@ class InjectMetadata[**P, T](Caller[P, T], EventListener):
         self.__setup_queue = None
 
     def __setup(self) -> None:
-        queue = self.__setup_queue
-
-        if queue is None:
+        if (queue := self.__setup_queue) is None:
             return
 
         while True:
@@ -1037,11 +1098,13 @@ class SyncInjectedFunction[**P, T](InjectedFunction[P, T]):
         return self.__inject_metadata__.call(*args, **kwargs)
 
 
-def _get_caller[**P, T](function: Callable[P, T]) -> Caller[P, T]:
+def extract_caller[**P, T](
+    function: Callable[P, T] | Callable[P, Awaitable[T]],
+) -> Caller[P, T]:
     if iscoroutinefunction(function):
         return AsyncCaller(function)
 
     elif isinstance(function, InjectedFunction):
         return function.__inject_metadata__
 
-    return SyncCaller(function)
+    return SyncCaller(function)  # type: ignore[arg-type]

injection/_core/scope.py

@@ -0,0 +1,209 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections import defaultdict
+from collections.abc import AsyncIterator, Iterator, MutableMapping
+from contextlib import AsyncExitStack, ExitStack, asynccontextmanager, contextmanager
+from contextvars import ContextVar
+from dataclasses import dataclass, field
+from types import TracebackType
+from typing import (
+    Any,
+    AsyncContextManager,
+    ContextManager,
+    Final,
+    NoReturn,
+    Protocol,
+    Self,
+    runtime_checkable,
+)
+
+from injection._core.common.key import new_short_key
+from injection.exceptions import (
+    ScopeAlreadyDefinedError,
+    ScopeError,
+    ScopeUndefinedError,
+)
+
+
+@dataclass(repr=False, slots=True)
+class _ScopeState:
+    # Shouldn't be instantiated outside `__SCOPES`.
+
+    __context_var: ContextVar[Scope] = field(
+        default_factory=lambda: ContextVar(f"scope@{new_short_key()}"),
+        init=False,
+    )
+    __references: set[Scope] = field(
+        default_factory=set,
+        init=False,
+    )
+    __shared_value: Scope | None = field(
+        default=None,
+        init=False,
+    )
+
+    @property
+    def active_scopes(self) -> Iterator[Scope]:
+        yield from self.__references
+
+        if shared_value := self.__shared_value:
+            yield shared_value
+
+    @contextmanager
+    def bind_contextual_scope(self, scope: Scope) -> Iterator[None]:
+        self.__references.add(scope)
+        token = self.__context_var.set(scope)
+
+        try:
+            yield
+        finally:
+            self.__context_var.reset(token)
+            self.__references.remove(scope)
+
+    @contextmanager
+    def bind_shared_scope(self, scope: Scope) -> Iterator[None]:
+        if next(self.active_scopes, None):
+            raise ScopeError(
+                "A shared scope can't be defined when one or more contextual scopes "
+                "are defined on the same name."
+            )
+
+        self.__shared_value = scope
+
+        try:
+            yield
+        finally:
+            self.__shared_value = None
+
+    def get_scope(self) -> Scope | None:
+        return self.__context_var.get(self.__shared_value)
+
+
+__SCOPES: Final[defaultdict[str, _ScopeState]] = defaultdict(_ScopeState)
+
+
+@asynccontextmanager
+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 define_scope(name: str, *, shared: bool = False) -> Iterator[None]:
+    with SyncScope() as scope:
+        scope.enter(_bind_scope(name, scope, shared))
+        yield
+
+
+def get_active_scopes(name: str) -> tuple[Scope, ...]:
+    return tuple(__SCOPES[name].active_scopes)
+
+
+def get_scope(name: str) -> Scope:
+    scope = __SCOPES[name].get_scope()
+
+    if scope is None:
+        raise ScopeUndefinedError(
+            f"Scope `{name}` isn't defined in the current context."
+        )
+
+    return scope
+
+
+@contextmanager
+def _bind_scope(name: str, scope: Scope, shared: bool) -> Iterator[None]:
+    state = __SCOPES[name]
+
+    if state.get_scope():
+        raise ScopeAlreadyDefinedError(
+            f"Scope `{name}` is already defined in the current context."
+        )
+
+    strategy = (
+        state.bind_shared_scope(scope) if shared else state.bind_contextual_scope(scope)
+    )
+
+    try:
+        with strategy:
+            yield
+    finally:
+        scope.cache.clear()
+
+
+@runtime_checkable
+class Scope(Protocol):
+    __slots__ = ()
+
+    cache: MutableMapping[Any, Any]
+
+    @abstractmethod
+    async def aenter[T](self, context_manager: AsyncContextManager[T]) -> T:
+        raise NotImplementedError
+
+    @abstractmethod
+    def enter[T](self, context_manager: ContextManager[T]) -> T:
+        raise NotImplementedError
+
+
+@dataclass(repr=False, frozen=True, slots=True)
+class BaseScope[T](Scope, ABC):
+    delegate: T
+    cache: MutableMapping[Any, Any] = field(
+        default_factory=dict,
+        init=False,
+        hash=False,
+    )
+
+
+class AsyncScope(BaseScope[AsyncExitStack]):
+    __slots__ = ()
+
+    def __init__(self) -> None:
+        super().__init__(delegate=AsyncExitStack())
+
+    async def __aenter__(self) -> Self:
+        await self.delegate.__aenter__()
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> Any:
+        return await self.delegate.__aexit__(exc_type, exc_value, traceback)
+
+    async def aenter[T](self, context_manager: AsyncContextManager[T]) -> T:
+        return await self.delegate.enter_async_context(context_manager)
+
+    def enter[T](self, context_manager: ContextManager[T]) -> T:
+        return self.delegate.enter_context(context_manager)
+
+
+class SyncScope(BaseScope[ExitStack]):
+    __slots__ = ()
+
+    def __init__(self) -> None:
+        super().__init__(delegate=ExitStack())
+
+    def __enter__(self) -> Self:
+        self.delegate.__enter__()
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> Any:
+        return self.delegate.__exit__(exc_type, exc_value, traceback)
+
+    async def aenter[T](self, context_manager: AsyncContextManager[T]) -> NoReturn:
+        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)

injection/exceptions.py

@@ -7,6 +7,9 @@ __all__ = (
     "ModuleLockError",
     "ModuleNotUsedError",
     "NoInjectable",
+    "ScopeAlreadyDefinedError",
+    "ScopeError",
+    "ScopeUndefinedError",
 )
 
 
@@ -36,4 +39,13 @@ class ModuleLockError(ModuleError): ...
 class ModuleNotUsedError(KeyError, ModuleError): ...
 
 
+class ScopeError(InjectionError): ...
+
+
+class ScopeUndefinedError(LookupError, ScopeError): ...
+
+
+class ScopeAlreadyDefinedError(ScopeError): ...
+
+
 class HookError(InjectionError): ...

injection/integrations/fastapi.py

@@ -1,11 +1,9 @@
-from collections.abc import Awaitable
 from types import GenericAlias
 from typing import Any, TypeAliasType
 
 from fastapi import Depends
 
 from injection import Module, mod
-from injection.exceptions import InjectionError
 
 __all__ = ("Inject",)
 
@@ -13,51 +11,17 @@ __all__ = ("Inject",)
 def Inject[T](  # noqa: N802
     cls: type[T] | TypeAliasType | GenericAlias,
     /,
+    default: T = NotImplemented,
     module: Module | None = None,
-    *,
-    scoped: bool = True,
 ) -> Any:
     """
     Declare a FastAPI dependency with `python-injection`.
     """
 
-    dependency: InjectionDependency[T] = InjectionDependency(cls, module or mod())
-    return Depends(dependency, use_cache=scoped)
+    module = module or mod()
+    lazy_instance = module.aget_lazy_instance(cls, default)
 
+    async def getter() -> T:
+        return await lazy_instance
 
-class InjectionDependency[T]:
-    __slots__ = ("__class", "__lazy_instance", "__module")
-
-    __class: type[T] | TypeAliasType | GenericAlias
-    __lazy_instance: Awaitable[T]
-    __module: Module
-
-    def __init__(
-        self,
-        cls: type[T] | TypeAliasType | GenericAlias,
-        module: Module,
-    ) -> None:
-        self.__class = cls
-        self.__lazy_instance = module.aget_lazy_instance(cls, default=NotImplemented)
-        self.__module = module
-
-    async def __call__(self) -> T:
-        instance = await self.__lazy_instance
-
-        if instance is NotImplemented:
-            raise InjectionError(f"`{self.__class}` is an unknown dependency.")
-
-        return instance
-
-    def __eq__(self, other: Any) -> bool:
-        if isinstance(other, type(self)):
-            return self.__key == other.__key
-
-        return NotImplemented
-
-    def __hash__(self) -> int:
-        return hash(self.__key)
-
-    @property
-    def __key(self) -> tuple[type[T] | TypeAliasType | GenericAlias, Module]:
-        return self.__class, self.__module
+    return Depends(getter, use_cache=False)

injection/testing/__init__.py

@@ -9,6 +9,7 @@ __all__ = (
     "should_be_test_injectable",
     "test_constant",
     "test_injectable",
+    "test_scoped",
     "test_singleton",
 )
 
@@ -18,6 +19,7 @@ set_test_constant = mod(_TEST_PROFILE_NAME).set_constant
 should_be_test_injectable = mod(_TEST_PROFILE_NAME).should_be_injectable
 test_constant = mod(_TEST_PROFILE_NAME).constant
 test_injectable = mod(_TEST_PROFILE_NAME).injectable
+test_scoped = mod(_TEST_PROFILE_NAME).scoped
 test_singleton = mod(_TEST_PROFILE_NAME).singleton
 
 

injection/testing/__init__.pyi

@@ -1,12 +1,15 @@
-from typing import ContextManager
+from typing import ContextManager, Final
 
-import injection as _
+from injection import Module
 
-set_test_constant = _.set_constant
-should_be_test_injectable = _.should_be_injectable
-test_constant = _.constant
-test_injectable = _.injectable
-test_singleton = _.singleton
+__MODULE: Final[Module] = ...
+
+set_test_constant = __MODULE.set_constant
+should_be_test_injectable = __MODULE.should_be_injectable
+test_constant = __MODULE.constant
+test_injectable = __MODULE.injectable
+test_scoped = __MODULE.scoped
+test_singleton = __MODULE.singleton
 
 def load_test_profile(*names: str) -> ContextManager[None]:
     """

injection/utils.py

@@ -42,12 +42,17 @@ def load_modules_with_keywords(
     """
     Function to import modules from a Python package if one of the keywords is contained in the Python script.
     The default keywords are:
-        - `from injection`
+        - `from injection `
+        - `from injection.`
         - `import injection`
     """
 
     if keywords is None:
-        keywords = f"from {injection_package_name}", f"import {injection_package_name}"
+        keywords = (
+            f"from {injection_package_name} ",
+            f"from {injection_package_name}.",
+            f"import {injection_package_name}",
+        )
 
     b_keywords = tuple(keyword.encode() for keyword in keywords)
 

{python_injection-0.12.3.dist-info → python_injection-0.13.1.dist-info}/METADATA

@@ -1,31 +1,30 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: python-injection
-Version: 0.12.3
+Version: 0.13.1
 Summary: Fast and easy dependency injection framework.
-Home-page: https://github.com/100nm/python-injection
+Project-URL: Repository, https://github.com/100nm/python-injection
+Author: remimd
 License: MIT
 Keywords: dependencies,dependency,inject,injection
-Author: remimd
-Requires-Python: >=3.12, <4
 Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Topic :: Software Development :: Libraries
 Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: Software Development :: Testing
-Classifier: Programming Language :: Python
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Operating System :: OS Independent
-Classifier: Intended Audience :: Developers
-Classifier: Natural Language :: English
 Classifier: Typing :: Typed
-Project-URL: Repository, https://github.com/100nm/python-injection
+Requires-Python: <4,>=3.12
 Description-Content-Type: text/markdown
 
 # python-injection
 
 [![CI](https://github.com/100nm/python-injection/actions/workflows/ci.yml/badge.svg)](https://github.com/100nm/python-injection)
-[![PyPI](https://img.shields.io/pypi/v/python-injection.svg?color=blue)](https://pypi.org/project/python-injection/)
+[![PyPI](https://img.shields.io/pypi/v/python-injection.svg?color=blue)](https://pypi.org/project/python-injection)
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 
 Fast and easy dependency injection framework.
@@ -80,9 +79,9 @@ 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)
 * [**Integrations**](https://github.com/100nm/python-injection/tree/prod/documentation/integrations.md)
-* [**Concrete example**](https://github.com/100nm/python-injection/tree/prod/documentation/example)
-
+* [**Concrete example**](https://github.com/100nm/python-injection-example)

python_injection-0.13.1.dist-info/RECORD

@@ -0,0 +1,25 @@
+injection/__init__.py,sha256=X0vIAoN4MDlhR7YIkup1qHgqbOkwZ3PWgdSi7h-udaM,1049
+injection/__init__.pyi,sha256=LXBL7_ihiw6NyU94xWGdXkWwxvzRBoLYBSOv88PV2WM,9640
+injection/exceptions.py,sha256=T__732aXxWWUz0sKc39ySteyolCS5tpqQC0oCnzUF2E,917
+injection/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+injection/utils.py,sha256=SZBzmVAwRL-kilS2eRt9MCeNAL4zeaj_7Rm_2NLBzg0,3175
+injection/_core/__init__.py,sha256=XERocCxCZBxPGIaOR37yeiQOZyvjHQ6a4rgRmlkUSuU,1367
+injection/_core/descriptors.py,sha256=7fSHlgAqmgR_Uta8KocBapOt1Xyj2dI7RY9ZdoStTzw,726
+injection/_core/hook.py,sha256=Qv505pr3kjOE6UitftlLh9JKX9OCNqZBRtHbFha1gqM,3130
+injection/_core/injectables.py,sha256=SApYnP6vG3b1qi_KJx6hkJyPoyTmZfooxqPpOsxWSVI,4482
+injection/_core/module.py,sha256=wOoHW_bImPSwoxi3i8_rFXP_HWFJ_S78UuY_5EIilFQ,30595
+injection/_core/scope.py,sha256=TKOoxCmi2FIoXis0irReVNayDTte4KjLrTq8ZDcrOSk,5583
+injection/_core/common/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+injection/_core/common/asynchronous.py,sha256=LlYMde_55osS3r8Sc3Fh5lgPp5UWmIfvyBzUeIDmMiM,1698
+injection/_core/common/event.py,sha256=XjzV8gxtGlGvzZs_ykvoC60qmdpd3RN08Eiqz5QUwes,1236
+injection/_core/common/invertible.py,sha256=YZlAdh6bNJgf1-74TRjwJTm8xrlgY95ZhOUGLSJ4XcY,482
+injection/_core/common/key.py,sha256=ghkZD-Y8Moz6SEPNgMh3xgsZUjDVq-XYAmXaCu5VuCA,80
+injection/_core/common/lazy.py,sha256=ZKx2O9CCFsF9F0SLM4zb7jSLksJUv-FBLCPlWltMN5k,1398
+injection/_core/common/type.py,sha256=QbBBhJp7i1p6gLzWX0TgofvfG7yDH-gHfEQcssVZeHo,2186
+injection/integrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+injection/integrations/fastapi.py,sha256=YHSs85_3m6TUVtOwUcV157b3UZJQIw_aXWAg199a-YE,594
+injection/testing/__init__.py,sha256=ALcKuDYNdslmpgqotZzSWrXAW0kNNFUs9nzfO1ZgIGc,783
+injection/testing/__init__.pyi,sha256=6rv5NOYHEaiKMd82E1IIc8lFlLV9ttY57DLiMqGTXt8,482
+python_injection-0.13.1.dist-info/METADATA,sha256=y4ls59BE2tC-G8V8chV5dMl4um6zcLtYOejDr03Z3jQ,2996
+python_injection-0.13.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+python_injection-0.13.1.dist-info/RECORD,,

{python_injection-0.12.3.dist-info → python_injection-0.13.1.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: poetry-core 2.0.0
+Generator: hatchling 1.27.0
 Root-Is-Purelib: true
 Tag: py3-none-any

injection/_core/common/threading.py

@@ -1,11 +0,0 @@
-from collections.abc import Iterator
-from contextlib import contextmanager
-from threading import RLock
-
-
-@contextmanager
-def synchronized() -> Iterator[RLock]:
-    lock = RLock()
-
-    with lock:
-        yield lock

python_injection-0.12.3.dist-info/RECORD

@@ -1,24 +0,0 @@
-injection/__init__.py,sha256=1MI9kXuQfsqLGQK_5-Zm4JjecqopjGNlhsAW8iihn9M,919
-injection/__init__.pyi,sha256=Gwtvo6sJVizqz0pTKNaG-Jz_NW0gSqEsoZF7T6p3V1s,8820
-injection/_core/__init__.py,sha256=XERocCxCZBxPGIaOR37yeiQOZyvjHQ6a4rgRmlkUSuU,1367
-injection/_core/common/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-injection/_core/common/asynchronous.py,sha256=Sd7r5y42WSNXRtC4NvYRn5y2Jb6nNapj0aAOvkS4WIU,1726
-injection/_core/common/event.py,sha256=kev8WUESAXzMn11EJsbTcICaCvYiD556E6BOLvQ54s4,1243
-injection/_core/common/invertible.py,sha256=YZlAdh6bNJgf1-74TRjwJTm8xrlgY95ZhOUGLSJ4XcY,482
-injection/_core/common/lazy.py,sha256=ZKx2O9CCFsF9F0SLM4zb7jSLksJUv-FBLCPlWltMN5k,1398
-injection/_core/common/threading.py,sha256=OXm7L3p8c7O7eSkU-RTR7cobqIGMhuo-7gpDXsWKDNQ,214
-injection/_core/common/type.py,sha256=c4QfvbkMfYMlNxqt-vq6QJ83ubMnw6AIVI2Rp-tV1PI,1550
-injection/_core/descriptors.py,sha256=y1rFTQdCDIMLVQfuQE8ZkTPlVZKgzvwZ2Y20Si05DwM,662
-injection/_core/hook.py,sha256=Qv505pr3kjOE6UitftlLh9JKX9OCNqZBRtHbFha1gqM,3130
-injection/_core/injectables.py,sha256=rBcrTYRpZ69LkHSGm6bve6TGPwf66XkuK2XVACwcRNc,2427
-injection/_core/module.py,sha256=e0FVvhplVRbOGrAT-RCNKIR2pTng5qEAxCjuurm0cEA,28675
-injection/exceptions.py,sha256=-5Shs7R5rctQXhpMLfcjiMBCzrtFWxC88qETUIHz57s,692
-injection/integrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-injection/integrations/fastapi.py,sha256=tI9ohXOm_WucqkS-DZJceIVb_mE9LOY_UpIcr6hfRVM,1668
-injection/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-injection/testing/__init__.py,sha256=Wd9sq43CJCV7GjYFSIaikIf4hJ5lfVNS7GP3iI8a1X8,719
-injection/testing/__init__.pyi,sha256=Dyf1LjSj3LrjghXjM2xkMiINg-OPWQMtjCEnnfWzaDY,372
-injection/utils.py,sha256=a9y95B08Fr9IgDiBffeQdcawQcvAs5gwBDt9cCYX0uE,3061
-python_injection-0.12.3.dist-info/METADATA,sha256=8AyuGaX3P5JfCRxQBcnMrwkssXYeKP52UC64xJ5XE-o,2958
-python_injection-0.12.3.dist-info/WHEEL,sha256=RaoafKOydTQ7I_I3JTrPCg6kUmTgtm4BornzOqyEfJ8,88
-python_injection-0.12.3.dist-info/RECORD,,