python-injection 0.8.1.post0__tar.gz → 0.8.3__tar.gz

{python_injection-0.8.1.post0 → python_injection-0.8.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: python-injection
-Version: 0.8.1.post0
+Version: 0.8.3
 Summary: Fast and easy dependency injection framework.
 Home-page: https://github.com/100nm/python-injection
 License: MIT
@@ -136,7 +136,7 @@ class ConcreteServiceOverload(ConcreteService):
     ...
 ```
 
-If a class is registered in a package and you want to override it, there is the `override` parameter:
+If a class is registered in a package, and you want to override it, there is the `mode` parameter:
 
 ```python
 @injectable
@@ -145,7 +145,7 @@ class InaccessibleService:
 
 # ...
 
-@injectable(on=InaccessibleService, override=True)
+@injectable(on=InaccessibleService, mode="override")
 class ServiceOverload(InaccessibleService):
     ...
 ```

{python_injection-0.8.1.post0 → python_injection-0.8.3}/documentation/basic-usage.md

@@ -119,7 +119,7 @@ class ConcreteServiceOverload(ConcreteService):
     ...
 ```
 
-If a class is registered in a package and you want to override it, there is the `override` parameter:
+If a class is registered in a package, and you want to override it, there is the `mode` parameter:
 
 ```python
 @injectable
@@ -128,7 +128,7 @@ class InaccessibleService:
 
 # ...
 
-@injectable(on=InaccessibleService, override=True)
+@injectable(on=InaccessibleService, mode="override")
 class ServiceOverload(InaccessibleService):
     ...
 ```

python_injection-0.8.1.post0/injection/_pkg.py → python_injection-0.8.3/injection/__init__.py

@@ -1,7 +1,8 @@
-from .core import Injectable, Module, ModulePriority
+from .core import Injectable, InjectableMode, Module, ModulePriority
 
 __all__ = (
     "Injectable",
+    "InjectableMode",
     "Module",
     "ModulePriority",
     "default_module",

python_injection-0.8.1.post0/injection/_pkg.pyi → python_injection-0.8.3/injection/__init__.pyi

@@ -7,13 +7,14 @@ from typing import (
     Any,
     ContextManager,
     Final,
+    Literal,
     Protocol,
     TypeVar,
     final,
     runtime_checkable,
 )
 
-from injection.common.invertible import Invertible
+from .common.invertible import Invertible
 
 _T = TypeVar("_T")
 
@@ -54,7 +55,7 @@ class Module:
         cls: type[Injectable] = ...,
         inject: bool = ...,
         on: type | Iterable[type] | UnionType = ...,
-        override: bool = ...,
+        mode: InjectableMode | Literal["fallback", "normal", "override"] = ...,
     ):
         """
         Decorator applicable to a class or function. It is used to indicate how the
@@ -69,7 +70,7 @@ class Module:
         *,
         inject: bool = ...,
         on: type | Iterable[type] | UnionType = ...,
-        override: bool = ...,
+        mode: InjectableMode | Literal["fallback", "normal", "override"] = ...,
     ):
         """
         Decorator applicable to a class or function. It is used to indicate how the
@@ -89,7 +90,7 @@ class Module:
         instance: _T,
         on: type | Iterable[type] | UnionType = ...,
         *,
-        override: bool = ...,
+        mode: InjectableMode | Literal["fallback", "normal", "override"] = ...,
     ) -> _T:
         """
         Function for registering a specific instance to be injected. This is useful for
@@ -97,7 +98,7 @@ class Module:
         that no dependencies are resolved, so the module doesn't need to be locked.
         """
 
-    def get_instance(self, cls: type[_T], none: bool = ...) -> _T | None:
+    def get_instance(self, cls: type[_T], *, none: bool = ...) -> _T | None:
         """
         Function used to retrieve an instance associated with the type passed in
         parameter or return `None` but if `none` parameter is `False` an exception
@@ -107,6 +108,7 @@ class Module:
     def get_lazy_instance(
         self,
         cls: type[_T],
+        *,
         cache: bool = ...,
     ) -> Invertible[_T | None]:
         """
@@ -118,7 +120,12 @@ class Module:
         Example: instance = ~lazy_instance
         """
 
-    def use(self, module: Module, priority: ModulePriority = ...):
+    def use(
+        self,
+        module: Module,
+        *,
+        priority: ModulePriority | Literal["low", "high"] = ...,
+    ):
         """
         Function for using another module. Using another module replaces the module's
         dependencies with those of the module used. If the dependency is not found, it
@@ -133,13 +140,18 @@ class Module:
     def use_temporarily(
         self,
         module: Module,
-        priority: ModulePriority = ...,
+        *,
+        priority: ModulePriority | Literal["low", "high"] = ...,
     ) -> ContextManager | ContextDecorator:
         """
         Context manager or decorator for temporary use of a module.
         """
 
