engin 0.1.0rc1__py3-none-any.whl → 0.1.0rc2__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:
@@ -46,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):
@@ -108,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",
 }
 
@@ -74,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/_engin.py

@@ -61,8 +61,8 @@ class Engin:
        the Invoke options parameters are assembled.
     2. All Invocations are run sequentially in the order they were passed in to the Engin.
     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 for something to
-       set the ShutdownSwitch event.
+    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:

engin/_supervisor.py

@@ -58,19 +58,33 @@ class _SupervisorTask:
                 await self.factory()
                 self.complete = True
                 return
-            except get_cancelled_exc_class():
-                LOG.info(f"{self.name} cancelled")
+            except get_cancelled_exc_class() as err:
+                LOG.debug(f"supervised task '{self.name}' was cancelled", exc_info=err)
                 raise
             except Exception as err:
-                LOG.error(f"Supervisor: {self.name} raised {type(err).__name__}", exc_info=err)
                 self.last_exception = err
 
                 if self.on_exception == OnException.IGNORE:
+                    LOG.warning(
+                        f"supervisor task '{self.name}' raised {type(err).__name__} "
+                        "which will be ignored",
+                        exc_info=err,
+                    )
                     self.complete = True
                     return
                 if self.on_exception == OnException.RETRY:
+                    LOG.warning(
+                        f"supervisor task '{self.name}' raised {type(err).__name__} "
+                        "which will be retried",
+                        exc_info=err,
+                    )
                     continue
                 if self.on_exception == OnException.SHUTDOWN:
+                    LOG.error(
+                        f"supervisor task '{self.name}' raised {type(err).__name__}, "
+                        "starting shutdown",
+                        exc_info=err,
+                    )
                     self.complete = True
                     raise get_cancelled_exc_class() from None
                 assert_never(self.on_exception)

engin/exceptions.py

@@ -1,6 +1,7 @@
 from typing import TYPE_CHECKING, Any
 
 from engin._dependency import Provide
+from engin._type_utils import TypeId
 
 if TYPE_CHECKING:
     from engin._block import Block
@@ -12,12 +13,6 @@ class EnginError(Exception):
     """
 
 
-class AssemblerError(EnginError):
-    """
-    Base class for all custom exceptions raised by the Assembler.
-    """
-
-
 class InvalidBlockError(EnginError):
     """
     Raised when an invalid block is instantiated.
@@ -32,6 +27,25 @@ class InvalidBlockError(EnginError):
         return self.message
 
 
