engin 0.1.0b4__py3-none-any.whl → 0.1.0rc1__py3-none-any.whl

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,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/_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:

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/_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/_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/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.0b4.dist-info → engin-0.1.0rc1.dist-info}/METADATA

@@ -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.dist-info → engin-0.1.0rc1.dist-info}/RECORD

@@ -2,7 +2,7 @@ engin/__init__.py,sha256=O0vS570kZFBq7Kwy4FgeJFIhfo4aIg5mv_Z_9vAQRio,577
 engin/_assembler.py,sha256=MC14BRsgabGlq9weyv2VXylH4RE282uNTyNH5rN8Lqc,11359
 engin/_block.py,sha256=IacP4PoJKRhSQCbQSdoyCtmu362a4vj6qoUQKyaJwzI,3062
 engin/_dependency.py,sha256=xINk3sudxzsTmkUkNAKQwzBc0G0DfhpnrZli4z3ALBY,9459
-engin/_engin.py,sha256=GASnv9x0Qrrok_4zGbaFm7wWZqYNAZ55w0vU3Z-gn8g,9343
+engin/_engin.py,sha256=Eui-CtEjlF-PaXzZXZjUdB6ByTHJJan4hFMhPDLLJuE,9537
 engin/_graph.py,sha256=y1g7Lm_Zy5GPEgRsggCKV5DDaDzcwUl8v3IZCK8jyGI,1631
 engin/_introspect.py,sha256=VdREX6Lhhga5SnEP9G7mjHkgJR4mpqk_SMnmL2zTcqY,966
 engin/_lifecycle.py,sha256=cSWe3euZkmpxmUPFvph2lsTtvuZbxttEfBL-RnOI7lo,5325
@@ -11,16 +11,17 @@ engin/_supervisor.py,sha256=37h036bPe7ew88WjpIOmhZwCvOdLVcvalyJgbWZr1vU,3716
 engin/_type_utils.py,sha256=H3Tl-kJr2wY2RhaTXP9GrMqa2RsXMijHbjHKe1AxGmc,2276
 engin/exceptions.py,sha256=-VPwPReZb9YEIkrWMR9TW2K5HEwmHHgEO7QWH6wfV8c,1946
 engin/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-engin/_cli/__init__.py,sha256=koD5WTkZXb8QQIiVU5bJiSR1wwPGb5rv2iwd-v-BA7A,564
-engin/_cli/_common.py,sha256=zMYb1Bs1yUuR3qf3r6WuVozYzDwHJvTVthVbTQfTF9w,1261
+engin/_cli/__init__.py,sha256=Ixk3NoZeIN8Bj53I625uqJdLyyT9Gpbe_4GtNy-KQwM,636
+engin/_cli/_check.py,sha256=FCGFKs5kD3ImicNDz2B4aOEOliwqfoa7uAjKoZRQpHo,2274
+engin/_cli/_common.py,sha256=6tyjxAkROCViw0LOFdx-X1U-iSXKyeW5CoE9UxWRybI,3282
 engin/_cli/_graph.html,sha256=rR5dnDKoz7KtSff0ERCi2UKuoH_Z03MRYiXI_W03G5k,2430
-engin/_cli/_graph.py,sha256=HMC91nWvTOr6_czPBNx1RU55Ib3qesJRCmbnL2DsdDk,4659
-engin/_cli/_inspect.py,sha256=0jm25d4wcbXVNJkyaeECSKY-irsxd-EIYBH1GDW_Yjc,3163
+engin/_cli/_graph.py,sha256=jvk_CPe47z2nF4yTo9T4BTAyFdy2nIsjjcZTrG2kRf0,4714
+engin/_cli/_inspect.py,sha256=0ok7yglRHF29S31K9HChnWpsuxp13cB8g1Ret1hwJrM,3122
 engin/extensions/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-engin/extensions/asgi.py,sha256=d5Z6gtMVWDZdAlvrTaMt987sKyiq__A0X4gJQ7IETmA,3247
+engin/extensions/asgi.py,sha256=7vQFaVs1jxq1KbhHGN8k7x2UFab6SPUq2_hXfX6HiXU,3329
 engin/extensions/fastapi.py,sha256=7N6i-eZUEZRPo7kcvjS7kbRSY5QAPyKJXSeongSQ-OA,6371
-engin-0.1.0b4.dist-info/METADATA,sha256=GrfuoOkM35Dcjdjzf22LlZ_EgHhn7KtzMGEOybLhoxo,3201
-engin-0.1.0b4.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-engin-0.1.0b4.dist-info/entry_points.txt,sha256=sW247zZUMxm0b5UKYvPuqQQljYDtU-j2zK3cu7gHwM0,41
-engin-0.1.0b4.dist-info/licenses/LICENSE,sha256=XHh5LPUPKZWTBqBv2xxN2RU7D59nHoiJGb5RIt8f45w,1070
-engin-0.1.0b4.dist-info/RECORD,,
+engin-0.1.0rc1.dist-info/METADATA,sha256=oKmRR7rU91tH7IQIZqi9gMUrdYIBi1ghO_O4R8Gz8qQ,3274
+engin-0.1.0rc1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+engin-0.1.0rc1.dist-info/entry_points.txt,sha256=sW247zZUMxm0b5UKYvPuqQQljYDtU-j2zK3cu7gHwM0,41
+engin-0.1.0rc1.dist-info/licenses/LICENSE,sha256=XHh5LPUPKZWTBqBv2xxN2RU7D59nHoiJGb5RIt8f45w,1070
+engin-0.1.0rc1.dist-info/RECORD,,