engin 0.0.10__tar.gz → 0.0.12__tar.gz

{engin-0.0.10 → engin-0.0.12}/.github/workflows/check.yaml

@@ -32,4 +32,9 @@ jobs:
         run: uv run poe check
 
       - name: Test
-        run: uv run poe test
+        run: uv run poe ci-test
+
+      - name: Upload coverage reports to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}

{engin-0.0.10 → engin-0.0.12}/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.12] - 2025-03-03
+
+### Added
+
+- `Assembler` has a new method `add(provider: Provide) -> None` which allows adding a
+  provider to the Assembler post initialisation.
+
+### Changed
+
+- `Provide` now raises a `ValueError` if the factory function is circular, i.e. one of its
+  parameters is the same as its return type as the behaviour of this is undefined.
+- The ASGI utility method `engin_to_lifespan` has been improved so that it works "out of
+  the box" for more use cases now.
+
+
+## [0.0.11] - 2025-03-02
+
+### Added
+
+- Dependency types now have two new attributes `source_module` & `source_package`.
+
+### Changed
+
+- `engin-graph` now highlights external dependencies.
+
+
 ## [0.0.10] - 2025-02-27
 
 ### Added

{engin-0.0.10 → engin-0.0.12}/PKG-INFO

@@ -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 → engin-0.0.12}/README.md

@@ -1,3 +1,5 @@
+[![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 → engin-0.0.12}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "engin"
-version = "0.0.10"
+version = "0.0.12"
 description = "An async-first modular application framework"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -32,6 +32,7 @@ dev-dependencies = [
     "ruff>=0",
     "starlette>=0.39.2",
     "uvicorn>=0.31.1",
+    "pytest-cov>=6.0.0",
 ]
 
 
@@ -72,12 +73,17 @@ ignore = [
 
 
 [tool.pytest.ini_options]
-log_cli = true
+log_cli = false
 log_cli_level = "DEBUG"
 asyncio_mode = "auto"
 asyncio_default_fixture_loop_scope = "session"
 
 
+[tool.coverage.run]
+source = ["src"]
+omit = ["src/engin/scripts/**"]
+
+
 [tool.mypy]
 strict = true
 disable_error_code = [
@@ -102,5 +108,6 @@ check.sequence = [
 fix.default_item_type = "cmd"
 fix.sequence = ["ruff check src tests examples --fix"]
 
-test = "pytest -s tests"
+test = "pytest tests"
+ci-test = "pytest --cov=engin --cov-branch --cov-report=xml tests"
 docs = "mkdocs serve"

{engin-0.0.10 → engin-0.0.12}/src/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-0.0.10 → engin-0.0.12}/src/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-0.0.10 → engin-0.0.12}/src/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-0.0.10 → engin-0.0.12}/src/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-0.0.10 → engin-0.0.12}/src/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.12/tests/acceptance/test_fastapi.py

@@ -0,0 +1,72 @@
+from typing import Annotated
+
+import pytest
+import starlette.testclient
+from fastapi import APIRouter, FastAPI
+
+from engin import Engin, Provide, Supply
+from engin.ext.asgi import engin_to_lifespan
+from engin.ext.fastapi import APIRouteDependency, FastAPIEngin, Inject
+
+ROUTER = APIRouter(prefix="")
+
+
+@ROUTER.get("/")
+async def hello_world() -> str:
+    return "hello world"
+
+
+@ROUTER.get("/inject")
+async def route_with_dep(some_int: Annotated[int, Inject(int)]) -> int:
+    return some_int
+
+
+def app_factory(routers: list[APIRouter]) -> FastAPI:
+    app = FastAPI()
+    for router in routers:
+        app.include_router(router)
+    return app
+
+
+async def test_fastapi():
+    engin = FastAPIEngin(Provide(app_factory), Supply([ROUTER]))
+
+    with starlette.testclient.TestClient(engin) as client:
+        result = client.get("http://127.0.0.1:8000/")
+
+    assert result.json() == "hello world"
+
+
+async def test_inject():
+    engin = FastAPIEngin(Provide(app_factory), Supply([ROUTER]), Supply(10))
+
+    with starlette.testclient.TestClient(engin) as client:
+        result = client.get("http://127.0.0.1:8000/inject")
+
+    assert result.json() == 10
+
+
+async def test_graph():
+    engin = FastAPIEngin(Provide(app_factory), Supply([ROUTER]), Supply(10))
+
+    nodes = engin.graph()
+
+    assert len(nodes) == 5
+    assert len([node for node in nodes if isinstance(node.node, APIRouteDependency)]) == 2
+
+
+async def test_invalid_engin():
+    with pytest.raises(LookupError, match="FastAPI"):
+        FastAPIEngin()
+
+
+async def test_engin_to_lifespan():
+    engin = Engin(Supply(10))
+
+    app = FastAPI(lifespan=engin_to_lifespan(engin))
+    app.include_router(ROUTER)
+
+    with starlette.testclient.TestClient(app) as client:
+        result = client.get("http://127.0.0.1:8000/inject")
+
+    assert result.json() == 10

