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

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/_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/_shutdown.py

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

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/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.0.20.dist-info → engin-0.1.0a2.dist-info}/METADATA

@@ -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.dist-info → engin-0.1.0a2.dist-info}/RECORD

@@ -1,12 +1,14 @@
-engin/__init__.py,sha256=A8TE_ci7idoR683535YoBrWZbYTgXXS-q7Y2y51nZ5M,486
+engin/__init__.py,sha256=v5OWwQoxTtqh2sB2E5iSMg3gATJoXKOuJLq28aZX6C8,642
 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/_engin.py,sha256=XkGUG3D7z8X31rZhbu02_NFhFwSKB4JPSoma5jv6nq4,9135
 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/_type_utils.py,sha256=H3Tl-kJr2wY2RhaTXP9GrMqa2RsXMijHbjHKe1AxGmc,2276
 engin/exceptions.py,sha256=-VPwPReZb9YEIkrWMR9TW2K5HEwmHHgEO7QWH6wfV8c,1946
 engin/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -17,9 +19,9 @@ 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,,
+engin/extensions/fastapi.py,sha256=7N6i-eZUEZRPo7kcvjS7kbRSY5QAPyKJXSeongSQ-OA,6371
+engin-0.1.0a2.dist-info/METADATA,sha256=eg-rPpaGOV1MDNenGqSGCldPlTHh2yZ3CcZ0b5agakc,2408
+engin-0.1.0a2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+engin-0.1.0a2.dist-info/entry_points.txt,sha256=sW247zZUMxm0b5UKYvPuqQQljYDtU-j2zK3cu7gHwM0,41
+engin-0.1.0a2.dist-info/licenses/LICENSE,sha256=XHh5LPUPKZWTBqBv2xxN2RU7D59nHoiJGb5RIt8f45w,1070
+engin-0.1.0a2.dist-info/RECORD,,