engin 0.0.10__py3-none-any.whl → 0.0.12__py3-none-any.whl

engin/_assembler.py

@@ -141,7 +141,44 @@ class Assembler:
             return value  # type: ignore[return-value]
 
     def has(self, type_: type[T]) -> bool:
-        return type_id_of(type_) in self._providers
+        """
+        Returns True if this Assembler has a provider for the given type.
+
+        Args:
+            type_: the type to check.
+
+        Returns:
+            True if the Assembler has a provider for type else False.
+        """
+        type_id = type_id_of(type_)
+        if type_id.multi:
+            return type_id in self._multiproviders
+        else:
+            return type_id in self._providers
+
+    def add(self, provider: Provide) -> None:
+        """
+        Add a provider to the Assembler post-initialisation.
+
+        Args:
+            provider: the Provide instance to add.
+
+        Returns:
+             None
+
+        Raises:
+            ValueError: if a provider for this type already exists.
+        """
+        type_id = provider.return_type_id
+        if provider.is_multiprovider:
+            if type_id in self._multiproviders:
+                self._multiproviders[type_id].append(provider)
+            else:
+                self._multiproviders[type_id] = [provider]
+        else:
+            if type_id in self._providers:
+                raise ValueError(f"A provider for '{type_id}' already exists")
+            self._providers[type_id] = provider
 
     def _resolve_providers(self, type_id: TypeId) -> Collection[Provide]:
         if type_id.multi:

engin/_dependency.py

@@ -3,6 +3,7 @@ import typing
 from abc import ABC
 from collections.abc import Awaitable, Callable
 from inspect import Parameter, Signature, isclass, iscoroutinefunction
+from types import FrameType
 from typing import (
     Any,
     Generic,
@@ -23,22 +24,43 @@ Func: TypeAlias = Callable[P, T]
 def _noop(*args: Any, **kwargs: Any) -> None: ...
 
 
+def _walk_stack() -> FrameType:
+    stack = inspect.stack()[1]
+    frame = stack.frame
+    while True:
+        if frame.f_globals["__package__"] != "engin" or frame.f_back is None:
+            return frame
+        else:
+            frame = frame.f_back
+
+
 class Dependency(ABC, Generic[P, T]):
     def __init__(self, func: Func[P, T], block_name: str | None = None) -> None:
         self._func = func
         self._is_async = iscoroutinefunction(func)
         self._signature = inspect.signature(self._func)
         self._block_name = block_name
+        self._source_frame = _walk_stack()
 
     @property
-    def origin(self) -> str:
+    def source_module(self) -> str:
         """
         The module that this Dependency originated from.
 
         Returns:
             A string, e.g. "examples.fastapi.app"
         """
-        return self._func.__module__
+        return self._source_frame.f_globals["__name__"]  # type: ignore[no-any-return]
+
+    @property
+    def source_package(self) -> str:
+        """
+        The package that this Dependency originated from.
+
+        Returns:
+            A string, e.g. "engin"
+        """
+        return self._source_frame.f_globals["__package__"]  # type: ignore[no-any-return]
 
     @property
     def block_name(self) -> str | None:
@@ -115,10 +137,6 @@ 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)]
@@ -140,6 +158,15 @@ class Provide(Dependency[Any, T]):
         super().__init__(func=builder, block_name=block_name)
         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()
+        ):
+            raise ValueError("A provider cannot depend on its own return type")
+
+        # Validate that multiproviders only return a list of one type.
         if self._is_multi:
             args = typing.get_args(self.return_type)
             if len(args) != 1:
@@ -186,10 +213,6 @@ 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/ext/asgi.py

@@ -1,9 +1,10 @@
+import contextlib
 import traceback
 from collections.abc import AsyncIterator, Awaitable, Callable, MutableMapping
 from contextlib import AbstractAsyncContextManager, asynccontextmanager
 from typing import Any, ClassVar, Protocol, TypeAlias
 
-from engin import Engin, Entrypoint, Option
+from engin import Engin, Entrypoint, Option, Supply
 
 __all__ = ["ASGIEngin", "ASGIType", "engin_to_lifespan"]
 
