engin 0.0.15__tar.gz → 0.0.17__tar.gz

{engin-0.0.15 → engin-0.0.17}/CHANGELOG.md

@@ -6,6 +6,32 @@ 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.17] - 2025-04-20
+
+### Added
+
+- `Provide` now has the `as_type` parameter that `Supply` had previously.
+
+### Changed
+
+- Renamed `parameter_types` property on dependencies to `parameter_type_ids` to be more
+  explicit.
+
+
+## [0.0.16] - 2025-04-16
+
+### Added
+
+- Preliminary support for scoped providers. Scoped providers are only accessible when
+  the assembler is in the matching scope, and the built output is only cached until the
+  assembler leaves the matching scope. This can be used for example to have request scoped
+  providers in a Web Server.
+
+### Changed
+
+- Minor improvements to the work-in-progress dependency grapher.
+
+
 ## [0.0.15] - 2025-03-25
 
 ### Changed

{engin-0.0.15 → engin-0.0.17}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: engin
-Version: 0.0.15
+Version: 0.0.17
 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 → engin-0.0.17}/examples/fastapi/main.py

@@ -9,7 +9,7 @@ from examples.fastapi.routes.cats.block import CatBlock
 
 logging.basicConfig(level=logging.DEBUG)
 
-app = FastAPIEngin(AppBlock(), CatBlock(), Supply(AppConfig(debug=True)))
+app = FastAPIEngin(AppBlock(), CatBlock(), Supply(AppConfig(debug=True), override=True))
 
 
 if __name__ == "__main__":

{engin-0.0.15 → engin-0.0.17}/pyproject.toml

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

{engin-0.0.15 → engin-0.0.17}/src/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.
@@ -205,7 +228,7 @@ class Assembler:
         yield from (
             child_provider
             for root_provider in root_providers
-            for root_provider_param in root_provider.parameter_types
+            for root_provider_param in root_provider.parameter_type_ids
             for child_provider in self._resolve_providers(root_provider_param)
         )
         yield from root_providers
@@ -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-0.0.15 → engin-0.0.17}/src/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-0.0.17/src/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-0.0.15 → engin-0.0.17}/src/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,13 +159,13 @@ 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]
+        entrypoint_type = node.parameter_type_ids[0]
         md += f"{entrypoint_type}"
         return f'{node_id}[/"`{md}`"\\]{style}'
     if isinstance(node, Invoke):
@@ -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-0.0.15 → engin-0.0.17}/src/engin/_dependency.py

@@ -76,7 +76,7 @@ class Dependency(ABC, Option, Generic[P, T]):
             return f"{self._func.__module__}.{self._func.__name__}"
 
     @property
-    def parameter_types(self) -> list[TypeId]:
+    def parameter_type_ids(self) -> list[TypeId]:
         parameters = list(self._signature.parameters.values())
         if not parameters:
             return []
@@ -136,7 +136,7 @@ class Entrypoint(Invoke):
         super().__init__(invocation=_noop)
 
     @property
-    def parameter_types(self) -> list[TypeId]:
+    def parameter_type_ids(self) -> list[TypeId]:
         return [TypeId.from_type(self._type)]
 
     @property
@@ -152,24 +152,40 @@ 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,
+        as_type: type | 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.
+            as_type: (optional) allows you to explicitly specify the provided type, e.g.
+                to type erase a concrete type, or to provide a mock implementation.
+            override: (optional) allow this provider to override other providers for the
+                same type from the same package.
         """
         super().__init__(func=builder)
+        self._scope = scope
         self._override = override
+        self._explicit_type = as_type
+
+        if self._explicit_type is not None:
+            self._signature = self._signature.replace(return_annotation=self._explicit_type)
+
         self._is_multi = typing.get_origin(self.return_type) is list
 
         # Validate that the provider does to depend on its own output value, as this will
         # cause a recursion error and is undefined behaviour wise.
         if any(
             self.return_type == param.annotation
-            for param in self.signature.parameters.values()
+            for param in self._signature.parameters.values()
         ):
             raise ValueError("A provider cannot depend on its own return type")
 
@@ -183,6 +199,8 @@ class Provide(Dependency[Any, T]):
 
     @property
     def return_type(self) -> type[T]:
+        if self._explicit_type is not None:
+            return self._explicit_type
         if isclass(self._func):
             return_type = self._func  # __init__ returns self
         else:
@@ -203,6 +221,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:
@@ -245,23 +267,19 @@ class Supply(Provide, Generic[T]):
         function.
 
         Args:
-            value: the value to Supply
-            as_type: allows you to specify the provided type, useful for type erasing,
-              e.g. Supply a concrete value but specify it as an interface or other
-              abstraction.
-            override: allow this provider to override existing providers from the same
-              package.
+            value: the value to Supply.
+            as_type: (optional) allows you to explicitly specify the provided type, e.g.
+              to type erase a concrete type, or to provide a mock implementation.
+            override: (optional) allow this provider to override other providers for the
+              same type from the same package.
         """
         self._value = value
