engin 0.1.0rc3__py3-none-any.whl → 0.2.0__py3-none-any.whl

engin/_assembler.py

@@ -8,6 +8,8 @@ from inspect import BoundArguments, Signature
 from types import TracebackType
 from typing import Any, Generic, TypeVar, cast
 
+from typing_extensions import Self
+
 from engin._dependency import Dependency, Provide, Supply
 from engin._type_utils import TypeId
 from engin.exceptions import NotInScopeError, ProviderError, TypeNotProvidedError
@@ -76,6 +78,34 @@ class Assembler:
             else:
                 self._multiproviders[type_id].append(provider)
 
+    @classmethod
+    def from_mapped_providers(
+        cls,
+        providers: dict[TypeId, Provide[Any]],
+        multiproviders: dict[TypeId, list[Provide[list[Any]]]],
+    ) -> Self:
+        """
+        Create an Assembler from pre-mapped providers.
+
+        This method is only exposed for performance reasons in the case that Providers
+        have already been mapped, it is recommended to use the `__init__` method if this
+        is no the case.
+
+        Args:
+            providers: a dictionary of Providers with the Provider's `return_type_id` as
+              the key.
+            multiproviders: a dictionary of list of Providers with the Provider's
+              `return_type_id` as key. All Providers in the given list must be for the
+              related `return_type_id`.
+
+        Returns:
+            An Assembler instance.
+        """
+        assembler = cls(tuple())  # noqa: C408
+        assembler._providers = providers
+        assembler._multiproviders = multiproviders
+        return assembler
+
     @property
     def providers(self) -> Sequence[Provide[Any]]:
         multi_providers = [p for multi in self._multiproviders.values() for p in multi]

engin/_cli/_common.py

@@ -1,11 +1,11 @@
 import importlib
 import sys
 from pathlib import Path
-from typing import Never
 
 import typer
 from rich import print
 from rich.panel import Panel
+from typing_extensions import Never
 
 from engin import Engin
 

engin/_dependency.py

@@ -171,6 +171,9 @@ class Provide(Dependency[Any, T]):
             override: (optional) allow this provider to override other providers for the
                 same type from the same package.
         """
+        if not callable(factory):
+            msg = "Provided value is not callable, did you mean to use Supply instead?"
+            raise ValueError(msg)
         super().__init__(func=factory)
         self._scope = scope
         self._override = override
@@ -181,7 +184,9 @@ class Provide(Dependency[Any, T]):
         if self._explicit_type is not None:
             self._signature = self._signature.replace(return_annotation=self._explicit_type)
 
-        self._is_multi = typing.get_origin(self._return_type) is list
+        self._is_multi = (
+            typing.get_origin(self._return_type) is list or self._return_type is list
+        )
 
         # Validate that the provider does to depend on its own output value, as this will
         # cause a recursion error and is undefined behaviour wise.
@@ -195,9 +200,11 @@ class Provide(Dependency[Any, T]):
         if self._is_multi:
             args = typing.get_args(self._return_type)
             if len(args) != 1:
-                raise ValueError(
-                    f"A multiprovider must be of the form list[X], not '{self._return_type}'"
+                msg = (
+                    "A multiprovider must be of the form list[X], not "
+                    f"'{self._return_type_id}'"
                 )
+                raise ValueError(msg)
 
     @property
     def return_type(self) -> type[T]:

engin/_engin.py

@@ -1,14 +1,14 @@
 import asyncio
 import logging
-import os
 import signal
+import sys
 from asyncio import Event
 from collections import defaultdict
 from contextlib import AsyncExitStack
 from enum import Enum
 from itertools import chain
 from types import FrameType
-from typing import ClassVar
+from typing import TYPE_CHECKING, ClassVar
 
 from anyio import create_task_group, open_signal_receiver
 
@@ -18,10 +18,12 @@ from engin._graph import DependencyGrapher, Node
 from engin._lifecycle import Lifecycle
 from engin._option import Option
 from engin._supervisor import Supervisor
-from engin._type_utils import TypeId
 from engin.exceptions import EnginError
 
-_OS_IS_WINDOWS = os.name == "nt"
+if TYPE_CHECKING:
+    from engin._type_utils import TypeId
+
+_OS_IS_WINDOWS = sys.platform == "win32"
 LOG = logging.getLogger("engin")
 
 
@@ -107,12 +109,9 @@ class Engin:
         self._stop_requested_event = Event()
         self._stop_complete_event = Event()
         self._exit_stack = AsyncExitStack()
-        self._assembler = Assembler([])
         self._async_context_run_task: asyncio.Task | None = None
 
-        self._providers: dict[TypeId, Provide] = {
-            TypeId.from_type(Assembler): Supply(self._assembler),
-        }
+        self._providers: dict[TypeId, Provide] = {}
         self._multiproviders: dict[TypeId, list[Provide]] = defaultdict(list)
         self._invocations: list[Invoke] = []
 
@@ -120,10 +119,12 @@ class Engin:
         for option in chain(self._LIB_OPTIONS, options):
             option.apply(self)
 
-        multi_providers = [p for multi in self._multiproviders.values() for p in multi]
-
-        for provider in chain(self._providers.values(), multi_providers):
-            self._assembler.add(provider)
+        # initialise Assembler
+        self._assembler = Assembler.from_mapped_providers(
+            providers=self._providers,
+            multiproviders=self._multiproviders,
+        )
+        self._assembler.add(Supply(self._assembler))
 
     @property
     def assembler(self) -> Assembler:
@@ -253,29 +254,37 @@ class Engin:
 async def _stop_engin_on_signal(stop_requested_event: Event) -> None:
     """
     A task that waits for a stop signal (SIGINT/SIGTERM) and notifies the given event.
