python-injection 0.10.2__tar.gz → 0.10.3__tar.gz

{python_injection-0.10.2 → python_injection-0.10.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: python-injection
-Version: 0.10.2
+Version: 0.10.3
 Summary: Fast and easy dependency injection framework.
 Home-page: https://github.com/100nm/python-injection
 License: MIT

{python_injection-0.10.2 → python_injection-0.10.3}/injection/__init__.py

@@ -1,12 +1,10 @@
-from ._core.module import Injectable, Module
-from ._core.module import Mode as InjectableMode
-from ._core.module import Priority as ModulePriority
+from ._core.module import Injectable, Mode, Module, Priority
 
 __all__ = (
     "Injectable",
-    "InjectableMode",
+    "Mode",
     "Module",
-    "ModulePriority",
+    "Priority",
     "constant",
     "find_instance",
     "get_instance",

{python_injection-0.10.2 → python_injection-0.10.3}/injection/__init__.pyi

@@ -16,8 +16,7 @@ from ._core.common.invertible import Invertible as _Invertible
 from ._core.common.type import InputType as _InputType
 from ._core.common.type import TypeInfo as _TypeInfo
 from ._core.module import InjectableFactory as _InjectableFactory
-from ._core.module import ModeStr as InjectableModeStr
-from ._core.module import PriorityStr as ModulePriorityStr
+from ._core.module import ModeStr, PriorityStr
 
 _: Module = ...
 
@@ -68,7 +67,7 @@ class Module:
         cls: _InjectableFactory[T] = ...,
         inject: bool = ...,
         on: _TypeInfo[T] = ...,
-        mode: InjectableMode | InjectableModeStr = ...,
+        mode: Mode | ModeStr = ...,
     ):
         """
         Decorator applicable to a class or function. It is used to indicate how the
@@ -83,7 +82,7 @@ class Module:
         *,
         inject: bool = ...,
         on: _TypeInfo[T] = ...,
-        mode: InjectableMode | InjectableModeStr = ...,
+        mode: Mode | ModeStr = ...,
     ):
         """
         Decorator applicable to a class or function. It is used to indicate how the
@@ -104,7 +103,7 @@ class Module:
         /,
         *,
         on: _TypeInfo[T] = ...,
-        mode: InjectableMode | InjectableModeStr = ...,
+        mode: Mode | ModeStr = ...,
     ):
         """
         Decorator applicable to a class or function. It is used to indicate how the
@@ -118,7 +117,7 @@ class Module:
         on: _TypeInfo[T] = ...,
         *,
         alias: bool = ...,
-        mode: InjectableMode | InjectableModeStr = ...,
+        mode: Mode | ModeStr = ...,
     ) -> Self:
         """
         Function for registering a specific instance to be injected. This is useful for
@@ -162,7 +161,7 @@ class Module:
         self,
         module: Module,
         *,
-        priority: ModulePriority | ModulePriorityStr = ...,
+        priority: Priority | PriorityStr = ...,
     ) -> Self:
         """
         Function for using another module. Using another module replaces the module's
@@ -179,7 +178,7 @@ class Module:
         self,
         module: Module,
         *,
-        priority: ModulePriority | ModulePriorityStr = ...,
+        priority: Priority | PriorityStr = ...,
     ) -> ContextManager[None] | ContextDecorator:
         """
         Context manager or decorator for temporary use of a module.
@@ -188,7 +187,7 @@ class Module:
     def change_priority(
         self,
         module: Module,
-        priority: ModulePriority | ModulePriorityStr,
+        priority: Priority | PriorityStr,
     ) -> Self:
         """
         Function for changing the priority of a module in use.
@@ -217,7 +216,7 @@ class Module:
         """
 
 @final
-class ModulePriority(Enum):
+class Priority(Enum):
     LOW = ...
     HIGH = ...
 
@@ -230,7 +229,7 @@ class Injectable[T](Protocol):
     def get_instance(self) -> T: ...
 
 @final
-class InjectableMode(Enum):
+class Mode(Enum):
     FALLBACK = ...
     NORMAL = ...
     OVERRIDE = ...

python_injection-0.10.3/injection/_core/__init__.py