@@ -79,7 +80,13 @@ def engin_to_lifespan(engin: Engin) -> Callable[[ASGIType], AbstractAsyncContext
     """
 
     @asynccontextmanager
-    async def engin_lifespan(_: ASGIType) -> AsyncIterator[None]:
+    async def engin_lifespan(app: ASGIType) -> AsyncIterator[None]:
+        # ensure the Engin
+        with contextlib.suppress(ValueError):
+            engin.assembler.add(Supply(app))
+
+        app.state.assembler = engin.assembler  # type: ignore[attr-defined]
+
         await engin.start()
         yield
         await engin.stop()

engin/ext/fastapi.py

@@ -6,8 +6,8 @@ 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 import Assembler, Engin, Entrypoint, Invoke, Option
+from engin._dependency import Dependency, Supply, _noop
 from engin._graph import DependencyGrapher, Node
 from engin._type_utils import TypeId, type_id_of
 from engin.ext.asgi import ASGIEngin
@@ -24,15 +24,16 @@ except ImportError as err:
 __all__ = ["APIRouteDependency", "FastAPIEngin", "Inject"]
 
 
-def _attach_engin(
-    app: FastAPI,
-    engin: Engin,
-) -> None:
-    app.state.engin = engin
+def _attach_assembler(app: FastAPI, engin: Engin) -> None:
+    """
+    An invocation that attaches the Engin's Assembler to the FastAPI application, enabling
+    the Inject marker.
+    """
+    app.state.assembler = engin.assembler
 
 
 class FastAPIEngin(ASGIEngin):
-    _LIB_OPTIONS: ClassVar[list[Option]] = [*ASGIEngin._LIB_OPTIONS, Invoke(_attach_engin)]
+    _LIB_OPTIONS: ClassVar[list[Option]] = [*ASGIEngin._LIB_OPTIONS, Invoke(_attach_assembler)]
     _asgi_type = FastAPI
 
     def graph(self) -> list[Node]:
@@ -40,7 +41,7 @@ class FastAPIEngin(ASGIEngin):
         return grapher.resolve(
             [
                 Entrypoint(self._asgi_type),
-                *[i for i in self._invocations if i.func_name != "_attach_engin"],
+                *[i for i in self._invocations if i.func_name != "_attach_assembler"],
             ]
         )
 
@@ -50,8 +51,11 @@ 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)
+        try:
+            assembler: Assembler = conn.app.state.assembler
+        except AttributeError:
+            raise RuntimeError("Assembler is not attached to Application state") from None
+        return await assembler.get(interface)
 
     dep = Depends(inner)
     dep.__engin__ = True  # type: ignore[attr-defined]
@@ -113,7 +117,7 @@ def _extract_routes_from_supply(supply: Supply) -> list[Dependency]:
         inner = supply._value[0]
         if isinstance(inner, APIRouter):
             return [
-                APIRouteDependency(route, block_name=supply.block_name)
+                APIRouteDependency(supply, route)
                 for route in inner.routes
                 if isinstance(route, APIRoute)
             ]
@@ -128,13 +132,26 @@ class APIRouteDependency(Dependency):
     This class should never be constructed in application code.
     """
 
-    def __init__(self, route: APIRoute, block_name: str | None = None) -> None:
+    def __init__(
+        self,
+        wraps: Dependency,
+        route: APIRoute,
+    ) -> None:
         """
         Warning: this should never be constructed in application code.
         """
+        super().__init__(_noop, wraps.block_name)
+        self._wrapped = wraps
         self._route = route
         self._signature = inspect.signature(route.endpoint)
-        self._block_name = block_name
+
+    @property
+    def source_module(self) -> str:
+        return self._wrapped.source_module
+
+    @property
+    def source_package(self) -> str:
+        return self._wrapped.source_package
 
     @property
     def route(self) -> APIRoute:

engin/scripts/graph.py

@@ -28,6 +28,8 @@ args.add_argument(
     ),
 )
 
+_APP_ORIGIN = ""
+
 
 def serve_graph() -> None:
     # add cwd to path to enable local package imports
@@ -44,6 +46,9 @@ def serve_graph() -> None:
             "Expected an argument of the form 'module:attribute', e.g. 'myapp:engin'"
         ) from None
 
+    global _APP_ORIGIN
+    _APP_ORIGIN = module_name.split(".", maxsplit=1)[0]
+
     module = importlib.import_module(module_name)
 
     try:
@@ -112,7 +117,17 @@ def _render_node(node: Dependency) -> str:
         if n not in _BLOCK_IDX:
             _BLOCK_IDX[n] = len(_SEEN_BLOCKS) % 8
             _SEEN_BLOCKS.append(n)
-        style = f":::b{_BLOCK_IDX[n]}"
+        style = f"b{_BLOCK_IDX[n]}"
+
+    node_root_package = node.source_package.split(".", maxsplit=1)[0]
+    if node_root_package != _APP_ORIGIN:
+        if style:
+            style += "E"
+        else:
+            style = "external"
+
+    if style:
+        style = f":::{style}"
 
     if isinstance(node, Supply):
         md += f"{node.return_type_id}"
@@ -144,6 +159,7 @@ _GRAPH_HTML = """
           graph LR
             %%LEGEND%%
             classDef b0 fill:#7fc97f;
+            classDef external stroke-dasharray: 5 5;
         </pre>
     </div>
     <pre class="mermaid">
@@ -157,6 +173,15 @@ _GRAPH_HTML = """
           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';