+class AssemblerError(EnginError):
+    """
+    Base class for all custom exceptions raised by the Assembler.
+    """
+
+
+class TypeNotProvidedError(AssemblerError):
+    """
+    Raised when the Assembler cannot assemble a type due to a missing Provider.
+    """
+
+    def __init__(self, type_id: TypeId) -> None:
+        self.type_id = type_id
+        self.message = f"no provider found for '{type_id}'"
+
+    def __str__(self) -> str:
+        return self.message
+
+
 class ProviderError(AssemblerError):
     """
     Raised when a Provider errors during Assembly.
@@ -77,4 +91,5 @@ __all__ = [
     "InvalidBlockError",
     "NotInScopeError",
     "ProviderError",
+    "TypeNotProvidedError",
 ]

{engin-0.1.0rc1.dist-info → engin-0.1.0rc2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: engin
-Version: 0.1.0rc1
+Version: 0.1.0rc2
 Summary: An async-first modular application framework
 Project-URL: Homepage, https://github.com/invokermain/engin
 Project-URL: Documentation, https://engin.readthedocs.io/en/latest/
@@ -33,13 +33,13 @@ Engin is a lightweight application framework powered by dependency injection, it
 you build and maintain large monoliths and many microservices.
 
 
-## Features
+## Feature
 
-The Engin framework includes:
+The Engin framework gives you:
 
 - A fully-featured dependency injection system.
 - A robust application runtime with lifecycle hooks and supervised background tasks.
-- Zero boiler-plate code reuse across multiple applications.
+- Zero boiler-plate code reuse across applications.
 - Integrations for other frameworks such as FastAPI.
 - Full async support.
 - CLI commands to aid local development.
@@ -47,7 +47,7 @@ The Engin framework includes:
 
 ## Installation
 
-Engin is available on PyPI, install using your favourite dependency manager:
+Engin is available on PyPI, install it using your favourite dependency manager:
 
 - `pip install engin`
 - `poetry add engin`
@@ -55,13 +55,13 @@ Engin is available on PyPI, install using your favourite dependency manager:
 
 ## Example
 
-A small example which shows some of the runtime features of Engin. This application
-makes a http request and then performs a shutdown.
+A small example which shows some of the features of Engin. This application
+makes 3 http requests and shuts itself down.
 
 ```python
 import asyncio
 from httpx import AsyncClient
-from engin import Engin, Invoke, Lifecycle, Provide, Supervisor
+from engin import Engin, Invoke, Lifecycle, OnException, Provide, Supervisor
 
 
 def httpx_client_factory(lifecycle: Lifecycle) -> AsyncClient:
@@ -76,13 +76,17 @@ async def main(
     httpx_client: AsyncClient,
     supervisor: Supervisor,
 ) -> None:
-    async def http_request():
-        await httpx_client.get("https://httpbin.org/get")
-        # one we've made the http request shutdown the application
-        raise asyncio.CancelledError("Forcing shutdown")
+    async def http_requests_task():
+        # simulate a background task
+        for x in range(3):
+            await httpx_client.get("https://httpbin.org/get")
+            await asyncio.sleep(1.0)
+        # raise an error to shutdown the application, normally you wouldn't do this!
+        raise RuntimeError("Forcing shutdown")
+
+    # supervise the http requests as part of the application's lifecycle
+    supervisor.supervise(http_requests_task, on_exception=OnException.SHUTDOWN)
 
-    # supervise the http request as part of the application's lifecycle
-    supervisor.supervise(http_request)
 
 # define our modular application
 engin = Engin(Provide(httpx_client_factory), Invoke(main))
@@ -97,6 +101,15 @@ With logs enabled this will output:
 INFO:engin:starting engin
 INFO:engin:startup complete
 INFO:httpx:HTTP Request: GET https://httpbin.org/get "HTTP/1.1 200 OK"
+INFO:httpx:HTTP Request: GET https://httpbin.org/get "HTTP/1.1 200 OK"
+INFO:httpx:HTTP Request: GET https://httpbin.org/get "HTTP/1.1 200 OK"
+ERROR:engin:supervisor task 'http_requests_task' raised RuntimeError, starting shutdown
+Traceback (most recent call last):
+  File "C:\dev\python\engin\src\engin\_supervisor.py", line 58, in __call__
+    await self.factory()
+  File "C:\dev\python\engin\readme_example.py", line 29, in http_requests_task
+    raise RuntimeError("Forcing shutdown")
+RuntimeError: Forcing shutdown
 INFO:engin:stopping engin
 INFO:engin:shutdown complete
 ```
@@ -106,4 +119,4 @@ INFO:engin:shutdown complete
 Engin is heavily inspired by [Uber's Fx framework for Go](https://github.com/uber-go/fx)
 and the [Injector framework for Python](https://github.com/python-injector/injector).
 
-They are both great projects, check them out.
+They are both great projects, go check them out.

{engin-0.1.0rc1.dist-info → engin-0.1.0rc2.dist-info}/RECORD

@@ -1,27 +1,27 @@
 engin/__init__.py,sha256=O0vS570kZFBq7Kwy4FgeJFIhfo4aIg5mv_Z_9vAQRio,577
-engin/_assembler.py,sha256=MC14BRsgabGlq9weyv2VXylH4RE282uNTyNH5rN8Lqc,11359
+engin/_assembler.py,sha256=0uXgtcO5M3EHg0I-TQK9y7LOzfxkLFmKia-zLyVHaxA,11178
 engin/_block.py,sha256=IacP4PoJKRhSQCbQSdoyCtmu362a4vj6qoUQKyaJwzI,3062
 engin/_dependency.py,sha256=xINk3sudxzsTmkUkNAKQwzBc0G0DfhpnrZli4z3ALBY,9459
-engin/_engin.py,sha256=Eui-CtEjlF-PaXzZXZjUdB6ByTHJJan4hFMhPDLLJuE,9537
+engin/_engin.py,sha256=oGaf_iedMNKxl3rbADpPzIvNtTx1Pfs-6o0e8yRrmHk,9532
 engin/_graph.py,sha256=y1g7Lm_Zy5GPEgRsggCKV5DDaDzcwUl8v3IZCK8jyGI,1631
 engin/_introspect.py,sha256=VdREX6Lhhga5SnEP9G7mjHkgJR4mpqk_SMnmL2zTcqY,966
 engin/_lifecycle.py,sha256=cSWe3euZkmpxmUPFvph2lsTtvuZbxttEfBL-RnOI7lo,5325
 engin/_option.py,sha256=nZcdrehp1QwgxMUoIpsM0PJuu1q1pbXzhcVsetbsHpc,223
-engin/_supervisor.py,sha256=37h036bPe7ew88WjpIOmhZwCvOdLVcvalyJgbWZr1vU,3716
+engin/_supervisor.py,sha256=HI0D4StqSJZE2l6x7RtouRLKWx1HOhUmLHqu8pUcWbQ,4343
 engin/_type_utils.py,sha256=H3Tl-kJr2wY2RhaTXP9GrMqa2RsXMijHbjHKe1AxGmc,2276
-engin/exceptions.py,sha256=-VPwPReZb9YEIkrWMR9TW2K5HEwmHHgEO7QWH6wfV8c,1946
+engin/exceptions.py,sha256=lSMOJI4Yl-VIM0yDzFWbPhC0mQm4f0WvGULr9SldIaY,2353
 engin/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 engin/_cli/__init__.py,sha256=Ixk3NoZeIN8Bj53I625uqJdLyyT9Gpbe_4GtNy-KQwM,636
-engin/_cli/_check.py,sha256=FCGFKs5kD3ImicNDz2B4aOEOliwqfoa7uAjKoZRQpHo,2274
+engin/_cli/_check.py,sha256=YA37Gi4rimKIH-XMs7SEAFkSRNBIMG8OCKfF3W1V3-g,1976
 engin/_cli/_common.py,sha256=6tyjxAkROCViw0LOFdx-X1U-iSXKyeW5CoE9UxWRybI,3282
-engin/_cli/_graph.html,sha256=rR5dnDKoz7KtSff0ERCi2UKuoH_Z03MRYiXI_W03G5k,2430
-engin/_cli/_graph.py,sha256=jvk_CPe47z2nF4yTo9T4BTAyFdy2nIsjjcZTrG2kRf0,4714
-engin/_cli/_inspect.py,sha256=0ok7yglRHF29S31K9HChnWpsuxp13cB8g1Ret1hwJrM,3122
+engin/_cli/_graph.html,sha256=YIv34LR00aWsWgjNrqO4XBNu4frPo_y-i1CijaZyySo,29073
+engin/_cli/_graph.py,sha256=MsxsNpL1v0v1AUT57ZS97l1diwacqRaPdVBObHHIGJE,6753
+engin/_cli/_inspect.py,sha256=_uzldpHA51IX4srpUGzL4lZNiepqucsO9M3Zo83XBBM,3159
 engin/extensions/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 engin/extensions/asgi.py,sha256=7vQFaVs1jxq1KbhHGN8k7x2UFab6SPUq2_hXfX6HiXU,3329
 engin/extensions/fastapi.py,sha256=7N6i-eZUEZRPo7kcvjS7kbRSY5QAPyKJXSeongSQ-OA,6371
-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,,
+engin-0.1.0rc2.dist-info/METADATA,sha256=I7BtKglKAs30NQ6n73p3gzLhZhxcvsIZXuuM356Ipa4,3951
+engin-0.1.0rc2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+engin-0.1.0rc2.dist-info/entry_points.txt,sha256=sW247zZUMxm0b5UKYvPuqQQljYDtU-j2zK3cu7gHwM0,41
+engin-0.1.0rc2.dist-info/licenses/LICENSE,sha256=XHh5LPUPKZWTBqBv2xxN2RU7D59nHoiJGb5RIt8f45w,1070
+engin-0.1.0rc2.dist-info/RECORD,,