engin 0.0.19__tar.gz → 0.0.20__tar.gz

{engin-0.0.19 → engin-0.0.20}/CHANGELOG.md

@@ -6,6 +6,18 @@ 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.20] - 2025-06-18
+
+### Changed
+
+- Improved string representation of Provide & Supply to make error messages more helpful.
+
+### Fixed
+
+- Engin now correctly supports postponed evaluation of annotations, e.g. `x: "MyType"` in
+  a factory function.
+
+
 ## [0.0.19] - 2025-04-27
 
 ### Added

{engin-0.0.19 → engin-0.0.20}/PKG-INFO

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

@@ -33,6 +33,7 @@ nav:
       - Providers: "concepts/providers.md"
       - Invocations: "concepts/invocations.md"
       - Lifecycle: "concepts/lifecycle.md"
+      - Blocks: "concepts/blocks.md"
   - Guides:
       - FastAPI: "guides/fastapi.md"
   - Reference: "reference.md"

{engin-0.0.19 → engin-0.0.20}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "engin"
-version = "0.0.19"
+version = "0.0.20"
 description = "An async-first modular application framework"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -38,6 +38,7 @@ dev = [
     "typer>=0.15.2",
     "pytest-mock>=3.14.0",
     "pytest-benchmark>=5.1.0",
+    "websockets>=15.0.1",
 ]
 docs = [
     "mkdocs-material>=9.5.50",

{engin-0.0.19 → engin-0.0.20}/src/engin/_dependency.py

@@ -33,7 +33,7 @@ class Dependency(ABC, Option, Generic[P, T]):
     def __init__(self, func: Func[P, T]) -> None:
         self._func = func
         self._is_async = iscoroutinefunction(func)
-        self._signature = inspect.signature(self._func)
+        self._signature = inspect.signature(self._func, eval_str=True)
         self._block_name: str | None = None
 
         source_frame = get_first_external_frame()
@@ -154,24 +154,24 @@ class Entrypoint(Invoke):
 class Provide(Dependency[Any, T]):
     def __init__(
         self,
-        builder: Func[P, T],
+        factory: 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.
+        Provide a type via a factory function.
 
         Args:
-            builder: the builder function that returns the type.
+            factory: the factory function that returns the type.
             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)
+        super().__init__(func=factory)
         self._scope = scope
         self._override = override
         self._explicit_type = as_type
@@ -231,9 +231,9 @@ class Provide(Dependency[Any, T]):
         # overwriting a dependency from the same package must be explicit
         if is_same_package and not self._override:
             msg = (
-                f"Provider '{self.name}' is implicitly overriding "
-                f"'{existing_provider.name}', if this is intended specify "
-                "`override=True` for the overriding Provider"
+                f"{self} from '{self._source_frame}' is implicitly overriding "
+                f"{existing_provider} from '{existing_provider.source_module}', if this "
+                "is intentional specify `override=True` for the overriding Provider"
             )
             raise RuntimeError(msg)
 
@@ -243,7 +243,7 @@ class Provide(Dependency[Any, T]):
         return hash(self.return_type_id)
 
     def __str__(self) -> str:
-        return f"Provide({self.return_type_id})"
+        return f"Provide(factory={self.func_name}, type={self._return_type_id})"
 
     def _resolve_return_type(self) -> type[T]:
         if self._explicit_type is not None:
@@ -279,7 +279,14 @@ class Supply(Provide, Generic[T]):
               same type from the same package.
         """
         self._value = value
-        super().__init__(builder=self._get_val, as_type=as_type, override=override)
+        super().__init__(factory=self._get_val, as_type=as_type, override=override)
+
+    @property
+    def name(self) -> str:
+        if self._block_name:
+            return f"{self._block_name}.supply"
+        else:
+            return f"{self._source_frame}.supply"
 
     def _resolve_return_type(self) -> type[T]:
         if self._explicit_type is not None:
@@ -292,4 +299,4 @@ class Supply(Provide, Generic[T]):
         return self._value
 
     def __str__(self) -> str:
-        return f"Supply({self.return_type_id})"
+        return f"Supply(value={self._value}, type={self.return_type_id})"

{engin-0.0.19 → engin-0.0.20}/src/engin/_type_utils.py

@@ -33,8 +33,8 @@ class TypeId:
             return TypeId(type=type_, multi=False)
 
     def __str__(self) -> str:
-        module = self.type.__module__
-        out = f"{module}." if module not in _implict_modules else ""
+        module = getattr(self.type, "__module__", None)
+        out = f"{module}." if module and module not in _implict_modules else ""
         out += _args_to_str(self.type)
         if self.multi:
             out += "[]"

{engin-0.0.19 → engin-0.0.20}/tests/acceptance/test_fastapi.py

@@ -4,6 +4,7 @@ from typing import Annotated
 import pytest
 import starlette.testclient
 from fastapi import APIRouter, FastAPI
+from starlette.websockets import WebSocket
 
 from engin import Engin, Provide, Supply
 from engin.extensions.asgi import engin_to_lifespan
@@ -22,6 +23,16 @@ async def route_with_dep(some_int: Annotated[int, Inject(int)]) -> int:
     return some_int
 
 
+@ROUTER.websocket("/websocket")
+async def websocket_with_dep(
+    websocket: WebSocket, some_int: Annotated[int, Inject(int)]
+) -> None:
+    await websocket.accept()
+    for i in range(5):
+        await websocket.send_text(str(i + some_int))
+    await websocket.close()
+
+
 @ROUTER.get("/inject2")
 async def route_with_dep_2(
     some_int: Annotated[int, Inject(int)], some_str: Annotated[str, Inject(str)]
@@ -37,7 +48,7 @@ def app_factory(routers: list[APIRouter]) -> FastAPI:
     return app
 
 
-async def test_fastapi():
+def test_fastapi():
     engin = FastAPIEngin(Provide(app_factory), Supply([ROUTER]))
 
     with starlette.testclient.TestClient(engin) as client:
@@ -46,15 +57,26 @@ async def test_fastapi():
     assert result.json() == "hello world"
 
 
-async def test_inject():
+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")
+        result = client.get("/inject")
 
     assert result.json() == 10
 
 
+def test_inject_websocket():
+    engin = FastAPIEngin(Provide(app_factory), Supply([ROUTER]), Supply(10))
+
+    with (
+        starlette.testclient.TestClient(engin) as client,
+        client.websocket_connect("/websocket") as ws,
+    ):
+        data = ws.receive_text()
+        assert data == "10"
+
+
 async def test_graph():
     engin = FastAPIEngin(Provide(app_factory), Supply([ROUTER]), Supply(10), Supply("a"))
 

{engin-0.0.19 → engin-0.0.20}/tests/test_dependencies.py

@@ -90,7 +90,7 @@ def test_provider_cannot_depend_on_self():
         Provide(invalid_provider_2)
 
 
-def test_provides_implicit_overrides():
+def test_provides_implicit_overrides_providers():
     provide_a = int_provider()
     provide_b = int_provider()
 
@@ -103,6 +103,19 @@ def test_provides_implicit_overrides():
         provide_b.apply(engin)
 
 
+def test_provides_implicit_overrides_supply():
+    provide_a = Supply(3)
+    provide_b = Supply(4)
+
+    engin = Mock()
+    engin._providers = {}
+
+    provide_a.apply(engin)
+
+    with pytest.raises(RuntimeError, match="implicit"):
+        provide_b.apply(engin)
+
+
 def test_provides_explicit_overrides_allowed():
     provide_a = int_provider()
     provide_b = int_provider(override=True)

engin-0.0.19/tests/test_utils.py → engin-0.0.20/tests/test_type_id.py

@@ -1,7 +1,7 @@
 from collections.abc import Callable
 from typing import Annotated, TypeAlias
 
-from engin._type_utils import TypeId
+from engin import TypeId
 
 
 def test_type_id_of_int():