engin 0.0.9__tar.gz → 0.0.11__tar.gz

{engin-0.0.9 → engin-0.0.11}/.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.9 → engin-0.0.11}/CHANGELOG.md

@@ -6,6 +6,30 @@ 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.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
+
+- A utility function for ASGI extension `engin_to_lifespan` enabling users to easily
+  integrate Engin into an existing ASGI application.
+- Further documentation work, including a FastAPI guide.
+
+### Fixed
+
+- The warning for missing multiproviders is only logged once for each given type now.
+
+
 ## [0.0.9] - 2025-02-22
 
 ### Added

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

@@ -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.9 → engin-0.0.11}/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.9 → engin-0.0.11}/docs/concepts/engin.md

@@ -3,6 +3,7 @@
 The Engin is a self-contained modular application.
 
 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 Invocations parameters are assembled.
 2. All Invocations are run sequentially in the order they were passed in to the Engin.

{engin-0.0.9 → engin-0.0.11}/docs/concepts/invocations.md

@@ -71,7 +71,8 @@ considered idiomatic as they have more explicit semantics.
 
 Sometimes you want to have logic that runs before the lifecycle startup occurs and after
 the dependency graph is built, some examples might be:
-- Pining a server to check its healthy.
+
+- Pinging a server to check its healthy.
 - Running database migrations.
 - Configuring a logger.
 

engin-0.0.11/docs/getting-started.md

@@ -0,0 +1,7 @@
+## Installation
+
+Engin is available on PyPI, install using your favourite dependency manager:
+
+- **pip**:`pip install engin`
+- **poetry**: `poetry add engin`
+- **uv**: `uv add engin`

engin-0.0.11/docs/guides/fastapi.md