@@ -169,6 +194,6 @@ _GRAPH_HTML = """
 
 DEFAULT_LEGEND = (
     "0[/Invoke/] ~~~ 1[/Entrypoint\\] ~~~ 2[Provide] ~~~ 3(Supply)"
-    ' ~~~ 4["`Block Grouping`"]:::b0'
+    ' ~~~ 4["`Block Grouping`"]:::b0 ~~~ 5[External Dependency]:::external'
 )
-ASGI_ENGIN_LEGEND = DEFAULT_LEGEND + " ~~~ 5[[API Route]]"
+ASGI_ENGIN_LEGEND = DEFAULT_LEGEND + " ~~~ 6[[API Route]]"

{engin-0.0.10.dist-info → engin-0.0.12.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: engin
-Version: 0.0.10
+Version: 0.0.12
 Summary: An async-first modular application framework
 Project-URL: Homepage, https://github.com/invokermain/engin
 Project-URL: Documentation, https://engin.readthedocs.io/en/latest/
@@ -12,6 +12,8 @@ Keywords: Application Framework,Dependency Injection
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 
+[![codecov](https://codecov.io/gh/invokermain/engin/graph/badge.svg?token=4PJOIMV6IB)](https://codecov.io/gh/invokermain/engin)
+
 # Engin 🏎️
 
 Engin is a zero-dependency application framework for modern Python.

{engin-0.0.10.dist-info → engin-0.0.12.dist-info}/RECORD

@@ -1,7 +1,7 @@
 engin/__init__.py,sha256=yTc8k0HDGMIrxDdEEA90qGD_dExQjVIbXCyaOFRrnMg,508
-engin/_assembler.py,sha256=6n8RBOwano3U3WM1P8Y6HLHo8IuPD_7jUMoTHBJoEA8,7713
+engin/_assembler.py,sha256=1ODW3HenDlIQLetg0LNEPPbsI6HkFnPU_AHzkR9Zxmc,8844
 engin/_block.py,sha256=0QJtqyP5uTFjXsdVGr4ZONLI2LhfzUKmQGnNQWouB3o,2121
-engin/_dependency.py,sha256=Nmyk4cGcK6ZZA8YWNZWgckLpDdKsRwOeRQhqRlxZmI0,5883
+engin/_dependency.py,sha256=RWOyGpMFp_5aLq5TP2wLKz0HT5f6CRoLvFyWvVif9jY,6825
 engin/_engin.py,sha256=MTE4MkLrK45h0Nv7p5H92Kv5URa1nX246B9Pp1JkM3A,9134
 engin/_exceptions.py,sha256=fsc4pTOIGHUh0x7oZhEXPJUTE268sIhswLoiqXaudiw,635
 engin/_graph.py,sha256=1pMB0cr--uS0XJycDb1rS_X45RBpoyA6NkKqbeSuz1Q,1628
@@ -9,12 +9,12 @@ 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=PCnemGVVB0jUZVcphz7y283sZ7D5Gog1o6rJ6g2TuCQ,2944
-engin/ext/fastapi.py,sha256=p9NekfRHbdNzK_1ttVNr500AO-IwLpBlG9Fhk6R0mmg,5649
+engin/ext/asgi.py,sha256=RUxkG03VTlvI6EG19c1nEJY8FnQw6MQwolfJSFnhUFE,3168
+engin/ext/fastapi.py,sha256=GO3AIZNQ69MtzbWuACffx_6Pp34wC5a5Fi_fIAaQvTg,6186
 engin/scripts/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-engin/scripts/graph.py,sha256=kmC_sSypGvIH89GddHz3KoRBEvooGNsGtrwLgw_uxNQ,4968
-engin-0.0.10.dist-info/METADATA,sha256=qal9-bNGzl3dvBhuoc9wZUN3F8dCl23oxvZKLMXSPFc,2162
-engin-0.0.10.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-engin-0.0.10.dist-info/entry_points.txt,sha256=Dehk4j5nK6zyuQtgOSRAoLE609V6eLzEp32bjqhO62Q,64
-engin-0.0.10.dist-info/licenses/LICENSE,sha256=XHh5LPUPKZWTBqBv2xxN2RU7D59nHoiJGb5RIt8f45w,1070
-engin-0.0.10.dist-info/RECORD,,
+engin/scripts/graph.py,sha256=por62FkzcWx72V2Ha9sIoki-o99fe2Ifm1w-mdoHZIQ,5922
+engin-0.0.12.dist-info/METADATA,sha256=lNUoVBIDpm9KlzvkPQWdY29gZsgfMI-3HHoQT7slA6k,2291
+engin-0.0.12.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+engin-0.0.12.dist-info/entry_points.txt,sha256=Dehk4j5nK6zyuQtgOSRAoLE609V6eLzEp32bjqhO62Q,64
+engin-0.0.12.dist-info/licenses/LICENSE,sha256=XHh5LPUPKZWTBqBv2xxN2RU7D59nHoiJGb5RIt8f45w,1070
+engin-0.0.12.dist-info/RECORD,,