engin 0.0.19__py3-none-any.whl → 0.1a1__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/_dependency.py

@@ -33,7 +33,7 @@ class Dependency(ABC, Option, Generic[P, T]):
     def __init__(self, func: Func[P, T]) -> None:
         self._func = func
         self._is_async = iscoroutinefunction(func)
-        self._signature = inspect.signature(self._func)
+        self._signature = inspect.signature(self._func, eval_str=True)
         self._block_name: str | None = None
 
         source_frame = get_first_external_frame()
@@ -154,24 +154,24 @@ class Entrypoint(Invoke):
 class Provide(Dependency[Any, T]):
     def __init__(
         self,
-        builder: Func[P, T],
+        factory: Func[P, T],
         *,
         scope: str | None = None,
         as_type: type | None = None,
         override: bool = False,
     ) -> None:
         """
-        Provide a type via a builder or factory function.
+        Provide a type via a factory function.
 
         Args:
-            builder: the builder function that returns the type.
+            factory: the factory function that returns the type.
             scope: (optional) associate this provider with a specific scope.
             as_type: (optional) allows you to explicitly specify the provided type, e.g.
                 to type erase a concrete type, or to provide a mock implementation.
             override: (optional) allow this provider to override other providers for the
                 same type from the same package.
         """
-        super().__init__(func=builder)
+        super().__init__(func=factory)
         self._scope = scope
         self._override = override
         self._explicit_type = as_type
@@ -231,9 +231,9 @@ class Provide(Dependency[Any, T]):
         # overwriting a dependency from the same package must be explicit
         if is_same_package and not self._override:
             msg = (
-                f"Provider '{self.name}' is implicitly overriding "
-                f"'{existing_provider.name}', if this is intended specify "
-                "`override=True` for the overriding Provider"
+                f"{self} from '{self._source_frame}' is implicitly overriding "
+                f"{existing_provider} from '{existing_provider.source_module}', if this "
+                "is intentional specify `override=True` for the overriding Provider"
             )
             raise RuntimeError(msg)
 
@@ -243,7 +243,7 @@ class Provide(Dependency[Any, T]):
         return hash(self.return_type_id)
 
     def __str__(self) -> str:
-        return f"Provide({self.return_type_id})"
+        return f"Provide(factory={self.func_name}, type={self._return_type_id})"
 
     def _resolve_return_type(self) -> type[T]:
         if self._explicit_type is not None:
@@ -279,7 +279,14 @@ class Supply(Provide, Generic[T]):
               same type from the same package.
         """
         self._value = value
-        super().__init__(builder=self._get_val, as_type=as_type, override=override)
+        super().__init__(factory=self._get_val, as_type=as_type, override=override)
+
+    @property
+    def name(self) -> str:
+        if self._block_name:
+            return f"{self._block_name}.supply"
+        else:
+            return f"{self._source_frame}.supply"
 
     def _resolve_return_type(self) -> type[T]:
         if self._explicit_type is not None:
@@ -292,4 +299,4 @@ class Supply(Provide, Generic[T]):
         return self._value
 
     def __str__(self) -> str:
-        return f"Supply({self.return_type_id})"
+        return f"Supply(value={self._value}, type={self.return_type_id})"

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

@@ -33,8 +33,8 @@ class TypeId:
             return TypeId(type=type_, multi=False)
 
     def __str__(self) -> str:
-        module = self.type.__module__
-        out = f"{module}." if module not in _implict_modules else ""
+        module = getattr(self.type, "__module__", None)
+        out = f"{module}." if module and module not in _implict_modules else ""
         out += _args_to_str(self.type)
         if self.multi:
             out += "[]"

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.19.dist-info → engin-0.1a1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: engin
-Version: 0.0.19
+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.19.dist-info → engin-0.1a1.dist-info}/RECORD

@@ -1,13 +1,15 @@
-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=Nfq6L92LN4X53QpiMCIF3MjmWfuntYVOnZmmoPYYJEw,9165
-engin/_engin.py,sha256=yIpZdeqvm8hv0RxOV0veFuvyu9xQ054JSaeuUWwHdOQ,7380
+engin/_dependency.py,sha256=xINk3sudxzsTmkUkNAKQwzBc0G0DfhpnrZli4z3ALBY,9459
+engin/_engin.py,sha256=UGS-dIMGcdhRWvsQBuwIH6I7XFxYMlgSZeuvl3ur3Eo,8417
 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=Pmm4m1_WdevT5KTe8tzY_BseNxPyhu_nKsLGgyNcPpo,2247
+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
 engin/_cli/__init__.py,sha256=koD5WTkZXb8QQIiVU5bJiSR1wwPGb5rv2iwd-v-BA7A,564
@@ -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.19.dist-info/METADATA,sha256=Rb1VPxLjnzVxhnq8Llie5XRxpI0GANR-dK31BEcPAqg,2354
-engin-0.0.19.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-engin-0.0.19.dist-info/entry_points.txt,sha256=sW247zZUMxm0b5UKYvPuqQQljYDtU-j2zK3cu7gHwM0,41
-engin-0.0.19.dist-info/licenses/LICENSE,sha256=XHh5LPUPKZWTBqBv2xxN2RU7D59nHoiJGb5RIt8f45w,1070
-engin-0.0.19.dist-info/RECORD,,
+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,,