engin 0.1.0b4__tar.gz → 0.1.0rc1__tar.gz

{engin-0.1.0b4 → engin-0.1.0rc1}/.github/workflows/benchmark.yaml

@@ -4,6 +4,9 @@ on:
   push:
     branches: [main]
 
+env:
+  UV_FROZEN: "1"
+
 jobs:
   benchmark-main:
     runs-on: ubuntu-latest

{engin-0.1.0b4 → engin-0.1.0rc1}/.github/workflows/check.yaml

@@ -3,6 +3,9 @@ name: Check
 on:
   push:
 
+env:
+  UV_FROZEN: "1"
+
 jobs:
   check:
     name: python
@@ -40,6 +43,7 @@ jobs:
         run: uv run poe ci-test
 
       - name: Upload coverage reports to Codecov
+        if: matrix.os == 'ubuntu-latest'
         uses: codecov/codecov-action@v5
         with:
           token: ${{ secrets.CODECOV_TOKEN }}

{engin-0.1.0b4 → engin-0.1.0rc1}/CHANGELOG.md

@@ -10,10 +10,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - Supervisor class which can safely supervise long running tasks.
-
-### Changed
-
-- `ASGIEngin.run()` now raises an error to prevent incorrect usage.
+- A new cli option `engin check` that validates whether you have any missing providers. 
+- Support for specifying `default-instance` in your `pyproject.toml` under `[tool.engin]`
+  which is used as a default value for the `app` parameter when using the cli.
 
 
 ## [0.0.20] - 2025-06-18

