engin 0.0.7__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

@@ -18,7 +18,6 @@ from engin._type_utils import TypeId, type_id_of
 P = ParamSpec("P")
 T = TypeVar("T")
 Func: TypeAlias = Callable[P, T]
-_SELF = object()
 
 
 def _noop(*args: Any, **kwargs: Any) -> None: ...
@@ -31,10 +30,24 @@ class Dependency(ABC, Generic[P, T]):
         self._signature = inspect.signature(self._func)
         self._block_name = block_name
 
+    @property
+    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:
@@ -102,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)]
@@ -169,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/_engin.py

@@ -13,6 +13,7 @@ from engin import Entrypoint
 from engin._assembler import AssembledDependency, Assembler
 from engin._block import Block
 from engin._dependency import Dependency, Invoke, Provide, Supply
+from engin._graph import DependencyGrapher, Node
 from engin._lifecycle import Lifecycle
 from engin._type_utils import TypeId
 
@@ -80,7 +81,6 @@ class Engin:
         Args:
             *options: an instance of Provide, Supply, Invoke, Entrypoint or a Block.
         """
-
         self._stop_requested_event = Event()
         self._stop_complete_event = Event()
         self._exit_stack: AsyncExitStack = AsyncExitStack()
@@ -95,8 +95,6 @@ class Engin:
         self._destruct_options(chain(self._LIB_OPTIONS, options))
         multi_providers = [p for multi in self._multiproviders.values() for p in multi]
         self._assembler = Assembler(chain(self._providers.values(), multi_providers))
-        self._providers.clear()
-        self._multiproviders.clear()
 
     @property
     def assembler(self) -> Assembler:
@@ -162,6 +160,10 @@ class Engin:
             return
         await self._stop_complete_event.wait()
 
+    def graph(self) -> list[Node]:
+        grapher = DependencyGrapher({**self._providers, **self._multiproviders})
+        return grapher.resolve(self._invocations)
+
     async def _shutdown(self) -> None:
         LOG.info("stopping engin")
         await self._exit_stack.aclose()

engin/_graph.py

@@ -0,0 +1,50 @@
+from collections.abc import Iterable
+from dataclasses import dataclass
+
+from engin import Provide
+from engin._dependency import Dependency
+from engin._type_utils import TypeId
+
+
+@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]:
+        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:
+                provider = self._providers[parameter]
+
+                # multiprovider
+                if isinstance(provider, list):
+                    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(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

@@ -0,0 +1,174 @@
+import importlib
+import logging
+import socketserver
+import sys
+import threading
+from argparse import ArgumentParser
+from http.server import BaseHTTPRequestHandler
+from time import sleep
+from typing import Any
+
+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()
+
+args = ArgumentParser(
+    prog="engin-graph",
+    description="Creates a visualisation of your application's dependencies",
+)
+args.add_argument(
+    "app",
+    help=(
+        "the import path of your Engin instance, in the form "
+        "'package:application', e.g. 'app.main:engin'"
+    ),
+)
+
+
+def serve_graph() -> None:
+    # add cwd to path to enable local package imports
+    sys.path.insert(0, "")
+
+    parsed = args.parse_args()
+
+    app = parsed.app
+
+    try:
+        module_name, engin_name = app.split(":", maxsplit=1)
+    except ValueError:
+        raise ValueError(
+            "Expected an argument of the form 'module:attribute', e.g. 'myapp:engin'"
+        ) from None
+
+    module = importlib.import_module(module_name)
+
+    try:
+        instance = getattr(module, engin_name)
+    except LookupError:
+        raise LookupError(f"Module '{module_name}' has no attribute '{engin_name}'") from None
+
+    if not isinstance(instance, Engin):
+        raise TypeError(f"'{app}' is not an Engin instance")
+
+    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
+    ]
+
+    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:
+            self.send_response(200, "OK")
+            self.send_header("Content-type", "html")
+            self.end_headers()
+            self.wfile.write(html)
+
+        def log_message(self, format: str, *args: Any) -> None:
+            return
+
+    def _start_server() -> None:
+        with socketserver.TCPServer(("localhost", 8123), Handler) as httpd:
+            print("Serving dependency graph on http://localhost:8123")
+            httpd.serve_forever()
+
+    server_thread = threading.Thread(target=_start_server)
+    server_thread.daemon = True  # Daemonize the thread so it exits when the main script exits
+    server_thread.start()
+
+    try:
+        sleep(10000)
+    except KeyboardInterrupt:
+        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):
+        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 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';
+      let config = { flowchart: { useMaxWidth: false, htmlLabels: true } };
+      mermaid.initialize(config);
+    </script>
+  </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.7.dist-info → engin-0.0.9.dist-info}/METADATA

@@ -1,8 +1,14 @@
 Metadata-Version: 2.4
 Name: engin
-Version: 0.0.7
+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/
+Project-URL: Repository, https://github.com/invokermain/engin.git
+Project-URL: Changelog, https://github.com/invokermain/engin/blob/main/CHANGELOG.md
+License-Expression: MIT
 License-File: LICENSE
+Keywords: Application Framework,Dependency Injection
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 

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.9.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+engin-graph = engin.scripts.graph:serve_graph

engin-0.0.7.dist-info/RECORD

@@ -1,16 +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=vqBwKNHH_V3MZZQ29A1zWknFSkkzghJgpWN0mjvjtyY,5425
-engin/_engin.py,sha256=lPce5p4fCz2AdBdmXdEFvehryIi4FPmD0zjvDFcL8Jc,8987
-engin/_exceptions.py,sha256=fsc4pTOIGHUh0x7oZhEXPJUTE268sIhswLoiqXaudiw,635
-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-0.0.7.dist-info/METADATA,sha256=mnVPfy7Bdtd_ilWcVn2zHyw1utyepBx3inRlAi3BCHc,1806
-engin-0.0.7.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-engin-0.0.7.dist-info/licenses/LICENSE,sha256=XHh5LPUPKZWTBqBv2xxN2RU7D59nHoiJGb5RIt8f45w,1070
-engin-0.0.7.dist-info/RECORD,,