engin 0.0.9__py3-none-any.whl → 0.0.11__py3-none-any.whl

engin/_assembler.py

@@ -152,6 +152,8 @@ class Assembler:
             if type_id.multi:
                 LOG.warning(f"no provider for '{type_id}' defaulting to empty list")
                 providers = [(Supply([], type_hint=list[type_id.type]))]  # type: ignore[name-defined]
+                # store default to prevent the warning appearing multiple times
+                self._multiproviders[type_id] = providers
             else:
                 raise LookupError(f"No Provider registered for dependency '{type_id}'")
 

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)]
@@ -186,10 +204,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/_engin.py

@@ -39,6 +39,7 @@ class Engin:
     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
        the Invoke options parameters are assembled.
     2. All Invocations are run sequentially in the order they were passed in to the Engin.

engin/ext/asgi.py

@@ -1,10 +1,11 @@
 import traceback
-from collections.abc import Awaitable, Callable, MutableMapping
+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
 
-__all__ = ["ASGIEngin", "ASGIType"]
+__all__ = ["ASGIEngin", "ASGIType", "engin_to_lifespan"]
 
 from engin._graph import DependencyGrapher, Node
 
@@ -61,3 +62,26 @@ class _Rereceive:
 
     async def __call__(self, *args: Any, **kwargs: Any) -> _Message:
         return self._message
+
+
+def engin_to_lifespan(engin: Engin) -> Callable[[ASGIType], AbstractAsyncContextManager[None]]:
+    """
+    Transforms the Engin instance into an ASGI lifespan task.
+
+    This is to enable users to use the Engin framework with existing ASGI applications,
+    where it is not desired to replace the ASGI application with an ASGIEngin.
+
+    Args:
+        engin: the engin instance to transform.
+
+    Returns:
+        An ASGI lifespan task.
+    """
+
+    @asynccontextmanager
+    async def engin_lifespan(_: ASGIType) -> AsyncIterator[None]:
+        await engin.start()
+        yield
+        await engin.stop()
+
+    return engin_lifespan

engin/ext/fastapi.py

@@ -7,7 +7,7 @@ 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._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
@@ -113,7 +113,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 +128,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.9.dist-info → engin-0.0.11.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: engin
-Version: 0.0.9
+Version: 0.0.11
 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.11.dist-info/RECORD

@@ -0,0 +1,20 @@
+engin/__init__.py,sha256=yTc8k0HDGMIrxDdEEA90qGD_dExQjVIbXCyaOFRrnMg,508
+engin/_assembler.py,sha256=6n8RBOwano3U3WM1P8Y6HLHo8IuPD_7jUMoTHBJoEA8,7713
+engin/_block.py,sha256=0QJtqyP5uTFjXsdVGr4ZONLI2LhfzUKmQGnNQWouB3o,2121
+engin/_dependency.py,sha256=URAuzA8pfLxAnwhrEZQGqO1wNCVN-WQLlFg1j1Kn-vs,6380
+engin/_engin.py,sha256=MTE4MkLrK45h0Nv7p5H92Kv5URa1nX246B9Pp1JkM3A,9134
+engin/_exceptions.py,sha256=fsc4pTOIGHUh0x7oZhEXPJUTE268sIhswLoiqXaudiw,635
+engin/_graph.py,sha256=1pMB0cr--uS0XJycDb1rS_X45RBpoyA6NkKqbeSuz1Q,1628
+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=whlzhkyG0l-fF2JQ0IeBBtg1NjwjaIUxKrM3FuAgKyE,5885
+engin/scripts/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+engin/scripts/graph.py,sha256=por62FkzcWx72V2Ha9sIoki-o99fe2Ifm1w-mdoHZIQ,5922
+engin-0.0.11.dist-info/METADATA,sha256=p63ZZiEGzl4jLTj6mQc0n7t-rLoStbp-c5vKI49cF2Y,2291
+engin-0.0.11.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+engin-0.0.11.dist-info/entry_points.txt,sha256=Dehk4j5nK6zyuQtgOSRAoLE609V6eLzEp32bjqhO62Q,64
+engin-0.0.11.dist-info/licenses/LICENSE,sha256=XHh5LPUPKZWTBqBv2xxN2RU7D59nHoiJGb5RIt8f45w,1070
+engin-0.0.11.dist-info/RECORD,,

engin-0.0.9.dist-info/RECORD

@@ -1,20 +0,0 @@
-engin/__init__.py,sha256=yTc8k0HDGMIrxDdEEA90qGD_dExQjVIbXCyaOFRrnMg,508
-engin/_assembler.py,sha256=VCZA_Gq4hnH5LueB_vEVqsKbGXx-nI6KQ65YhzXw-VY,7575
-engin/_block.py,sha256=0QJtqyP5uTFjXsdVGr4ZONLI2LhfzUKmQGnNQWouB3o,2121
-engin/_dependency.py,sha256=Nmyk4cGcK6ZZA8YWNZWgckLpDdKsRwOeRQhqRlxZmI0,5883
-engin/_engin.py,sha256=i2IxMIz-3yKjedyg5L6gQEpdFDUZnCbXi9Pwhw8Hsxk,9133
-engin/_exceptions.py,sha256=fsc4pTOIGHUh0x7oZhEXPJUTE268sIhswLoiqXaudiw,635
-engin/_graph.py,sha256=1pMB0cr--uS0XJycDb1rS_X45RBpoyA6NkKqbeSuz1Q,1628
-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=ViAWw-PNaP6y5fHK2rSGRfaxj7xxo217eqU2z2rhnq8,2200
-engin/ext/fastapi.py,sha256=p9NekfRHbdNzK_1ttVNr500AO-IwLpBlG9Fhk6R0mmg,5649
-engin/scripts/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-engin/scripts/graph.py,sha256=kmC_sSypGvIH89GddHz3KoRBEvooGNsGtrwLgw_uxNQ,4968
-engin-0.0.9.dist-info/METADATA,sha256=fzCqyXhGBzC1hMcTtbRM9-oXVaHEP000abzPi9QZbFQ,2161
-engin-0.0.9.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-engin-0.0.9.dist-info/entry_points.txt,sha256=Dehk4j5nK6zyuQtgOSRAoLE609V6eLzEp32bjqhO62Q,64
-engin-0.0.9.dist-info/licenses/LICENSE,sha256=XHh5LPUPKZWTBqBv2xxN2RU7D59nHoiJGb5RIt8f45w,1070
-engin-0.0.9.dist-info/RECORD,,