engin 0.0.11__tar.gz → 0.0.13__tar.gz

{engin-0.0.11 → engin-0.0.13}/CHANGELOG.md

@@ -6,6 +6,28 @@ 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.13] - 2025-03-12
+
+### Changed
+
+- `Provide` now supports union types.
+
+
+## [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

{engin-0.0.11 → engin-0.0.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: engin
-Version: 0.0.11
+Version: 0.0.13
 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.11 → engin-0.0.13}/mkdocs.yaml

@@ -57,7 +57,7 @@ plugins:
           show_signature_annotations: true
           show_source: false
           signature_crossrefs: true
-        import:
+        inventories:
           - url: https://docs.python.org/3/objects.inv
             domains: [py, std]
 

{engin-0.0.11 → engin-0.0.13}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "engin"
-version = "0.0.11"
+version = "0.0.13"
 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",
 ]
 
 
@@ -40,9 +41,6 @@ docs = [
     "mkdocs-material>=9.5.50",
     "mkdocstrings[python]>=0.27.0",
 ]
-dev = [
-    "pytest-cov>=6.0.0",
-]
 
 
 [project.scripts]
@@ -75,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 = [
@@ -105,6 +108,6 @@ check.sequence = [
 fix.default_item_type = "cmd"
 fix.sequence = ["ruff check src tests examples --fix"]
 
-test = "pytest -s tests"
-ci-test = "pytest -s tests --cov-branch --cov-report=xml"
+test = "pytest tests"
+ci-test = "pytest --cov=engin --cov-branch --cov-report=xml tests"
 docs = "mkdocs serve"

{engin-0.0.11 → engin-0.0.13}/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.11 → engin-0.0.13}/src/engin/_dependency.py

@@ -158,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:

{engin-0.0.11 → engin-0.0.13}/src/engin/_type_utils.py

@@ -1,8 +1,9 @@
 import typing
 from dataclasses import dataclass
+from types import UnionType
 from typing import Any
 
-_implict_modules = ["builtins", "typing", "collections.abc"]
+_implict_modules = ["builtins", "typing", "collections.abc", "types"]
 
 
 @dataclass(frozen=True, eq=True, slots=True)
@@ -43,7 +44,7 @@ class TypeId:
 def _args_to_str(type_: Any) -> str:
     args = typing.get_args(type_)
     if args:
-        arg_str = f"{type_.__name__}["
+        arg_str = "Union[" if isinstance(type_, UnionType) else f"{type_.__name__}["
         for idx, arg in enumerate(args):
             if isinstance(arg, list):
                 arg_str += "["

{engin-0.0.11 → engin-0.0.13}/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.11 → engin-0.0.13}/src/engin/ext/fastapi.py

@@ -6,7 +6,7 @@ from typing import ClassVar, TypeVar
 
 from fastapi.routing import APIRoute
 
-from engin import Engin, Entrypoint, Invoke, Option
+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
@@ -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]

engin-0.0.13/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.11 → engin-0.0.13}/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.11 → engin-0.0.13}/tests/test_dependencies.py

@@ -1,5 +1,7 @@
 from typing import Annotated
 
+import pytest
+
 from engin import Provide
 from engin._dependency import Entrypoint, Supply
 from tests.deps import make_aliased_int, make_int
@@ -75,3 +77,17 @@ def test_dependency_sources():
     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)

{engin-0.0.11 → engin-0.0.13}/tests/test_utils.py

@@ -60,3 +60,10 @@ def test_type_id_of_complex_annotation():
     type_id = type_id_of(annotated)
     assert type_id == TypeId(type=Annotated[Callable[[int], str], "Activity"], multi=False)
     assert str(type_id) == "Annotated[Callable[[int], str], Activity]"
+
+
+def test_type_id_of_union():
+    union = int | str
+    type_id = type_id_of(union)
+    assert type_id == TypeId(type=int | str, multi=False)
+    assert str(type_id) == "Union[int, str]"

{engin-0.0.11 → engin-0.0.13}/uv.lock

@@ -206,7 +206,7 @@ toml = [
 
 [[package]]
 name = "engin"
-version = "0.0.11"
+version = "0.0.13"
 source = { editable = "." }
 
 [package.dev-dependencies]