-    def change_priority(self, module: Module, priority: ModulePriority):
+    def change_priority(
+        self,
+        module: Module,
+        priority: ModulePriority | Literal["low", "high"],
+    ):
         """
         Function for changing the priority of a module in use.
         There are two priority values:
@@ -154,9 +166,9 @@ class Module:
         """
 
 @final
-class ModulePriority(Enum):
-    HIGH = ...
+class ModulePriority(str, Enum):
     LOW = ...
+    HIGH = ...
 
 @runtime_checkable
 class Injectable(Protocol[_T]):
@@ -166,3 +178,9 @@ class Injectable(Protocol[_T]):
     def unlock(self): ...
     @abstractmethod
     def get_instance(self) -> _T: ...
+
+@final
+class InjectableMode(str, Enum):
+    FALLBACK = ...
+    NORMAL = ...
+    OVERRIDE = ...

{python_injection-0.8.1.post0 → python_injection-0.8.3}/injection/core/module.py

@@ -11,11 +11,10 @@ from collections.abc import (
     Iterator,
     Mapping,
     MutableMapping,
-    Set,
 )
 from contextlib import ContextDecorator, contextmanager, suppress
 from dataclasses import dataclass, field
-from enum import Enum, auto
+from enum import Enum
 from functools import partialmethod, singledispatchmethod, update_wrapper
 from inspect import Signature, isclass
 from types import MethodType, UnionType