@@ -0,0 +1,174 @@
+# FastAPI
+
+Engin ships with a FastAPI integration that is available under the `engin.ext.fastapi`
+module. The integration allows one to write idiomatic FastAPI code whilst leveraging Engin
+for Dependency Injection and modularising the application.
+
+!!! note
+
+    There is also a
+    [fastapi example](https://github.com/invokermain/engin/tree/main/examples/fastapi) in
+    the Github repo if you want to see it in action.
+
+
+## Setup
+
+To run an empty FastAPI server with Engin, simply use the `FastAPIEngin` class and
+provide an instance of a `FastAPI` application:
+
+```python
+from engin import Supply
+from engin.ext.fastapi import FastAPIEngin
+from fastapi import FastAPI
+import uvicorn
+
+app = FastAPIEngin(Supply(FastAPI()))
+
+if __name__ == "__main__":
+    uvicorn.run(app)
+```
+
+The `FastAPIEngin` instance is just a thin wrapper on top of the FastAPI application and
+exposes the normal ASGI application interface and therefore can be run by uvicorn or
+other server implementations. Under the hood it will just pass calls to the `FastAPI`
+instance that you provided.
+
+
+!!!tip
+
+    It is also easy to integrate Engin with an existing FastAPI application by using the
+    `engin_to_lifespan` function in the `engin.ext.asgi` module.
+
+
+## Dependency Injection
+
+FastAPI comes with its own simple dependency injection system which allows you inject
+depenendencies into a route by declaring a parameter with a special type hint of the form
+`Annotated[T, Depends(func)]`. For example if we wanted to inject an instance of
+`SomeClass`:
+
+```python
+async def make_some_class():
+    return SomeClass(a=1, b=2)
+
+@app.get("/")
+async def read_items(some_class: Annotated[SomeClass, Depends(make_some_class)]):
+    # do something with some_class
+    return "hello"
+```
+
+Engin ships with a similar marker, called `Inject`, which can be used to inject
+dependencies it has providers for, for example if Engin provided `SomeClass` instead:
+
+```python
+@app.get("/")
+async def read_items(some_class: Annotated[SomeClass, Inject(SomeClass)]):
+    # do something with some_class
+    return "hello"
+```
+
+The `Inject` marker can be used anywhere that `Depends` can be used. This can be useful as
+FastAPI dependencies can have per request lifecycle, for example if we wanted to have a
+reusable SQL session per request, we could use a nested dependency:
+
+```python
+from typing import Annotated, AsyncIterable
+
+from engin.ext.fastapi import Inject
+from fastapi import Depends
+
+async def database_session(
+    database: Annotated[Database, Inject(Database)])
+) -> AsyncIterable[Session]:
+    with database.new_session() as session:
+        yield session
+        session.commit()
+
+@app.post("/{id}")
+async def add_item(session: Annotated[Session, Depends(database_session)]):
+    session.add(MyORMModel(...))
+```
+
+
+## Attaching Routers to Engin
+
+The usual way to declare an `APIRouter` is as a module level variable, for example:
+
+```python title="api.py"
+from fastapi import APIRouter
+
+users_router = APIRouter(prefix="/users")
+
+@users_router.get("/{user_id}")
+def get_user(user_id: int) -> dict[str, Any]:
+    return {"id": user_id, "name": "Rakim"}
+```
+
+To attach this to our `FastAPIEngin`, we need to provide it. The recommended way to do
+this is to use `Supply` as the router is already instantiated. We also need to add the
+`APIRouter` to our `FastAPI` application, we can do this in the provider for `FastAPI`.
+
+```python title="app.py"
+from engin.ext.fastapi import FastAPIEngin
+from fastapi import FastAPI
+
+from api import users_router
+
+def create_fastapi_app(api_routers: list[APIRouter]) -> FastAPI:
+    app = FastAPI()
+    
+    for api_router in api_routers:
+        app.include_router(api_router)
+        
+    return app
+
+
+app = FastAPIEngin(Provide(create_fastapi_app), Supply([users_router]))
+```
+
+!!!info
+
+    Notice that the `users_router` is supplied in a list, as we want to be able to
+    support multiple APIRouters as our application grows.
+
+Or similarly, we could use a block instead:
+
+```python title="app.py"
+from engin import Block, provide
+from engin.ext.fastapi import FastAPIEngin
+from fastapi import FastAPI
+
+from api import users_router
+
+class AppBlock(Block):
+    options = [Supply([users_router])]
+    
+    @provide
+    def create_fastapi_app(self, api_routers: list[APIRouter]) -> FastAPI:
+        app = FastAPI()
+        
+        for api_router in api_routers:
+            app.include_router(api_router)
+            
+        return app
+
+
+app = FastAPIEngin(AppBlock())
+```
+
+
+## Graphing Dependencies
+
+Engin provides dependency visualisation functionality via the `engin-graph` script. When
+working with a FastAPI application this can be used to visualise API Routes along with
+their respective dependencies.
+
+![fastapi-graph.png](fastapi-graph.png){ width="500", loading=lazy }
+/// caption
+Visualisation of the FastAPI example's dependency graph.
+///
+
+Note that due to the split between Engin's dependency injection framework and FastAPI's,
+resolving API Routers and their dependencies is slightly harder for Engin. Due to this
+there is currently a limitation where Engin will only be aware of APIRouters that have
+been provided using `Supply` and not via `Provide` or `@provide` in a Block.

{engin-0.0.9 → engin-0.0.11}/docs/index.md

@@ -9,21 +9,13 @@ Engin is inspired by [Uber's Fx framework for Go](https://github.com/uber-go/fx)
 
 - **Dependency Injection** - Engin includes a fully-featured Dependency Injection system,
   powered by type hints.
-- **Lifecycle Management** - Engin provides a simple & portable approach for attaching
-  startup and shutdown tasks to the application's lifecycle.
+- **Applicaton Management** - Engin can run your whole application from start to end with
+  a simple call to `run()` including managing lifecycle startup and shutdown tasks. 
 - **Code Reuse** - Engin's modular components, called Blocks, work great as distributed
   packages allowing zero boiler-plate code reuse across multiple applications. Perfect for
   maintaining many services across your organisation.
 - **Ecosystem Compatability** - Engin ships with integrations for popular frameworks that
-  provide their own Dependency Injection, for example FastAPI, allowing you to integrate
+  provide their own Dependency Injection, such as FastAPI, allowing you to integrate
   Engin into existing code bases incrementally.
 - **Async Native**: Engin is an async framework, meaning first class support for async
-  dependencies. However Engin will happily run synchronous code as well.
-
-## Installation
-
-Engin is available on PyPI, install using your favourite dependency manager:
-
-- **pip**:`pip install engin`
-- **poetry**: `poetry add engin`
-- **uv**: `uv add engin`
+  dependencies and applications, but can easily run synchronous code as well.

engin-0.0.11/docs/reference.md

@@ -0,0 +1,12 @@
+
+## Engin
+
+::: engin.Engin
+
+## Provide
+
+::: engin.Provide
+
+## Lifecycle
+
+::: engin.Lifecycle

{engin-0.0.9 → engin-0.0.11}/mkdocs.yaml

@@ -5,6 +5,9 @@ site_url: !ENV READTHEDOCS_CANONICAL_URL
 theme:
     name: 'material'
     custom_dir: 'docs/overrides'
+    features:
+      - navigation.instant
+      - navigation.tabs
     palette:
       - scheme: 'default'
         media: '(prefers-color-scheme: light)'
@@ -22,6 +25,19 @@ repo_name: invokermain/engin
 repo_url: https://github.com/invokermain/engin/
 edit_uri: ""
 
+nav:
+  - Home: "index.md"
+  - Getting Started: "getting-started.md"
+  - Concepts:
+      - Engin: "concepts/engin.md"
+      - Providers: "concepts/providers.md"
+      - Invocations: "concepts/invocations.md"
+      - Lifecycle: "concepts/lifecycle.md"
+  - Guides:
+      - Dependency Injection: "guides/dependency_injection.md"
+      - FastAPI: "guides/fastapi.md"
+  - Reference: "reference.md"
+
 extra_javascript:
   - js/readthedocs.js
 
@@ -39,6 +55,7 @@ plugins:
             ignore_init_summary: true
           merge_init_into_class: true
           show_signature_annotations: true
+          show_source: false
           signature_crossrefs: true
         import:
           - url: https://docs.python.org/3/objects.inv
@@ -48,6 +65,11 @@ watch:
   - src
 
 markdown_extensions:
+  - admonition
+  - attr_list
+  - md_in_html
+  - pymdownx.blocks.caption
+  - pymdownx.details
   - pymdownx.highlight:
       anchor_linenums: true
       line_spans: __span

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

@@ -1,6 +1,6 @@
 [project]
 name = "engin"
-version = "0.0.9"
+version = "0.0.11"
 description = "An async-first modular application framework"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -40,6 +40,9 @@ docs = [
     "mkdocs-material>=9.5.50",
     "mkdocstrings[python]>=0.27.0",
 ]
+dev = [
+    "pytest-cov>=6.0.0",
+]
 
 
 [project.scripts]
@@ -100,6 +103,8 @@ check.sequence = [
 ]
 
 fix.default_item_type = "cmd"
-fix.sequence = ["ruff check src tests --fix"]
+fix.sequence = ["ruff check src tests examples --fix"]
 
 test = "pytest -s tests"
+ci-test = "pytest -s tests --cov-branch --cov-report=xml"
+docs = "mkdocs serve"

{engin-0.0.9 → engin-0.0.11}/src/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-0.0.9 → engin-0.0.11}/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)]
@@ -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-0.0.9 → engin-0.0.11}/src/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-0.0.9 → engin-0.0.11}/src/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-0.0.9 → engin-0.0.11}/src/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-0.0.9 → engin-0.0.11}/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.9 → engin-0.0.11}/tests/test_dependencies.py

@@ -1,8 +1,8 @@
 from typing import Annotated
 
 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 +57,21 @@ 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"