{engin-0.1.0b4 → engin-0.1.0rc1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: engin
-Version: 0.1.0b4
+Version: 0.1.0rc1
 Summary: An async-first modular application framework
 Project-URL: Homepage, https://github.com/invokermain/engin
 Project-URL: Documentation, https://engin.readthedocs.io/en/latest/
@@ -13,6 +13,7 @@ Requires-Python: >=3.10
 Requires-Dist: anyio>=4
 Requires-Dist: exceptiongroup>=1
 Provides-Extra: cli
+Requires-Dist: tomli>=2.0; (python_version < '3.11') and extra == 'cli'
 Requires-Dist: typer>=0.15; extra == 'cli'
 Description-Content-Type: text/markdown
 

{engin-0.1.0b4 → engin-0.1.0rc1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "engin"
-version = "0.1.0b4"
+version = "0.1.0rc1"
 description = "An async-first modular application framework"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -13,7 +13,7 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
-cli = ["typer>=0.15"]
+cli = ["typer>=0.15", "tomli>=2.0; python_version < '3.11'"]
 
 [project.scripts]
 engin = "engin._cli:app"

{engin-0.1.0b4 → engin-0.1.0rc1}/src/engin/_cli/__init__.py

@@ -9,6 +9,7 @@ except ImportError:
         " `cli` extra, e.g. pip install engin[cli]"
     ) from None
 
+from engin._cli._check import cli as check_cli
 from engin._cli._graph import cli as graph_cli
 from engin._cli._inspect import cli as inspect_cli
 
@@ -20,5 +21,6 @@ sys.path.insert(0, "")
 
 app = typer.Typer()
 
+app.add_typer(check_cli)
 app.add_typer(graph_cli)
 app.add_typer(inspect_cli)

engin-0.1.0rc1/src/engin/_cli/_check.py

@@ -0,0 +1,71 @@
+from typing import Annotated
+
+import typer
+from rich.console import Console
+
+from engin._cli._common import COMMON_HELP, get_engin_instance
+
+cli = typer.Typer()
+
+
+@cli.command(name="check")
+def check_dependencies(
+    app: Annotated[
+        str | None,
+        typer.Argument(help=COMMON_HELP["app"]),
+    ] = None,
+) -> None:
+    """
+    Validates that all dependencies are satisfied for the given engin instance.
+
+    This command checks that all providers required by invocations and other providers
+    are available. It's intended for use in CI to catch missing dependencies.
+
+    Examples:
+
+        1. `engin check`
+
+    Returns:
+        Exit code 0 if all dependencies are satisfied.
+        Exit code 1 if there are missing providers.
+    """
+    _, _, instance = get_engin_instance(app)
+
+    console = Console()
+    assembler = instance.assembler
+    missing_providers = set()
+
+    # Check dependencies for all invocations
+    for invocation in instance._invocations:
+        for param_type_id in invocation.parameter_type_ids:
+            try:
+                assembler._resolve_providers(param_type_id, set())
+            except LookupError:
+                missing_providers.add(param_type_id)
+
+    # Check dependencies for all providers
+    for provider in assembler.providers:
+        for param_type_id in provider.parameter_type_ids:
+            try:
+                assembler._resolve_providers(param_type_id, set())
+            except LookupError:
+                missing_providers.add(param_type_id)
+
+    if missing_providers:
+        sorted_missing = sorted(str(type_id) for type_id in missing_providers)
+
+        console.print("❌ Missing providers found:", style="red bold")
+        for missing_type in sorted_missing:
+            console.print(f"  • {missing_type}", style="red")
+
+        available_providers = sorted(
+            str(provider.return_type_id) for provider in assembler.providers
+        )
+        console.print("\nAvailable providers:", style="yellow")
+        for available_type in available_providers:
+            console.print(f"  • {available_type}", style="yellow")
+
+        raise typer.Exit(code=1)
+    else:
+        console.print("✅ All dependencies are satisfied!", style="green bold")
+        raise typer.Exit(code=0)

engin-0.1.0rc1/src/engin/_cli/_common.py

@@ -0,0 +1,121 @@
+import importlib
+import sys
+from pathlib import Path
+from typing import Never
+
+import typer
+from rich import print
+from rich.panel import Panel
+
+from engin import Engin
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib
+
+
+def print_error(msg: str) -> Never:
+    print(
+        Panel(
+            title="Error",
+            renderable=msg,
+            title_align="left",
+            border_style="red",
+            highlight=True,
+        )
+    )
+    raise typer.Exit(code=1)
+
+
+COMMON_HELP = {
+    "app": (
+        "The import path of your Engin instance, in the form 'package:application'"
+        ", e.g. 'app.main:engin'. If not provided, will try to use the `default-instance`"
+        " value specified in your pyproject.toml"
+    )
+}
+
+
+def _find_pyproject_toml() -> Path | None:
+    """Find pyproject.toml file starting from current directory and walking up."""
+    current_path = Path.cwd()
+
+    for path in [current_path, *current_path.parents]:
+        pyproject_path = path / "pyproject.toml"
+        if pyproject_path.exists():
+            return pyproject_path
+
+    return None
+
+
+def _get_default_engin_from_pyproject() -> str | None:
+    """Get the default engin instance from pyproject.toml."""
+    pyproject_path = _find_pyproject_toml()
+    if not pyproject_path:
+        return None
+
+    try:
+        with Path(pyproject_path).open("rb") as f:
+            data = tomllib.load(f)
+
+        tool_section = data.get("tool", {})
+        engin_section = tool_section.get("engin", {})
+        instance = engin_section.get("default-instance")
+
+        if instance is None:
+            return None
+
+        if not isinstance(instance, str):
+            print_error("value of `default-instance` is not a string")
+
+        return instance
+
+    except (OSError, tomllib.TOMLDecodeError):
+        print_error("invalid toml detected")
+
+
+NO_APP_FOUND_ERROR = (
+    "App path not specified and no default instance specified in pyproject.toml"
+)
+
+
+def get_engin_instance(app: str | None = None) -> tuple[str, str, Engin]:
+    """
+    Get an Engin instance either from the provided value or from pyproject.toml.
+
+    Args:
+        app: Optional string in format 'module:attribute'. If not provided will lookup in
+            pyproject.toml.
+
+    Returns:
+        Tuple of (module_name, engin_name, engin_instance)
+
+    Raises:
+        typer.Exit: If no app is provided and no default instance is specified in the user's
+            pyproject.toml.
+    """
+    if app is None:
+        app = _get_default_engin_from_pyproject()
+        if app is None:
+            print_error(NO_APP_FOUND_ERROR)
+
+    try:
+        module_name, engin_name = app.split(":", maxsplit=1)
+    except ValueError:
+        print_error("Expected an argument of the form 'module:attribute', e.g. 'myapp:engin'")
+
+    try:
+        module = importlib.import_module(module_name)
+    except ModuleNotFoundError:
+        print_error(f"Unable to find module '{module_name}'")
+
+    try:
+        instance = getattr(module, engin_name)
+    except AttributeError:
+        print_error(f"Module '{module_name}' has no attribute '{engin_name}'")
+
+    if not isinstance(instance, Engin):
+        print_error(f"'{app}' is not an Engin instance")
+
+    return module_name, engin_name, instance

{engin-0.1.0b4 → engin-0.1.0rc1}/src/engin/_cli/_graph.py

@@ -28,12 +28,16 @@ _APP_ORIGIN = ""
 @cli.command(name="graph")
 def serve_graph(
     app: Annotated[
-        str,
+        str | None,
         typer.Argument(help=COMMON_HELP["app"]),
-    ],
+    ] = None,
 ) -> None:
     """
     Creates a visualisation of your application's dependencies.
+
+    Examples:
+
+        1. `engin graph`
     """
     module_name, _, instance = get_engin_instance(app)
 

