engin 0.0.20__tar.gz → 0.1.0a2__tar.gz

{engin-0.0.20 → engin-0.1.0a2}/CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.0] - UNRELEASED
+
+### Added
+
+- Supervisor class which can safely supervise long running tasks.
+
 
 ## [0.0.20] - 2025-06-18
 

{engin-0.0.20 → engin-0.1.0a2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: engin
-Version: 0.0.20
+Version: 0.1.0a2
 Summary: An async-first modular application framework
 Project-URL: Homepage, https://github.com/invokermain/engin
 Project-URL: Documentation, https://engin.readthedocs.io/en/latest/
@@ -10,6 +10,8 @@ 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
@@ -18,7 +20,7 @@ Description-Content-Type: text/markdown
 
 # Engin 🏎️
 
-Engin is a zero-dependency application framework for modern Python.
+Engin is a lightweight application framework for modern Python.
 
 **Documentation**: https://engin.readthedocs.io/
 

{engin-0.0.20 → engin-0.1.0a2}/README.md

@@ -2,7 +2,7 @@
 
 # Engin 🏎️
 
-Engin is a zero-dependency application framework for modern Python.
+Engin is a lightweight application framework for modern Python.
 
 **Documentation**: https://engin.readthedocs.io/
 

{engin-0.0.20 → engin-0.1.0a2}/docs/index.md

@@ -1,6 +1,6 @@
 # Introduction
 
-Engin is a zero-dependency application framework for modern Python.
+Engin is a lightweight application framework for modern Python.
 
 Engin is 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).

{engin-0.0.20 → engin-0.1.0a2}/pyproject.toml

@@ -1,12 +1,16 @@
 [project]
 name = "engin"
-version = "0.0.20"
+version = "0.1.0a2"
 description = "An async-first modular application framework"
 readme = "README.md"
 requires-python = ">=3.10"
 license = "MIT"
 keywords = ["Dependency Injection", "Application Framework"]
-dependencies = []
+dependencies = [
+    "anyio>=4",
+    # backwards compatability for exception group in 3.10
+    "exceptiongroup>=1",
+]
 
 [project.optional-dependencies]
 cli = ["typer>=0.15"]
