engin 0.1.0a2__tar.gz → 0.1.0b2__tar.gz

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

@@ -11,6 +11,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Supervisor class which can safely supervise long running tasks.
 
+### Changed
+
+- `ASGIEngin.run()` now raises an error to prevent incorrect usage.
+
 
 ## [0.0.20] - 2025-06-18
 

engin-0.1.0b2/PKG-INFO

@@ -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.1.0b2/README.md

@@ -0,0 +1,90 @@
+# 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.1.0a2 → engin-0.1.0b2}/docs/concepts/invocations.md

@@ -3,8 +3,8 @@
 Invocations define the behaviour of your application, therefore without any Invocations
 your application will not do anything.
 
-Like providers invocations are functions that take one or more dependencies as parameters,
-and they should always return None as the return value will not used by the Engin.
+Like providers, invocations are functions that take one or more dependencies as
+parameters, but they should always return None as the return value will not used by Engin.
 
 As part of the Engin's startup, all declared invocations will be called sequentially in
 the order they were registered.
@@ -13,7 +13,7 @@ Invocations can be used to define behaviour in two ways.
 
 **Implicit: Provider Lifecycle**
 
-Invocations are always called therefore their dependencies are always assembled. This
+Invocations are always called and therefore their dependencies are always assembled. This
 means that any providers with lifecycles will register their lifecycles with the
 application if directly or indirectly used by an invocation.
 

{engin-0.1.0a2 → engin-0.1.0b2}/docs/concepts/lifecycle.md

@@ -1,5 +1,3 @@
-from contextlib import asynccontextmanager
-
 # Lifecycle
 
 Certain types of object naturally have some form of startup and shutdown behaviour

engin-0.1.0b2/docs/index.md

@@ -0,0 +1,62 @@
+# Engin 🏎️
+
+Engin is a lightweight application framework powered by dependency injection, it helps
+you build both large monoliths and multiple 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
+
+=== "uv"
+
+    ```shell
+    uv add engin
+    ```
+
+=== "poetry"
+
+    ```shell
+    poetry add engin
+    ```
+
+=== "pip"
+
+    ```shell
+    pip install 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())
+```
+

{engin-0.1.0a2 → engin-0.1.0b2}/mkdocs.yaml

@@ -7,7 +7,7 @@ theme:
     custom_dir: 'docs/overrides'
     features:
       - navigation.instant
-      - navigation.tabs
+      - content.code.copy
     palette:
       - scheme: 'default'
         media: '(prefers-color-scheme: light)'
@@ -27,7 +27,6 @@ edit_uri: ""
 
 nav:
   - Home: "index.md"
-  - Getting Started: "getting-started.md"
   - Concepts:
       - Engin: "concepts/engin.md"
       - Providers: "concepts/providers.md"
@@ -60,6 +59,7 @@ plugins:
         inventories:
           - url: https://docs.python.org/3/objects.inv
             domains: [py, std]
+- search
 
 watch:
   - src
@@ -71,9 +71,13 @@ markdown_extensions:
   - pymdownx.blocks.caption
   - pymdownx.details
   - pymdownx.highlight:
-      anchor_linenums: true
-      line_spans: __span
-      pygments_lang_class: true
+        anchor_linenums: true
+        line_spans: __span
+        pygments_lang_class: true
   - pymdownx.inlinehilite
-  - pymdownx.snippets
+  - pymdownx.snippets:
+      base_path: [!relative $config_dir]
+      check_paths: true
   - pymdownx.superfences
+  - pymdownx.tabbed:
+      alternate_style: true

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

@@ -1,6 +1,6 @@
 [project]
 name = "engin"
-version = "0.1.0a2"
+version = "0.1.0b2"
 description = "An async-first modular application framework"
 readme = "README.md"
 requires-python = ">=3.10"

{engin-0.1.0a2 → engin-0.1.0b2}/src/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-0.1.0a2 → engin-0.1.0b2}/src/engin/_engin.py

@@ -2,7 +2,7 @@ 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
@@ -10,14 +10,13 @@ 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
@@ -29,25 +28,15 @@ LOG = logging.getLogger("engin")
 class _EnginState(Enum):
     IDLE = 0
     """
-    Not yet started.
+    Engin is not yet started.
     """
 
-    STARTED = 1
+    RUNNING = 1
     """
-    Engin started via .start() call
+    Engin is currently running.
     """
 
-    RUNNING = 2
-    """
-    Engin running via .run() call
-    """
-
-    STOPPING = 3
-    """
-    Engin stopped via .stop() call
-    """
-
-    SHUTDOWN = 4
+    SHUTDOWN = 2
     """
     Engin has performed shutdown
     """
@@ -113,16 +102,15 @@ class Engin:
             *options: an instance of Provide, Supply, Invoke, Entrypoint or a Block.
         """
         self._state = _EnginState.IDLE
-        self._stop_requested_event = ShutdownSwitch()
+        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] = []
@@ -147,31 +135,6 @@ 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()
-
-        # 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:
-        """
-        Start the engin.
-
-        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`.
-        """
         if self._state != _EnginState.IDLE:
             raise EnginError("Engin is not idle, unable to start")
 
@@ -189,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():
@@ -206,8 +165,30 @@ class Engin:
             await self._shutdown()
             return
 
+        supervisor = await self._assembler.build(Supervisor)
+
         LOG.info("startup complete")
-        self._state = _EnginState.STARTED
+        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()
+
+    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:
         """
@@ -217,18 +198,25 @@ class Engin:
         Note this method can be safely called at any point, even before the engin is
         started.
         """
-        # 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()
+        self._stop_requested_event.set()
+        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()
@@ -241,32 +229,29 @@ 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-0.1.0a2 → engin-0.1.0b2}/src/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)