@@ -23,6 +22,7 @@ from typing import (
     Any,
     ClassVar,
     ContextManager,
+    Literal,
     NamedTuple,
     NoReturn,
     Protocol,
@@ -45,12 +45,12 @@ from injection.exceptions import (
     NoInjectable,
 )
 
-__all__ = ("Injectable", "Module", "ModulePriority")
+__all__ = ("Injectable", "InjectableMode", "Module", "ModulePriority")
 
 _logger = logging.getLogger(__name__)
 
 _T = TypeVar("_T")
-Types = Iterable[type] | UnionType
+_Types = Iterable[type] | UnionType
 
 
 """
@@ -66,7 +66,7 @@ class ContainerEvent(Event, ABC):
 @dataclass(frozen=True, slots=True)
 class ContainerDependenciesUpdated(ContainerEvent):
     classes: Collection[type]
-    override: bool
+    mode: InjectableMode
 
     def __str__(self) -> str:
         length = len(self.classes)
@@ -104,6 +104,7 @@ class ModuleEventProxy(ModuleEvent):
 @dataclass(frozen=True, slots=True)
 class ModuleAdded(ModuleEvent):
     module_added: Module
+    priority: ModulePriority
 
     def __str__(self) -> str:
         return f"`{self.on_module}` now uses `{self.module_added}`."
@@ -124,7 +125,7 @@ class ModulePriorityUpdated(ModuleEvent):
 
     def __str__(self) -> str:
         return (
-            f"In `{self.on_module}`, the priority `{self.priority.name}` "
+            f"In `{self.on_module}`, the priority `{self.priority}` "
             f"has been applied to `{self.module_updated}`."
         )
 
@@ -153,13 +154,6 @@ class Injectable(Protocol[_T]):
         raise NotImplementedError
 
 
-class FallbackInjectable(Injectable[_T], ABC):
-    __slots__ = ()
-
-    def __bool__(self) -> bool:
-        return False
-
-
 @dataclass(repr=False, frozen=True, slots=True)
 class BaseInjectable(Injectable[_T], ABC):
     factory: Callable[[], _T]
@@ -200,7 +194,7 @@ class SingletonInjectable(BaseInjectable[_T]):
 
 
 @dataclass(repr=False, frozen=True, slots=True)
-class ShouldBeInjectable(FallbackInjectable[_T]):
+class ShouldBeInjectable(Injectable[_T]):
     cls: type[_T]
 
     def get_instance(self) -> NoReturn:
@@ -239,49 +233,68 @@ Container
 """
 
 
+class InjectableMode(str, Enum):
+    FALLBACK = "fallback"
+    NORMAL = "normal"
+    OVERRIDE = "override"
+
+    @property
+    def rank(self) -> int:
+        return tuple(type(self)).index(self)
+
+    @classmethod
+    def get_default(cls):
+        return cls.NORMAL
+
+
+_Mode = InjectableMode | Literal["fallback", "normal", "override"]
+
+
+class Record(NamedTuple):
+    injectable: Injectable
+    mode: InjectableMode
+
+
 @dataclass(repr=False, frozen=True, slots=True)
 class Container(Broker):
-    __data: dict[type, Injectable] = field(default_factory=dict, init=False)
+    __records: dict[type, Record] = field(default_factory=dict, init=False)
     __channel: EventChannel = field(default_factory=EventChannel, init=False)
 
     def __getitem__(self, cls: type[_T] | UnionType, /) -> Injectable[_T]:
-        for origin in get_origins(cls):
-            with suppress(KeyError):
-                return self.__data[origin]
+        for cls in get_origins(cls):
+            try:
+                injectable, _ = self.__records[cls]
+            except KeyError:
+                continue
+
+            return injectable
 
         raise NoInjectable(cls)
 
     def __contains__(self, cls: type | UnionType, /) -> bool:
-        return any(origin in self.__data for origin in get_origins(cls))
+        return any(cls in self.__records for cls in get_origins(cls))
 
     @property
     def is_locked(self) -> bool:
         return any(injectable.is_locked for injectable in self.__injectables)
 
-    @property
-    def __classes(self) -> frozenset[type]:
-        return frozenset(self.__data)
-
     @property
     def __injectables(self) -> frozenset[Injectable]:
-        return frozenset(self.__data.values())
+        return frozenset(injectable for injectable, _ in self.__records.values())
 
     @synchronized()
-    def update(self, classes: Iterable[type], injectable: Injectable, override: bool):
-        classes = frozenset(get_origins(*classes))
+    def update(self, classes: Iterable[type], injectable: Injectable, mode: _Mode):
+        mode = InjectableMode(mode)
+        records = {
+            cls: Record(injectable, mode)
+            for cls in self.__filter_classes(classes, mode)
+        }
 
-        if not injectable:
-            classes -= self.__classes
-            override = True
-
-        if classes:
-            event = ContainerDependenciesUpdated(self, classes, override)
+        if records:
+            event = ContainerDependenciesUpdated(self, records.keys(), mode)
 
             with self.notify(event):
-                if not override:
-                    self.__check_if_exists(classes)
-
-                self.__data.update((cls, injectable) for cls in classes)
+                self.__records.update(records)
 
         return self
 
@@ -299,14 +312,30 @@ class Container(Broker):
     def notify(self, event: Event) -> ContextManager | ContextDecorator:
         return self.__channel.dispatch(event)
 
-    def __check_if_exists(self, classes: Set[type]):
-        intersection = classes & self.__classes
+    def __filter_classes(
+        self,
+        classes: Iterable[type],
+        mode: InjectableMode,
+    ) -> Iterator[type]:
+        rank = mode.rank
+
+        for cls in frozenset(get_origins(*classes)):
+            try:
+                _, current_mode = self.__records[cls]
+
+            except KeyError:
+                pass
+
+            else:
+                if mode == current_mode:
+                    raise RuntimeError(
+                        f"An injectable already exists for the class `{format_type(cls)}`."
+                    )
+
+                elif rank < current_mode.rank:
+                    continue
 
-        for cls in intersection:
-            if self.__data[cls]:
-                raise RuntimeError(
-                    f"An injectable already exists for the class `{format_type(cls)}`."
-                )
+            yield cls
 
 
 """
@@ -314,15 +343,18 @@ Module
 """
 
 
-class ModulePriority(Enum):
-    HIGH = auto()
-    LOW = auto()
+class ModulePriority(str, Enum):
+    LOW = "low"
+    HIGH = "high"
 
     @classmethod
     def get_default(cls):
         return cls.LOW
 
 
+_Priority = ModulePriority | Literal["low", "high"]
+
+
 @dataclass(repr=False, eq=False, frozen=True, slots=True)
 class Module(EventListener, Broker):
     name: str = field(default=None)
@@ -368,14 +400,14 @@ class Module(EventListener, Broker):
         *,
         cls: type[Injectable] = NewInjectable,
         inject: bool = True,
-        on: type | Types = None,
-        override: bool = False,
+        on: type | _Types = None,
+        mode: _Mode = InjectableMode.get_default(),
     ):
         def decorator(wp):
             factory = self.inject(wp, return_factory=True) if inject else wp
             injectable = cls(factory)
             classes = find_types(wp, on)
-            self.update(classes, injectable, override)
+            self.update(classes, injectable, mode)
             return wp
 
         return decorator(wrapped) if wrapped else decorator
@@ -384,7 +416,11 @@ class Module(EventListener, Broker):
 
     def should_be_injectable(self, wrapped: type = None, /):
         def decorator(wp):
-            self[wp] = ShouldBeInjectable(wp)
+            self.update(
+                (wp,),
+                ShouldBeInjectable(wp),
+                mode=InjectableMode.FALLBACK,
+            )
             return wp
 
         return decorator(wrapped) if wrapped else decorator