-        self._type_hint = as_type
-        if self._type_hint is not None:
-            self._get_val.__annotations__["return"] = as_type
-        super().__init__(builder=self._get_val, override=override)
+        super().__init__(builder=self._get_val, as_type=as_type, override=override)
 
     @property
     def return_type(self) -> type[T]:
-        if self._type_hint is not None:
-            return self._type_hint
+        if self._explicit_type is not None:
+            return self._explicit_type
         if isinstance(self._value, list):
             return list[type(self._value[0])]  # type: ignore[misc,return-value]
         return type(self._value)

engin-0.0.17/src/engin/_exceptions.py

@@ -0,0 +1,54 @@
+from typing import Any
+
+from engin._dependency import Provide
+
+
+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.
+    """
+
+    def __init__(
+        self,
+        provider: Provide[Any],
+        error_type: type[Exception],
+        error_message: str,
+    ) -> None:
+        self.provider = provider
+        self.error_type = error_type
+        self.error_message = error_message
+        self.message = (
+            f"provider '{provider.name}' errored with error "
+            f"({error_type.__name__}): '{error_message}'"
+        )
+
+    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-0.0.15 → engin-0.0.17}/src/engin/_graph.py

@@ -31,7 +31,7 @@ class DependencyGrapher:
     ) -> list[Node]:
         nodes: list[Node] = []
         for root in roots:
-            for parameter in root.parameter_types:
+            for parameter in root.parameter_type_ids:
                 provider = self._providers[parameter]
 
                 # multiprovider

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

@@ -75,7 +75,7 @@ class _FastAPIDependencyGrapher(DependencyGrapher):
     ) -> list[Node]:
         nodes: list[Node] = []
         for root in roots:
-            for parameter in root.parameter_types:
+            for parameter in root.parameter_type_ids:
                 provider = self._providers[parameter]
 
                 # multiprovider
@@ -162,7 +162,7 @@ class APIRouteDependency(Dependency):
         return self._route
 
     @property
-    def parameter_types(self) -> list[TypeId]:
+    def parameter_type_ids(self) -> list[TypeId]:
         parameters = list(self._signature.parameters.values())
         if not parameters:
             return []

{engin-0.0.15 → engin-0.0.17}/tests/acceptance/test_fastapi.py

@@ -1,3 +1,4 @@
+import time
 from typing import Annotated
 
 import pytest
@@ -21,6 +22,14 @@ async def route_with_dep(some_int: Annotated[int, Inject(int)]) -> int:
     return some_int
 
 
+@ROUTER.get("/inject2")
+async def route_with_dep_2(
+    some_int: Annotated[int, Inject(int)], some_str: Annotated[str, Inject(str)]
+) -> int:
+    assert some_int == int(some_str)
+    return some_int
+
+
 def app_factory(routers: list[APIRouter]) -> FastAPI:
     app = FastAPI()
     for router in routers:
@@ -47,12 +56,12 @@ async def test_inject():
 
 
 async def test_graph():
-    engin = FastAPIEngin(Provide(app_factory), Supply([ROUTER]), Supply(10))
+    engin = FastAPIEngin(Provide(app_factory), Supply([ROUTER]), Supply(10), Supply("a"))
 
     nodes = engin.graph()
 
-    assert len(nodes) == 5
-    assert len([node for node in nodes if isinstance(node.node, APIRouteDependency)]) == 2
+    assert len(nodes) == 8
+    assert len([node for node in nodes if isinstance(node.node, APIRouteDependency)]) == 3
 
 
 async def test_invalid_engin():
@@ -70,3 +79,27 @@ async def test_engin_to_lifespan():
         result = client.get("http://127.0.0.1:8000/inject")
 
     assert result.json() == 10
+
+
+async def test_asgi_request_scope():
+    def scoped_factory() -> int:
+        return time.time_ns()
+
+    def child_factory(some: int) -> str:
+        return str(some)
+
+    app = FastAPIEngin(
+        Provide(app_factory),
+        Provide(scoped_factory, scope="request"),
+        Provide(child_factory),
+        Supply([ROUTER]),
+    )
+
+    with starlette.testclient.TestClient(app) as client:
+        first_call = client.get("http://127.0.0.1:8000/inject").json()
+        second_call = client.get("http://127.0.0.1:8000/inject").json()
+
+        # these should differ as the factory is request scoped to each request
+        assert first_call != second_call
+
+        client.get("http://127.0.0.1:8000/inject2")