+
+    On unix-like systems we can use asyncio's `loop.add_signal_handler` method but this
+    does not work on Windows as `signal.set_wakeup_fd` is not supported.
+
+    Therefore on Windows we fallback to using `signal.signal` directly.
     """
     if not _OS_IS_WINDOWS:
-        with open_signal_receiver(signal.SIGINT, signal.SIGTERM) as recieved_signals:
-            async for signum in recieved_signals:
-                LOG.debug(f"received {signum.name} signal")
+        with open_signal_receiver(signal.SIGINT, signal.SIGTERM) as received_signals:
+            async for signum in received_signals:
+                LOG.debug(f"received signal: {signum.name}")
                 stop_requested_event.set()
+                break
     else:
-        should_stop = False
 
-        # windows does not support signal_handlers, so this is the workaround
         def ctrlc_handler(sig: int, frame: FrameType | None) -> None:
-            LOG.debug(f"received {signal.SIGINT.name} signal")
-            nonlocal should_stop
-            if should_stop:
+            LOG.debug(f"received signal: {signal.Signals(sig).name}")
+            if stop_requested_event.is_set():
                 raise KeyboardInterrupt("Forced keyboard interrupt")
-            should_stop = True
+            else:
+                stop_requested_event.set()
 
-        signal.signal(signal.SIGINT, ctrlc_handler)
+        previous_signal_handler_sigint = signal.signal(signal.SIGINT, ctrlc_handler)
 
-        while not should_stop:
-            # In case engin is stopped via external `stop` call.
-            if stop_requested_event.is_set():
-                return
-            await asyncio.sleep(0.1)
+        # technically not needed due to the _OS_IS_WINDOWS checks but keeps mypy happy
+        if hasattr(signal, "SIGBREAK"):
+            previous_signal_handler_sigbreak = signal.signal(signal.SIGBREAK, ctrlc_handler)
 
-        stop_requested_event.set()
+        try:
+            await stop_requested_event.wait()
+        finally:
+            # restore orginal signal handlers
+            signal.signal(signal.SIGINT, previous_signal_handler_sigint)
+            if hasattr(signal, "SIGBREAK"):
+                signal.signal(signal.SIGBREAK, previous_signal_handler_sigbreak)

engin/_supervisor.py

@@ -5,17 +5,18 @@ from collections.abc import Awaitable, Callable
 from dataclasses import dataclass
 from enum import Enum
 from types import TracebackType
-from typing import TypeAlias, assert_never
+from typing import TypeAlias
 
 import anyio
 from anyio import get_cancelled_exc_class
+from typing_extensions import assert_never
 
 if typing.TYPE_CHECKING:
     from anyio.abc import TaskGroup
 
 LOG = logging.getLogger("engin")
 
-TaskFactory: TypeAlias = Callable[[], Awaitable[None]]
+AsyncFunction: TypeAlias = Callable[[], Awaitable[None]]
 
 
 class OnException(Enum):
@@ -41,15 +42,16 @@ class _SupervisorTask:
     """
     Attributes:
         - factory: a coroutine function that can create the task.
