engin 0.0.20__py3-none-any.whl → 0.1.0__py3-none-any.whl

engin/_supervisor.py

@@ -0,0 +1,137 @@
+import inspect
+import logging
+import typing
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from enum import Enum
+from types import TracebackType
+from typing import TypeAlias, assert_never
+
+import anyio
+from anyio import get_cancelled_exc_class
+
+if typing.TYPE_CHECKING:
+    from anyio.abc import TaskGroup
+
+LOG = logging.getLogger("engin")
+
+TaskFactory: TypeAlias = Callable[[], Awaitable[None]]
+
+
+class OnException(Enum):
+    SHUTDOWN = 0
+    """
+    Cancel all other supervised tasks and shutdown the Engin.
+    """
+
+    RETRY = 1
+    """
+    Retry the task.
+    """
+
+    IGNORE = 2
+    """
+    The task will be not be retried and the engin will not be stopped, other tasks will
+    continue to run.
+    """
+
+
+@dataclass(kw_only=True, slots=True, eq=False)
+class _SupervisorTask:
+    """
+    Attributes:
+        - factory: a coroutine function that can create the task.
+        - on_exception: determines the behaviour when 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
+    on_exception: OnException
+    complete: bool = False
+    last_exception: Exception | None = None
+
+    async def __call__(self) -> None:
+        # loop to allow for restarting erroring tasks
+        while True:
+            try:
+                await self.factory()
+                self.complete = True
+                return
+            except get_cancelled_exc_class() as err:
+                LOG.debug(f"supervised task '{self.name}' was cancelled", exc_info=err)
+                raise
+            except Exception as err:
+                self.last_exception = err
+                if self.on_exception == OnException.IGNORE:
+                    LOG.warning(
+                        f"supervisor task '{self.name}' raised {type(err).__name__} "
+                        "which will be ignored",
+                        exc_info=err,
+                    )
+                    self.complete = True
+                    return
+                if self.on_exception == OnException.RETRY:
+                    LOG.warning(
+                        f"supervisor task '{self.name}' raised {type(err).__name__} "
+                        "which will be retried",
+                        exc_info=err,
+                    )
+                    continue
+                if self.on_exception == OnException.SHUTDOWN:
+                    LOG.error(
+                        f"supervisor task '{self.name}' raised {type(err).__name__}, "
+                        "starting shutdown",
+                        exc_info=err,
+                    )
+                    self.complete = True
+                    raise get_cancelled_exc_class() from None
+                assert_never(self.on_exception)
+
+    @property
+    def name(self) -> str:
+        factory = self.factory
+        if inspect.ismethod(factory):
+            return f"{factory.__self__.__class__.__name__}.{factory.__func__.__name__}"
+        if inspect.isclass(factory):
+            return type(factory).__name__
+        if inspect.isfunction(factory):
+            return factory.__name__
+        return str(factory)
+
+
+class Supervisor:
+    def __init__(self) -> None:
+        self._tasks: list[_SupervisorTask] = []
+        self._task_group: TaskGroup | None = None
+
+    def supervise(
+        self, func: TaskFactory, *, on_exception: OnException = OnException.SHUTDOWN
+    ) -> None:
+        self._tasks.append(_SupervisorTask(factory=func, on_exception=on_exception))
+
+    @property
+    def empty(self) -> bool:
+        return not self._tasks
+
+    async def __aenter__(self) -> None:
+        if not self._tasks:
+            return
+
+        self._task_group = await anyio.create_task_group().__aenter__()
+
+        for task in self._tasks:
+            LOG.info(f"supervising task: {task.name}")
+            self._task_group.start_soon(task, name=task.name)
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+        /,
+    ) -> None:
+        if self._task_group:
+            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/exceptions.py

@@ -1,6 +1,7 @@
 from typing import TYPE_CHECKING, Any
 
 from engin._dependency import Provide
+from engin._type_utils import TypeId
 
 if TYPE_CHECKING:
     from engin._block import Block
@@ -12,12 +13,6 @@ class EnginError(Exception):
     """
 
 