@@ -0,0 +1,53 @@
+from collections.abc import Iterable
+from typing import Any
+
+from injection._core.common.type import InputType, standardize_types
+from injection._core.hook import HookGenerator
+from injection._core.module import Locator, Mode, Record, Updater
+
+__all__ = ()
+
+
+@Locator.static_hooks.on_conflict
+def check_mode[T](
+    new: Record[T],
+    existing: Record[T],
+    cls: InputType[T],
+    *_: Any,
+    **__: Any,
+) -> HookGenerator[bool]:
+    new_mode = new.mode
+    is_override = new_mode == Mode.OVERRIDE
+
+    if new_mode == existing.mode and not is_override:
+        raise RuntimeError(f"An injectable already exists for the class `{cls}`.")
+
+    value = yield
+    return value or is_override
+
+
+@Locator.static_hooks.on_conflict
+def compare_mode_rank[T](
+    new: Record[T],
+    existing: Record[T],
+    *_: Any,
+    **__: Any,
+) -> HookGenerator[bool]:
+    value = yield
+    return value or new.mode.rank > existing.mode.rank
+
+
+@Locator.static_hooks.on_input
+def standardize_input_classes[T](
+    *_: Any,
+    **__: Any,
+) -> HookGenerator[Iterable[InputType[T]]]:
+    classes = yield
+    return tuple(standardize_types(*classes, with_origin=True))
+
+
+@Locator.static_hooks.on_update
+def standardize_classes[T](*_: Any, **__: Any) -> HookGenerator[Updater[T]]:
+    updater = yield
+    updater.classes = set(standardize_types(*updater.classes))
+    return updater

{python_injection-0.10.2 → python_injection-0.10.3}/injection/_core/common/type.py

@@ -1,22 +1,34 @@
-from collections.abc import Callable, Iterable, Iterator
-from inspect import get_annotations, isfunction
-from types import UnionType
-from typing import (
-    Annotated,
-    Any,
-    TypeAliasType,
-    Union,
-    cast,
-    get_args,
-    get_origin,
-)
-
-type TypeDef[T] = type[T] | TypeAliasType
+from collections.abc import Awaitable, Callable, Iterable, Iterator
+from inspect import iscoroutinefunction, isfunction
+from types import GenericAlias, UnionType
+from typing import Annotated, Any, Union, get_args, get_origin, get_type_hints
+
+type TypeDef[T] = type[T] | GenericAlias
 type InputType[T] = TypeDef[T] | UnionType
 type TypeInfo[T] = InputType[T] | Callable[..., T] | Iterable[TypeInfo[T]]
 
 
