engin 0.1a1__py3-none-any.whl → 0.1.0b2__py3-none-any.whl

engin/__init__.py

@@ -4,7 +4,6 @@ from engin._dependency import Entrypoint, Invoke, Provide, Supply
 from engin._engin import Engin
 from engin._lifecycle import Lifecycle
 from engin._option import Option
-from engin._shutdown import ShutdownSwitch
 from engin._supervisor import OnException, Supervisor
 from engin._type_utils import TypeId
 
@@ -18,7 +17,6 @@ __all__ = [
     "OnException",
     "Option",
     "Provide",
-    "ShutdownSwitch",
     "Supervisor",
     "Supply",
     "TypeId",

engin/_engin.py

@@ -2,28 +2,46 @@ import asyncio
 import logging
 import os
 import signal
-from asyncio import Event, Task
+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 anyio import CancelScope, create_task_group, get_cancelled_exc_class
+from anyio import create_task_group, get_cancelled_exc_class
 
 from engin._assembler import AssembledDependency, Assembler
 from engin._dependency import Invoke, Provide, Supply
 from engin._graph import DependencyGrapher, Node
 from engin._lifecycle import Lifecycle
 from engin._option import Option
-from engin._shutdown import ShutdownSwitch
 from engin._supervisor import Supervisor
 from engin._type_utils import TypeId
+from engin.exceptions import EnginError
 
 _OS_IS_WINDOWS = os.name == "nt"
 LOG = logging.getLogger("engin")
 
 
+class _EnginState(Enum):
+    IDLE = 0
+    """
+    Engin is not yet started.
+    """
+
+    RUNNING = 1
+    """
+    Engin is currently running.
+    """
+
+    SHUTDOWN = 2
+    """
+    Engin has performed shutdown
+    """
+
+
 class Engin:
     """
     The Engin is a modular application defined by a collection of options.
@@ -83,16 +101,16 @@ class Engin:
         Args:
             *options: an instance of Provide, Supply, Invoke, Entrypoint or a Block.
         """
-        self._stop_requested_event = ShutdownSwitch()
+        self._state = _EnginState.IDLE
+        self._start_complete_event = Event()
+        self._stop_requested_event = Event()
         self._stop_complete_event = Event()
-        self._exit_stack: AsyncExitStack = AsyncExitStack()
-        self._shutdown_task: Task | None = None
-        self._run_task: Task | None = None
+        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),
-            TypeId.from_type(ShutdownSwitch): Supply(self._stop_requested_event),
         }
         self._multiproviders: dict[TypeId, list[Provide]] = defaultdict(list)
         self._invocations: list[Invoke] = []
@@ -117,26 +135,9 @@ class Engin:
         The engin will run until it is stopped via an external signal (i.e. SIGTERM or
         SIGINT), the `stop` method is called on the engin, or a lifecycle task errors.
         """
-        await self.start()
-        if self._shutdown_task:
-            self._shutdown_task.cancel("redundant")
-        async with create_task_group() as tg:
-            tg.start_soon(_stop_engin_on_signal, self._stop_requested_event)
-            try:
-                await self._stop_requested_event.wait()
-                await self._shutdown()
-            except get_cancelled_exc_class():
-                with CancelScope(shield=True):
-                    await self._shutdown()
-
-    async def start(self) -> None:
-        """
-        Start the engin.
+        if self._state != _EnginState.IDLE:
+            raise EnginError("Engin is not idle, unable to start")
 
-        This is an alternative to calling `run`. This method waits for the startup
-        lifecycle to complete and then returns. The caller is then responsible for
-        calling `stop`.
-        """
         LOG.info("starting engin")
         assembled_invocations: list[AssembledDependency] = [
             await self._assembler.assemble(invocation) for invocation in self._invocations
@@ -151,10 +152,6 @@ class Engin:
                 return
 
         lifecycle = await self._assembler.build(Lifecycle)
-        supervisor = await self._assembler.build(Supervisor)
-
-        if not supervisor.empty:
-            lifecycle.append(supervisor)
 
         try:
             for hook in lifecycle.list():
@@ -168,9 +165,30 @@ class Engin:
             await self._shutdown()
             return
 
+        supervisor = await self._assembler.build(Supervisor)
+
         LOG.info("startup complete")
+        self._state = _EnginState.RUNNING
+        self._start_complete_event.set()
+
+        async with create_task_group() as tg:
+            tg.start_soon(_stop_engin_on_signal, self._stop_requested_event)
+
+            try:
+                async with supervisor:
+                    await self._stop_requested_event.wait()
+            except get_cancelled_exc_class():
+                pass
+            tg.cancel_scope.cancel()
+            await self._shutdown()
 
-        self._shutdown_task = asyncio.create_task(self._shutdown_when_stopped())
+    async def start(self) -> None:
+        """
+        Starts the engin in the background. This method will wait until the engin is fully
+        started to return so it is safe to use immediately after.
+        """
+        self._async_context_run_task = asyncio.create_task(self.run())
+        await self._start_complete_event.wait()
 
     async def stop(self) -> None:
         """
