engin 0.1.0b5__tar.gz → 0.1.0rc1__tar.gz

{engin-0.1.0b5 → 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.0b5 → engin-0.1.0rc1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: engin
-Version: 0.1.0b5
+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.0b5 → engin-0.1.0rc1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "engin"
-version = "0.1.0b5"
+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.0b5 → 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.0b5 → 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.0b5 → 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.0b5 → engin-0.1.0rc1}/src/engin/_engin.py

@@ -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:
         """
@@ -172,7 +173,8 @@ 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:

{engin-0.1.0b5 → 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.0b5 → 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"
 
 

engin-0.1.0rc1/tests/cli/test_check.py

@@ -0,0 +1,95 @@
+from typer.testing import CliRunner
+
+from engin import Engin, Invoke, Provide
+from engin._cli._check import cli
+from tests.deps import ABlock, make_str
+
+satisfied_engin = Engin(ABlock)
+
+
+def needs_missing_dependency(missing_type: int) -> None:
+    pass
+
+
+unsatisfied_engin = Engin(
+    Provide(make_str),
+    Invoke(needs_missing_dependency),
+)
+
+
+def needs_complex_type(custom_type: dict[str, int]) -> None:
+    pass
+
+
+complex_unsatisfied_engin = Engin(
+    ABlock,
+    Invoke(needs_complex_type),
+)
+
+runner = CliRunner()
+
+
+def test_check_all_dependencies_satisfied():
+    result = runner.invoke(
+        app=cli,
+        args=["tests.cli.test_check:satisfied_engin"],
+    )
+    assert result.exit_code == 0
+    assert "✅ All dependencies are satisfied!" in result.output
+
+
+def test_check_missing_dependencies():
+    result = runner.invoke(
+        app=cli,
+        args=["tests.cli.test_check:unsatisfied_engin"],
+    )
+    assert result.exit_code == 1
+    assert "❌ Missing providers found:" in result.output
+    assert "int" in result.output
+    assert "Available providers:" in result.output
+
+
+def test_check_complex_missing_dependencies():
+    result = runner.invoke(
+        app=cli,
+        args=["tests.cli.test_check:complex_unsatisfied_engin"],
+    )
+    assert result.exit_code == 1
+    assert "❌ Missing providers found:" in result.output
+    assert "dict" in result.output
+
+
+def test_check_invalid_app_path():
+    result = runner.invoke(
+        app=cli,
+        args=["tests.cli.nonexistent:engin"],
+    )
+    assert result.exit_code == 1
+    assert "Unable to find module" in result.output
+
+
+def test_check_invalid_app_attribute():
+    result = runner.invoke(
+        app=cli,
+        args=["tests.cli.test_check:nonexistent_engin"],
+    )
+    assert result.exit_code == 1
+    assert "has no attribute" in result.output
+
+
+def test_check_invalid_app_format():
+    result = runner.invoke(
+        app=cli,
+        args=["invalid_format"],
+    )
+    assert result.exit_code == 1
+    assert "Expected an argument of the form 'module:attribute'" in result.output
+
+
+def test_check_not_engin_instance():
+    result = runner.invoke(
+        app=cli,
+        args=["tests.cli.test_check:runner"],  # CliRunner is not an Engin
+    )
+    assert result.exit_code == 1
+    assert "is not an Engin instance" in result.output

engin-0.1.0rc1/tests/cli/test_get_engin_instance.py

@@ -0,0 +1,111 @@
+import tempfile
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+from click.exceptions import Exit
+
+from engin import Engin
+from engin._cli._common import get_engin_instance
+
+instance_a = Engin()
+instance_b = Engin()
+
+
+def test_get_engin_instance_with_default_from_pyproject():
+    pyproject_content = """
+[tool.engin]
+default-instance = "tests.cli.test_get_engin_instance:instance_a"
+"""
+
+    with tempfile.TemporaryDirectory() as temp_dir:
+        temp_path = Path(temp_dir)
+        pyproject_path = temp_path / "pyproject.toml"
+        pyproject_path.write_text(pyproject_content)
+
+        with patch("pathlib.Path.cwd", return_value=temp_path):
+            _, _, found_instance = get_engin_instance()
+            assert found_instance == instance_a
+
+
+def test_get_engin_instance_when_app_overrides_default():
+    pyproject_content = """
+[tool.engin]
+default-instance = "tests.cli.test_check:instance_a"
+"""
+
+    with tempfile.TemporaryDirectory() as temp_dir:
+        temp_path = Path(temp_dir)
+        pyproject_path = temp_path / "pyproject.toml"
+        pyproject_path.write_text(pyproject_content)
+
+        with patch("pathlib.Path.cwd", return_value=temp_path):
+            _, _, found_instance = get_engin_instance(
+                "tests.cli.test_get_engin_instance:instance_b"
+            )
+            assert found_instance == instance_b
+
+
+def test_get_engin_instance_with_no_default_no_app():
+    pyproject_content = """
+[project]
+name = "test"
+"""
+
+    with tempfile.TemporaryDirectory() as temp_dir:
+        temp_path = Path(temp_dir)
+        pyproject_path = temp_path / "pyproject.toml"
+        pyproject_path.write_text(pyproject_content)
+
+        with (
+            patch("pathlib.Path.cwd", return_value=temp_path),
+            pytest.raises(Exit),
+        ):
+            get_engin_instance()
+
+
+def test_get_engin_instance_with_no_default_and_no_pyproject_toml():
+    with tempfile.TemporaryDirectory() as temp_dir:
+        temp_path = Path(temp_dir)
+
+        with (
+            patch("pathlib.Path.cwd", return_value=temp_path),
+            pytest.raises(Exit),
+        ):
+            get_engin_instance()
+
+
+def test_check_with_no_default_and_invalid_toml():
+    pyproject_content = """
+[]]
+name -- test
+"""
+
+    with tempfile.TemporaryDirectory() as temp_dir:
+        temp_path = Path(temp_dir)
+        pyproject_path = temp_path / "pyproject.toml"
+        pyproject_path.write_text(pyproject_content)
+
+        with (
+            patch("pathlib.Path.cwd", return_value=temp_path),
+            pytest.raises(Exit),
+        ):
+            get_engin_instance()
+
+
+def test_check_with_no_default_and_invalid_value_type():
+    pyproject_content = """
+[tool.engin]
+default-instance = 3.1
+"""
+
+    with tempfile.TemporaryDirectory() as temp_dir:
+        temp_path = Path(temp_dir)
+        pyproject_path = temp_path / "pyproject.toml"
+        pyproject_path.write_text(pyproject_content)
+
+        with (
+            patch("pathlib.Path.cwd", return_value=temp_path),
+            pytest.raises(Exit),
+        ):
+            get_engin_instance()