@@ -392,16 +428,16 @@ class Module(EventListener, Broker):
     def set_constant(
         self,
         instance: _T,
-        on: type | Types = None,
+        on: type | _Types = None,
         *,
-        override: bool = False,
+        mode: _Mode = InjectableMode.get_default(),
     ) -> _T:
         cls = type(instance)
         self.injectable(
             lambda: instance,
             inject=False,
             on=(cls, on),
-            override=override,
+            mode=mode,
         )
         return instance
 
@@ -428,7 +464,7 @@ class Module(EventListener, Broker):
 
         return decorator(wrapped) if wrapped else decorator
 
-    def get_instance(self, cls: type[_T], none: bool = True) -> _T | None:
+    def get_instance(self, cls: type[_T], *, none: bool = True) -> _T | None:
         try:
             injectable = self[cls]
         except KeyError as exc:
@@ -443,6 +479,7 @@ class Module(EventListener, Broker):
     def get_lazy_instance(
         self,
         cls: type[_T],
+        *,
         cache: bool = False,
     ) -> Invertible[_T | None]:
         if cache:
@@ -456,15 +493,16 @@ class Module(EventListener, Broker):
         self,
         classes: Iterable[type],
         injectable: Injectable,
-        override: bool = False,
+        mode: _Mode = InjectableMode.get_default(),
     ):
-        self.__container.update(classes, injectable, override)
+        self.__container.update(classes, injectable, mode)
         return self
 
     def use(
         self,
         module: Module,
-        priority: ModulePriority = ModulePriority.get_default(),
+        *,
+        priority: _Priority = ModulePriority.get_default(),
     ):
         if module is self:
             raise ModuleError("Module can't be used by itself.")
@@ -472,7 +510,8 @@ class Module(EventListener, Broker):
         if module in self.__modules:
             raise ModuleError(f"`{self}` already uses `{module}`.")
 
-        event = ModuleAdded(self, module)
+        priority = ModulePriority(priority)
+        event = ModuleAdded(self, module, priority)
 
         with self.notify(event):
             self.__modules[module] = None
@@ -495,13 +534,15 @@ class Module(EventListener, Broker):
     def use_temporarily(
         self,
         module: Module,
-        priority: ModulePriority = ModulePriority.get_default(),
+        *,
+        priority: _Priority = ModulePriority.get_default(),
     ) -> ContextManager | ContextDecorator:
-        self.use(module, priority)
+        self.use(module, priority=priority)
         yield
         self.stop_using(module)
 
-    def change_priority(self, module: Module, priority: ModulePriority):
+    def change_priority(self, module: Module, priority: _Priority):
+        priority = ModulePriority(priority)
         event = ModulePriorityUpdated(self, module, priority)
 
         with self.notify(event):
@@ -541,7 +582,7 @@ class Module(EventListener, Broker):
             raise ModuleLockError(f"`{self}` is locked.")
 
     def __move_module(self, module: Module, priority: ModulePriority):
-        last = priority == ModulePriority.LOW
+        last = priority != ModulePriority.HIGH
 
         try:
             self.__modules.move_to_end(module, last=last)
@@ -637,7 +678,8 @@ class InjectedFunction(EventListener):
     )
 
     def __init__(self, wrapped: Callable[..., Any], /):
-        update_wrapper(self, wrapped)
+        self.__update_vars_from(wrapped)
+        update_wrapper(self, wrapped, updated=())
         self.__dependencies = Dependencies.empty()
         self.__owner = None
         self.__setup_queue = LimitedQueue[Callable[[], Any]]()
@@ -727,3 +769,23 @@ class InjectedFunction(EventListener):
     def __set_signature(self):
         self.__signature__ = inspect.signature(self.wrapped, eval_str=True)
         return self
+
+    def __update_vars_from(self, obj: Any):
+        try:
+            variables = vars(obj)
+        except TypeError:
+            pass
+        else:
+            self.__update_vars(variables)
+
+    def __update_vars(self, variables: Mapping[str, Any]):
+        def is_dunder(var: str) -> bool:
+            return var.startswith("__") and var.endswith("__")
+
+        restricted_vars = frozenset(var for var in dir(self) if not is_dunder(var))
+        variables = (
+            (var, value)
+            for var, value in variables.items()
+            if var not in restricted_vars
+        )
+        vars(self).update(variables)

{python_injection-0.8.1.post0 → python_injection-0.8.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "python-injection"
-version = "0.8.1.post0"
+version = "0.8.3"
 description = "Fast and easy dependency injection framework."
 authors = ["remimd"]
 keywords = ["dependencies", "inject", "injection"]

python_injection-0.8.1.post0/injection/__init__.py

@@ -1 +0,0 @@
-from ._pkg import *