engin 0.0.19__py3-none-any.whl → 0.1.0__py3-none-any.whl

engin/__init__.py

@@ -4,6 +4,7 @@ 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._supervisor import OnException, Supervisor
 from engin._type_utils import TypeId
 
 __all__ = [
@@ -13,8 +14,10 @@ __all__ = [
     "Entrypoint",
     "Invoke",
     "Lifecycle",
+    "OnException",
     "Option",
     "Provide",
+    "Supervisor",
     "Supply",
     "TypeId",
     "invoke",

engin/_assembler.py

@@ -10,7 +10,7 @@ from typing import Any, Generic, TypeVar, cast
 
 from engin._dependency import Dependency, Provide, Supply
 from engin._type_utils import TypeId
-from engin.exceptions import NotInScopeError, ProviderError
+from engin.exceptions import NotInScopeError, ProviderError, TypeNotProvidedError
 
 LOG = logging.getLogger("engin")
 
@@ -65,7 +65,7 @@ class Assembler:
         self._multiproviders: dict[TypeId, list[Provide[list[Any]]]] = defaultdict(list)
         self._assembled_outputs: dict[TypeId, Any] = {}
         self._lock = asyncio.Lock()
-        self._graph_cache: dict[TypeId, set[Provide]] = defaultdict(set)
+        self._graph_cache: dict[TypeId, list[Provide]] = defaultdict(list)
 
         for provider in providers:
             type_id = provider.return_type_id
@@ -111,7 +111,7 @@ class Assembler:
             type_: the type of the desired value to build.
 
         Raises:
-            LookupError: When no provider is found for the given type.
+            TypeNotProvidedError: When no provider is found for the given type.
             ProviderError: When a provider errors when trying to construct the type or
                 any of its dependent types.
 
@@ -123,7 +123,7 @@ class Assembler:
             return cast("T", self._assembled_outputs[type_id])
         if type_id.multi:
             if type_id not in self._multiproviders:
-                raise LookupError(f"no provider found for target type id '{type_id}'")
+                raise TypeNotProvidedError(type_id)
 
             out = []
             for provider in self._multiproviders[type_id]:
@@ -142,7 +142,7 @@ class Assembler:
             return out  # type: ignore[return-value]
         else:
             if type_id not in self._providers:
-                raise LookupError(f"no provider found for target type id '{type_id}'")
+                raise TypeNotProvidedError(type_id)
 
             provider = self._providers[type_id]
             if provider.scope and provider.scope not in _get_scope():
@@ -206,10 +206,10 @@ class Assembler:
             if provider.scope == scope:
                 self._assembled_outputs.pop(type_id, None)
 
-    def _resolve_providers(self, type_id: TypeId, resolved: set[TypeId]) -> set[Provide]:
+    def _resolve_providers(self, type_id: TypeId, resolved: set[TypeId]) -> Iterable[Provide]:
         """
         Resolves the chain of providers required to satisfy the provider of a given type.
-        Ordering of the return value is very important!
+        Ordering of the return value is very important here!
         """
         if type_id in self._graph_cache:
             return self._graph_cache[type_id]
@@ -226,18 +226,18 @@ class Assembler:
                 # store default to prevent the warning appearing multiple times
                 self._multiproviders[type_id] = root_providers
             else:
-                available = sorted(str(k) for k in self._providers)
-                msg = f"Missing Provider for type '{type_id}', available: {available}"
-                raise LookupError(msg)
+                raise TypeNotProvidedError(type_id)
 
         # providers that must be satisfied to satisfy the root level providers
-        resolved_providers = {
+        resolved_providers = [
             child_provider
             for root_provider in root_providers
             for root_provider_param in root_provider.parameter_type_ids
             for child_provider in self._resolve_providers(root_provider_param, resolved)
             if root_provider_param not in resolved
-        } | set(root_providers)
+        ]
+
+        resolved_providers.extend(root_providers)
 
         resolved.add(type_id)
         self._graph_cache[type_id] = resolved_providers

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/_cli/_check.py

@@ -0,0 +1,56 @@
+from typing import Annotated
+
+import typer
+from rich.console import Console
+
+from engin._cli._common import COMMON_HELP, get_engin_instance
+from engin.exceptions import TypeNotProvidedError
+
+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()
+
+    for invocation in instance._invocations:
+        for param_type_id in invocation.parameter_type_ids:
+            try:
+                assembler._resolve_providers(param_type_id, set())
+            except TypeNotProvidedError:
+                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")
+
+        raise typer.Exit(code=1)
+    else:
+        console.print("✅ All dependencies are satisfied!", style="green bold")
+        raise typer.Exit(code=0)

engin/_cli/_common.py

@@ -1,4 +1,6 @@
 import importlib
+import sys
+from pathlib import Path
 from typing import Never
 
 import typer
@@ -7,6 +9,11 @@ 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(
@@ -24,12 +31,75 @@ def print_error(msg: str) -> Never:
 COMMON_HELP = {
     "app": (
         "The import path of your Engin instance, in the form 'package:application'"
-        ", e.g. 'app.main:engin'"
+        ", e.g. 'app.main:engin'. If not provided, will try to use the `default-instance`"
+        " value specified in your pyproject.toml"
     )
 }
 
 
-def get_engin_instance(app: str) -> tuple[str, str, Engin]:
+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: