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

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,6 +30,10 @@ class Dependency(ABC, Generic[P, T]):
         self._signature = inspect.signature(self._func)
         self._block_name = block_name
 
+    @property
+    def module(self) -> str:
+        return self._func.__module__
+
     @property
     def block_name(self) -> str | None:
         return self._block_name
@@ -136,7 +139,7 @@ class Provide(Dependency[Any, T]):
             return_type = self._func  # __init__ returns self
         else:
             try:
-                return_type = get_type_hints(self._func)["return"]
+                return_type = get_type_hints(self._func, include_extras=True)["return"]
             except KeyError as err:
                 raise RuntimeError(
                     f"Dependency '{self.name}' requires a return typehint"

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
 
@@ -35,8 +36,7 @@ class Engin:
     Supply) and at least one invocation (Invoke or Entrypoint).
 
     When instantiated the Engin can be run. This is typically done via the `run` method,
-    but certain use cases, e.g. testing, it can be easier to use the `start` and `stop`
-    methods.
+    but for advanced usecases it can be easier to use the `start` and `stop` methods.
 
     When ran the Engin takes care of the complete application lifecycle:
     1. The Engin assembles all Invocations. Only Providers that are required to satisfy
@@ -81,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()
@@ -96,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:
@@ -163,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,39 @@
+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/scripts/graph.py

@@ -0,0 +1,122 @@
+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
+from engin._dependency import Dependency, Provide
+
+# 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(
+    "-e", "--exclude", help="a list of packages or module to exclude", default=["engin"]
+)
+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
+    excluded_modules = parsed.exclude
+
+    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
+        and not _should_exclude(node["node"].module, excluded_modules)
+    ]
+
+    html = _GRAPH_HTML.replace("%%DATA%%", "\n".join(dependencies)).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...")
+
+
+def _render_node(node: Dependency) -> str:
+    if isinstance(node, Provide):
+        return str(node.return_type_id)
+    else:
+        return node.name
+
+
+def _should_exclude(module: str, excluded: list[str]) -> bool:
+    return any(module.startswith(e) for e in excluded)
+
+
+_GRAPH_HTML = """
+<!doctype html>
+<html lang="en">
+  <body>
+    <pre class="mermaid">
+      graph TD
+          %%DATA%%
+    </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>
+"""

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

@@ -1,8 +1,14 @@
 Metadata-Version: 2.4
 Name: engin
-Version: 0.0.6
+Version: 0.0.8
 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.6.dist-info → engin-0.0.8.dist-info}/RECORD

@@ -1,16 +1,20 @@
 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=oh1T7oR-c9MGcZ6ZFUgPnvHRf-n6AIvpbm59R97To80,5404
-engin/_engin.py,sha256=Dp1i0COcmaXWwrckBq3-vym-B7umsZG_0vXjasA5y70,9002
+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-0.0.6.dist-info/METADATA,sha256=SSsLRciMAahwVMjw6Igdcq1jt1zv24FrPuXm_1uykjg,1806
-engin-0.0.6.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-engin-0.0.6.dist-info/licenses/LICENSE,sha256=XHh5LPUPKZWTBqBv2xxN2RU7D59nHoiJGb5RIt8f45w,1070
-engin-0.0.6.dist-info/RECORD,,
+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,,

engin-0.0.8.dist-info/entry_points.txt

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