-        - on_exception: determines the behaviour when task raises an exception.
+        - on_exception: determines the behaviour when the task raises an exception.
         - complete: will be set to true if task stops for any reason except cancellation.
         - last_exception: the last exception raised by the task.
     """
 
-    factory: TaskFactory
+    factory: AsyncFunction
     on_exception: OnException
     complete: bool = False
     last_exception: Exception | None = None
+    shutdown_hook: AsyncFunction | None = None
 
     async def __call__(self) -> None:
         # loop to allow for restarting erroring tasks
@@ -106,9 +108,17 @@ class Supervisor:
         self._task_group: TaskGroup | None = None
 
     def supervise(
-        self, func: TaskFactory, *, on_exception: OnException = OnException.SHUTDOWN
+        self,
+        func: AsyncFunction,
+        *,
+        on_exception: OnException = OnException.SHUTDOWN,
+        shutdown_hook: AsyncFunction | None = None,
     ) -> None:
-        self._tasks.append(_SupervisorTask(factory=func, on_exception=on_exception))
+        self._tasks.append(
+            _SupervisorTask(
+                factory=func, on_exception=on_exception, shutdown_hook=shutdown_hook
+            )
+        )
 
     @property
     def empty(self) -> bool:
@@ -132,6 +142,10 @@ class Supervisor:
         /,
     ) -> None:
         if self._task_group:
+            for task in self._tasks:
+                if task.shutdown_hook is not None:
+                    LOG.debug(f"supervised task shutdown hook: {task.name}")
+                    await task.shutdown_hook()
             if not self._task_group.cancel_scope.cancel_called:
                 self._task_group.cancel_scope.cancel()
             await self._task_group.__aexit__(exc_type, exc_value, traceback)

{engin-0.1.0rc3.dist-info → engin-0.2.0.dist-info}/METADATA

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: engin
-Version: 0.1.0rc3
-Summary: An async-first modular application framework
+Version: 0.2.0
+Summary: A dependency-injection powered application framework
 Project-URL: Homepage, https://github.com/invokermain/engin
 Project-URL: Documentation, https://engin.readthedocs.io/en/latest/
 Project-URL: Repository, https://github.com/invokermain/engin.git
@@ -12,6 +12,7 @@ Keywords: Application Framework,Dependency Injection
 Requires-Python: >=3.10
 Requires-Dist: anyio>=4
 Requires-Dist: exceptiongroup>=1
+Requires-Dist: typing-extensions>=4
 Provides-Extra: cli
 Requires-Dist: tomli>=2.0; (python_version < '3.11') and extra == 'cli'
 Requires-Dist: typer>=0.15; extra == 'cli'
@@ -33,13 +34,13 @@ Engin is a lightweight application framework powered by dependency injection, it
 you build and maintain large monoliths and many microservices.
 
 
-## Feature
+## Features
 
 The Engin framework gives you:
 
 - A fully-featured dependency injection system.
 - A robust application runtime with lifecycle hooks and supervised background tasks.
-- Zero boiler-plate code reuse across applications.
+- Zero boilerplate code reuse across applications.
 - Integrations for other frameworks such as FastAPI.
 - Full async support.
 - CLI commands to aid local development.
@@ -120,3 +121,8 @@ Engin is heavily inspired by [Uber's Fx framework for Go](https://github.com/ube
 and the [Injector framework for Python](https://github.com/python-injector/injector).
 
 They are both great projects, go check them out.
+
+## Benchmarks
+
+Automated benchmarks for the Engin framework can be viewed
+[here](https://invokermain.github.io/engin/dev/bench/).

{engin-0.1.0rc3.dist-info → engin-0.2.0.dist-info}/RECORD

@@ -1,27 +1,27 @@
 engin/__init__.py,sha256=O0vS570kZFBq7Kwy4FgeJFIhfo4aIg5mv_Z_9vAQRio,577
-engin/_assembler.py,sha256=0uXgtcO5M3EHg0I-TQK9y7LOzfxkLFmKia-zLyVHaxA,11178
+engin/_assembler.py,sha256=Afi9i5wcbhbzqhJlCB_oa9LcR6RMYaQoR40JfSfnuGo,12235
 engin/_block.py,sha256=IacP4PoJKRhSQCbQSdoyCtmu362a4vj6qoUQKyaJwzI,3062
-engin/_dependency.py,sha256=xINk3sudxzsTmkUkNAKQwzBc0G0DfhpnrZli4z3ALBY,9459
-engin/_engin.py,sha256=1bgZmdmRlwHIZ9pz5rysYgvFu5s8e0gzlc9iq-Of97c,9651
+engin/_dependency.py,sha256=Z2eS-w_5TM_JgnOtrzCbwtQT6yGmkg-o0-zG02Nk1XU,9722
+engin/_engin.py,sha256=ip4kazNp7pz7tLLi2jFwFJ7oCLLC9bj0p3sWU0EE0dA,10129
 engin/_graph.py,sha256=y1g7Lm_Zy5GPEgRsggCKV5DDaDzcwUl8v3IZCK8jyGI,1631
 engin/_introspect.py,sha256=VdREX6Lhhga5SnEP9G7mjHkgJR4mpqk_SMnmL2zTcqY,966
 engin/_lifecycle.py,sha256=cSWe3euZkmpxmUPFvph2lsTtvuZbxttEfBL-RnOI7lo,5325
 engin/_option.py,sha256=nZcdrehp1QwgxMUoIpsM0PJuu1q1pbXzhcVsetbsHpc,223
-engin/_supervisor.py,sha256=nRz8GMFBJ5dAzMBO94HL_U1W2c89ZXg_LPeoD4H-s-4,4397
+engin/_supervisor.py,sha256=E7bGOGP11qIcbueMUkn-felJdP_bLMJmTBrenQtNdTU,4853
 engin/_type_utils.py,sha256=H3Tl-kJr2wY2RhaTXP9GrMqa2RsXMijHbjHKe1AxGmc,2276
 engin/exceptions.py,sha256=lSMOJI4Yl-VIM0yDzFWbPhC0mQm4f0WvGULr9SldIaY,2353
 engin/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 engin/_cli/__init__.py,sha256=Ixk3NoZeIN8Bj53I625uqJdLyyT9Gpbe_4GtNy-KQwM,636
 engin/_cli/_check.py,sha256=w9GA9RmCgSflvSU7EQqXKiOCqgrZB-pLS_UoJOqV56E,1666
-engin/_cli/_common.py,sha256=6tyjxAkROCViw0LOFdx-X1U-iSXKyeW5CoE9UxWRybI,3282
+engin/_cli/_common.py,sha256=dY9YEqoo1yNIZNPptM-GZjU1LaPcnkSqmIUcWkSii54,3293
 engin/_cli/_graph.html,sha256=5Dw5eyhsrU8KrpdhGn1mxo5kTUTJLMSzT-MBKvSv13g,29073
 engin/_cli/_graph.py,sha256=MsxsNpL1v0v1AUT57ZS97l1diwacqRaPdVBObHHIGJE,6753
 engin/_cli/_inspect.py,sha256=_uzldpHA51IX4srpUGzL4lZNiepqucsO9M3Zo83XBBM,3159
 engin/extensions/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 engin/extensions/asgi.py,sha256=7vQFaVs1jxq1KbhHGN8k7x2UFab6SPUq2_hXfX6HiXU,3329
 engin/extensions/fastapi.py,sha256=7N6i-eZUEZRPo7kcvjS7kbRSY5QAPyKJXSeongSQ-OA,6371
-engin-0.1.0rc3.dist-info/METADATA,sha256=T_BJ7UppMFU5rbi9xCRaqBIrSUvoQChxBF3bVsDGVrM,3951
-engin-0.1.0rc3.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-engin-0.1.0rc3.dist-info/entry_points.txt,sha256=sW247zZUMxm0b5UKYvPuqQQljYDtU-j2zK3cu7gHwM0,41
-engin-0.1.0rc3.dist-info/licenses/LICENSE,sha256=XHh5LPUPKZWTBqBv2xxN2RU7D59nHoiJGb5RIt8f45w,1070
-engin-0.1.0rc3.dist-info/RECORD,,
+engin-0.2.0.dist-info/METADATA,sha256=RtzssuxOEpDcTkl_eMXR_-utl6UMq7Ey-ayQgpUrVtw,4123
+engin-0.2.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+engin-0.2.0.dist-info/entry_points.txt,sha256=sW247zZUMxm0b5UKYvPuqQQljYDtU-j2zK3cu7gHwM0,41
+engin-0.2.0.dist-info/licenses/LICENSE,sha256=XHh5LPUPKZWTBqBv2xxN2RU7D59nHoiJGb5RIt8f45w,1070
+engin-0.2.0.dist-info/RECORD,,