feat: ✨ Async support

Author: remimd

.github/actions/environment/action.yml

@@ -20,7 +20,6 @@ runs:
       run: |
         pip install --upgrade pip
         pip install poetry
-        poetry config installer.modern-installation true
         poetry config virtualenvs.create false
         poetry check
         poetry install --compile

documentation/basic-usage.md

@@ -89,6 +89,14 @@ from injection import get_instance
 service_a = get_instance(ServiceA)
 ```
 
+_Example with `aget_instance` function:_
+
+```python
+from injection import aget_instance
+
+service_a = await aget_instance(ServiceA)
+```
+
 _Example with `get_lazy_instance` function:_
 
 ```python
@@ -99,6 +107,16 @@ lazy_service_a = get_lazy_instance(ServiceA)
 service_a = ~lazy_service_a
 ```
 
+_Example with `aget_lazy_instance` function:_
+
+```python
+from injection import aget_lazy_instance
+
+lazy_service_a = aget_lazy_instance(ServiceA)
+# ...
+service_a = await lazy_service_a
+```
+
 ## Inheritance
 
 In the case of inheritance, you can use the decorator parameter `on` to link the injection to one or several other
@@ -159,6 +177,28 @@ def service_d_recipe() -> ServiceD:
     """ recipe implementation """
 ```
 
+### Async recipes
+
+An asynchronous recipe is defined in the same way as a conventional recipe. To retrieve an instance of an asynchronous
+recipe, you need to be in an asynchronous context (decorate an asynchronous function with `@inject` or use an
+asynchronous getter).
+
+Asynchronous singletons can be retrieved in a synchronous context if they have already been instantiated. The
+`all_ready` method ensures that all singletons have been instantiated.
+
+```python
+from injection import get_instance, mod, singleton
+
+@singleton
+async def service_e_recipe() -> ServiceE:
+    """ recipe implementation """
+
+async def main():
+    await mod().all_ready()
+    # ...
+    service_e = get_instance(ServiceE)
+```
+
 ## Working with type aliases
 
 ```python

documentation/integrations.md

@@ -2,35 +2,6 @@
 
 **Integrations make it easy to connect `python-injection` to other frameworks.**
 
-## [BlackSheep](https://github.com/Neoteroi/BlackSheep)
-
-_[See more](https://www.neoteroi.dev/blacksheep/dependency-injection) about BlackSheep and its dependency injection._
-
-Example:
-
-```python
-from blacksheep import Application
-from injection.integrations.blacksheep import InjectionServices
-
-app = Application(
-    services=InjectionServices(),
-)
-```
-
-Example with a custom injection module:
-
-```python
-from blacksheep import Application
-from injection import mod
-from injection.integrations.blacksheep import InjectionServices
-
-custom_module = mod("custom_module")
-
-app = Application(
-    services=InjectionServices(custom_module),
-)
-```
-
 ## [FastAPI](https://github.com/fastapi/fastapi)
 
 Exemple:

injection/__init__.py

@@ -1,12 +1,16 @@
 from ._core.descriptors import LazyInstance
-from ._core.module import Injectable, Mode, Module, Priority
+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",
@@ -19,14 +23,9 @@
     "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
@@ -21,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
@@ -53,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
@@ -131,12 +134,25 @@ 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,
@@ -149,12 +165,28 @@ class Module:
         """
 
     @overload
-    def get_instance[T, _](
+    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],
@@ -172,7 +204,7 @@ class Module:
         """
 
     @overload
-    def get_lazy_instance[T, _](
+    def get_lazy_instance[T](
         self,
         cls: _InputType[T],
         default: None = ...,
@@ -229,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:
@@ -253,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

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 @@ def __invert__(self) -> T:
 
 @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()