@@ -181,55 +199,59 @@ class Engin:
         started.
         """
         self._stop_requested_event.set()
-        if self._shutdown_task is None:
-            return
         await self._stop_complete_event.wait()
 
     def graph(self) -> list[Node]:
+        """
+        Creates a graph representation of the engin's dependencies which can be used for
+        introspection or visualisations.
+
+        Returns: a list of Node objects.
+        """
         grapher = DependencyGrapher({**self._providers, **self._multiproviders})
         return grapher.resolve(self._invocations)
 
+    def is_running(self) -> bool:
+        return self._state == _EnginState.RUNNING
+
+    def is_stopped(self) -> bool:
+        return self._state == _EnginState.SHUTDOWN
+
     async def _shutdown(self) -> None:
         LOG.info("stopping engin")
         await self._exit_stack.aclose()
         self._stop_complete_event.set()
         LOG.info("shutdown complete")
-
-    async def _shutdown_when_stopped(self) -> None:
-        await self._stop_requested_event.wait()
-        await self._shutdown()
+        self._state = _EnginState.SHUTDOWN
 
 
 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.
     """
-    try:
-        # try to gracefully handle sigint/sigterm
-        if not _OS_IS_WINDOWS:
-            loop = asyncio.get_running_loop()
-            for signame in (signal.SIGINT, signal.SIGTERM):
-                loop.add_signal_handler(signame, stop_requested_event.set)
-
-            await stop_requested_event.wait()
-        else:
-            should_stop = False
-
-            # windows does not support signal_handlers, so this is the workaround
-            def ctrlc_handler(sig: int, frame: FrameType | None) -> None:
-                nonlocal should_stop
-                if should_stop:
-                    raise KeyboardInterrupt("Forced keyboard interrupt")
-                should_stop = True
-
-            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)
-
-            stop_requested_event.set()
-    except asyncio.CancelledError:
-        pass
+    # try to gracefully handle sigint/sigterm
+    if not _OS_IS_WINDOWS:
+        loop = asyncio.get_running_loop()
+        for signame in (signal.SIGINT, signal.SIGTERM):
+            loop.add_signal_handler(signame, stop_requested_event.set)
+
+        await stop_requested_event.wait()
+    else:
+        should_stop = False
+
+        # windows does not support signal_handlers, so this is the workaround
+        def ctrlc_handler(sig: int, frame: FrameType | None) -> None:
+            nonlocal should_stop
+            if should_stop:
+                raise KeyboardInterrupt("Forced keyboard interrupt")
+            should_stop = True
+
+        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)
+
+        stop_requested_event.set()

engin/_supervisor.py

@@ -2,17 +2,13 @@ import inspect
 import logging
 import typing
 from collections.abc import Awaitable, Callable
-from contextlib import AsyncExitStack
 from dataclasses import dataclass
 from enum import Enum
 from types import TracebackType
-from typing import TypeAlias
+from typing import TypeAlias, assert_never
 
 import anyio
 from anyio import get_cancelled_exc_class
-from exceptiongroup import BaseExceptionGroup, catch
-
-from engin._shutdown import ShutdownSwitch
 
 if typing.TYPE_CHECKING:
     from anyio.abc import TaskGroup
@@ -72,13 +68,12 @@ class _SupervisorTask:
                 if self.on_exception == OnException.IGNORE:
                     self.complete = True
                     return
-
                 if self.on_exception == OnException.RETRY:
                     continue
-
                 if self.on_exception == OnException.SHUTDOWN:
                     self.complete = True
-                    raise
+                    raise get_cancelled_exc_class() from None
+                assert_never(self.on_exception)
 
     @property
     def name(self) -> str:
@@ -93,12 +88,8 @@ class _SupervisorTask:
 
 
 class Supervisor:
-    def __init__(self, shutdown: ShutdownSwitch) -> None:
+    def __init__(self) -> None:
         self._tasks: list[_SupervisorTask] = []
-        self._shutdown = shutdown
-        self._is_complete: bool = False
-
-        self._exit_stack: AsyncExitStack | None = None
         self._task_group: TaskGroup | None = None
 
     def supervise(
@@ -114,15 +105,7 @@ class Supervisor:
         if not self._tasks:
             return
 
-        def _handler(_: BaseExceptionGroup) -> None:
-            self._shutdown.set()
-
-        self._exit_stack = AsyncExitStack()
-        await self._exit_stack.__aenter__()
-        self._exit_stack.enter_context(catch({Exception: _handler}))
-        self._task_group = await self._exit_stack.enter_async_context(
-            anyio.create_task_group()
-        )
+        self._task_group = await anyio.create_task_group().__aenter__()
 
         for task in self._tasks:
             self._task_group.start_soon(task, name=task.name)
@@ -134,8 +117,7 @@ class Supervisor:
         traceback: TracebackType | None,
         /,
     ) -> None:
