feat: ✨ Add constant injectable

Author: remimd

documentation/basic-usage.md

@@ -2,6 +2,8 @@
 
 ## Create an injectable
 
+> **Note**: If the class needs dependencies, these will be resolved when the instance is retrieved.
+
 If you wish to inject a singleton, use `singleton` decorator.
 
 ```python
@@ -22,7 +24,13 @@ class Injectable:
     """ class implementation """
 ```
 
-> **Note**: If the class needs dependencies, these will be resolved when the instance is retrieved.
+If you have a constant (such as a global variable) and wish to register it as an injectable, use `constant` function.
+
+```python
+from injection import constant
+
+app = constant(Application())
+```
 
 ## Inject an instance
 
@@ -40,6 +48,9 @@ def my_function(instance: Injectable):
 If `inject` decorates a class, it will be applied to the `__init__` method.
 _Especially useful for dataclasses:_
 
+> **Note**: Doesn't work with Pydantic `BaseModel` because the signature of the `__init__` method doesn't contain the
+> dependencies.
+
 ```python
 from dataclasses import dataclass
 
@@ -51,9 +62,6 @@ class DataClass:
     instance: Injectable = ...
 ```
 
-> **Note**: Doesn't work with Pydantic `BaseModel` because the signature of the `__init__` method doesn't contain the
-> dependencies.
-
 ## Get an instance
 
 _Example with `get_instance` function:_

injection/_pkg.py

@@ -3,6 +3,7 @@
 __all__ = (
     "Module",
     "ModulePriorities",
+    "constant",
     "default_module",
     "get_instance",
     "get_lazy_instance",
@@ -13,6 +14,7 @@
 
 default_module = Module(f"{__name__}:default_module")
 
+constant = default_module.constant
 get_instance = default_module.get_instance
 get_lazy_instance = default_module.get_lazy_instance
 

injection/_pkg.pyi

@@ -10,6 +10,7 @@ _T = TypeVar("_T")
 
 default_module: Final[Module] = ...
 
+constant = default_module.constant
 get_instance = default_module.get_instance
 get_lazy_instance = default_module.get_lazy_instance
 
@@ -59,12 +60,22 @@ class Module:
         singleton will be constructed. At injection time, the injected instance will
         always be the same.
         """
-    def get_instance(self, cls: type[_T] | UnionType) -> _T | None:
+    def constant(
+        self,
+        instance: _T,
+        on: type | Iterable[type] | UnionType = ...,
+    ) -> _T:
+        """
+        Function for registering a specific instance to be injected. This is useful for
+        registering global variables. The difference with the singleton decorator is
+        that no dependencies are resolved, so the module doesn't need to be locked.
+        """
+    def get_instance(self, cls: type[_T]) -> _T | None:
         """
         Function used to retrieve an instance associated with the type passed in
         parameter or return `None`.
         """
-    def get_lazy_instance(self, cls: type[_T] | UnionType) -> Lazy[_T | None]:
+    def get_lazy_instance(self, cls: type[_T]) -> Lazy[_T | None]:
         """
         Function used to retrieve an instance associated with the type passed in
         parameter or `None`. Return a `Lazy` object. To access the instance contained

injection/core/module.py

@@ -46,6 +46,7 @@
 _thread_lock = RLock()
 
 _T = TypeVar("_T")
+Types = Iterable[type] | UnionType
 
 
 """
@@ -211,7 +212,7 @@ def is_locked(self) -> bool:
     def __injectables(self) -> frozenset[Injectable]:
         return frozenset(self.__data.values())
 
-    def update(self, classes: Iterable[type] | UnionType, injectable: Injectable):
+    def update(self, classes: Types, injectable: Injectable):
         classes = frozenset(get_origins(*classes))
 
         if classes:
@@ -308,7 +309,16 @@ def __brokers(self) -> Iterator[Container | Module]:
         yield from tuple(self.__modules)
         yield self.__container
 
-    def get_instance(self, cls: type[_T] | UnionType) -> _T | None:
+    def constant(self, instance: _T, on: type | Types = None) -> _T:
+        cls = type(instance)
+
+        @self.injectable(on=(cls, on))
+        def get_constant():
+            return instance
+
+        return instance
+
+    def get_instance(self, cls: type[_T]) -> _T | None:
         try:
             injectable = self[cls]
         except KeyError:
@@ -317,10 +327,10 @@ def get_instance(self, cls: type[_T] | UnionType) -> _T | None:
         instance = injectable.get_instance()
         return cast(cls, instance)
 
-    def get_lazy_instance(self, cls: type[_T] | UnionType) -> Lazy[_T | None]:
+    def get_lazy_instance(self, cls: type[_T]) -> Lazy[_T | None]:
         return Lazy(lambda: self.get_instance(cls))
 
-    def update(self, classes: Iterable[type] | UnionType, injectable: Injectable):
+    def update(self, classes: Types, injectable: Injectable):
         self.__container.update(classes, injectable)
         return self
 
@@ -548,39 +558,29 @@ def __call__(
         wrapped: Callable[..., Any] = None,
         /,
         *,
-        on: type | Iterable[type] | UnionType = None,
+        on: type | Types = None,
     ):
         def decorator(wp):
-            @lambda fn: fn()
-            def classes():
-                if cls := self.__get_class(wp):
-                    yield cls
-
-                if on is None:
-                    return
-                elif isinstance(on, type | str):
-                    yield on
-                else:
-                    yield from on
-
             @self.__module.inject
             @wraps(wp, updated=())
             def factory(*args, **kwargs):
                 return wp(*args, **kwargs)
 
             injectable = self.__injectable_type(factory)
+            classes = self.__get_classes(wp, on)
             self.__module.update(classes, injectable)
-
             return wp
 
         return decorator(wrapped) if wrapped else decorator
 
-    @staticmethod
-    def __get_class(wrapped: Callable[..., Any]) -> type | None:
-        if isclass(wrapped):
-            return wrapped
+    @classmethod
+    def __get_classes(cls, *objects: Any) -> Iterator[type | UnionType]:
+        for obj in objects:
+            if isinstance(obj, Iterable) and not isinstance(obj, type | str):
+                yield from cls.__get_classes(*obj)
 
-        if isfunction(wrapped):
-            return get_annotations(wrapped, eval_str=True).get("return")
+            elif isfunction(obj):
+                yield get_annotations(obj, eval_str=True).get("return")
 
-        return None
+            else:
+                yield obj

poetry.lock

@@ -14,7 +14,7 @@ python = ">=3.10, <4"
 
 [tool.poetry.group.dev.dependencies]
 black = "*"
-blacksheep = "^2.0.4"
+blacksheep = "^2.0.5"
 flake8 = "*"
 isort = "*"
 pydantic = "^2.5.3"

pyproject.toml

@@ -113,6 +113,23 @@ def test_get_lazy_instance_with_no_injectable_return_lazy_none(self, module):
         assert ~lazy_instance is None
         assert lazy_instance.is_set
 
+    """
+    constant
+    """
+
+    def test_constant_with_success_return_instance(self, module):
+        instance = SomeClass()
+        return_value = module.constant(instance)
+        assert instance is return_value is module.get_instance(SomeClass)
+
+    def test_constant_with_on_return_instance(self, module):
+        class Class(SomeClass):
+            ...
+
+        instance = Class()
+        module.constant(instance, on=SomeClass)
+        assert instance is module.get_instance(Class) is module.get_instance(SomeClass)
+
     """
     use
     """