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

engin/_cli/_graph.py

@@ -1,4 +1,5 @@
 import contextlib
+import json
 import socketserver
 import threading
 from http.server import BaseHTTPRequestHandler
@@ -9,9 +10,10 @@ from typing import Annotated, Any
 import typer
 from rich import print
 
-from engin import Entrypoint, Invoke, TypeId
+from engin import Engin, Entrypoint, Invoke, TypeId
 from engin._cli._common import COMMON_HELP, get_engin_instance
 from engin._dependency import Dependency, Provide, Supply
+from engin._graph import Node
 from engin.extensions.asgi import ASGIEngin
 
 try:
@@ -28,12 +30,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)
 
@@ -42,37 +48,11 @@ def serve_graph(
 
     nodes = instance.graph()
 
-    # transform dependencies into mermaid syntax
-    dependencies = [
-        f"{_render_node(node.parent)} --> {_render_node(node.node)}"
-        for node in nodes
-        if node.parent is not None
-        and not (node.node.block_name and node.node.block_name == node.parent.block_name)
-    ]
+    # Generate JSON data for interactive graph
+    graph_data = _generate_graph_data(nodes, instance)
 
-    blocks = {node.node.block_name for node in nodes if node.node.block_name is not None}
-
-    # group blocks into subgraphs
-    for block in blocks:
-        dependencies.append(f"subgraph {block}")
-        dependencies.extend(
-            [
-                f"{_render_node(node.parent, False)} --> {_render_node(node.node, False)}"
-                for node in nodes
-                if node.parent is not None
-                and node.node.block_name == block
-                and node.parent.block_name == block
-            ]
-        )
-        dependencies.append("end")
-
-    html = (
-        _GRAPH_HTML.replace("%%DATA%%", "\n".join(dependencies))
-        .replace(
-            "%%LEGEND%%",
-            ASGI_ENGIN_LEGEND if isinstance(instance, ASGIEngin) else DEFAULT_LEGEND,
-        )
-        .encode("utf8")
+    html = _GRAPH_HTML.replace("%%GRAPH_DATA%%", json.dumps(graph_data, indent=2)).encode(
+        "utf8"
     )
 
     class Handler(BaseHTTPRequestHandler):
@@ -104,47 +84,130 @@ def wait_for_interrupt() -> None:
     sleep(10000)
 
 
-_BLOCK_IDX: dict[str, int] = {}
-_SEEN_BLOCKS: list[str] = []
+def _generate_graph_data(nodes: list[Node], instance: Engin) -> dict[str, Any]:
+    """Generate JSON data structure for interactive graph rendering."""
+    all_deps = set()
+    for node in nodes:
+        all_deps.add(node.node)
+        if node.parent:
+            all_deps.add(node.parent)
+
+    # Generate node data
+    node_data = []
+    for dep in all_deps:
+        node_info = _get_node_info(dep)
+        node_data.append(node_info)
+
+    # Generate edge data
+    edge_data = [
+        {
+            "from": f"n{id(node.parent)}",
+            "to": f"n{id(node.node)}",
+            "from_block": node.parent.block_name,
+            "to_block": node.node.block_name,
+        }
+        for node in nodes
+        if node.parent is not None
+    ]
 
+    # Get block information
+    blocks = list({node.node.block_name for node in nodes if node.node.block_name is not None})
 
-def _render_node(node: Dependency, render_block: bool = True) -> str:
-    node_id = id(node)
-    md = ""
-    style = ""
+    # Generate legend
+    legend = ASGI_ENGIN_LEGEND if isinstance(instance, ASGIEngin) else DEFAULT_LEGEND
 
-    # format block name
-    if render_block and (n := node.block_name):
-        md += f"_{n}_\n"
+    return {
+        "nodes": node_data,
+        "edges": edge_data,
+        "blocks": blocks,
+        "legend": legend,
+        "app_origin": _APP_ORIGIN,
+    }
 
-    node_root_package = node.source_package.split(".", maxsplit=1)[0]
-    if node_root_package != _APP_ORIGIN:
-        if style:
-            style += "E"
-        else:
-            style = "external"
 
-    if style:
-        style = f":::{style}"
+def _get_node_info(node: Dependency) -> dict[str, Any]:
+    """Extract node information for JSON representation."""
+    node_id = f"n{id(node)}"  # Add 'n' prefix to match mermaid node IDs
+    label = ""
+    style_classes = []
 
+    # Determine if external
+    node_root_package = node.source_package.split(".", maxsplit=1)[0]
+    is_external = node_root_package != _APP_ORIGIN
+    if is_external:
+        style_classes.append("external")
+
+    # Collect detailed information for tooltips
+    details: dict[str, Any] = {
+        "full_name": node.name,
+        "source_module": node.source_module,
+        "source_package": node.source_package,
+        "parameters": [],
+        "return_type": None,
+        "scope": None,
+    }
+
+    # Get parameter information
+    if hasattr(node, "parameter_type_ids"):
+        details["parameters"] = [str(param_id) for param_id in node.parameter_type_ids]
+
+    # Determine node type and extract specific details
     if isinstance(node, Supply):
-        md += f"{_short_name(node.return_type_id)}"
-        return f'{node_id}("`{md}`"){style}'
-    if isinstance(node, Provide):
-        md += f"{_short_name(node.return_type_id)}"
-        return f'{node_id}["`{md}`"]{style}'
-    if isinstance(node, Entrypoint):
+        node_type = "Supply"
+        label += f"{_short_name(node.return_type_id)}"
+        shape = "round"
+        details["return_type"] = str(node.return_type_id)
+        if hasattr(node, "_value"):
+            details["value_type"] = type(node._value).__name__
+    elif isinstance(node, Provide):
+        node_type = "Provide"
+        label += f"{_short_name(node.return_type_id)}"
+        shape = "rect"
+        details["return_type"] = str(node.return_type_id)
+        details["factory_function"] = node.func_name
+        if node.scope:
+            details["scope"] = node.scope
+            style_classes.append(f"scope-{node.scope}")
+        if node.is_multiprovider:
+            details["multiprovider"] = True
+            style_classes.append("multi")
+    elif isinstance(node, Entrypoint):
+        node_type = "Entrypoint"
         entrypoint_type = node.parameter_type_ids[0]
-        md += f"{entrypoint_type}"
-        return f'{node_id}[/"`{md}`"\\]{style}'
-    if isinstance(node, Invoke):
-        md += f"{node.func_name}"
-        return f'{node_id}[/"`{md}`"/]{style}'
-    if isinstance(node, APIRouteDependency):
-        md += f"{node.name}"
-        return f'{node_id}[["`{md}`"]]{style}'
+        label += f"{entrypoint_type}"
+        shape = "trapezoid"
+        details["entrypoint_type"] = str(entrypoint_type)
+    elif isinstance(node, Invoke):
+        node_type = "Invoke"
+        label += f"{node.func_name}"
+        shape = "trapezoid"
+        details["function"] = node.func_name
+    elif APIRouteDependency is not None and isinstance(node, APIRouteDependency):
+        node_type = "APIRoute"
+        label += f"{node.name}"
+        shape = "subroutine"
+        if hasattr(node, "route"):
+            details["methods"] = (
+                list(node.route.methods) if hasattr(node.route, "methods") else []
+            )
+            details["path"] = getattr(node.route, "path", "")
     else:
-        return f'{node_id}["`{node.name}`"]{style}'
+        node_type = "Other"
+        label += f"{node.name}"
+        shape = "rect"
+
+    return {
+        "id": node_id,
+        "label": label,
+        "type": node_type,
+        "external": is_external,
+        "block": node.block_name,
+        "shape": shape,
+        "style_classes": style_classes,
+        "source_module": node.source_module,
+        "source_package": node.source_package,
+        "details": details,
+    }
 
 
 def _short_name(name: TypeId) -> str:

engin/_cli/_inspect.py

@@ -11,7 +11,7 @@ from engin._cli._common import COMMON_HELP, get_engin_instance, print_error
 cli = typer.Typer()
 _CLI_HELP = {
     "type": "Filter providers by the provided type, e.g. `AsyncClient` or `float[]`",
-    "module": "Filter providers by the provided types' module, e.g. `engin` or `httpx`",
+    "module": "Filter providers by the provided type's module, e.g. `engin` or `httpx`",
     "verbose": "Enables verbose output",
 }
 
@@ -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)
 
@@ -75,8 +74,11 @@ def serve_graph(
         available = sorted(map(str, instance.assembler.providers))
         print_error(f"No matching providers, available: {available}")
 
-    if matching_provider_count > 1:
-        console.print(f"Found {matching_provider_count} matching providers", style="dim")
+    console.print(
+        f"Found {matching_provider_count} matching provider"
+        + ("s" if matching_provider_count > 1 else ""),
+        style="dim",
+    )
 
     table = Table(show_header=False, show_lines=False, box=box.ASCII)
 

engin/_dependency.py

@@ -33,7 +33,7 @@ class Dependency(ABC, Option, Generic[P, T]):
     def __init__(self, func: Func[P, T]) -> None:
         self._func = func
         self._is_async = iscoroutinefunction(func)
-        self._signature = inspect.signature(self._func)
+        self._signature = inspect.signature(self._func, eval_str=True)
         self._block_name: str | None = None
 
         source_frame = get_first_external_frame()
@@ -154,24 +154,24 @@ class Entrypoint(Invoke):
 class Provide(Dependency[Any, T]):
     def __init__(
         self,
-        builder: Func[P, T],
+        factory: Func[P, T],
         *,
         scope: str | None = None,
         as_type: type | None = None,
         override: bool = False,
     ) -> None:
         """
-        Provide a type via a builder or factory function.
+        Provide a type via a factory function.
 
         Args:
-            builder: the builder function that returns the type.
+            factory: the factory function that returns the type.
             scope: (optional) associate this provider with a specific scope.
             as_type: (optional) allows you to explicitly specify the provided type, e.g.
                 to type erase a concrete type, or to provide a mock implementation.
             override: (optional) allow this provider to override other providers for the
                 same type from the same package.
         """
-        super().__init__(func=builder)
+        super().__init__(func=factory)
         self._scope = scope
         self._override = override
         self._explicit_type = as_type
@@ -231,9 +231,9 @@ class Provide(Dependency[Any, T]):
         # overwriting a dependency from the same package must be explicit
         if is_same_package and not self._override:
             msg = (
-                f"Provider '{self.name}' is implicitly overriding "
-                f"'{existing_provider.name}', if this is intended specify "
-                "`override=True` for the overriding Provider"
+                f"{self} from '{self._source_frame}' is implicitly overriding "
+                f"{existing_provider} from '{existing_provider.source_module}', if this "
+                "is intentional specify `override=True` for the overriding Provider"
             )
             raise RuntimeError(msg)
 
@@ -243,7 +243,7 @@ class Provide(Dependency[Any, T]):
         return hash(self.return_type_id)
 
     def __str__(self) -> str:
-        return f"Provide({self.return_type_id})"
+        return f"Provide(factory={self.func_name}, type={self._return_type_id})"
 
     def _resolve_return_type(self) -> type[T]:
         if self._explicit_type is not None:
@@ -279,7 +279,14 @@ class Supply(Provide, Generic[T]):
               same type from the same package.
         """
         self._value = value
-        super().__init__(builder=self._get_val, as_type=as_type, override=override)
+        super().__init__(factory=self._get_val, as_type=as_type, override=override)
+
+    @property
+    def name(self) -> str:
+        if self._block_name:
+            return f"{self._block_name}.supply"
+        else:
+            return f"{self._source_frame}.supply"
 
     def _resolve_return_type(self) -> type[T]:
         if self._explicit_type is not None:
@@ -292,4 +299,4 @@ class Supply(Provide, Generic[T]):
         return self._value
 
     def __str__(self) -> str:
-        return f"Supply({self.return_type_id})"
+        return f"Supply(value={self._value}, type={self.return_type_id})"

engin/_engin.py

@@ -2,24 +2,46 @@ import asyncio
 import logging
 import os
 import signal
-from asyncio import Event, Task
+from asyncio import Event
 from collections import defaultdict
 from contextlib import AsyncExitStack
+from enum import Enum
 from itertools import chain
 from types import FrameType
 from typing import ClassVar
 
+from anyio import create_task_group, open_signal_receiver
+
 from engin._assembler import AssembledDependency, Assembler
 from engin._dependency import Invoke, Provide, Supply
 from engin._graph import DependencyGrapher, Node
 from engin._lifecycle import Lifecycle
 from engin._option import Option
+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
+    """
+    Engin is not yet started.
+    """
+
+    RUNNING = 1
+    """
+    Engin is currently running.
+    """
+
+    SHUTDOWN = 2
+    """
+    Engin has performed shutdown
+    """
+
+
 class Engin:
     """
     The Engin is a modular application defined by a collection of options.
@@ -38,10 +60,10 @@ class Engin:
     1. The Engin assembles all Invocations. Only Providers that are required to satisfy
        the Invoke options parameters are assembled.
     2. All Invocations are run sequentially in the order they were passed in to the Engin.
-    3. Any Lifecycle Startup defined by a provider that was assembled in order to satisfy
-       the constructors is ran.
-    4. The Engin waits for a stop signal, i.e. SIGINT or SIGTERM.
-    5. Any Lifecyce Shutdown task is ran, in the reverse order to the Startup order.
+    3. Lifecycle Startup tasks registered by assembled dependencies are run sequentially.
+    4. The Engin waits for a stop signal, i.e. SIGINT or SIGTERM, or a supervised task that
+       causes a shutdown.
+    5. Lifecyce Shutdown tasks are run in the reverse order to the Startup order.
 
     Examples:
         ```python
@@ -49,11 +71,13 @@ class Engin:
 
         from httpx import AsyncClient
 
-        from engin import Engin, Invoke, Provide
+        from engin import Engin, Invoke, Lifecycle, Provide
 
 
-        def httpx_client() -> AsyncClient:
-            return AsyncClient()
+        def httpx_client(lifecycle: Lifecycle) -> AsyncClient:
+            client = AsyncClient()
+            lifecycle.append(client)
+            return client
 
 
         async def main(http_client: AsyncClient) -> None:
@@ -65,7 +89,8 @@ class Engin:
         ```
     """
 
-    _LIB_OPTIONS: ClassVar[list[Option]] = [Provide(Lifecycle)]
+    _LIB_OPTIONS: ClassVar[list[Option]] = [Provide(Lifecycle), Provide(Supervisor)]
+    _STOP_ON_SINGAL: ClassVar[bool] = True
 
     def __init__(self, *options: Option) -> None:
         """
@@ -77,14 +102,16 @@ class Engin:
         Args:
             *options: an instance of Provide, Supply, Invoke, Entrypoint or a Block.
         """
+        self._state = _EnginState.IDLE
+        self._start_complete_event = Event()
         self._stop_requested_event = Event()
         self._stop_complete_event = Event()
-        self._exit_stack: AsyncExitStack = AsyncExitStack()
-        self._shutdown_task: Task | None = None
-        self._run_task: Task | None = None
+        self._exit_stack = AsyncExitStack()
+        self._assembler = Assembler([])
+        self._async_context_run_task: asyncio.Task | None = None
 
         self._providers: dict[TypeId, Provide] = {
-            TypeId.from_type(Engin): Supply(self, as_type=Engin)
+            TypeId.from_type(Assembler): Supply(self._assembler),
         }
         self._multiproviders: dict[TypeId, list[Provide]] = defaultdict(list)
         self._invocations: list[Invoke] = []
@@ -94,7 +121,9 @@ class Engin:
             option.apply(self)
 
         multi_providers = [p for multi in self._multiproviders.values() for p in multi]
-        self._assembler = Assembler(chain(self._providers.values(), multi_providers))
+
+        for provider in chain(self._providers.values(), multi_providers):
+            self._assembler.add(provider)
 
     @property
     def assembler(self) -> Assembler:
@@ -105,20 +134,11 @@ class Engin:
         Run the engin.
 
         The engin will run until it is stopped via an external signal (i.e. SIGTERM or
-        SIGINT) or the `stop` method is called on the engin.
-        """
-        await self.start()
-        self._run_task = asyncio.create_task(_wait_for_stop_signal(self._stop_requested_event))
-        await self._stop_requested_event.wait()
-
-    async def start(self) -> None:
+        SIGINT), the `stop` method is called on the engin, or a lifecycle task errors.
         """
-        Start the engin.
+        if self._state != _EnginState.IDLE:
+            raise EnginError("Engin is not idle, unable to start")
 
-        This is an alternative to calling `run`. This method waits for the startup
-        lifecycle to complete and then returns. The caller is then responsible for
-        calling `stop`.
-        """
         LOG.info("starting engin")
         assembled_invocations: list[AssembledDependency] = [
             await self._assembler.assemble(invocation) for invocation in self._invocations
@@ -130,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)
 
@@ -146,9 +166,52 @@ class Engin:
             await self._shutdown()
             return
 
+        supervisor = await self._assembler.build(Supervisor)
+
         LOG.info("startup complete")
+        self._state = _EnginState.RUNNING
+        self._start_complete_event.set()
 
-        self._shutdown_task = asyncio.create_task(self._shutdown_when_stopped())
+        async with create_task_group() as tg:
+            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()
+
+                # shutdown after stopping supervised tasks
+                await self._shutdown()
+            except BaseException:
+                await self._shutdown()
+
+            tg.cancel_scope.cancel()
+
+    async def start(self) -> None:
+        """
+        Starts the engin in the background. This method will wait until the engin is fully
+        started to return so it is safe to use immediately after.
+        """
+        self._async_context_run_task = asyncio.create_task(self.run())
+        wait_tasks = [
+            asyncio.create_task(self._start_complete_event.wait()),
+            asyncio.create_task(self._stop_complete_event.wait()),
+        ]
+        await asyncio.wait(
+            [
+                self._async_context_run_task,  # if a provider errors this will return first
+                *wait_tasks,
+            ],
+            return_when=asyncio.FIRST_COMPLETED,
+        )
+        for task in wait_tasks:
+            task.cancel()
+
+        # raise the exception from the startup during run
+        if self._async_context_run_task.done():
+            startup_exception = self._async_context_run_task.exception()
+            if startup_exception is not None:
+                raise startup_exception
 
     async def stop(self) -> None:
         """
@@ -159,52 +222,60 @@ class Engin:
         started.
         """
         self._stop_requested_event.set()
-        if self._shutdown_task is None:
-            return
-        await self._stop_complete_event.wait()
+        if self._state == _EnginState.RUNNING:
+            await self._stop_complete_event.wait()
 
     def graph(self) -> list[Node]:
+        """
+        Creates a graph representation of the engin's dependencies which can be used for
+        introspection or visualisations.
+
+        Returns: a list of Node objects.
+        """
         grapher = DependencyGrapher({**self._providers, **self._multiproviders})
         return grapher.resolve(self._invocations)
 
+    def is_running(self) -> bool:
+        return self._state == _EnginState.RUNNING
+
+    def is_stopped(self) -> bool:
+        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")
-
-    async def _shutdown_when_stopped(self) -> None:
-        await self._stop_requested_event.wait()
-        await self._shutdown()
-
-
-async def _wait_for_stop_signal(stop_requested_event: Event) -> None:
-    try:
-        # 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()
-        else:
-            should_stop = False
-
-            # windows does not support signal_handlers, so this is the workaround
-            def ctrlc_handler(sig: int, frame: FrameType | None) -> None:
-                nonlocal should_stop
-                if should_stop:
-                    raise KeyboardInterrupt("Forced keyboard interrupt")
-                should_stop = True
-
-            signal.signal(signal.SIGINT, ctrlc_handler)
-
-            while not should_stop:
-                # In case engin is stopped via external `stop` call.
-                if stop_requested_event.is_set():
-                    return
-                await asyncio.sleep(0.1)
-
-            stop_requested_event.set()
-    except asyncio.CancelledError:
-        pass
+        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.
+    """
+    if not _OS_IS_WINDOWS:
+        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
+
+        # windows does not support signal_handlers, so this is the workaround
+        def ctrlc_handler(sig: int, frame: FrameType | None) -> None:
+            LOG.debug(f"received {signal.SIGINT.name} signal")
+            nonlocal should_stop
+            if should_stop:
+                raise KeyboardInterrupt("Forced keyboard interrupt")
+            should_stop = True
+
+        signal.signal(signal.SIGINT, ctrlc_handler)
+
+        while not should_stop:
+            # In case engin is stopped via external `stop` call.
+            if stop_requested_event.is_set():
+                return
+            await asyncio.sleep(0.1)
+
+        stop_requested_event.set()