-        if not self._tasks:
-            return
-
-        if self._exit_stack:
-            await self._exit_stack.__aexit__(exc_type, exc_value, traceback)
+        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-0.1.0b2.dist-info/METADATA

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: engin
+Version: 0.1.0b2
+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: 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.
+
+
+## Features
+
+The Engin framework includes:
+
+- A fully-featured dependency injection system.
+- A robust application runtime with lifecycle hooks and supervised background tasks.
+- Zero boiler-plate code reuse across multiple applications.
+- Integrations for other frameworks such as FastAPI.
+- Full async support.
+- CLI commands to aid local development.
+
+
+## Installation
+
+Engin is available on PyPI, install using your favourite dependency manager:
+
+- `pip install engin`
+- `poetry add engin`
+- `uv add engin`
+
+## Example
+
+A small example which shows some of the runtime features of Engin. This application
+makes a http request and then performs a shutdown.
+
+```python
+import asyncio
+from httpx import AsyncClient
+from engin import Engin, Invoke, Lifecycle, 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_request():
+        await httpx_client.get("https://httpbin.org/get")
+        # one we've made the http request shutdown the application
+        raise asyncio.CancelledError("Forcing shutdown")
+
+    # supervise the http request as part of the application's lifecycle
+    supervisor.supervise(http_request)
+
+# 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: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, check them out.

{engin-0.1a1.dist-info → engin-0.1.0b2.dist-info}/RECORD

@@ -1,14 +1,13 @@
-engin/__init__.py,sha256=v5OWwQoxTtqh2sB2E5iSMg3gATJoXKOuJLq28aZX6C8,642
+engin/__init__.py,sha256=O0vS570kZFBq7Kwy4FgeJFIhfo4aIg5mv_Z_9vAQRio,577
 engin/_assembler.py,sha256=-ENSrXPMWacionIYrTSQO7th9DDBOPyAT8ybPbBRtQw,11318
 engin/_block.py,sha256=IacP4PoJKRhSQCbQSdoyCtmu362a4vj6qoUQKyaJwzI,3062
 engin/_dependency.py,sha256=xINk3sudxzsTmkUkNAKQwzBc0G0DfhpnrZli4z3ALBY,9459
-engin/_engin.py,sha256=UGS-dIMGcdhRWvsQBuwIH6I7XFxYMlgSZeuvl3ur3Eo,8417
+engin/_engin.py,sha256=BiibP76Pfq1Wpbu79u0anqqeXbrT2GIEzYMBfgPYoKo,8661
 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/_shutdown.py,sha256=G85Cz-wG06ZxQz6QVPcpIcNaGY44aZp6SL8H9J4YvfU,61
-engin/_supervisor.py,sha256=wKfGPjz8q1SH8ZP84USO-SxY3uTEXWy2NkTlhZQGRDE,4131
+engin/_supervisor.py,sha256=37h036bPe7ew88WjpIOmhZwCvOdLVcvalyJgbWZr1vU,3716
 engin/_type_utils.py,sha256=H3Tl-kJr2wY2RhaTXP9GrMqa2RsXMijHbjHKe1AxGmc,2276
 engin/exceptions.py,sha256=-VPwPReZb9YEIkrWMR9TW2K5HEwmHHgEO7QWH6wfV8c,1946
 engin/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -20,8 +19,8 @@ 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=7N6i-eZUEZRPo7kcvjS7kbRSY5QAPyKJXSeongSQ-OA,6371
-engin-0.1a1.dist-info/METADATA,sha256=f5atVNZHxnofJLnnf2upFC_MYjAJv3lVkQIxe62z1TA,2410
-engin-0.1a1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-engin-0.1a1.dist-info/entry_points.txt,sha256=sW247zZUMxm0b5UKYvPuqQQljYDtU-j2zK3cu7gHwM0,41
-engin-0.1a1.dist-info/licenses/LICENSE,sha256=XHh5LPUPKZWTBqBv2xxN2RU7D59nHoiJGb5RIt8f45w,1070
-engin-0.1a1.dist-info/RECORD,,
+engin-0.1.0b2.dist-info/METADATA,sha256=2_LESFF10wAgmJKpPg0lBFd1Ggf_iZKXOjzIbiK9Khk,3201
+engin-0.1.0b2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+engin-0.1.0b2.dist-info/entry_points.txt,sha256=sW247zZUMxm0b5UKYvPuqQQljYDtU-j2zK3cu7gHwM0,41
+engin-0.1.0b2.dist-info/licenses/LICENSE,sha256=XHh5LPUPKZWTBqBv2xxN2RU7D59nHoiJGb5RIt8f45w,1070
+engin-0.1.0b2.dist-info/RECORD,,

engin/_shutdown.py

@@ -1,4 +0,0 @@
-from asyncio import Event
-
-
-class ShutdownSwitch(Event): ...

engin-0.1a1.dist-info/METADATA

@@ -1,73 +0,0 @@
-Metadata-Version: 2.4
-Name: engin
-Version: 0.1a1
-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: 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())
-```
-