{engin-0.0.10 → engin-0.0.12}/tests/test_assembler.py

@@ -83,3 +83,40 @@ async def test_annotations():
 
     assert await assembler.get(Annotated[str, "1"]) == "bar"
     assert await assembler.get(Annotated[str, "2"]) == "foo"
+
+
+async def test_assembler_has():
+    def make_str() -> str:
+        raise RuntimeError("foo")
+
+    assembler = Assembler([Provide(make_str)])
+
+    assert assembler.has(str)
+    assert not assembler.has(int)
+    assert not assembler.has(list[str])
+
+
+async def test_assembler_has_multi():
+    def make_str() -> list[str]:
+        raise RuntimeError("foo")
+
+    assembler = Assembler([Provide(make_str)])
+
+    assert assembler.has(list[str])
+    assert not assembler.has(int)
+    assert not assembler.has(str)
+
+
+async def test_assembler_add():
+    assembler = Assembler([])
+    assembler.add(Provide(make_int))
+    assembler.add(Provide(make_many_int))
+
+    assert assembler.has(int)
+    assert assembler.has(list[int])
+
+    with pytest.raises(ValueError, match="exists"):
+        assembler.add(Provide(make_int))
+
+    # can always add more multiproviders
+    assembler.add(Provide(make_many_int))

{engin-0.0.10 → engin-0.0.12}/tests/test_dependencies.py

@@ -1,8 +1,10 @@
 from typing import Annotated
 
+import pytest
+
 from engin import Provide
-from engin._dependency import Supply
-from tests.deps import make_aliased_int
+from engin._dependency import Entrypoint, Supply
+from tests.deps import make_aliased_int, make_int
 
 
 def test_provide_discriminates_singular():
@@ -57,3 +59,35 @@ def test_provide_with_annotation():
 
     assert provider.return_type_id.type
     assert str(provider.return_type_id) == "Annotated[str, 1]"
+
+
+def test_dependency_sources():
+    provide = Provide(make_int)
+    assert provide.source_module == "tests.test_dependencies"
+    assert provide.source_package == "tests"
+
+    supply = Supply(3)
+    assert supply.source_module == "tests.test_dependencies"
+    assert supply.source_package == "tests"
+
+    invoke = Provide(make_int)
+    assert invoke.source_module == "tests.test_dependencies"
+    assert invoke.source_package == "tests"
+
+    entrypoint = Entrypoint(3)
+    assert entrypoint.source_module == "tests.test_dependencies"
+    assert entrypoint.source_package == "tests"
+
+
+def test_provider_cannot_depend_on_self():
+    def invalid_provider_1(a: int) -> int:
+        return 1
+
+    def invalid_provider_2(a: list[int]) -> list[int]:
+        return [1]
+
+    with pytest.raises(ValueError, match="return type"):
+        Provide(invalid_provider_1)
+
+    with pytest.raises(ValueError, match="return type"):
+        Provide(invalid_provider_2)