{engin-0.1.0b4 → engin-0.1.0rc1}/src/engin/_cli/_inspect.py

@@ -19,9 +19,9 @@ _CLI_HELP = {
 @cli.command(name="inspect")
 def serve_graph(
     app: Annotated[
-        str,
+        str | None,
         typer.Argument(help=COMMON_HELP["app"]),
-    ],
+    ] = None,
     type_: Annotated[
         str | None,
         typer.Option("--type", help=_CLI_HELP["type"]),
@@ -39,9 +39,8 @@ def serve_graph(
 
     Examples:
 
-        1. `engin inspect examples.simple.main:engin --module httpx`
-
-        2. `engin inspect examples.simple.main:engin --type AsyncClient`
+        1. `engin inspect --module httpx`
+        2. `engin inspect --type AsyncClient`
     """
     module_name, _, instance = get_engin_instance(app)
 

{engin-0.1.0b4 → engin-0.1.0rc1}/src/engin/_engin.py

@@ -10,7 +10,7 @@ from itertools import chain
 from types import FrameType
 from typing import ClassVar
 
-from anyio import create_task_group, get_cancelled_exc_class
+from anyio import create_task_group, open_signal_receiver
 
 from engin._assembler import AssembledDependency, Assembler
 from engin._dependency import Invoke, Provide, Supply
@@ -90,6 +90,7 @@ class Engin:
     """
 
     _LIB_OPTIONS: ClassVar[list[Option]] = [Provide(Lifecycle), Provide(Supervisor)]
+    _STOP_ON_SINGAL: ClassVar[bool] = True
 
     def __init__(self, *options: Option) -> None:
         """
@@ -149,7 +150,7 @@ class Engin:
             except Exception as err:
                 name = invocation.dependency.name
                 LOG.error(f"invocation '{name}' errored, exiting", exc_info=err)
-                return
+                raise
 
         lifecycle = await self._assembler.build(Lifecycle)
 
@@ -172,15 +173,17 @@ class Engin:
         self._start_complete_event.set()
 
         async with create_task_group() as tg:
-            tg.start_soon(_stop_engin_on_signal, self._stop_requested_event)
+            if self._STOP_ON_SINGAL:
+                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
+                    await self._shutdown()
+            except BaseException:
+                await self._shutdown()
+
             tg.cancel_scope.cancel()
-            await self._shutdown()
 
     async def start(self) -> None:
         """
@@ -217,7 +220,8 @@ class Engin:
         started.
         """
         self._stop_requested_event.set()
-        await self._stop_complete_event.wait()
+        if self._state == _EnginState.RUNNING:
+            await self._stop_complete_event.wait()
 
     def graph(self) -> list[Node]:
         """
@@ -236,24 +240,23 @@ class Engin:
         return self._state == _EnginState.SHUTDOWN
 
     async def _shutdown(self) -> None:
-        LOG.info("stopping engin")
-        await self._exit_stack.aclose()
-        self._stop_complete_event.set()
-        LOG.info("shutdown complete")
-        self._state = _EnginState.SHUTDOWN
+        if self._state == _EnginState.RUNNING:
+            LOG.info("stopping engin")
+            await self._exit_stack.aclose()
+            self._stop_complete_event.set()
+            LOG.info("shutdown complete")
+            self._state = _EnginState.SHUTDOWN
 
 
 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 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()
+        with open_signal_receiver(signal.SIGINT, signal.SIGTERM) as recieved_signals:
+            async for signum in recieved_signals:
+                LOG.debug(f"received {signum.name} signal")
+                stop_requested_event.set()
     else:
         should_stop = False
 

{engin-0.1.0b4 → engin-0.1.0rc1}/src/engin/extensions/asgi.py

@@ -21,6 +21,8 @@ class ASGIType(Protocol):
 
 
 class ASGIEngin(Engin, ASGIType):
+    _STOP_ON_SINGAL = False  # web server implementation is responsible for this
+
     _asgi_type: ClassVar[type[ASGIType]] = ASGIType  # type: ignore[type-abstract]
     _asgi_app: ASGIType
 

engin-0.1.0rc1/tests/acceptance/test_engin_signal_handling.py

@@ -0,0 +1,28 @@
+import asyncio
+import signal
+import sys
+
+import pytest
+
+from engin import Engin
+
+
+@pytest.mark.skipif(sys.platform == "win32", reason="`signal.raise_signal` not supported")
+async def test_engin_signal_handling_when_run():
+    engin = Engin()
+    task = asyncio.create_task(engin.run())
+    await asyncio.sleep(0.1)
+    signal.raise_signal(signal.SIGTERM)
+    await asyncio.sleep(0.1)
+    assert engin.is_stopped()
+    del task
+
+
+@pytest.mark.skipif(sys.platform == "win32", reason="`signal.raise_signal` not supported")
+async def test_engin_signal_handling_when_start():
+    engin = Engin()
+    await engin.start()
+    await asyncio.sleep(0.1)
+    signal.raise_signal(signal.SIGTERM)
+    await asyncio.sleep(0.1)
+    assert engin.is_stopped()

engin-0.1.0rc1/tests/acceptance/test_error_in_invocation.py

@@ -0,0 +1,28 @@
+import asyncio
+
+import pytest
+
+from engin import Engin, Invoke
+
+
+async def test_error_in_invocation_when_run():
+    async def main() -> None:
+        raise ValueError("foo")
+
+    engin = Engin(Invoke(main))
+
+    with pytest.raises(ValueError, match="foo"):
+        await asyncio.wait_for(engin.run(), timeout=0.5)
+
+
+async def test_error_in_invocation_when_start():
+    async def main() -> None:
+        raise ValueError("foo")
+
+    engin = Engin(Invoke(main))
+
+    with pytest.raises(ValueError, match="foo"):
+        await asyncio.wait_for(engin.start(), timeout=0.5)
+
+    # check we can shutdown the app
+    await asyncio.wait_for(engin.stop(), timeout=0.5)

engin-0.1.0b4/tests/acceptance/test_error_in_shutdown.py → engin-0.1.0rc1/tests/acceptance/test_error_in_lifecycle_shutdown.py

@@ -1,3 +1,4 @@
+import asyncio
 from contextlib import asynccontextmanager
 
 from starlette.applications import Starlette
@@ -29,13 +30,20 @@ def b(lifecycle: Lifecycle) -> None:
     lifecycle.append(_b_startup())
 
 
-async def test_error_in_shutdown():
+async def test_error_in_shutdown_when_start():
     engin = Engin(Invoke(a), Invoke(b))
 
-    await engin.start()
+    await asyncio.wait_for(engin.start(), timeout=0.5)
     assert B_LIFECYCLE_STATE == 1
 
-    await engin.stop()
+    await asyncio.wait_for(engin.stop(), timeout=0.5)
+    assert B_LIFECYCLE_STATE == 2
+
+
+async def test_error_in_shutdown_when_run():
+    engin = Engin(Invoke(a), Invoke(b))
+
+    await asyncio.wait_for(engin.run(), timeout=0.5)
     assert B_LIFECYCLE_STATE == 2
 
 

engin-0.1.0b4/tests/acceptance/test_error_in_start_up.py → engin-0.1.0rc1/tests/acceptance/test_error_in_lifecycle_startup.py

@@ -42,8 +42,11 @@ async def test_error_in_startup_handled_when_start():
     await asyncio.wait_for(engin.start(), timeout=0.5)
     assert not B_LIFECYCLE_STATE
 
+    # check we can shutdown the app
+    await asyncio.wait_for(engin.stop(), timeout=0.5)
 
-async def test_error_in_startup_asgi():
+
+async def test_error_in_startup_asgi_handled_when_run():
     def asgi_type() -> ASGIType:
         return Starlette()
 
@@ -51,3 +54,16 @@ async def test_error_in_startup_asgi():
 
     await engin.run()
     assert not B_LIFECYCLE_STATE
+
+
+async def test_error_in_startup_asgi_handled_when_start():
+    def asgi_type() -> ASGIType:
+        return Starlette()
+
+    engin = ASGIEngin(Invoke(a), Invoke(b), Provide(asgi_type))
+
+    await asyncio.wait_for(engin.start(), timeout=0.5)
+    assert not B_LIFECYCLE_STATE
+
+    # check we can shutdown the app
+    await asyncio.wait_for(engin.stop(), timeout=0.5)

engin-0.1.0rc1/tests/acceptance/test_error_in_provider.py

@@ -0,0 +1,35 @@
+import asyncio
+
+import pytest
+
+from engin import Engin, Invoke, Provide
+from engin.exceptions import ProviderError
+
+
+async def test_error_in_provider_when_run():
+    async def raise_value_error() -> int:
+        raise ValueError("foo")
+
+    async def main(foo: int) -> None:
+        return
+
+    engin = Engin(Provide(raise_value_error), Invoke(main))
+
+    with pytest.raises(ProviderError, match="foo"):
+        await asyncio.wait_for(engin.run(), timeout=0.5)
+
+
+async def test_error_in_provider_when_start():
+    async def raise_value_error() -> int:
+        raise ValueError("foo")
+
+    async def main(foo: int) -> None:
+        return
+
+    engin = Engin(Provide(raise_value_error), Invoke(main))
+
+    with pytest.raises(ProviderError, match="foo"):
+        await asyncio.wait_for(engin.start(), timeout=0.5)
+
+    # check we can shutdown the app
+    await asyncio.wait_for(engin.stop(), timeout=0.5)

engin-0.1.0b4/tests/acceptance/test_error_in_supervised_task.py → engin-0.1.0rc1/tests/acceptance/test_error_in_supervisor_task.py

@@ -15,7 +15,7 @@ def supervise(supervisor: Supervisor) -> None:
 async def test_error_in_supervised_task_handled_when_run(caplog):
     caplog.set_level(logging.INFO)
     engin = Engin(Invoke(supervise))
-    await engin.run()
+    await asyncio.wait_for(engin.run(), timeout=0.5)
     assert "Process errored" in caplog.text
     assert engin.is_stopped()
 
@@ -23,7 +23,7 @@ async def test_error_in_supervised_task_handled_when_run(caplog):
 async def test_error_in_supervised_task_handled_when_start(caplog):
     caplog.set_level(logging.INFO)
     engin = Engin(Invoke(supervise))
-    await engin.start()
+    await asyncio.wait_for(engin.start(), timeout=0.5)
     await asyncio.sleep(0.1)
     assert "Process errored" in caplog.text
     assert engin.is_stopped()

{engin-0.1.0b4 → engin-0.1.0rc1}/tests/acceptance/test_fastapi.py

@@ -54,6 +54,7 @@ def test_fastapi():
     with starlette.testclient.TestClient(engin) as client:
         result = client.get("http://127.0.0.1:8000/")
 
+    assert result.status_code == 200
     assert result.json() == "hello world"