-class AssemblerError(EnginError):
-    """
-    Base class for all custom exceptions raised by the Assembler.
-    """
-
-
 class InvalidBlockError(EnginError):
     """
     Raised when an invalid block is instantiated.
@@ -32,6 +27,25 @@ class InvalidBlockError(EnginError):
         return self.message
 
 
+class AssemblerError(EnginError):
+    """
+    Base class for all custom exceptions raised by the Assembler.
+    """
+
+
+class TypeNotProvidedError(AssemblerError):
+    """
+    Raised when the Assembler cannot assemble a type due to a missing Provider.
+    """
+
+    def __init__(self, type_id: TypeId) -> None:
+        self.type_id = type_id
+        self.message = f"no provider found for '{type_id}'"
+
+    def __str__(self) -> str:
+        return self.message
+
+
 class ProviderError(AssemblerError):
     """
     Raised when a Provider errors during Assembly.
@@ -77,4 +91,5 @@ __all__ = [
     "InvalidBlockError",
     "NotInScopeError",
     "ProviderError",
+    "TypeNotProvidedError",
 ]

engin/extensions/asgi.py

@@ -21,6 +21,8 @@ class ASGIType(Protocol):
 
 
 class ASGIEngin(Engin, ASGIType):
+    _STOP_ON_SINGAL = False  # web server implementation is responsible for this
+
     _asgi_type: ClassVar[type[ASGIType]] = ASGIType  # type: ignore[type-abstract]
     _asgi_app: ASGIType
 

engin/extensions/fastapi.py

@@ -24,12 +24,12 @@ except ImportError as err:
 __all__ = ["APIRouteDependency", "FastAPIEngin", "Inject"]
 
 
-def _attach_assembler(app: FastAPI, engin: Engin) -> None:
+def _attach_assembler(app: FastAPI, assembler: Assembler) -> None:
     """
     An invocation that attaches the Engin's Assembler to the FastAPI application, enabling
     the Inject marker.
     """
-    app.state.assembler = engin.assembler
+    app.state.assembler = assembler
 
 
 class FastAPIEngin(ASGIEngin):

