engin 0.2.0a1__py3-none-any.whl → 0.2.1__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/_block.py

@@ -10,6 +10,8 @@ from engin.exceptions import InvalidBlockError
 if TYPE_CHECKING:
     from engin._engin import Engin
 
+_BUILTIN_CLASS_FUNCTIONS = ("__annotate_func__",)
+
 
 def provide(
     func_: Func | None = None, *, scope: str | None = None, override: bool = False
@@ -84,6 +86,8 @@ class Block:
     @classmethod
     def _method_options(cls) -> Iterable[Provide | Invoke]:
         for name, method in inspect.getmembers(cls, inspect.isfunction):
+            if name in _BUILTIN_CLASS_FUNCTIONS:
+                continue
             if option := getattr(method, "_opt", None):
                 if not isinstance(option, Provide | Invoke):
                     raise InvalidBlockError(

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

@@ -184,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.
@@ -198,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,10 +5,11 @@ 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

{engin-0.2.0a1.dist-info → engin-0.2.1.dist-info}/METADATA

@@ -1,20 +1,20 @@
 Metadata-Version: 2.4
 Name: engin
-Version: 0.2.0a1
-Summary: An async-first modular 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
-Project-URL: Changelog, https://github.com/invokermain/engin/blob/main/CHANGELOG.md
+Version: 0.2.1
+Summary: A dependency-injection powered application framework
+Keywords: Dependency Injection,Application Framework
 License-Expression: MIT
-License-File: LICENSE
-Keywords: Application Framework,Dependency Injection
-Requires-Python: >=3.10
 Requires-Dist: anyio>=4
 Requires-Dist: exceptiongroup>=1
+Requires-Dist: typing-extensions>=4
+Requires-Dist: typer>=0.15 ; extra == 'cli'
+Requires-Dist: tomli>=2.0 ; python_full_version < '3.11' and extra == 'cli'
+Requires-Python: >=3.10
+Project-URL: Changelog, https://github.com/invokermain/engin/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://engin.readthedocs.io/en/latest/
+Project-URL: Homepage, https://github.com/invokermain/engin
+Project-URL: Repository, https://github.com/invokermain/engin.git
 Provides-Extra: cli
-Requires-Dist: tomli>=2.0; (python_version < '3.11') and extra == 'cli'
-Requires-Dist: typer>=0.15; extra == 'cli'
 Description-Content-Type: text/markdown
 
 # Engin 🏎️
@@ -29,11 +29,11 @@ Description-Content-Type: text/markdown
 
 ---
 
-Engin is a lightweight application framework powered by dependency injection, it helps
-you build and maintain large monoliths and many microservices.
+Engin is a lightweight application framework powered by dependency injection. It helps
+you build and maintain everything from large monoliths to hundreds of microservices.
 
 
-## Feature
+## Features
 
 The Engin framework gives you:
 
@@ -120,3 +120,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.2.0a1.dist-info → engin-0.2.1.dist-info}/RECORD

@@ -1,27 +1,26 @@
 engin/__init__.py,sha256=O0vS570kZFBq7Kwy4FgeJFIhfo4aIg5mv_Z_9vAQRio,577
-engin/_assembler.py,sha256=0uXgtcO5M3EHg0I-TQK9y7LOzfxkLFmKia-zLyVHaxA,11178
-engin/_block.py,sha256=IacP4PoJKRhSQCbQSdoyCtmu362a4vj6qoUQKyaJwzI,3062
-engin/_dependency.py,sha256=Ie-z0obe7Ut6TF1O7BjP3Z7i216ufKqSeT_D82krdAc,9615
-engin/_engin.py,sha256=1bgZmdmRlwHIZ9pz5rysYgvFu5s8e0gzlc9iq-Of97c,9651
+engin/_assembler.py,sha256=Afi9i5wcbhbzqhJlCB_oa9LcR6RMYaQoR40JfSfnuGo,12235
+engin/_block.py,sha256=Rwcpg9j_-tVd0lNJJYZOBgFi0cNKOJ_04MZzMIk9hAc,3187
+engin/_cli/__init__.py,sha256=Ixk3NoZeIN8Bj53I625uqJdLyyT9Gpbe_4GtNy-KQwM,636
+engin/_cli/_check.py,sha256=w9GA9RmCgSflvSU7EQqXKiOCqgrZB-pLS_UoJOqV56E,1666
+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/_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=WGio-mfPHo2Wdfqo5ZB66WAoAU2ey0urwM0Dl4vRUTA,4824
+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/_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.2.0a1.dist-info/METADATA,sha256=OntxY2pdrpJuvpqb-zvj2SJwpohHmEjbjLmqc7w1zqE,3949
-engin-0.2.0a1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-engin-0.2.0a1.dist-info/entry_points.txt,sha256=sW247zZUMxm0b5UKYvPuqQQljYDtU-j2zK3cu7gHwM0,41
-engin-0.2.0a1.dist-info/licenses/LICENSE,sha256=XHh5LPUPKZWTBqBv2xxN2RU7D59nHoiJGb5RIt8f45w,1070
-engin-0.2.0a1.dist-info/RECORD,,
+engin/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+engin-0.2.1.dist-info/WHEEL,sha256=ZbtZh9LqsQoZs-WmwRO6z-tavdkb5LzNxvrOv2F_OXE,78
+engin-0.2.1.dist-info/entry_points.txt,sha256=MpK_1W7JQVbtK2hJ0ehBWQG2O6C5m_HVIAhC_LpGmv0,42
+engin-0.2.1.dist-info/METADATA,sha256=l92ASKlLENk4-Ng1yVV-Nw8Fq83q-DvcD8VtmRoFd_0,4128
+engin-0.2.1.dist-info/RECORD,,

engin-0.2.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.9.1
+Root-Is-Purelib: true
+Tag: py3-none-any

{engin-0.2.0a1.dist-info → engin-0.2.1.dist-info}/entry_points.txt

@@ -1,2 +1,3 @@
 [console_scripts]
 engin = engin._cli:app
+

engin-0.2.0a1.dist-info/WHEEL

@@ -1,4 +0,0 @@
-Wheel-Version: 1.0
-Generator: hatchling 1.27.0
-Root-Is-Purelib: true
-Tag: py3-none-any

engin-0.2.0a1.dist-info/licenses/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2024 Tim OSullivan
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.