engin 0.0.8__tar.gz → 0.0.9__tar.gz

{engin-0.0.8 → engin-0.0.9}/CHANGELOG.md

@@ -6,6 +6,22 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 
+## [0.0.9] - 2025-02-22
+
+### Added
+
+- Dependency class now has a new attribute: `func_name`.
+
+### Changed
+
+- Improved `engin-graph` output.
+- The `module` attribute of dependencies has been renamed to `origin`
+
+### Fixed
+
+- Options provided under the `options` on a Block now have the `block_name` set.
+
+
 ## [0.0.8] - 2025-02-22
 
 ### Added

{engin-0.0.8 → engin-0.0.9}/PKG-INFO

@@ -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.8 → engin-0.0.9}/examples/asgi/main.py

@@ -12,4 +12,6 @@ logging.basicConfig(level=logging.DEBUG)
 
 app = ASGIEngin(AppBlock(), DatabaseBlock(), CatBlock(), Supply(AppConfig(debug=True)))
 
-uvicorn.run(app)
+
+if __name__ == "__main__":
+    uvicorn.run(app)

engin-0.0.9/examples/fastapi/app.py

@@ -0,0 +1,29 @@
+from fastapi import APIRouter, FastAPI
+from pydantic_settings import BaseSettings
+
+from engin import Block, provide
+
+
+class AppConfig(BaseSettings):
+    debug: bool = False
+
+
+class AppBlock(Block):
+    @provide
+    def default_config(self) -> AppConfig:
+        return AppConfig()
+
+    @provide
+    def app_factory(self, app_config: AppConfig, routers: list[APIRouter]) -> FastAPI:
+        app = FastAPI(debug=app_config.debug)
+
+        for router in routers:
+            app.include_router(router)
+
+        app.add_api_route(path="/health", endpoint=_health)
+
+        return app
+
+
+async def _health() -> dict[str, bool]:
+    return {"ok": True}

{engin-0.0.8 → engin-0.0.9}/examples/fastapi/routes/cats/block.py

@@ -1,16 +1,14 @@
-from fastapi import FastAPI
+from typing import ClassVar
 
-from engin import Block, invoke, provide
+from engin import Block, Invoke, Provide, Supply, provide
 from examples.fastapi.routes.cats.adapters.repository import InMemoryCatRepository
 from examples.fastapi.routes.cats.api import router
 from examples.fastapi.routes.cats.ports import CatRepository
 
 
 class CatBlock(Block):
+    options: ClassVar[list[Provide | Invoke]] = [Supply([router])]
+
     @provide
     def cat_repository(self) -> CatRepository:
         return InMemoryCatRepository()
-
-    @invoke
-    def attach_router(self, app: FastAPI) -> None:
-        app.include_router(router)

{engin-0.0.8 → engin-0.0.9}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "engin"
-version = "0.0.8"
+version = "0.0.9"
 description = "An async-first modular application framework"
 readme = "README.md"
 requires-python = ">=3.10"

{engin-0.0.8 → engin-0.0.9}/src/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-0.0.8 → engin-0.0.9}/src/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-0.0.9/src/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-0.0.8 → engin-0.0.9}/src/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-0.0.9/src/engin/ext/fastapi.py

@@ -0,0 +1,168 @@
+import inspect
+import typing
+from collections.abc import Iterable
+from inspect import Parameter
+from typing import ClassVar, TypeVar
+
+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 APIRouter, FastAPI
+    from fastapi.params import Depends
+    from starlette.requests import HTTPConnection
+except ImportError as err:
+    raise ImportError(
+        "fastapi package must be installed to use the fastapi extension"
+    ) from err
+
+__all__ = ["APIRouteDependency", "FastAPIEngin", "Inject"]
+
+
+def _attach_engin(
+    app: FastAPI,
+    engin: Engin,
+) -> None:
+    app.state.engin = engin
+
+
+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")
+
+
+def Inject(interface: type[T]) -> Depends:
+    async def inner(conn: HTTPConnection) -> T:
+        engin: Engin = conn.app.state.engin
+        return await engin.assembler.get(interface)
+
+    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-0.0.8 → engin-0.0.9}/src/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/examples/fastapi/app.py

@@ -1,25 +0,0 @@
-from fastapi import FastAPI
-from pydantic_settings import BaseSettings
-
-from engin import Block, invoke, provide
-
-
-class AppConfig(BaseSettings):
-    debug: bool = False
-
-
-class AppBlock(Block):
-    @provide
-    def app_factory(self, app_config: AppConfig) -> FastAPI:
-        return FastAPI(debug=app_config.debug)
-
-    @provide
-    def default_config(self) -> AppConfig:
-        return AppConfig()
-
-    @invoke
-    def add_health_endpoint(self, app: FastAPI) -> None:
-        async def health() -> dict[str, bool]:
-            return {"ok": True}
-
-        app.add_api_route(path="/health", endpoint=health)

engin-0.0.8/src/engin/_graph.py

@@ -1,39 +0,0 @@
-from collections.abc import Iterable
-from typing import TypedDict
-
-from engin._dependency import Dependency, Provide
-from engin._type_utils import TypeId
-
-
-class Node(TypedDict):
-    node: Dependency
-    parent: Dependency | None
-
-
-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] = []
-
-        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]))
-                # single provider
-                else:
-                    nodes.append({"node": provider, "parent": root})
-                    nodes.extend(self.resolve([provider]))
-
-        return nodes

engin-0.0.8/src/engin/ext/fastapi.py

@@ -1,38 +0,0 @@
-from typing import ClassVar, TypeVar
-
-from engin import Engin, Invoke, Option
-from engin.ext.asgi import ASGIEngin
-
-try:
-    from fastapi import FastAPI
-    from fastapi.params import Depends
-    from starlette.requests import HTTPConnection
-except ImportError as err:
-    raise ImportError(
-        "fastapi package must be installed to use the fastapi extension"
-    ) from err
-
-__all__ = ["FastAPIEngin", "Inject"]
-
-
-def _attach_engin(
-    app: FastAPI,
-    engin: Engin,
-) -> None:
-    app.state.engin = engin
-
-
-class FastAPIEngin(ASGIEngin):
-    _LIB_OPTIONS: ClassVar[list[Option]] = [*ASGIEngin._LIB_OPTIONS, Invoke(_attach_engin)]
-    _asgi_type = FastAPI
-
-
-T = TypeVar("T")
-
-
-def Inject(interface: type[T]) -> Depends:
-    async def inner(conn: HTTPConnection) -> T:
-        engin: Engin = conn.app.state.engin
-        return await engin.assembler.get(interface)
-
-    return Depends(inner)