engin-0.1.0.dist-info/METADATA

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: engin
+Version: 0.1.0
+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
+License-Expression: MIT
+License-File: LICENSE
+Keywords: Application Framework,Dependency Injection
+Requires-Python: >=3.10
+Requires-Dist: anyio>=4
+Requires-Dist: exceptiongroup>=1
+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 🏎️
+
+[![codecov](https://codecov.io/gh/invokermain/engin/graph/badge.svg?token=4PJOIMV6IB)](https://codecov.io/gh/invokermain/engin)
+
+---
+
+**Documentation**: [https://engin.readthedocs.io/](https://engin.readthedocs.io/)
+
+**Source Code**: [https://github.com/invokermain/engin](https://github.com/invokermain/engin)
+
+---
+
+Engin is a lightweight application framework powered by dependency injection, it helps
+you build and maintain large monoliths and many microservices.
+
+
+## Feature
+
+The Engin framework gives you:
+
+- A fully-featured dependency injection system.
+- A robust application runtime with lifecycle hooks and supervised background tasks.
+- Zero boilerplate code reuse across applications.
+- Integrations for other frameworks such as FastAPI.
+- Full async support.
+- CLI commands to aid local development.
+
+
+## Installation
+
+Engin is available on PyPI, install it using your favourite dependency manager:
+
+- `pip install engin`
+- `poetry add engin`
+- `uv add engin`
+
+## Example
+
+A small example which shows some of the features of Engin. This application
+makes 3 http requests and shuts itself down.
+
+```python
+import asyncio
+from httpx import AsyncClient
+from engin import Engin, Invoke, Lifecycle, OnException, Provide, Supervisor
+
+
+def httpx_client_factory(lifecycle: Lifecycle) -> AsyncClient:
+    # create our http client
+    client = AsyncClient()
+    # this will open and close the AsyncClient as part of the application's lifecycle
+    lifecycle.append(client)
+    return client
+
+
+async def main(
+    httpx_client: AsyncClient,
+    supervisor: Supervisor,
+) -> None:
+    async def http_requests_task():
+        # simulate a background task
+        for x in range(3):
+            await httpx_client.get("https://httpbin.org/get")
+            await asyncio.sleep(1.0)
+        # raise an error to shutdown the application, normally you wouldn't do this!
+        raise RuntimeError("Forcing shutdown")
+
+    # supervise the http requests as part of the application's lifecycle
+    supervisor.supervise(http_requests_task, on_exception=OnException.SHUTDOWN)
+
+
+# define our modular application
+engin = Engin(Provide(httpx_client_factory), Invoke(main))
+
+# run it!
+asyncio.run(engin.run())
+```
+
+With logs enabled this will output:
+
+```shell
+INFO:engin:starting engin
+INFO:engin:startup complete
+INFO:httpx:HTTP Request: GET https://httpbin.org/get "HTTP/1.1 200 OK"
+INFO:httpx:HTTP Request: GET https://httpbin.org/get "HTTP/1.1 200 OK"
+INFO:httpx:HTTP Request: GET https://httpbin.org/get "HTTP/1.1 200 OK"
+ERROR:engin:supervisor task 'http_requests_task' raised RuntimeError, starting shutdown
+Traceback (most recent call last):
+  File "C:\dev\python\engin\src\engin\_supervisor.py", line 58, in __call__
+    await self.factory()
+  File "C:\dev\python\engin\readme_example.py", line 29, in http_requests_task
+    raise RuntimeError("Forcing shutdown")
+RuntimeError: Forcing shutdown
+INFO:engin:stopping engin
+INFO:engin:shutdown complete
+```
+
+## Inspiration
+
+Engin is heavily inspired by [Uber's Fx framework for Go](https://github.com/uber-go/fx)
+and the [Injector framework for Python](https://github.com/python-injector/injector).
+
+They are both great projects, go check them out.

engin-0.1.0.dist-info/RECORD

@@ -0,0 +1,27 @@
+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=xINk3sudxzsTmkUkNAKQwzBc0G0DfhpnrZli4z3ALBY,9459
+engin/_engin.py,sha256=1bgZmdmRlwHIZ9pz5rysYgvFu5s8e0gzlc9iq-Of97c,9651
+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/_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.1.0.dist-info/METADATA,sha256=Eny-piAImwQB6Ij3djngjTqvg0ILyGlbr9aprE28bNE,3947
+engin-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+engin-0.1.0.dist-info/entry_points.txt,sha256=sW247zZUMxm0b5UKYvPuqQQljYDtU-j2zK3cu7gHwM0,41
+engin-0.1.0.dist-info/licenses/LICENSE,sha256=XHh5LPUPKZWTBqBv2xxN2RU7D59nHoiJGb5RIt8f45w,1070
+engin-0.1.0.dist-info/RECORD,,

engin-0.0.20.dist-info/METADATA

@@ -1,71 +0,0 @@
-Metadata-Version: 2.4
-Name: engin
-Version: 0.0.20
-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
-License-Expression: MIT
-License-File: LICENSE
-Keywords: Application Framework,Dependency Injection
-Requires-Python: >=3.10
-Provides-Extra: cli
-Requires-Dist: typer>=0.15; extra == 'cli'
-Description-Content-Type: text/markdown
-
-[![codecov](https://codecov.io/gh/invokermain/engin/graph/badge.svg?token=4PJOIMV6IB)](https://codecov.io/gh/invokermain/engin)
-
-# Engin 🏎️
-
-Engin is a zero-dependency application framework for modern Python.
-
-**Documentation**: https://engin.readthedocs.io/
-
-## Features ✨
-
-- **Dependency Injection** - Engin includes a fully-featured Dependency Injection system,
-  powered by type hints.
-- **Lifecycle Management** - Engin provides a simple & portable approach for attaching
-  startup and shutdown tasks to the application's lifecycle.
-- **Code Reuse** - Engin's modular components, called Blocks, work great as distributed
-  packages allowing zero boiler-plate code reuse across multiple applications. Perfect for
-  maintaining many services across your organisation.
-- **Ecosystem Compatability** - Engin ships with integrations for popular frameworks that
-  provide their own Dependency Injection, for example FastAPI, allowing you to integrate
-  Engin into existing code bases incrementally.
-- **Async Native**: Engin is an async framework, meaning first class support for async
-  dependencies. However Engin will happily run synchronous code as well.
-
-## Installation
-
-Engin is available on PyPI, install using your favourite dependency manager:
-
-- **pip**:`pip install engin`
-- **poetry**: `poetry add engin`
-- **uv**: `uv add engin`
-
-## Getting Started
-
-A minimal example:
-
-```python
-import asyncio
-
-from httpx import AsyncClient
-
-from engin import Engin, Invoke, Provide
-
-
-def httpx_client() -> AsyncClient:
-    return AsyncClient()
-
-
-async def main(http_client: AsyncClient) -> None:
-    print(await http_client.get("https://httpbin.org/get"))
-
-engin = Engin(Provide(httpx_client), Invoke(main))
-
-asyncio.run(engin.run())
-```
-

engin-0.0.20.dist-info/RECORD

@@ -1,25 +0,0 @@
-engin/__init__.py,sha256=A8TE_ci7idoR683535YoBrWZbYTgXXS-q7Y2y51nZ5M,486
-engin/_assembler.py,sha256=-ENSrXPMWacionIYrTSQO7th9DDBOPyAT8ybPbBRtQw,11318
-engin/_block.py,sha256=IacP4PoJKRhSQCbQSdoyCtmu362a4vj6qoUQKyaJwzI,3062
-engin/_dependency.py,sha256=xINk3sudxzsTmkUkNAKQwzBc0G0DfhpnrZli4z3ALBY,9459
-engin/_engin.py,sha256=yIpZdeqvm8hv0RxOV0veFuvyu9xQ054JSaeuUWwHdOQ,7380
-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/_type_utils.py,sha256=H3Tl-kJr2wY2RhaTXP9GrMqa2RsXMijHbjHKe1AxGmc,2276
-engin/exceptions.py,sha256=-VPwPReZb9YEIkrWMR9TW2K5HEwmHHgEO7QWH6wfV8c,1946
-engin/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-engin/_cli/__init__.py,sha256=koD5WTkZXb8QQIiVU5bJiSR1wwPGb5rv2iwd-v-BA7A,564
-engin/_cli/_common.py,sha256=zMYb1Bs1yUuR3qf3r6WuVozYzDwHJvTVthVbTQfTF9w,1261
-engin/_cli/_graph.html,sha256=rR5dnDKoz7KtSff0ERCi2UKuoH_Z03MRYiXI_W03G5k,2430
-engin/_cli/_graph.py,sha256=HMC91nWvTOr6_czPBNx1RU55Ib3qesJRCmbnL2DsdDk,4659
-engin/_cli/_inspect.py,sha256=0jm25d4wcbXVNJkyaeECSKY-irsxd-EIYBH1GDW_Yjc,3163
-engin/extensions/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-engin/extensions/asgi.py,sha256=d5Z6gtMVWDZdAlvrTaMt987sKyiq__A0X4gJQ7IETmA,3247
-engin/extensions/fastapi.py,sha256=e8F4L_nZ9dU9j8mb9lXKwJG6CTu5aIk4N5faRj4EyUA,6369
-engin-0.0.20.dist-info/METADATA,sha256=KiKW4DvikfKJJNzoXh7oC4RMdr02W0PkhtxXB8DN6bo,2354
-engin-0.0.20.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-engin-0.0.20.dist-info/entry_points.txt,sha256=sW247zZUMxm0b5UKYvPuqQQljYDtU-j2zK3cu7gHwM0,41
-engin-0.0.20.dist-info/licenses/LICENSE,sha256=XHh5LPUPKZWTBqBv2xxN2RU7D59nHoiJGb5RIt8f45w,1070
-engin-0.0.20.dist-info/RECORD,,