engin 0.0.8__py3-none-any.whl → 0.0.9__py3-none-any.whl

engin/_block.py

@@ -59,6 +59,8 @@ class Block(Iterable[Provide | Invoke]):
                     raise RuntimeError("Block option is not an instance of Provide or Invoke")
                 opt.set_block_name(self._name)
                 self._options.append(opt)
+        for opt in self.options:
+            opt.set_block_name(self._name)
 
     @property
     def name(self) -> str:

engin/_dependency.py

@@ -31,13 +31,23 @@ class Dependency(ABC, Generic[P, T]):
         self._block_name = block_name
 
     @property
-    def module(self) -> str:
+    def origin(self) -> str:
+        """
+        The module that this Dependency originated from.
+
+        Returns:
+            A string, e.g. "examples.fastapi.app"
+        """
         return self._func.__module__
 
     @property
     def block_name(self) -> str | None:
         return self._block_name
 
+    @property
+    def func_name(self) -> str:
+        return self._func.__name__
+
     @property
     def name(self) -> str:
         if self._block_name:
@@ -105,6 +115,10 @@ class Entrypoint(Invoke):
         self._type = type_
         super().__init__(invocation=_noop, block_name=block_name)
 
+    @property
+    def origin(self) -> str:
+        return self._type.__module__
+
     @property
     def parameter_types(self) -> list[TypeId]:
         return [type_id_of(self._type)]
@@ -172,6 +186,10 @@ class Supply(Provide, Generic[T]):
             self._get_val.__annotations__["return"] = type_hint
         super().__init__(builder=self._get_val, block_name=block_name)
 
+    @property
+    def origin(self) -> str:
+        return self._value.__module__
+
     @property
     def return_type(self) -> type[T]:
         if self._type_hint is not None:

engin/_graph.py

@@ -1,39 +1,50 @@
 from collections.abc import Iterable
-from typing import TypedDict
+from dataclasses import dataclass
 
-from engin._dependency import Dependency, Provide
+from engin import Provide
+from engin._dependency import Dependency
 from engin._type_utils import TypeId
 
 
-class Node(TypedDict):
+@dataclass(slots=True, frozen=True, kw_only=True)
+class Node:
+    """
+    A Node in the Dependency Graph.
+    """
+
     node: Dependency
     parent: Dependency | None
 
+    def __repr__(self) -> str:
+        return f"Node(node={self.node!s},parent={self.parent!s})"
+
 
 class DependencyGrapher:
     def __init__(self, providers: dict[TypeId, Provide | list[Provide]]) -> None:
         self._providers: dict[TypeId, Provide | list[Provide]] = providers
 
     def resolve(self, roots: Iterable[Dependency]) -> list[Node]:
-        seen: set[TypeId] = set()
-        nodes: list[Node] = []
+        return self._resolve_recursive(roots, seen=set())
 
+    def _resolve_recursive(
+        self, roots: Iterable[Dependency], *, seen: set[TypeId]
+    ) -> list[Node]:
+        nodes: list[Node] = []
         for root in roots:
             for parameter in root.parameter_types:
-                if parameter in seen:
-                    continue
-
-                seen.add(parameter)
                 provider = self._providers[parameter]
 
                 # multiprovider
                 if isinstance(provider, list):
-                    for p in provider:
-                        nodes.append({"node": p, "parent": root})
-                        nodes.extend(self.resolve([p]))
+                    nodes.extend(Node(node=p, parent=root) for p in provider)
+                    if parameter not in seen:
+                        nodes.extend(self._resolve_recursive(provider, seen=seen))
                 # single provider
                 else:
-                    nodes.append({"node": provider, "parent": root})
-                    nodes.extend(self.resolve([provider]))
+                    nodes.append(Node(node=provider, parent=root))
+                    if parameter not in seen:
+                        nodes.extend(self._resolve_recursive([provider], seen=seen))
+
+                seen.add(parameter)
 
         return nodes

engin/ext/asgi.py

@@ -2,10 +2,11 @@ import traceback
 from collections.abc import Awaitable, Callable, MutableMapping
 from typing import Any, ClassVar, Protocol, TypeAlias
 
