engin 0.0.15__py3-none-any.whl → 0.0.16__py3-none-any.whl

engin/_assembler.py

@@ -2,17 +2,26 @@ import asyncio
 import logging
 from collections import defaultdict
 from collections.abc import Iterable
+from contextvars import ContextVar
 from dataclasses import dataclass
 from inspect import BoundArguments, Signature
+from types import TracebackType
 from typing import Any, Generic, TypeVar, cast
 
 from engin._dependency import Dependency, Provide, Supply
-from engin._exceptions import ProviderError
+from engin._exceptions import NotInScopeError, ProviderError
 from engin._type_utils import TypeId
 
 LOG = logging.getLogger("engin")
 
 T = TypeVar("T")
+_SCOPE: ContextVar[list[str] | None] = ContextVar("_SCOPE", default=None)
+
+
+def _get_scope() -> list[str]:
+    if _SCOPE.get() is None:
+        _SCOPE.set([])
+    return cast("list[str]", _SCOPE.get())
 
 
 @dataclass(slots=True, kw_only=True, frozen=True)
@@ -112,6 +121,8 @@ class Assembler:
 
             out = []
             for provider in self._multiproviders[type_id]:
+                if provider.scope and provider.scope not in _get_scope():
+                    raise NotInScopeError(provider=provider, scope_stack=_get_scope())
                 assembled_dependency = await self.assemble(provider)
                 try:
                     out.extend(await assembled_dependency())
@@ -127,12 +138,16 @@ class Assembler:
             if type_id not in self._providers:
                 raise LookupError(f"no provider found for target type id '{type_id}'")
 
-            assembled_dependency = await self.assemble(self._providers[type_id])
+            provider = self._providers[type_id]
+            if provider.scope and provider.scope not in _get_scope():
+                raise NotInScopeError(provider=provider, scope_stack=_get_scope())
+
+            assembled_dependency = await self.assemble(provider)
             try:
                 value = await assembled_dependency()
             except Exception as err:
                 raise ProviderError(
-                    provider=self._providers[type_id],
+                    provider=provider,
                     error_type=type(err),
                     error_message=str(err),
                 ) from err
@@ -178,6 +193,14 @@ class Assembler:
                 del self._assembled_outputs[type_id]
             self._providers[type_id] = provider
 
