python-injection 0.10.12.post0__py3-none-any.whl → 0.12.0__py3-none-any.whl

injection/__init__.py

@@ -1,10 +1,16 @@
-from ._core.module import Injectable, Mode, Module, Priority
+from ._core.descriptors import LazyInstance
+from ._core.injectables import Injectable
+from ._core.module import Mode, Module, Priority, mod
 
 __all__ = (
     "Injectable",
+    "LazyInstance",
     "Mode",
     "Module",
     "Priority",
+    "afind_instance",
+    "aget_instance",
+    "aget_lazy_instance",
     "constant",
     "find_instance",
     "get_instance",
@@ -17,14 +23,9 @@ __all__ = (
     "singleton",
 )
 
-
-def mod(name: str | None = None, /) -> Module:
-    if name is None:
-        return Module.default()
-
-    return Module.from_name(name)
-
-
+afind_instance = mod().afind_instance
+aget_instance = mod().aget_instance
+aget_lazy_instance = mod().aget_lazy_instance
 constant = mod().constant
 find_instance = mod().find_instance
 get_instance = mod().get_instance

injection/__init__.pyi

@@ -1,5 +1,5 @@
 from abc import abstractmethod
-from collections.abc import Callable
+from collections.abc import Awaitable, Callable
 from contextlib import ContextDecorator
 from enum import Enum
 from logging import Logger
@@ -9,6 +9,7 @@ from typing import (
     Protocol,
     Self,
     final,
+    overload,
     runtime_checkable,
 )
 
@@ -20,6 +21,9 @@ from ._core.module import ModeStr, PriorityStr
 
 _: 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
@@ -52,59 +56,59 @@ class Module:
     def __contains__(self, cls: _InputType[Any], /) -> bool: ...
     @property
     def is_locked(self) -> bool: ...
-    def inject[**P, T](self, wrapped: Callable[P, T] = ..., /):  # type: ignore[no-untyped-def]
+    def inject[**P, T](self, wrapped: Callable[P, T] = ..., /) -> Any:
         """
         Decorator applicable to a class or function. Inject function dependencies using
         parameter type annotations. If applied to a class, the dependencies resolved
         will be those of the `__init__` method.
         """
 
-    def injectable[**P, T](  # type: ignore[no-untyped-def]
+    def injectable[**P, T](
         self,
-        wrapped: Callable[P, T] = ...,
+        wrapped: Callable[P, T] | Callable[P, Awaitable[T]] = ...,
         /,
         *,
         cls: _InjectableFactory[T] = ...,
         inject: bool = ...,
         on: _TypeInfo[T] = ...,
         mode: Mode | ModeStr = ...,
-    ):
+    ) -> Any:
         """
         Decorator applicable to a class or function. It is used to indicate how the
         injectable will be constructed. At injection time, a new instance will be
         injected each time.
         """
 
-    def singleton[**P, T](  # type: ignore[no-untyped-def]
+    def singleton[**P, T](
         self,
-        wrapped: Callable[P, T] = ...,
+        wrapped: Callable[P, T] | Callable[P, Awaitable[T]] = ...,
         /,
         *,
         inject: bool = ...,
         on: _TypeInfo[T] = ...,
         mode: Mode | ModeStr = ...,
-    ):
+    ) -> Any:
         """
         Decorator applicable to a class or function. It is used to indicate how the
         singleton will be constructed. At injection time, the injected instance will
         always be the same.
         """
 
-    def should_be_injectable[T](self, wrapped: type[T] = ..., /):  # type: ignore[no-untyped-def]
+    def should_be_injectable[T](self, wrapped: type[T] = ..., /) -> Any:
         """
         Decorator applicable to a class. It is used to specify whether an injectable
         should be registered. Raise an exception at injection time if the class isn't
         registered.
         """
 
-    def constant[T](  # type: ignore[no-untyped-def]
+    def constant[T](
         self,
         wrapped: type[T] = ...,
         /,
         *,
         on: _TypeInfo[T] = ...,
         mode: Mode | ModeStr = ...,
-    ):
+    ) -> Any:
         """
         Decorator applicable to a class or function. It is used to indicate how the
         constant is constructed. At injection time, the injected instance will always
@@ -130,29 +134,66 @@ class Module:
         wrapped: Callable[P, T],
         /,
     ) -> Callable[P, T]: ...
+    async def afind_instance[T](self, cls: _InputType[T]) -> T: ...
     def find_instance[T](self, cls: _InputType[T]) -> T:
         """
         Function used to retrieve an instance associated with the type passed in
         parameter or an exception will be raised.
         """
 
+    @overload
+    async def aget_instance[T, Default](
+        self,
+        cls: _InputType[T],
+        default: Default,
+    ) -> T | Default: ...
+    @overload
+    async def aget_instance[T](
+        self,
+        cls: _InputType[T],
+        default: None = ...,
+    ) -> T | None: ...
+    @overload
     def get_instance[T, Default](
         self,
         cls: _InputType[T],
-        default: Default | None = ...,
-    ) -> T | Default | None:
+        default: Default,
+    ) -> T | Default:
         """
         Function used to retrieve an instance associated with the type passed in
         parameter or return `None`.
         """
 
+    @overload
+    def get_instance[T](
+        self,
+        cls: _InputType[T],
+        default: None = ...,
+    ) -> T | None: ...
+    @overload
+    def aget_lazy_instance[T, Default](
+        self,
+        cls: _InputType[T],
+        default: Default,
+        *,
+        cache: bool = ...,
+    ) -> Awaitable[T | Default]: ...
+    @overload
+    def aget_lazy_instance[T](
+        self,
+        cls: _InputType[T],
+        default: None = ...,
+        *,
+        cache: bool = ...,
+    ) -> Awaitable[T | None]: ...
+    @overload
     def get_lazy_instance[T, Default](
         self,
         cls: _InputType[T],
-        default: Default | None = ...,
+        default: Default,
         *,
         cache: bool = ...,
-    ) -> _Invertible[T | Default | None]:
+    ) -> _Invertible[T | Default]:
         """
         Function used to retrieve an instance associated with the type passed in
         parameter or `None`. Return a `Invertible` object. To access the instance
@@ -162,6 +203,14 @@ class Module:
         Example: instance = ~lazy_instance
         """
 
+    @overload
+    def get_lazy_instance[T](
+        self,
+        cls: _InputType[T],
+        default: None = ...,
+        *,
+        cache: bool = ...,
+    ) -> _Invertible[T | None]: ...
     def init_modules(self, *modules: Module) -> Self:
         """
         Function to clean modules in use and to use those passed as parameters.
@@ -212,6 +261,7 @@ class Module:
         Function to unlock the module by deleting cached instances of singletons.
         """
 
+    async def all_ready(self) -> None: ...
     def add_logger(self, logger: Logger) -> Self: ...
     @classmethod
     def from_name(cls, name: str) -> Module:
@@ -236,6 +286,8 @@ class Injectable[T](Protocol):
     def is_locked(self) -> bool: ...
     def unlock(self) -> None: ...
     @abstractmethod
+    async def aget_instance(self) -> T: ...
+    @abstractmethod
     def get_instance(self) -> T: ...
 
 @final
@@ -243,3 +295,10 @@ 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: ...

injection/_core/__init__.py

@@ -49,5 +49,5 @@ def standardize_input_classes[T](
 @Locator.static_hooks.on_update
 def standardize_classes[T](*_: Any, **__: Any) -> HookGenerator[Updater[T]]:
     updater = yield
-    updater.classes = set(standardize_types(*updater.classes))
+    updater.classes = frozenset(standardize_types(*updater.classes))
     return updater

injection/_core/common/asynchronous.py

@@ -0,0 +1,54 @@
+from abc import abstractmethod
+from collections.abc import Awaitable, Callable, Generator
+from dataclasses import dataclass
+from typing import Any, NoReturn, Protocol, override, runtime_checkable
+
+
+@dataclass(repr=False, eq=False, frozen=True, slots=True)
+class SimpleAwaitable[T](Awaitable[T]):
+    callable: Callable[..., Awaitable[T]]
+
+    @override
+    def __await__(self) -> Generator[Any, Any, T]:
+        return self.callable().__await__()
+
+
+@runtime_checkable
+class Caller[**P, T](Protocol):
+    __slots__ = ()
+
+    @abstractmethod
+    async def acall(self, /, *args: P.args, **kwargs: P.kwargs) -> T:
+        raise NotImplementedError
+
+    @abstractmethod
+    def call(self, /, *args: P.args, **kwargs: P.kwargs) -> T:
+        raise NotImplementedError
+
+
+@dataclass(repr=False, eq=False, frozen=True, slots=True)
+class AsyncCaller[**P, T](Caller[P, T]):
+    callable: Callable[P, Awaitable[T]]
+
+    @override
+    async def acall(self, /, *args: P.args, **kwargs: P.kwargs) -> T:
+        return await self.callable(*args, **kwargs)
+
+    @override
+    def call(self, /, *args: P.args, **kwargs: P.kwargs) -> NoReturn:
+        raise RuntimeError(
+            "Synchronous call isn't supported for an asynchronous Callable."
+        )
+
+
+@dataclass(repr=False, eq=False, frozen=True, slots=True)
+class SyncCaller[**P, T](Caller[P, T]):
+    callable: Callable[P, T]
+
+    @override
+    async def acall(self, /, *args: P.args, **kwargs: P.kwargs) -> T:
+        return self.callable(*args, **kwargs)
+
+    @override
+    def call(self, /, *args: P.args, **kwargs: P.kwargs) -> T:
+        return self.callable(*args, **kwargs)

injection/_core/common/invertible.py

@@ -13,8 +13,8 @@ class Invertible[T](Protocol):
 
 @dataclass(repr=False, eq=False, frozen=True, slots=True)
 class SimpleInvertible[T](Invertible[T]):
-    getter: Callable[..., T]
+    callable: Callable[..., T]
 
     @override
     def __invert__(self) -> T:
-        return self.getter()
+        return self.callable()

injection/_core/common/type.py

@@ -1,5 +1,5 @@
-from collections.abc import Awaitable, Callable, Iterable, Iterator
-from inspect import iscoroutinefunction, isfunction
+from collections.abc import Callable, Iterable, Iterator
+from inspect import isfunction
 from types import GenericAlias, UnionType
 from typing import (
     Annotated,
@@ -24,9 +24,6 @@ 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")):
-            if iscoroutinefunction(arg):
-                return_type = Awaitable[return_type]  # type: ignore[valid-type]
-
             inner_args = (return_type,)
 
         else:

injection/_core/descriptors.py

@@ -0,0 +1,25 @@
+from typing import Self
+
+from injection._core.common.invertible import Invertible
+from injection._core.common.type import InputType
+from injection._core.module import Module, mod
+
+
+class LazyInstance[T]:
+    __slots__ = ("__value",)
+
+    __value: Invertible[T]
+
+    def __init__(self, cls: InputType[T], module: Module | None = None) -> None:
+        module = module or mod()
+        self.__value = module.get_lazy_instance(cls, default=NotImplemented)
+
+    def __get__(
+        self,
+        instance: object | None = None,
+        owner: type | None = None,
+    ) -> Self | T:
+        if instance is None:
+            return self
+
+        return ~self.__value

injection/_core/hook.py

@@ -2,12 +2,13 @@ import itertools
 from collections.abc import Callable, Generator, Iterator
 from dataclasses import dataclass, field
 from inspect import isclass, isgeneratorfunction
-from typing import Any, Self
+from typing import Any, Self, TypeGuard
 
 from injection.exceptions import HookError
 
 type HookGenerator[T] = Generator[None, T, T]
-type HookFunction[**P, T] = Callable[P, T | HookGenerator[T]]
+type HookGeneratorFunction[**P, T] = Callable[P, HookGenerator[T]]
+type HookFunction[**P, T] = Callable[P, T] | HookGeneratorFunction[P, T]
 
 
 @dataclass(eq=False, frozen=True, slots=True)
@@ -18,12 +19,12 @@ class Hook[**P, T]:
         repr=False,
     )
 
-    def __call__(  # type: ignore[no-untyped-def]
+    def __call__(
         self,
         wrapped: HookFunction[P, T] | type[HookFunction[P, T]] | None = None,
         /,
-    ):
-        def decorator(wp):  # type: ignore[no-untyped-def]
+    ) -> Any:
+        def decorator(wp: Any) -> Any:
             self.add(wp() if isclass(wp) else wp)
             return wp
 
@@ -48,11 +49,11 @@ class Hook[**P, T]:
         handler: Callable[P, T],
         function: HookFunction[P, T],
     ) -> Callable[P, T]:
-        if not cls.__is_generator_function(function):
+        if not cls.__is_hook_generator_function(function):
             return function  # type: ignore[return-value]
 
         def wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
-            hook: HookGenerator[T] = function(*args, **kwargs)  # type: ignore[assignment]
+            hook: HookGenerator[T] = function(*args, **kwargs)
 
             try:
                 next(hook)
@@ -88,9 +89,11 @@ class Hook[**P, T]:
         return handler
 
     @staticmethod
-    def __is_generator_function(obj: Any) -> bool:
-        for o in obj, getattr(obj, "__call__", None):
-            if isgeneratorfunction(o):
+    def __is_hook_generator_function[**_P, _T](
+        function: HookFunction[_P, _T],
+    ) -> TypeGuard[HookGeneratorFunction[_P, _T]]:
+        for fn in function, getattr(function, "__call__", None):
+            if isgeneratorfunction(fn):
                 return True
 
         return False

injection/_core/injectables.py

@@ -0,0 +1,106 @@
+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, override, runtime_checkable
+
+from injection._core.common.asynchronous import Caller
+from injection._core.common.threading import synchronized
+from injection.exceptions import InjectionError
+
+
+@runtime_checkable
+class Injectable[T](Protocol):
+    __slots__ = ()
+
+    @property
+    def is_locked(self) -> bool:
+        return False
+
+    def unlock(self) -> None:
+        return
+
+    @abstractmethod
+    async def aget_instance(self) -> T:
+        raise NotImplementedError
+
+    @abstractmethod
+    def get_instance(self) -> T:
+        raise NotImplementedError
+
+
+@dataclass(repr=False, frozen=True, slots=True)
+class BaseInjectable[T](Injectable[T], ABC):
+    factory: Caller[..., T]
+
+
+class SimpleInjectable[T](BaseInjectable[T]):
+    __slots__ = ()
+
+    @override
+    async def aget_instance(self) -> T:
+        return await self.factory.acall()
+
+    @override
+    def get_instance(self) -> T:
+        return self.factory.call()
+
+
+class SingletonInjectable[T](BaseInjectable[T]):
+    __slots__ = ("__dict__",)
+
+    __key: ClassVar[str] = "$instance"
+
+    @property
+    def cache(self) -> MutableMapping[str, Any]:
+        return self.__dict__
+
+    @property
+    @override
+    def is_locked(self) -> bool:
+        return self.__key in self.cache
+
+    @override
+    def unlock(self) -> None:
+        self.cache.clear()
+
+    @override
+    async def aget_instance(self) -> T:
+        with suppress(KeyError):
+            return self.__check_instance()
+
+        with synchronized():
+            instance = await self.factory.acall()
+            self.__set_instance(instance)
+
+        return instance
+
+    @override
+    def get_instance(self) -> T:
+        with suppress(KeyError):
+            return self.__check_instance()
+
+        with synchronized():
+            instance = self.factory.call()
+            self.__set_instance(instance)
+
+        return instance
+
+    def __check_instance(self) -> T:
+        return self.cache[self.__key]
+
+    def __set_instance(self, value: T) -> None:
+        self.cache[self.__key] = value
+
+
+@dataclass(repr=False, frozen=True, slots=True)
+class ShouldBeInjectable[T](Injectable[T]):
+    cls: type[T]
+
+    @override
+    async def aget_instance(self) -> T:
+        return self.get_instance()
+
+    @override
+    def get_instance(self) -> NoReturn:
+        raise InjectionError(f"`{self.cls}` should be an injectable.")