-from engin import Engin, Option
+from engin import Engin, Entrypoint, Option
 
 __all__ = ["ASGIEngin", "ASGIType"]
 
+from engin._graph import DependencyGrapher, Node
 
 _Scope: TypeAlias = MutableMapping[str, Any]
 _Message: TypeAlias = MutableMapping[str, Any]
@@ -49,6 +50,10 @@ class ASGIEngin(Engin, ASGIType):
         await self.start()
         self._asgi_app = await self._assembler.get(self._asgi_type)
 
+    def graph(self) -> list[Node]:
+        grapher = DependencyGrapher({**self._providers, **self._multiproviders})
+        return grapher.resolve([Entrypoint(self._asgi_type), *self._invocations])
+
 
 class _Rereceive:
     def __init__(self, message: _Message) -> None:

engin/ext/fastapi.py

@@ -1,10 +1,19 @@
+import inspect
+import typing
+from collections.abc import Iterable
+from inspect import Parameter
 from typing import ClassVar, TypeVar
 
-from engin import Engin, Invoke, Option
+from fastapi.routing import APIRoute
+
+from engin import Engin, Entrypoint, Invoke, Option
+from engin._dependency import Dependency, Supply
+from engin._graph import DependencyGrapher, Node
+from engin._type_utils import TypeId, type_id_of
 from engin.ext.asgi import ASGIEngin
 
 try:
-    from fastapi import FastAPI
+    from fastapi import APIRouter, FastAPI
     from fastapi.params import Depends
     from starlette.requests import HTTPConnection
 except ImportError as err:
@@ -12,7 +21,7 @@ except ImportError as err:
         "fastapi package must be installed to use the fastapi extension"
     ) from err
 