-def analyze_types(
+def get_return_types(*args: TypeInfo[Any]) -> Iterator[InputType[Any]]:
+    for arg in args:
+        if isinstance(arg, Iterable) and not (
+            isinstance(arg, type | str) or isinstance(get_origin(arg), type)
+        ):
+            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:
+            yield arg  # type: ignore[misc]
+            continue
+
+        yield from get_return_types(*inner_args)
+
+
+def standardize_types(
     *types: InputType[Any],
     with_origin: bool = False,
 ) -> Iterator[TypeDef[Any]]:
@@ -40,23 +52,4 @@ def analyze_types(
 
             continue
 
-        yield from analyze_types(*inner_types, with_origin=with_origin)
-
-
-def get_return_types(*args: TypeInfo[Any]) -> Iterator[InputType[Any]]:
-    for arg in args:
-        if isinstance(arg, Iterable) and not (
-            isinstance(arg, type | str) or isinstance(get_origin(arg), type)
-        ):
-            inner_args = arg
-
-        elif isfunction(arg) and (
-            return_type := get_annotations(arg, eval_str=True).get("return")
-        ):
-            inner_args = (return_type,)
-
-        else:
-            yield cast(InputType[Any], arg)
-            continue
-
-        yield from get_return_types(*inner_args)
+        yield from standardize_types(*inner_types, with_origin=with_origin)

python_injection-0.10.3/injection/_core/hook.py

@@ -0,0 +1,96 @@
+import itertools
+from collections.abc import Callable, Generator, Iterator
+from dataclasses import dataclass, field
+from inspect import isclass, isgeneratorfunction
+from typing import Self
+
+from injection.exceptions import HookError
+
+type HookGenerator[T] = Generator[None, T, T]
+type HookFunction[**P, T] = Callable[P, T | HookGenerator[T]]
+
+
+@dataclass(eq=False, frozen=True, slots=True)
+class Hook[**P, T]:
+    __functions: list[HookFunction[P, T]] = field(
+        default_factory=list,
+        init=False,
+        repr=False,
+    )
+
+    def __call__(  # type: ignore[no-untyped-def]
+        self,
+        wrapped: HookFunction[P, T] | type[HookFunction[P, T]] | None = None,
+        /,
+    ):
+        def decorator(wp):  # type: ignore[no-untyped-def]
+            self.add(wp() if isclass(wp) else wp)
+            return wp
+
+        return decorator(wrapped) if wrapped else decorator
+
+    @property
+    def __stack(self) -> Iterator[HookFunction[P, T]]:
+        return iter(self.__functions)
+
+    def add(self, *functions: HookFunction[P, T]) -> Self:
+        self.__functions.extend(functions)
+        return self
+
+    @classmethod
+    def apply_several(cls, handler: Callable[P, T], *hooks: Self) -> Callable[P, T]:
+        stack = itertools.chain.from_iterable((hook.__stack for hook in hooks))
+        return cls.__apply_stack(handler, stack)
+
+    @classmethod
+    def __apply_function(
+        cls,
+        handler: Callable[P, T],
+        function: HookFunction[P, T],
+    ) -> Callable[P, T]:
+        if not isgeneratorfunction(function):
+            return function  # type: ignore[return-value]
+
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
+            hook = function(*args, **kwargs)
+
+            try:
+                next(hook)
+
+                try:
+                    value = handler(*args, **kwargs)
+                except BaseException as exc:
+                    hook.throw(exc)
+                else:
+                    hook.send(value)
+                    return value
+
+            except StopIteration as stop:
+                return stop.value
+
+            finally:
+                hook.close()
+
+            raise HookError("Missing return value.")
+
+        return wrapper
+
+    @classmethod
+    def __apply_stack(
+        cls,
+        handler: Callable[P, T],
+        stack: Iterator[HookFunction[P, T]],
+    ) -> Callable[P, T]:
+        for function in stack:
+            new_handler = cls.__apply_function(handler, function)
+            return cls.__apply_stack(new_handler, stack)
+
+        return handler
+
+
+def apply_hooks[**P, T](
+    handler: Callable[P, T],
+    hook: Hook[P, T],
+    *hooks: Hook[P, T],
+) -> Callable[P, T]:
+    return Hook.apply_several(handler, hook, *hooks)

{python_injection-0.10.2 → python_injection-0.10.3}/injection/_core/module.py

@@ -37,13 +37,8 @@ from injection._core.common.event import Event, EventChannel, EventListener
 from injection._core.common.invertible import Invertible, SimpleInvertible
 from injection._core.common.lazy import Lazy, LazyMapping
 from injection._core.common.threading import synchronized
-from injection._core.common.type import (
-    InputType,
-    TypeDef,
-    TypeInfo,
-    analyze_types,
-    get_return_types,
-)
+from injection._core.common.type import InputType, TypeInfo, get_return_types
+from injection._core.hook import Hook, apply_hooks
 from injection.exceptions import (
     InjectionError,
     ModuleError,
@@ -64,7 +59,7 @@ class LocatorEvent(Event, ABC):
 
 @dataclass(frozen=True, slots=True)
 class LocatorDependenciesUpdated[T](LocatorEvent):
-    classes: Collection[TypeDef[T]]
+    classes: Collection[InputType[T]]
     mode: Mode
 
     @override
@@ -206,6 +201,13 @@ class ShouldBeInjectable[T](Injectable[T]):
     def get_instance(self) -> NoReturn:
         raise InjectionError(f"`{self.cls}` should be an injectable.")
 
+    @classmethod
+    def from_callable(cls, callable: Callable[..., T]) -> Self:
+        if not isclass(callable):
+            raise TypeError(f"`{callable}` should be a class.")
+
+        return cls(callable)
+
 
 """
 Broker
@@ -255,22 +257,58 @@ class Mode(StrEnum):
 
 type ModeStr = Literal["fallback", "normal", "override"]
 
+type InjectableFactory[T] = Callable[[Callable[..., T]], Injectable[T]]
+
 
 class Record[T](NamedTuple):
     injectable: Injectable[T]
     mode: Mode
 
 
+@dataclass(repr=False, eq=False, kw_only=True, slots=True)
+class Updater[T]:
+    factory: Callable[..., T]
+    classes: Iterable[InputType[T]]
+    injectable_factory: InjectableFactory[T]
+    mode: Mode
+
+    def make_record(self) -> Record[T]:
+        injectable = self.injectable_factory(self.factory)
+        return Record(injectable, self.mode)
+
+
+class LocatorHooks[T](NamedTuple):
+    on_conflict: Hook[[Record[T], Record[T], InputType[T]], bool]
+    on_input: Hook[[Iterable[InputType[T]]], Iterable[InputType[T]]]
+    on_update: Hook[[Updater[T]], Updater[T]]
+
+    @classmethod
+    def default(cls) -> Self:
+        return cls(
+            on_conflict=Hook(),
+            on_input=Hook(),
+            on_update=Hook(),
+        )
+
+
 @dataclass(repr=False, frozen=True, slots=True)
 class Locator(Broker):
-    __records: dict[TypeDef[Any], Record[Any]] = field(default_factory=dict, init=False)
-    __channel: EventChannel = field(default_factory=EventChannel, init=False)
+    __records: dict[InputType[Any], Record[Any]] = field(
+        default_factory=dict,
+        init=False,
+    )
+    __channel: EventChannel = field(
+        default_factory=EventChannel,
+        init=False,
+    )
+
+    static_hooks: ClassVar[LocatorHooks[Any]] = LocatorHooks.default()
 
     @override
     def __getitem__[T](self, cls: InputType[T], /) -> Injectable[T]:
-        for analyzed_class in analyze_types(cls, with_origin=True):
+        for input_class in self.__standardize_inputs((cls,)):
             try:
-                record = self.__records[analyzed_class]
+                record = self.__records[input_class]
             except KeyError:
                 continue
 
@@ -281,8 +319,8 @@ class Locator(Broker):
     @override
     def __contains__(self, cls: InputType[Any], /) -> bool:
         return any(
-            analyzed_class in self.__records
-            for analyzed_class in analyze_types(cls, with_origin=True)
+            input_class in self.__records
+            for input_class in self.__standardize_inputs((cls,))
         )
 
     @property
@@ -292,21 +330,16 @@ class Locator(Broker):
 
     @property
     def __injectables(self) -> frozenset[Injectable[Any]]:
-        return frozenset(injectable for injectable, _ in self.__records.values())
+        return frozenset(record.injectable for record in self.__records.values())
 
     @synchronized()
-    def update[T](
-        self,
-        classes: Iterable[InputType[T]],
-        injectable: Injectable[T],
-        mode: Mode | ModeStr,
-    ) -> Self:
-        mode = Mode(mode)
-        record = Record(injectable, mode)
-        records = {cls: record for cls in self.__prepare_for_updating(classes, mode)}
+    def update[T](self, updater: Updater[T]) -> Self:
+        updater = self.__update_preprocessing(updater)
+        record = updater.make_record()
+        records = dict(self.__prepare_for_updating(updater.classes, record))
 
         if records:
-            event = LocatorDependenciesUpdated(self, records.keys(), mode)
+            event = LocatorDependenciesUpdated(self, records.keys(), record.mode)
 
             with self.dispatch(event):
                 self.__records.update(records)
@@ -331,29 +364,38 @@ class Locator(Broker):
     def __prepare_for_updating[T](
         self,
         classes: Iterable[InputType[T]],
-        mode: Mode,
-    ) -> Iterator[TypeDef[T]]:
-        rank = mode.rank
-
-        for cls in frozenset(analyze_types(*classes)):
+        record: Record[T],
+    ) -> Iterator[tuple[InputType[T], Record[T]]]:
+        for cls in classes:
             try:
-                record = self.__records[cls]
-
+                existing = self.__records[cls]
             except KeyError:
                 ...
-
             else:
-                current_mode = record.mode
+                if not self.__keep_new_record(record, existing, cls):
+                    continue
 
-                if mode == current_mode and mode != Mode.OVERRIDE:
-                    raise RuntimeError(
-                        f"An injectable already exists for the class `{cls}`."
-                    )
+            yield cls, record
 
-                elif rank < current_mode.rank:
-                    continue
+    def __keep_new_record[T](
+        self,
+        new: Record[T],
+        existing: Record[T],
+        cls: InputType[T],
+    ) -> bool:
+        return apply_hooks(
+            lambda *args, **kwargs: False,
+            self.static_hooks.on_conflict,
+        )(new, existing, cls)
 
-            yield cls
+    def __standardize_inputs[T](
+        self,
+        classes: Iterable[InputType[T]],
+    ) -> Iterable[InputType[T]]:
+        return apply_hooks(lambda c: c, self.static_hooks.on_input)(classes)
+
+    def __update_preprocessing[T](self, updater: Updater[T]) -> Updater[T]:
+        return apply_hooks(lambda u: u, self.static_hooks.on_update)(updater)
 
 
 """
@@ -372,8 +414,6 @@ class Priority(StrEnum):
 
 type PriorityStr = Literal["low", "high"]
 
-type InjectableFactory[T] = Callable[[Callable[..., T]], Injectable[T]]
-
 
 @dataclass(eq=False, frozen=True, slots=True)
 class Module(Broker, EventListener):
@@ -438,9 +478,14 @@ class Module(Broker, EventListener):
     ):
         def decorator(wp):  # type: ignore[no-untyped-def]
             factory = self.inject(wp, return_factory=True) if inject else wp
-            injectable = cls(factory)
             classes = get_return_types(wp, on)
-            self.update(classes, injectable, mode)
+            updater = Updater(
+                factory=factory,
+                classes=classes,
+                injectable_factory=cls,
+                mode=Mode(mode),
+            )
+            self.update(updater)
             return wp
 
         return decorator(wrapped) if wrapped else decorator
@@ -449,11 +494,13 @@ class Module(Broker, EventListener):
 
     def should_be_injectable[T](self, wrapped: type[T] | None = None, /):  # type: ignore[no-untyped-def]
         def decorator(wp):  # type: ignore[no-untyped-def]
-            self.update(
-                (wp,),
-                ShouldBeInjectable(wp),
+            updater = Updater(
+                factory=wp,
+                classes=(wp,),
+                injectable_factory=ShouldBeInjectable.from_callable,
                 mode=Mode.FALLBACK,
             )
+            self.update(updater)
             return wp
 
         return decorator(wrapped) if wrapped else decorator
@@ -543,13 +590,8 @@ class Module(Broker, EventListener):
         function.set_owner(cls)
         return SimpleInvertible(function)
 
-    def update[T](
-        self,
-        classes: Iterable[InputType[T]],
-        injectable: Injectable[T],
-        mode: Mode | ModeStr = Mode.get_default(),
-    ) -> Self:
-        self.__locator.update(classes, injectable, mode)
+    def update[T](self, updater: Updater[T]) -> Self:
+        self.__locator.update(updater)
         return self
 
     def init_modules(self, *modules: Module) -> Self:
@@ -881,11 +923,7 @@ class InjectedFunction[**P, T](EventListener):
         yield
         self.update(event.module)
 
-    @synchronized()
     def __close_setup_queue(self) -> None:
-        if self.__setup_queue is None:
-            return
-
         self.__setup_queue = None
 
     def __setup(self) -> None:

{python_injection-0.10.2 → python_injection-0.10.3}/injection/exceptions.py

@@ -1,11 +1,12 @@
 from typing import Any
 
 __all__ = (
+    "HookError",
     "InjectionError",
-    "NoInjectable",
     "ModuleError",
     "ModuleLockError",
     "ModuleNotUsedError",
+    "NoInjectable",
 )
 
 
@@ -33,3 +34,6 @@ class ModuleLockError(ModuleError): ...
 
 
 class ModuleNotUsedError(KeyError, ModuleError): ...
+
+
+class HookError(InjectionError): ...

{python_injection-0.10.2 → python_injection-0.10.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "python-injection"
-version = "0.10.2"
+version = "0.10.3"
 description = "Fast and easy dependency injection framework."
 license = "MIT"
 authors = ["remimd"]