+    def scope(self, scope: str) -> "_ScopeContextManager":
+        return _ScopeContextManager(scope=scope, assembler=self)
+
+    def _exit_scope(self, scope: str) -> None:
+        for type_id, provider in self._providers.items():
+            if provider.scope == scope:
+                self._assembled_outputs.pop(type_id, None)
+
     def _resolve_providers(self, type_id: TypeId) -> Iterable[Provide]:
         """
         Resolves the chain of providers required to satisfy the provider of a given type.
@@ -251,3 +274,27 @@ class Assembler:
                 kwargs[param.name] = val
 
         return signature.bind(*args, **kwargs)
+
+
+class _ScopeContextManager:
+    def __init__(self, scope: str, assembler: Assembler) -> None:
+        self._scope = scope
+        self._assembler = assembler
+
+    def __enter__(self) -> Assembler:
+        _get_scope().append(self._scope)
+        return self._assembler
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+        /,
+    ) -> None:
+        popped = _get_scope().pop()
+        if popped != self._scope:
+            raise RuntimeError(
+                f"Exited scope '{popped}' is not the expected scope '{self._scope}'"
+            )
+        self._assembler._exit_scope(self._scope)

engin/_block.py

@@ -11,14 +11,14 @@ if TYPE_CHECKING:
 
 
 def provide(
-    func_: Func | None = None, *, override: bool = False
+    func_: Func | None = None, *, scope: str | None = None, override: bool = False
 ) -> Func | Callable[[Func], Func]:
     """
     A decorator for defining a Provider in a Block.
     """
 
     def _inner(func: Func) -> Func:
-        func._opt = Provide(func, override=override)  # type: ignore[attr-defined]
+        func._opt = Provide(func, override=override, scope=scope)  # type: ignore[attr-defined]
         return func
 
     if func_ is None:

engin/_cli/_graph.html

@@ -0,0 +1,78 @@
+<!doctype html>
+<html lang="en">
+  <style>
+    #mermaid-container {
+    width: 100%;
+    height: 100%;
+    overflow: auto; /* Enables scrolling */
+    border: 1px solid #ddd;
+    cursor: grab;
+    position: relative;
+    white-space: nowrap; /* Prevents wrapping */
+  }
+
+  #mermaid-content {
+    width: max-content; /* Ensures content can expand */
+    height: max-content;
+  }
+  </style>
+  <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, defaultRenderer: "elk" } };
+      mermaid.initialize(config);
+
+      // Drag-to-Move Functionality
+      const container = document.getElementById("mermaid-container");
+
+      let isDragging = false;
+      let startX, startY, scrollLeft, scrollTop;
+
+      container.addEventListener("pointerdown", (e) => {
+        isDragging = true;
+        startX = e.clientX;
+        startY = e.clientY;
+        scrollLeft = container.scrollLeft;
+        scrollTop = container.scrollTop;
+        container.style.cursor = "grabbing";
+      });
+
+      container.addEventListener("pointermove", (e) => {
+        if (!isDragging) return;
+        const x = e.clientX - startX;
+        const y = e.clientY - startY;
+        container.scrollLeft = scrollLeft - x;
+        container.scrollTop = scrollTop - y;
+      });
+
+      container.addEventListener("pointerup", () => {
+        isDragging = false;
+        container.style.cursor = "grab";
+      });
+
+      container.addEventListener("pointerleave", () => {
+        isDragging = false;
+        container.style.cursor = "grab";
+      });
+  </script>
+  <body>
+    <div style="border-style:outset">
+        <p>LEGEND</p>
+        <pre class="mermaid" id="legend">
+          graph LR
+            %%LEGEND%%
+            classDef b0 fill:#7fc97f;
+            classDef external stroke-dasharray: 5 5;
+        </pre>
+    </div>
+    <div id="mermaid-container" style="width: 100%; overflow-x: auto; border: 1px solid #ddd; cursor: grab; position: relative;">
+        <div id="mermaid-content" style="width: max-content; height: max-content;">
+            <pre class="mermaid" id="graph">
+              %%{init: {"flowchart": {"defaultRenderer": "elk"}} }%%
+              graph LR
+                  %%DATA%%
+                  classDef external stroke-dasharray: 5 5;
+            </pre>
+        </div>
+    </div>
+  </body>
+</html>

engin/_cli/_graph.py

@@ -5,13 +5,14 @@ import socketserver
 import sys
 import threading
 from http.server import BaseHTTPRequestHandler
+from pathlib import Path
 from time import sleep
 from typing import Annotated, Any
 
 import typer
 from rich import print
 
-from engin import Engin, Entrypoint, Invoke
+from engin import Engin, Entrypoint, Invoke, TypeId
 from engin._cli._utils import print_error
 from engin._dependency import Dependency, Provide, Supply
 from engin.ext.asgi import ASGIEngin
@@ -23,11 +24,9 @@ except ImportError:
 
 cli = typer.Typer()
 
-
 # mute logging from importing of files + engin's debug logging.
 logging.disable()
 
-
 _APP_ORIGIN = ""
 
 _CLI_HELP = {
@@ -79,8 +78,25 @@ def serve_graph(
         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)
     ]
 
+    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(
@@ -123,18 +139,14 @@ _BLOCK_IDX: dict[str, int] = {}
 _SEEN_BLOCKS: list[str] = []
 
 
-def _render_node(node: Dependency) -> str:
+def _render_node(node: Dependency, render_block: bool = True) -> str:
     node_id = id(node)
     md = ""
     style = ""
 
     # format block name
-    if n := node.block_name:
+    if render_block and (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]}"
 
     node_root_package = node.source_package.split(".", maxsplit=1)[0]
     if node_root_package != _APP_ORIGIN:
@@ -147,10 +159,10 @@ def _render_node(node: Dependency) -> str:
         style = f":::{style}"
 
     if isinstance(node, Supply):
-        md += f"{node.return_type_id}"
+        md += f"{_short_name(node.return_type_id)}"
         return f'{node_id}("`{md}`"){style}'
     if isinstance(node, Provide):
-        md += f"{node.return_type_id}"
+        md += f"{_short_name(node.return_type_id)}"
         return f'{node_id}["`{md}`"]{style}'
     if isinstance(node, Entrypoint):
         entrypoint_type = node.parameter_types[0]
@@ -166,48 +178,11 @@ def _render_node(node: Dependency) -> str:
         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;
-            classDef external stroke-dasharray: 5 5;
-        </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;
-          classDef b0E fill:#7fc97f,stroke-dasharray: 5 5;
-          classDef b1E fill:#beaed4,stroke-dasharray: 5 5;
-          classDef b2E fill:#fdc086,stroke-dasharray: 5 5;
-          classDef b3E fill:#ffff99,stroke-dasharray: 5 5;
-          classDef b4E fill:#386cb0,stroke-dasharray: 5 5;
-          classDef b5E fill:#f0027f,stroke-dasharray: 5 5;
-          classDef b6E fill:#bf5b17,stroke-dasharray: 5 5;
-          classDef b7E fill:#666666,stroke-dasharray: 5 5;
-          classDef external stroke-dasharray: 5 5;
-    </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>
-"""
+def _short_name(name: TypeId) -> str:
+    return str(name).rsplit(".", maxsplit=1)[-1]
+
+
+_GRAPH_HTML = (Path(__file__).parent / "_graph.html").read_text()
 
 DEFAULT_LEGEND = (
     "0[/Invoke/] ~~~ 1[/Entrypoint\\] ~~~ 2[Provide] ~~~ 3(Supply)"

engin/_dependency.py

@@ -152,16 +152,20 @@ class Entrypoint(Invoke):
 
 
 class Provide(Dependency[Any, T]):
-    def __init__(self, builder: Func[P, T], *, override: bool = False) -> None:
+    def __init__(
+        self, builder: Func[P, T], *, scope: str | None = None, override: bool = False
+    ) -> None:
         """
         Provide a type via a builder or factory function.
 
         Args:
             builder: the builder function that returns the type.
-            override: allow this provider to override existing providers from the same
-                package.
+            scope: (optional) associate this provider with a specific scope.
+            override: (optional) allow this provider to override existing providers from
+                the same package.
         """
         super().__init__(func=builder)
+        self._scope = scope
         self._override = override
         self._is_multi = typing.get_origin(self.return_type) is list
 
@@ -203,6 +207,10 @@ class Provide(Dependency[Any, T]):
     def is_multiprovider(self) -> bool:
         return self._is_multi
 
+    @property
+    def scope(self) -> str | None:
+        return self._scope
+
     def apply(self, engin: "Engin") -> None:
         type_id = self.return_type_id
         if self.is_multiprovider:

engin/_exceptions.py

@@ -3,7 +3,19 @@ from typing import Any
 from engin._dependency import Provide
 
 
-class ProviderError(Exception):
+class EnginError(Exception):
+    """
+    Base class for all custom exceptions in the Engin library.
+    """
+
+
+class AssemblerError(EnginError):
+    """
+    Base class for all custom exceptions raised by the Assembler.
+    """
+
+
+class ProviderError(AssemblerError):
     """
     Raised when a Provider errors during Assembly.
     """
@@ -24,3 +36,19 @@ class ProviderError(Exception):
 
     def __str__(self) -> str:
         return self.message
+
+
+class NotInScopeError(AssemblerError):
+    """
+    Raised when a Provider is requested outside of its scope.
+    """
+
+    def __init__(self, provider: Provide[Any], scope_stack: list[str]) -> None:
+        self.provider = provider
+        self.message = (
+            f"provider '{provider.name}' was requested outside of its specified scope "
+            f"'{provider.scope}', current scope stack is {scope_stack}"
+        )
+
+    def __str__(self) -> str:
+        return self.message

engin/ext/asgi.py

@@ -47,7 +47,8 @@ class ASGIEngin(Engin, ASGIType):
             elif message["type"] == "lifespan.shutdown":
                 await self.stop()
 
-        await self._asgi_app(scope, receive, send)
+        with self._assembler.scope("request"):
+            await self._asgi_app(scope, receive, send)
 
     async def _startup(self) -> None:
         self._asgi_app = await self._assembler.build(self._asgi_type)

{engin-0.0.15.dist-info → engin-0.0.16.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: engin
-Version: 0.0.15
+Version: 0.0.16
 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.15.dist-info → engin-0.0.16.dist-info}/RECORD

@@ -1,9 +1,9 @@
 engin/__init__.py,sha256=rBTteMLAVKg4TJSaMElJUwz72BA_X7nBTREg-I-bWhA,584
-engin/_assembler.py,sha256=GpTLW9AmGChnwWWK3SUq5AsxJJ8ukH7yWpemBiH87pw,9294
-engin/_block.py,sha256=Ypl6ffU52dgrHHgCcPokzfRD2-Lbu9b2wYMCgAZIx4g,2578
-engin/_dependency.py,sha256=w-MxF6Ju1Rc2umc7pk3bXTlc65NVIs1VEBj8825WEcg,8328
+engin/_assembler.py,sha256=8rt16LGvPpXHtjSdEDQJ6XC6DVwSbr_4_Mcfcfnpf70,10949
+engin/_block.py,sha256=8ysWrmHkWpTm6bmSc6jZVoO0Ax5Svu1HwxpZwAtIF_o,2617
+engin/_dependency.py,sha256=KM_d4TEu7NaoOSuIC7lRO7UvPzBFb0sxR74ZbInLMng,8561
 engin/_engin.py,sha256=yIpZdeqvm8hv0RxOV0veFuvyu9xQ054JSaeuUWwHdOQ,7380
-engin/_exceptions.py,sha256=fsc4pTOIGHUh0x7oZhEXPJUTE268sIhswLoiqXaudiw,635
+engin/_exceptions.py,sha256=UzMppJWDk_Hx3qWAypcPVLw9OYCibqiZjLYeTl22zaE,1355
 engin/_graph.py,sha256=1pMB0cr--uS0XJycDb1rS_X45RBpoyA6NkKqbeSuz1Q,1628
 engin/_introspect.py,sha256=VdREX6Lhhga5SnEP9G7mjHkgJR4mpqk_SMnmL2zTcqY,966
 engin/_lifecycle.py,sha256=cSWe3euZkmpxmUPFvph2lsTtvuZbxttEfBL-RnOI7lo,5325
@@ -11,13 +11,14 @@ engin/_option.py,sha256=nZcdrehp1QwgxMUoIpsM0PJuu1q1pbXzhcVsetbsHpc,223
 engin/_type_utils.py,sha256=Pmm4m1_WdevT5KTe8tzY_BseNxPyhu_nKsLGgyNcPpo,2247
 engin/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 engin/_cli/__init__.py,sha256=lp1KiBpcgk_dZU5V9DjgLPwmp0ja444fwLH2CYCscNc,302
-engin/_cli/_graph.py,sha256=1Kj09BnKh5BTmuM4tqaGICS4KVDGNWT4oGFIrUa9xdU,6230
+engin/_cli/_graph.html,sha256=rR5dnDKoz7KtSff0ERCi2UKuoH_Z03MRYiXI_W03G5k,2430
+engin/_cli/_graph.py,sha256=2v-l5rEC4zm36SWgmzQ2UK-nIHofYpexTo3et55AtE0,5539
 engin/_cli/_utils.py,sha256=AQFtLO8qjYRCTQc9A8Z1HVf7eZr8iGWogxbYzsgIkS4,360
 engin/ext/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-engin/ext/asgi.py,sha256=6V5Aad37MyGzkCtU5TlDrm0o5C04Un_LLvcomxnAmHY,3196
+engin/ext/asgi.py,sha256=d5Z6gtMVWDZdAlvrTaMt987sKyiq__A0X4gJQ7IETmA,3247
 engin/ext/fastapi.py,sha256=e8UV521Mq9Iqr55CT7_jtd51iaIZjWlAacoqFBXsh-k,6356
-engin-0.0.15.dist-info/METADATA,sha256=qYhQHzJ_YrJEaZ_p4ddZL4OZDOtzWHkQFLimPH_XNDE,2354
-engin-0.0.15.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-engin-0.0.15.dist-info/entry_points.txt,sha256=sW247zZUMxm0b5UKYvPuqQQljYDtU-j2zK3cu7gHwM0,41
-engin-0.0.15.dist-info/licenses/LICENSE,sha256=XHh5LPUPKZWTBqBv2xxN2RU7D59nHoiJGb5RIt8f45w,1070
-engin-0.0.15.dist-info/RECORD,,
+engin-0.0.16.dist-info/METADATA,sha256=1-9KPa3HdnKUM38_OD3yAdNHHTb4-cOBds8dlqedv9s,2354
+engin-0.0.16.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+engin-0.0.16.dist-info/entry_points.txt,sha256=sW247zZUMxm0b5UKYvPuqQQljYDtU-j2zK3cu7gHwM0,41
+engin-0.0.16.dist-info/licenses/LICENSE,sha256=XHh5LPUPKZWTBqBv2xxN2RU7D59nHoiJGb5RIt8f45w,1070
+engin-0.0.16.dist-info/RECORD,,