-__all__ = ["FastAPIEngin", "Inject"]
+__all__ = ["APIRouteDependency", "FastAPIEngin", "Inject"]
 
 
 def _attach_engin(
@@ -26,6 +35,15 @@ class FastAPIEngin(ASGIEngin):
     _LIB_OPTIONS: ClassVar[list[Option]] = [*ASGIEngin._LIB_OPTIONS, Invoke(_attach_engin)]
     _asgi_type = FastAPI
 
+    def graph(self) -> list[Node]:
+        grapher = _FastAPIDependencyGrapher({**self._providers, **self._multiproviders})
+        return grapher.resolve(
+            [
+                Entrypoint(self._asgi_type),
+                *[i for i in self._invocations if i.func_name != "_attach_engin"],
+            ]
+        )
+
 
 T = TypeVar("T")
 
@@ -35,4 +53,116 @@ def Inject(interface: type[T]) -> Depends:
         engin: Engin = conn.app.state.engin
         return await engin.assembler.get(interface)
 
-    return Depends(inner)
+    dep = Depends(inner)
+    dep.__engin__ = True  # type: ignore[attr-defined]
+    return dep
+
+
+class _FastAPIDependencyGrapher(DependencyGrapher):
+    """
+    This exists in order to bridge the gap between
+    """
+
+    def _resolve_recursive(
+        self, roots: Iterable[Dependency], *, seen: set[TypeId]
+    ) -> list[Node]:
+        nodes: list[Node] = []
+        for root in roots:
+            for parameter in root.parameter_types:
+                provider = self._providers[parameter]
+
+                # multiprovider
+                if isinstance(provider, list):
+                    for p in provider:
+                        nodes.append(Node(node=p, parent=root))
+
+                        if isinstance(p, Supply):
+                            route_dependencies = _extract_routes_from_supply(p)
+                            nodes.extend(
+                                Node(node=route_dependency, parent=p)
+                                for route_dependency in route_dependencies
+                            )
+                            nodes.extend(
+                                self._resolve_recursive(route_dependencies, seen=seen)
+                            )
+
+                        if parameter not in seen:
+                            nodes.extend(self._resolve_recursive(provider, seen=seen))
+                # single provider
+                else:
+                    nodes.append(Node(node=provider, parent=root))
+                    # not sure why anyone would ever supply a single APIRouter in an
+                    # application, but just in case
+                    if isinstance(provider, Supply):
+                        route_dependencies = _extract_routes_from_supply(provider)
+                        nodes.extend(
+                            Node(node=route_dependency, parent=provider)
+                            for route_dependency in route_dependencies
+                        )
+                        nodes.extend(self._resolve_recursive(route_dependencies, seen=seen))
+                    if parameter not in seen:
+                        nodes.extend(self._resolve_recursive([provider], seen=seen))
+
+                seen.add(parameter)
+
+        return nodes
+
+
+def _extract_routes_from_supply(supply: Supply) -> list[Dependency]:
+    if supply.is_multiprovider:
+        inner = supply._value[0]
+        if isinstance(inner, APIRouter):
+            return [
+                APIRouteDependency(route, block_name=supply.block_name)
+                for route in inner.routes
+                if isinstance(route, APIRoute)
+            ]
+    return []
+
+
+class APIRouteDependency(Dependency):
+    """
+    This is a pseudo-dependency that is only used when calling FastAPIEngin.graph() in
+    order to provide richer metadata to the Node.
+
+    This class should never be constructed in application code.
+    """
+
+    def __init__(self, route: APIRoute, block_name: str | None = None) -> None:
+        """
+        Warning: this should never be constructed in application code.
+        """
+        self._route = route
+        self._signature = inspect.signature(route.endpoint)
+        self._block_name = block_name
+
+    @property
+    def route(self) -> APIRoute:
+        return self._route
+
+    @property
+    def parameter_types(self) -> list[TypeId]:
+        parameters = list(self._signature.parameters.values())
+        if not parameters:
+            return []
+        if parameters[0].name == "self":
+            parameters.pop(0)
+        return [
+            type_id_of(typing.get_args(param.annotation)[0])
+            for param in parameters
+            if self._is_injected_param(param)
+        ]
+
+    @staticmethod
+    def _is_injected_param(param: Parameter) -> bool:
+        if typing.get_origin(param.annotation) != typing.Annotated:
+            return False
+        args = typing.get_args(param.annotation)
+        if len(args) != 2:
+            return False
+        return isinstance(args[1], Depends) and hasattr(args[1], "__engin__")
+
+    @property
+    def name(self) -> str:
+        methods = ",".join(self._route.methods)
+        return f"{methods} {self._route.path}"

engin/scripts/graph.py

@@ -8,8 +8,10 @@ from http.server import BaseHTTPRequestHandler
 from time import sleep
 from typing import Any
 
-from engin import Engin
-from engin._dependency import Dependency, Provide
+from engin import Engin, Entrypoint, Invoke
+from engin._dependency import Dependency, Provide, Supply
+from engin.ext.asgi import ASGIEngin
+from engin.ext.fastapi import APIRouteDependency
 
 # mute logging from importing of files + engin's debug logging.
 logging.disable()
@@ -18,9 +20,6 @@ args = ArgumentParser(
     prog="engin-graph",
     description="Creates a visualisation of your application's dependencies",
 )
-args.add_argument(
-    "-e", "--exclude", help="a list of packages or module to exclude", default=["engin"]
-)
 args.add_argument(
     "app",
     help=(
@@ -37,7 +36,6 @@ def serve_graph() -> None:
     parsed = args.parse_args()
 
     app = parsed.app
-    excluded_modules = parsed.exclude
 
     try:
         module_name, engin_name = app.split(":", maxsplit=1)
@@ -60,13 +58,19 @@ def serve_graph() -> None:
 
     # transform dependencies into mermaid syntax
     dependencies = [
-        f"{_render_node(node['parent'])} --> {_render_node(node['node'])}"
+        f"{_render_node(node.parent)} --> {_render_node(node.node)}"
         for node in nodes
-        if node["parent"] is not None
-        and not _should_exclude(node["node"].module, excluded_modules)
+        if node.parent is not None
     ]
 
-    html = _GRAPH_HTML.replace("%%DATA%%", "\n".join(dependencies)).encode("utf8")
+    html = (
+        _GRAPH_HTML.replace("%%DATA%%", "\n".join(dependencies))
+        .replace(
+            "%%LEGEND%%",
+            ASGI_ENGIN_LEGEND if isinstance(instance, ASGIEngin) else DEFAULT_LEGEND,
+        )
+        .encode("utf8")
+    )
 
     class Handler(BaseHTTPRequestHandler):
         def do_GET(self) -> None:
@@ -93,24 +97,66 @@ def serve_graph() -> None:
         print("Exiting the server...")
 
 
+_BLOCK_IDX: dict[str, int] = {}
+_SEEN_BLOCKS: list[str] = []
+
+
 def _render_node(node: Dependency) -> str:
+    node_id = id(node)
+    md = ""
+    style = ""
+
+    # format block name
+    if n := node.block_name:
+        md += f"_{n}_\n"
+        if n not in _BLOCK_IDX:
+            _BLOCK_IDX[n] = len(_SEEN_BLOCKS) % 8
+            _SEEN_BLOCKS.append(n)
+        style = f":::b{_BLOCK_IDX[n]}"
+
+    if isinstance(node, Supply):
+        md += f"{node.return_type_id}"
+        return f'{node_id}("`{md}`"){style}'
     if isinstance(node, Provide):
-        return str(node.return_type_id)
+        md += f"{node.return_type_id}"
+        return f'{node_id}["`{md}`"]{style}'
+    if isinstance(node, Entrypoint):
+        entrypoint_type = node.parameter_types[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}'
     else:
-        return node.name
-
-
-def _should_exclude(module: str, excluded: list[str]) -> bool:
-    return any(module.startswith(e) for e in excluded)
+        return f'{node_id}["`{node.name}`"]{style}'
 
 
 _GRAPH_HTML = """
 <!doctype html>
 <html lang="en">
   <body>
+    <div style="border-style:outset">
+        <p>LEGEND</p>
+        <pre class="mermaid">
+          graph LR
+            %%LEGEND%%
+            classDef b0 fill:#7fc97f;
+        </pre>
+    </div>
     <pre class="mermaid">
       graph TD
           %%DATA%%
+          classDef b0 fill:#7fc97f;
+          classDef b1 fill:#beaed4;
+          classDef b2 fill:#fdc086;
+          classDef b3 fill:#ffff99;
+          classDef b4 fill:#386cb0;
+          classDef b5 fill:#f0027f;
+          classDef b6 fill:#bf5b17;
+          classDef b7 fill:#666666;
     </pre>
     <script type="module">
       import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
@@ -120,3 +166,9 @@ _GRAPH_HTML = """
   </body>
 </html>
 """
+
+DEFAULT_LEGEND = (
+    "0[/Invoke/] ~~~ 1[/Entrypoint\\] ~~~ 2[Provide] ~~~ 3(Supply)"
+    ' ~~~ 4["`Block Grouping`"]:::b0'
+)
+ASGI_ENGIN_LEGEND = DEFAULT_LEGEND + " ~~~ 5[[API Route]]"

{engin-0.0.8.dist-info → engin-0.0.9.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: engin
-Version: 0.0.8
+Version: 0.0.9
 Summary: An async-first modular application framework
 Project-URL: Homepage, https://github.com/invokermain/engin
 Project-URL: Documentation, https://engin.readthedocs.io/en/latest/

engin-0.0.9.dist-info/RECORD

@@ -0,0 +1,20 @@
+engin/__init__.py,sha256=yTc8k0HDGMIrxDdEEA90qGD_dExQjVIbXCyaOFRrnMg,508
+engin/_assembler.py,sha256=VCZA_Gq4hnH5LueB_vEVqsKbGXx-nI6KQ65YhzXw-VY,7575
+engin/_block.py,sha256=0QJtqyP5uTFjXsdVGr4ZONLI2LhfzUKmQGnNQWouB3o,2121
+engin/_dependency.py,sha256=Nmyk4cGcK6ZZA8YWNZWgckLpDdKsRwOeRQhqRlxZmI0,5883
+engin/_engin.py,sha256=i2IxMIz-3yKjedyg5L6gQEpdFDUZnCbXi9Pwhw8Hsxk,9133
+engin/_exceptions.py,sha256=fsc4pTOIGHUh0x7oZhEXPJUTE268sIhswLoiqXaudiw,635
+engin/_graph.py,sha256=1pMB0cr--uS0XJycDb1rS_X45RBpoyA6NkKqbeSuz1Q,1628
+engin/_lifecycle.py,sha256=_jQnGFj4RYXsxMpcXPJQagFOwnoTVh7oSN8oUYoYuW0,3246
+engin/_type_utils.py,sha256=C71kX2Dr-gluGSL018K4uihX3zkTe7QNWaHhFU10ZmA,2127
+engin/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+engin/ext/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+engin/ext/asgi.py,sha256=ViAWw-PNaP6y5fHK2rSGRfaxj7xxo217eqU2z2rhnq8,2200
+engin/ext/fastapi.py,sha256=p9NekfRHbdNzK_1ttVNr500AO-IwLpBlG9Fhk6R0mmg,5649
+engin/scripts/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+engin/scripts/graph.py,sha256=kmC_sSypGvIH89GddHz3KoRBEvooGNsGtrwLgw_uxNQ,4968
+engin-0.0.9.dist-info/METADATA,sha256=fzCqyXhGBzC1hMcTtbRM9-oXVaHEP000abzPi9QZbFQ,2161
+engin-0.0.9.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+engin-0.0.9.dist-info/entry_points.txt,sha256=Dehk4j5nK6zyuQtgOSRAoLE609V6eLzEp32bjqhO62Q,64
+engin-0.0.9.dist-info/licenses/LICENSE,sha256=XHh5LPUPKZWTBqBv2xxN2RU7D59nHoiJGb5RIt8f45w,1070
+engin-0.0.9.dist-info/RECORD,,

engin-0.0.8.dist-info/RECORD

@@ -1,20 +0,0 @@
-engin/__init__.py,sha256=yTc8k0HDGMIrxDdEEA90qGD_dExQjVIbXCyaOFRrnMg,508
-engin/_assembler.py,sha256=VCZA_Gq4hnH5LueB_vEVqsKbGXx-nI6KQ65YhzXw-VY,7575
-engin/_block.py,sha256=-5qTp1Hdm3H54nScDGitFpcXRHLIyVHlDYATg_3dnPw,2045
-engin/_dependency.py,sha256=WjJKJY2KhseYpqM1Gg-VhYls4dcLg1CgdlpniJEUHjI,5489
-engin/_engin.py,sha256=i2IxMIz-3yKjedyg5L6gQEpdFDUZnCbXi9Pwhw8Hsxk,9133
-engin/_exceptions.py,sha256=fsc4pTOIGHUh0x7oZhEXPJUTE268sIhswLoiqXaudiw,635
-engin/_graph.py,sha256=piqcocrWt0mX_UAr0DVdkCtVYjkjVpkikLCdRVCoUnU,1230
-engin/_lifecycle.py,sha256=_jQnGFj4RYXsxMpcXPJQagFOwnoTVh7oSN8oUYoYuW0,3246
-engin/_type_utils.py,sha256=C71kX2Dr-gluGSL018K4uihX3zkTe7QNWaHhFU10ZmA,2127
-engin/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-engin/ext/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-engin/ext/asgi.py,sha256=6vuC4zIhsvAdmwRn2I6uuUWPYfqobox1dv7skg2OWwE,1940
-engin/ext/fastapi.py,sha256=CH2Zi7Oh_Va0TJGx05e7_LqAiCsoI1qcu0Z59_rgfRk,899
-engin/scripts/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-engin/scripts/graph.py,sha256=f_Yk4TRrw9N-gltdriiOviNGcowQckeM2R-7CPVXkHY,3424
-engin-0.0.8.dist-info/METADATA,sha256=xX0-36ECkPFBcDsYjiY04-dhn-066fQhKKzEceUPkhQ,2161
-engin-0.0.8.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-engin-0.0.8.dist-info/entry_points.txt,sha256=Dehk4j5nK6zyuQtgOSRAoLE609V6eLzEp32bjqhO62Q,64
-engin-0.0.8.dist-info/licenses/LICENSE,sha256=XHh5LPUPKZWTBqBv2xxN2RU7D59nHoiJGb5RIt8f45w,1070
-engin-0.0.8.dist-info/RECORD,,