engin 0.0.20__tar.gz → 0.1a1__tar.gz

{engin-0.0.20 → engin-0.1a1}/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.1a1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: engin
-Version: 0.0.20
+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/
@@ -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

{engin-0.0.20 → engin-0.1a1}/pyproject.toml

@@ -1,12 +1,16 @@
 [project]
 name = "engin"
-version = "0.0.20"
+version = "0.1.a1"
 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.1a1}/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.1a1}/src/engin/_engin.py

@@ -9,11 +9,15 @@ 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
 
 _OS_IS_WINDOWS = os.name == "nt"
@@ -38,10 +42,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 +53,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 +71,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 +83,16 @@ class Engin:
         Args:
             *options: an instance of Provide, Supply, Invoke, Entrypoint or a Block.
         """
-        self._stop_requested_event = Event()
+        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 +102,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 +115,19 @@ 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()
+        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:
         """
@@ -133,6 +151,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():
@@ -178,7 +200,10 @@ class Engin:
         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.1a1/src/engin/_shutdown.py

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

engin-0.1a1/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.1a1}/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.1a1/tests/acceptance/test_error_in_supervised_task.py

@@ -0,0 +1,17 @@
+import asyncio
+
+from engin import Engin, Invoke, Supervisor
+
+
+async def delayed_error_task():
+    await asyncio.sleep(0.5)
+    raise RuntimeError("Process errored")
+
+
+def supervise(supervisor: Supervisor) -> None:
+    supervisor.supervise(delayed_error_task)
+
+
+async def test_error_in_task(caplog):
+    engin = Engin(Invoke(supervise))
+    await engin.run()

engin-0.1a1/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()