engin 0.1a1__tar.gz → 0.1.0a2__tar.gz

{engin-0.1a1 → engin-0.1.0a2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: engin
-Version: 0.1a1
+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/
@@ -20,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.1a1 → 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.1a1 → 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.1a1 → engin-0.1.0a2}/pyproject.toml

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

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

@@ -5,6 +5,7 @@ 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
@@ -19,11 +20,39 @@ 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.
@@ -83,6 +112,7 @@ class Engin:
         Args:
             *options: an instance of Provide, Supply, Invoke, Entrypoint or a Block.
         """
+        self._state = _EnginState.IDLE
         self._stop_requested_event = ShutdownSwitch()
         self._stop_complete_event = Event()
         self._exit_stack: AsyncExitStack = AsyncExitStack()
@@ -118,8 +148,13 @@ class Engin:
         SIGINT), the `stop` method is called on the engin, or a lifecycle task errors.
         """
         await self.start()
-        if self._shutdown_task:
-            self._shutdown_task.cancel("redundant")
+
+        # 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:
@@ -137,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
@@ -169,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:
         """
@@ -180,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})
@@ -194,10 +234,7 @@ class Engin:
         await self._exit_stack.aclose()
         self._stop_complete_event.set()
         LOG.info("shutdown complete")
-
-    async def _shutdown_when_stopped(self) -> None:
-        await self._stop_requested_event.wait()
-        await self._shutdown()
+        self._state = _EnginState.SHUTDOWN
 
 
 async def _stop_engin_on_signal(stop_requested_event: Event) -> None:

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.1a1 → 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.1a1 → engin-0.1.0a2}/uv.lock

@@ -37,15 +37,16 @@ wheels = [
 
 [[package]]
 name = "backrefs"
-version = "5.8"
+version = "5.9"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/6c/46/caba1eb32fa5784428ab401a5487f73db4104590ecd939ed9daaf18b47e0/backrefs-5.8.tar.gz", hash = "sha256:2cab642a205ce966af3dd4b38ee36009b31fa9502a35fd61d59ccc116e40a6bd", size = 6773994, upload-time = "2025-02-25T18:15:32.003Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/eb/a7/312f673df6a79003279e1f55619abbe7daebbb87c17c976ddc0345c04c7b/backrefs-5.9.tar.gz", hash = "sha256:808548cb708d66b82ee231f962cb36faaf4f2baab032f2fbb783e9c2fdddaa59", size = 5765857, upload-time = "2025-06-22T19:34:13.97Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/bf/cb/d019ab87fe70e0fe3946196d50d6a4428623dc0c38a6669c8cae0320fbf3/backrefs-5.8-py310-none-any.whl", hash = "sha256:c67f6638a34a5b8730812f5101376f9d41dc38c43f1fdc35cb54700f6ed4465d", size = 380337, upload-time = "2025-02-25T16:53:14.607Z" },
-    { url = "https://files.pythonhosted.org/packages/a9/86/abd17f50ee21b2248075cb6924c6e7f9d23b4925ca64ec660e869c2633f1/backrefs-5.8-py311-none-any.whl", hash = "sha256:2e1c15e4af0e12e45c8701bd5da0902d326b2e200cafcd25e49d9f06d44bb61b", size = 392142, upload-time = "2025-02-25T16:53:17.266Z" },
-    { url = "https://files.pythonhosted.org/packages/b3/04/7b415bd75c8ab3268cc138c76fa648c19495fcc7d155508a0e62f3f82308/backrefs-5.8-py312-none-any.whl", hash = "sha256:bbef7169a33811080d67cdf1538c8289f76f0942ff971222a16034da88a73486", size = 398021, upload-time = "2025-02-25T16:53:26.378Z" },
-    { url = "https://files.pythonhosted.org/packages/04/b8/60dcfb90eb03a06e883a92abbc2ab95c71f0d8c9dd0af76ab1d5ce0b1402/backrefs-5.8-py313-none-any.whl", hash = "sha256:e3a63b073867dbefd0536425f43db618578528e3896fb77be7141328642a1585", size = 399915, upload-time = "2025-02-25T16:53:28.167Z" },
-    { url = "https://files.pythonhosted.org/packages/0c/37/fb6973edeb700f6e3d6ff222400602ab1830446c25c7b4676d8de93e65b8/backrefs-5.8-py39-none-any.whl", hash = "sha256:a66851e4533fb5b371aa0628e1fee1af05135616b86140c9d787a2ffdf4b8fdc", size = 380336, upload-time = "2025-02-25T16:53:29.858Z" },
+    { url = "https://files.pythonhosted.org/packages/19/4d/798dc1f30468134906575156c089c492cf79b5a5fd373f07fe26c4d046bf/backrefs-5.9-py310-none-any.whl", hash = "sha256:db8e8ba0e9de81fcd635f440deab5ae5f2591b54ac1ebe0550a2ca063488cd9f", size = 380267, upload-time = "2025-06-22T19:34:05.252Z" },
+    { url = "https://files.pythonhosted.org/packages/55/07/f0b3375bf0d06014e9787797e6b7cc02b38ac9ff9726ccfe834d94e9991e/backrefs-5.9-py311-none-any.whl", hash = "sha256:6907635edebbe9b2dc3de3a2befff44d74f30a4562adbb8b36f21252ea19c5cf", size = 392072, upload-time = "2025-06-22T19:34:06.743Z" },
+    { url = "https://files.pythonhosted.org/packages/9d/12/4f345407259dd60a0997107758ba3f221cf89a9b5a0f8ed5b961aef97253/backrefs-5.9-py312-none-any.whl", hash = "sha256:7fdf9771f63e6028d7fee7e0c497c81abda597ea45d6b8f89e8ad76994f5befa", size = 397947, upload-time = "2025-06-22T19:34:08.172Z" },
+    { url = "https://files.pythonhosted.org/packages/10/bf/fa31834dc27a7f05e5290eae47c82690edc3a7b37d58f7fb35a1bdbf355b/backrefs-5.9-py313-none-any.whl", hash = "sha256:cc37b19fa219e93ff825ed1fed8879e47b4d89aa7a1884860e2db64ccd7c676b", size = 399843, upload-time = "2025-06-22T19:34:09.68Z" },
+    { url = "https://files.pythonhosted.org/packages/fc/24/b29af34b2c9c41645a9f4ff117bae860291780d73880f449e0b5d948c070/backrefs-5.9-py314-none-any.whl", hash = "sha256:df5e169836cc8acb5e440ebae9aad4bf9d15e226d3bad049cf3f6a5c20cc8dc9", size = 411762, upload-time = "2025-06-22T19:34:11.037Z" },
+    { url = "https://files.pythonhosted.org/packages/41/ff/392bff89415399a979be4a65357a41d92729ae8580a66073d8ec8d810f98/backrefs-5.9-py39-none-any.whl", hash = "sha256:f48ee18f6252b8f5777a22a00a09a85de0ca931658f1dd96d4406a34f3748c60", size = 380265, upload-time = "2025-06-22T19:34:12.405Z" },
 ]
 
 [[package]]
@@ -210,7 +211,7 @@ toml = [
 
 [[package]]
 name = "engin"
-version = "0.0.20"
+version = "0.1a1"
 source = { editable = "." }
 dependencies = [
     { name = "anyio" },
@@ -841,16 +842,16 @@ wheels = [
 
 [[package]]
 name = "pydantic-settings"
-version = "2.10.0"
+version = "2.10.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "pydantic" },
     { name = "python-dotenv" },
     { name = "typing-inspection" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/c2/ef/3d61472b7801c896f9efd9bb8750977d9577098b05224c5c41820690155e/pydantic_settings-2.10.0.tar.gz", hash = "sha256:7a12e0767ba283954f3fd3fefdd0df3af21b28aa849c40c35811d52d682fa876", size = 172625, upload-time = "2025-06-21T13:56:55.898Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/68/85/1ea668bbab3c50071ca613c6ab30047fb36ab0da1b92fa8f17bbc38fd36c/pydantic_settings-2.10.1.tar.gz", hash = "sha256:06f0062169818d0f5524420a360d632d5857b83cffd4d42fe29597807a1614ee", size = 172583, upload-time = "2025-06-24T13:26:46.841Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/7d/9e/fce9331fecf1d2761ff0516c5dceab8a5fd415e82943e727dc4c5fa84a90/pydantic_settings-2.10.0-py3-none-any.whl", hash = "sha256:33781dfa1c7405d5ed2b6f150830a93bb58462a847357bd8f162f8bacb77c027", size = 45232, upload-time = "2025-06-21T13:56:53.682Z" },
+    { url = "https://files.pythonhosted.org/packages/58/f0/427018098906416f580e3cf1366d3b1abfb408a0652e9f31600c24a1903c/pydantic_settings-2.10.1-py3-none-any.whl", hash = "sha256:a60952460b99cf661dc25c29c0ef171721f98bfcb52ef8d9ea4c943d7c8cc796", size = 45235, upload-time = "2025-06-24T13:26:45.485Z" },
 ]
 
 [[package]]
@@ -958,11 +959,11 @@ wheels = [
 
 [[package]]
 name = "python-dotenv"
-version = "1.1.0"
+version = "1.1.1"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/88/2c/7bb1416c5620485aa793f2de31d3df393d3686aa8a8506d11e10e13c5baf/python_dotenv-1.1.0.tar.gz", hash = "sha256:41f90bc6f5f177fb41f53e87666db362025010eb28f60a01c9143bfa33a2b2d5", size = 39920, upload-time = "2025-03-25T10:14:56.835Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/f6/b0/4bc07ccd3572a2f9df7e6782f52b0c6c90dcbb803ac4a167702d7d0dfe1e/python_dotenv-1.1.1.tar.gz", hash = "sha256:a8a6399716257f45be6a007360200409fce5cda2661e3dec71d23dc15f6189ab", size = 41978, upload-time = "2025-06-24T04:21:07.341Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/1e/18/98a99ad95133c6a6e2005fe89faedf294a748bd5dc803008059409ac9b1e/python_dotenv-1.1.0-py3-none-any.whl", hash = "sha256:d7c01d9e2293916c18baf562d95698754b0dbbb5e74d457c45d4f6561fb9d55d", size = 20256, upload-time = "2025-03-25T10:14:55.034Z" },
+    { url = "https://files.pythonhosted.org/packages/5f/ed/539768cf28c661b5b068d66d96a2f155c4971a5d55684a514c1a0e0dec2f/python_dotenv-1.1.1-py3-none-any.whl", hash = "sha256:31f23644fe2602f88ff55e1f5c79ba497e01224ee7737937930c448e4d0e24dc", size = 20556, upload-time = "2025-06-24T04:21:06.073Z" },
 ]
 
 [[package]]

engin-0.1a1/tests/acceptance/test_error_in_supervised_task.py

@@ -1,17 +0,0 @@
-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()