@@ -79,7 +83,7 @@ ignore = [
 
 
 [tool.pytest.ini_options]
-log_cli = false
+log_cli = true
 log_cli_level = "DEBUG"
 asyncio_mode = "auto"
 asyncio_default_fixture_loop_scope = "session"

{engin-0.0.20 → engin-0.1.0a2}/src/engin/__init__.py

@@ -4,6 +4,8 @@ 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
 
 __all__ = [
@@ -13,8 +15,11 @@ __all__ = [
     "Entrypoint",
     "Invoke",
     "Lifecycle",
+    "OnException",
     "Option",
     "Provide",
+    "ShutdownSwitch",
+    "Supervisor",
     "Supply",
     "TypeId",
     "invoke",

{engin-0.0.20 → engin-0.1.0a2}/src/engin/_engin.py

@@ -5,21 +5,54 @@ import signal
 from asyncio import Event, Task
 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 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
+    """
+    Not yet started.
+    """
+
+    STARTED = 1
+    """
+    Engin started via .start() call
+    """
+
+    RUNNING = 2
+    """
+    Engin running via .run() call
+    """
+
+    STOPPING = 3
+    """
+    Engin stopped via .stop() call
+    """
+
+    SHUTDOWN = 4
+    """
+    Engin has performed shutdown
+    """
+
+
 class Engin:
     """
     The Engin is a modular application defined by a collection of options.
@@ -38,10 +71,10 @@ class Engin:
     1. The Engin assembles all Invocations. Only Providers that are required to satisfy
        the Invoke options parameters are assembled.
     2. All Invocations are run sequentially in the order they were passed in to the Engin.
-    3. Any Lifecycle Startup defined by a provider that was assembled in order to satisfy
-       the constructors is ran.
-    4. The Engin waits for a stop signal, i.e. SIGINT or SIGTERM.
-    5. Any Lifecyce Shutdown task is ran, in the reverse order to the Startup order.
+    3. Lifecycle Startup tasks registered by assembled dependencies are run sequentially.
+    4. The Engin waits for a stop signal, i.e. SIGINT or SIGTERM, or for something to
+       set the ShutdownSwitch event.
+    5. Lifecyce Shutdown tasks are run in the reverse order to the Startup order.
 
     Examples:
         ```python
@@ -49,11 +82,13 @@ class Engin:
 
         from httpx import AsyncClient
 
-        from engin import Engin, Invoke, Provide
+        from engin import Engin, Invoke, Lifecycle, Provide
 
 
-        def httpx_client() -> AsyncClient:
-            return AsyncClient()
+        def httpx_client(lifecycle: Lifecycle) -> AsyncClient:
+            client = AsyncClient()
+            lifecycle.append(client)
+            return client
 
 
         async def main(http_client: AsyncClient) -> None:
@@ -65,7 +100,7 @@ class Engin:
         ```
     """
 
-    _LIB_OPTIONS: ClassVar[list[Option]] = [Provide(Lifecycle)]
+    _LIB_OPTIONS: ClassVar[list[Option]] = [Provide(Lifecycle), Provide(Supervisor)]
 
     def __init__(self, *options: Option) -> None:
         """
@@ -77,14 +112,17 @@ class Engin:
         Args:
             *options: an instance of Provide, Supply, Invoke, Entrypoint or a Block.
         """
-        self._stop_requested_event = Event()
+        self._state = _EnginState.IDLE
+        self._stop_requested_event = ShutdownSwitch()
         self._stop_complete_event = Event()
         self._exit_stack: AsyncExitStack = AsyncExitStack()
         self._shutdown_task: Task | None = None
         self._run_task: Task | None = None
+        self._assembler = Assembler([])
 
         self._providers: dict[TypeId, Provide] = {
-            TypeId.from_type(Engin): Supply(self, as_type=Engin)
+            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] = []
@@ -94,7 +132,9 @@ class Engin:
             option.apply(self)
 
         multi_providers = [p for multi in self._multiproviders.values() for p in multi]
-        self._assembler = Assembler(chain(self._providers.values(), multi_providers))
+
+        for provider in chain(self._providers.values(), multi_providers):
+            self._assembler.add(provider)
 
     @property
     def assembler(self) -> Assembler:
@@ -105,11 +145,24 @@ class Engin:
         Run the engin.
 
         The engin will run until it is stopped via an external signal (i.e. SIGTERM or
-        SIGINT) or the `stop` method is called on the engin.
+        SIGINT), the `stop` method is called on the engin, or a lifecycle task errors.
         """
         await self.start()
-        self._run_task = asyncio.create_task(_wait_for_stop_signal(self._stop_requested_event))
-        await self._stop_requested_event.wait()
+
+        # engin failed to start, so exit early
+        if self._state != _EnginState.STARTED:
+            return
+
+        self._state = _EnginState.RUNNING
+
+        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:
         """
@@ -119,6 +172,9 @@ class Engin:
         lifecycle to complete and then returns. The caller is then responsible for
         calling `stop`.
         """
+        if self._state != _EnginState.IDLE:
+            raise EnginError("Engin is not idle, unable to start")
+
         LOG.info("starting engin")
         assembled_invocations: list[AssembledDependency] = [
             await self._assembler.assemble(invocation) for invocation in self._invocations
@@ -133,6 +189,10 @@ 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():
@@ -147,8 +207,7 @@ class Engin:
             return
 
         LOG.info("startup complete")
-
-        self._shutdown_task = asyncio.create_task(self._shutdown_when_stopped())
+        self._state = _EnginState.STARTED
 
     async def stop(self) -> None:
         """
@@ -158,10 +217,13 @@ class Engin:
         Note this method can be safely called at any point, even before the engin is
         started.
         """
-        self._stop_requested_event.set()
-        if self._shutdown_task is None:
-            return
-        await self._stop_complete_event.wait()
+        # If the Engin was ran via `start()` perform shutdown directly
+        if self._state == _EnginState.STARTED:
+            await self._shutdown()
+        # If the Engin was ran via `run()` notify via event
+        elif self._state == _EnginState.RUNNING:
+            self._stop_requested_event.set()
+            await self._stop_complete_event.wait()
 
     def graph(self) -> list[Node]:
         grapher = DependencyGrapher({**self._providers, **self._multiproviders})
@@ -172,13 +234,13 @@ class Engin:
         await self._exit_stack.aclose()
         self._stop_complete_event.set()
         LOG.info("shutdown complete")
+        self._state = _EnginState.SHUTDOWN
 
-    async def _shutdown_when_stopped(self) -> None:
-        await self._stop_requested_event.wait()
-        await self._shutdown()
 
-
-async def _wait_for_stop_signal(stop_requested_event: Event) -> None:
+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:

engin-0.1.0a2/src/engin/_shutdown.py

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

engin-0.1.0a2/src/engin/_supervisor.py

@@ -0,0 +1,141 @@
+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
+
+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
+
+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():
+                LOG.info(f"{self.name} cancelled")
+                raise
+            except Exception as err:
+                LOG.error(f"Supervisor: {self.name} raised {type(err).__name__}", exc_info=err)
+                self.last_exception = err
+
+                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
+
+    @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, shutdown: ShutdownSwitch) -> 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(
+        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
+
+        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()
+        )
+
+        for task in self._tasks:
+            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 not self._tasks:
+            return
+
+        if self._exit_stack:
+            await self._exit_stack.__aexit__(exc_type, exc_value, traceback)

{engin-0.0.20 → engin-0.1.0a2}/src/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.0a2/tests/acceptance/test_engin_signal_handling.py

@@ -0,0 +1,17 @@
+import asyncio
+from asyncio import TaskGroup
+
+from engin import Engin
+from engin._engin import _EnginState
+
+
+async def test_engin_signal_handling():
+    engin = Engin()
+
+    async with TaskGroup() as tg:
+        tg.create_task(engin.run())
+        # give it time to startup
+        await asyncio.sleep(0.1)
+        assert engin._state == _EnginState.RUNNING
+        await engin.stop()
+        assert engin._state == _EnginState.SHUTDOWN

{engin-0.0.20 → engin-0.1.0a2}/tests/acceptance/test_error_in_start_up.py

@@ -1,3 +1,4 @@
+import asyncio
 from contextlib import asynccontextmanager
 
 from starlette.applications import Starlette
@@ -35,6 +36,13 @@ async def test_error_in_startup():
     assert not B_LIFECYCLE_STATE
 
 
+async def test_error_in_startup_handled_when_run():
+    engin = Engin(Invoke(a), Invoke(b))
+
+    await asyncio.wait_for(engin.run(), timeout=0.5)
+    assert not B_LIFECYCLE_STATE
+
+
 async def test_error_in_startup_asgi():
     def asgi_type() -> ASGIType:
         return Starlette()

engin-0.1.0a2/tests/acceptance/test_error_in_supervised_task.py

@@ -0,0 +1,21 @@
+import asyncio
+
+from engin import Engin, Invoke, Supervisor
+
+
+async def delayed_error_task():
+    raise RuntimeError("Process errored")
+
+
+def supervise(supervisor: Supervisor) -> None:
+    supervisor.supervise(delayed_error_task)
+
+
+async def test_error_in_supervised_task_handled_when_run(caplog):
+    engin = Engin(Invoke(supervise))
+    await asyncio.wait_for(engin.run(), timeout=0.5)
+
+
+async def test_error_in_supervised_task_handled_when_start(caplog):
+    engin = Engin(Invoke(supervise))
+    await asyncio.wait_for(engin.start(), timeout=0.5)

engin-0.1.0a2/tests/test_supervisor.py

@@ -0,0 +1,115 @@
+import asyncio
+import contextlib
+from asyncio import CancelledError
+from dataclasses import dataclass
+
+from engin import OnException, ShutdownSwitch, Supervisor
+
+
+async def delayed_error_task():
+    await asyncio.sleep(0.05)
+    raise RuntimeError("Process errored")
+
+
+async def happy_task():
+    await asyncio.sleep(1)
+
+
+@dataclass
+class ClassHappyTask:
+    async def run(self) -> None:
+        await asyncio.sleep(1)
+
+
+async def test_empty_supervisor():
+    shutdown_event = ShutdownSwitch()
+    supervisor = Supervisor(shutdown_event)
+
+    with contextlib.suppress(CancelledError):
+        async with supervisor:
+            await asyncio.sleep(0.1)
+
+
+async def test_supervisor_on_exception_shutdown():
+    shutdown_event = ShutdownSwitch()
+    supervisor = Supervisor(shutdown_event)
+
+    supervisor.supervise(delayed_error_task, on_exception=OnException.SHUTDOWN)
+
+    with contextlib.suppress(CancelledError):
+        async with supervisor:
+            await asyncio.sleep(0.1)
+
+    assert shutdown_event.is_set()
+
+
+async def test_supervisor_on_exception_retry():
+    shutdown_event = ShutdownSwitch()
+    supervisor = Supervisor(shutdown_event)
+    attempt = 0
+
+    async def retry_task():
+        nonlocal attempt
+        if attempt == 0:
+            attempt += 1
+            raise RuntimeError("Process errored")
+
+    supervisor.supervise(retry_task, on_exception=OnException.RETRY)
+
+    with contextlib.suppress(CancelledError):
+        async with supervisor:
+            await asyncio.sleep(0.1)
+
+    assert supervisor._tasks[0].complete
+    assert isinstance(supervisor._tasks[0].last_exception, RuntimeError)
+    assert attempt == 1
+
+
+async def test_supervisor_on_exception_ignore():
+    shutdown_event = ShutdownSwitch()
+    supervisor = Supervisor(shutdown_event)
+
+    async def error_task():
+        raise RuntimeError("Process errored")
+
+    async def complete_task():
+        await asyncio.sleep(0.09)
+
+    supervisor.supervise(error_task, on_exception=OnException.IGNORE)
+    supervisor.supervise(complete_task, on_exception=OnException.SHUTDOWN)
+
+    with contextlib.suppress(CancelledError):
+        async with supervisor:
+            await asyncio.sleep(0.1)
+
+    assert supervisor._tasks[0].complete
+    assert isinstance(supervisor._tasks[0].last_exception, RuntimeError)
+    assert supervisor._tasks[1].complete
+    assert supervisor._tasks[1].last_exception is None
+
+
+async def test_supervisor():
+    shutdown_event = ShutdownSwitch()
+    supervisor = Supervisor(shutdown_event)
+
+    supervisor.supervise(delayed_error_task)
+    supervisor.supervise(happy_task)
+    supervisor.supervise(ClassHappyTask().run)
+
+    with contextlib.suppress(CancelledError):
+        async with supervisor:
+            await asyncio.sleep(1)
+
+    # task one completed and has error (as raised exception)
+    assert supervisor._tasks[0].complete
+    assert supervisor._tasks[0].last_exception is not None
+
+    # task two did not complete and has no error (as was cancelled)
+    assert not supervisor._tasks[1].complete
+    assert supervisor._tasks[1].last_exception is None
+
+    # task three did not complete and has no error (as was cancelled)
+    assert not supervisor._tasks[2].complete
+    assert supervisor._tasks[2].last_exception is None
+
+    assert shutdown_event.is_set()