engin 0.0.8__tar.gz → 0.0.10__tar.gz

{engin-0.0.8 → engin-0.0.10}/CHANGELOG.md

@@ -6,6 +6,35 @@ 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.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
+
+- Dependency class now has a new attribute: `func_name`.
+
+### Changed
+
+- Improved `engin-graph` output.
+- The `module` attribute of dependencies has been renamed to `origin`
+
+### Fixed
+
+- Options provided under the `options` on a Block now have the `block_name` set.
+
+
 ## [0.0.8] - 2025-02-22
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: engin
-Version: 0.0.8
+Version: 0.0.10
 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.8 → engin-0.0.10}/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.8 → engin-0.0.10}/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.10/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.10/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.8 → engin-0.0.10}/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.10/docs/reference.md

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

{engin-0.0.8 → engin-0.0.10}/examples/asgi/main.py

@@ -12,4 +12,6 @@ logging.basicConfig(level=logging.DEBUG)
 
 app = ASGIEngin(AppBlock(), DatabaseBlock(), CatBlock(), Supply(AppConfig(debug=True)))
 
-uvicorn.run(app)
+
+if __name__ == "__main__":
+    uvicorn.run(app)

engin-0.0.10/examples/fastapi/app.py

@@ -0,0 +1,29 @@
+from fastapi import APIRouter, FastAPI
+from pydantic_settings import BaseSettings
+
+from engin import Block, provide
+
+
+class AppConfig(BaseSettings):
+    debug: bool = False
+
+
+class AppBlock(Block):
+    @provide
+    def default_config(self) -> AppConfig:
+        return AppConfig()
+
+    @provide
+    def app_factory(self, app_config: AppConfig, routers: list[APIRouter]) -> FastAPI:
+        app = FastAPI(debug=app_config.debug)
+
+        for router in routers:
+            app.include_router(router)
+
+        app.add_api_route(path="/health", endpoint=_health)
+
+        return app
+
+
+async def _health() -> dict[str, bool]:
+    return {"ok": True}

{engin-0.0.8 → engin-0.0.10}/examples/fastapi/routes/cats/block.py

@@ -1,16 +1,14 @@
-from fastapi import FastAPI
+from typing import ClassVar
 
-from engin import Block, invoke, provide
+from engin import Block, Invoke, Provide, Supply, provide
 from examples.fastapi.routes.cats.adapters.repository import InMemoryCatRepository
 from examples.fastapi.routes.cats.api import router
 from examples.fastapi.routes.cats.ports import CatRepository
 
 
 class CatBlock(Block):
+    options: ClassVar[list[Provide | Invoke]] = [Supply([router])]
+
     @provide
     def cat_repository(self) -> CatRepository:
         return InMemoryCatRepository()
-
-    @invoke
-    def attach_router(self, app: FastAPI) -> None:
-        app.include_router(router)

{engin-0.0.8 → engin-0.0.10}/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.8 → engin-0.0.10}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "engin"
-version = "0.0.8"
+version = "0.0.10"
 description = "An async-first modular application framework"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -100,6 +100,7 @@ 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"
+docs = "mkdocs serve"

{engin-0.0.8 → engin-0.0.10}/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.8 → engin-0.0.10}/src/engin/_block.py

@@ -59,6 +59,8 @@ class Block(Iterable[Provide | Invoke]):
                     raise RuntimeError("Block option is not an instance of Provide or Invoke")
                 opt.set_block_name(self._name)
                 self._options.append(opt)
+        for opt in self.options:
+            opt.set_block_name(self._name)
 
     @property
     def name(self) -> str:

{engin-0.0.8 → engin-0.0.10}/src/engin/_dependency.py

@@ -31,13 +31,23 @@ class Dependency(ABC, Generic[P, T]):
         self._block_name = block_name
 
     @property
-    def module(self) -> str:
+    def origin(self) -> str:
+        """
+        The module that this Dependency originated from.
+
+        Returns:
+            A string, e.g. "examples.fastapi.app"
+        """
         return self._func.__module__
 
     @property
     def block_name(self) -> str | None:
         return self._block_name
 
+    @property
+    def func_name(self) -> str:
+        return self._func.__name__
+
     @property
     def name(self) -> str:
         if self._block_name:
@@ -105,6 +115,10 @@ 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)]
@@ -172,6 +186,10 @@ 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.8 → engin-0.0.10}/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.10/src/engin/_graph.py

@@ -0,0 +1,50 @@
+from collections.abc import Iterable
+from dataclasses import dataclass
+
+from engin import Provide
+from engin._dependency import Dependency
+from engin._type_utils import TypeId
+
+
+@dataclass(slots=True, frozen=True, kw_only=True)
+class Node:
+    """
+    A Node in the Dependency Graph.
+    """
+
+    node: Dependency
+    parent: Dependency | None
+
+    def __repr__(self) -> str:
+        return f"Node(node={self.node!s},parent={self.parent!s})"
+
+
+class DependencyGrapher:
+    def __init__(self, providers: dict[TypeId, Provide | list[Provide]]) -> None:
+        self._providers: dict[TypeId, Provide | list[Provide]] = providers
+
+    def resolve(self, roots: Iterable[Dependency]) -> list[Node]:
+        return self._resolve_recursive(roots, seen=set())
+
+    def _resolve_recursive(
+        self, roots: Iterable[Dependency], *, seen: set[TypeId]
+    ) -> list[Node]:
+        nodes: list[Node] = []
+        for root in roots:
+            for parameter in root.parameter_types:
+                provider = self._providers[parameter]
+
+                # multiprovider
+                if isinstance(provider, list):
+                    nodes.extend(Node(node=p, parent=root) for p in provider)
+                    if parameter not in seen:
+                        nodes.extend(self._resolve_recursive(provider, seen=seen))
+                # single provider
+                else:
+                    nodes.append(Node(node=provider, parent=root))
+                    if parameter not in seen:
+                        nodes.extend(self._resolve_recursive([provider], seen=seen))
+
+                seen.add(parameter)
+
+        return nodes

{engin-0.0.8 → engin-0.0.10}/src/engin/ext/asgi.py

@@ -1,11 +1,13 @@
 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, Option
+from engin import Engin, Entrypoint, Option
 
-__all__ = ["ASGIEngin", "ASGIType"]
+__all__ = ["ASGIEngin", "ASGIType", "engin_to_lifespan"]
 
+from engin._graph import DependencyGrapher, Node
 
 _Scope: TypeAlias = MutableMapping[str, Any]
 _Message: TypeAlias = MutableMapping[str, Any]
@@ -49,6 +51,10 @@ class ASGIEngin(Engin, ASGIType):
         await self.start()
         self._asgi_app = await self._assembler.get(self._asgi_type)
 
+    def graph(self) -> list[Node]:
+        grapher = DependencyGrapher({**self._providers, **self._multiproviders})
+        return grapher.resolve([Entrypoint(self._asgi_type), *self._invocations])
+
 
 class _Rereceive:
     def __init__(self, message: _Message) -> None:
@@ -56,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.10/src/engin/ext/fastapi.py

@@ -0,0 +1,168 @@
+import inspect
+import typing
+from collections.abc import Iterable
+from inspect import Parameter
+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._graph import DependencyGrapher, Node
+from engin._type_utils import TypeId, type_id_of
+from engin.ext.asgi import ASGIEngin
+
+try:
+    from fastapi import APIRouter, FastAPI
+    from fastapi.params import Depends
+    from starlette.requests import HTTPConnection
+except ImportError as err:
+    raise ImportError(
+        "fastapi package must be installed to use the fastapi extension"
+    ) from err
+
+__all__ = ["APIRouteDependency", "FastAPIEngin", "Inject"]
+
+
+def _attach_engin(
+    app: FastAPI,
+    engin: Engin,
+) -> None:
+    app.state.engin = engin
+
+
+class FastAPIEngin(ASGIEngin):
+    _LIB_OPTIONS: ClassVar[list[Option]] = [*ASGIEngin._LIB_OPTIONS, Invoke(_attach_engin)]
+    _asgi_type = FastAPI
+
+    def graph(self) -> list[Node]:
+        grapher = _FastAPIDependencyGrapher({**self._providers, **self._multiproviders})
+        return grapher.resolve(
+            [
+                Entrypoint(self._asgi_type),
+                *[i for i in self._invocations if i.func_name != "_attach_engin"],
+            ]
+        )
+
+
+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)
+
+    dep = Depends(inner)
+    dep.__engin__ = True  # type: ignore[attr-defined]
+    return dep
+
+
+class _FastAPIDependencyGrapher(DependencyGrapher):
+    """
+    This exists in order to bridge the gap between
+    """
+
+    def _resolve_recursive(
+        self, roots: Iterable[Dependency], *, seen: set[TypeId]
+    ) -> list[Node]:
+        nodes: list[Node] = []
+        for root in roots:
+            for parameter in root.parameter_types:
+                provider = self._providers[parameter]
+
+                # multiprovider
+                if isinstance(provider, list):
+                    for p in provider:
+                        nodes.append(Node(node=p, parent=root))
+
+                        if isinstance(p, Supply):
+                            route_dependencies = _extract_routes_from_supply(p)
+                            nodes.extend(
+                                Node(node=route_dependency, parent=p)
+                                for route_dependency in route_dependencies
+                            )
+                            nodes.extend(
+                                self._resolve_recursive(route_dependencies, seen=seen)
+                            )
+
+                        if parameter not in seen:
+                            nodes.extend(self._resolve_recursive(provider, seen=seen))
+                # single provider
+                else:
+                    nodes.append(Node(node=provider, parent=root))
+                    # not sure why anyone would ever supply a single APIRouter in an
+                    # application, but just in case
+                    if isinstance(provider, Supply):
+                        route_dependencies = _extract_routes_from_supply(provider)
+                        nodes.extend(
+                            Node(node=route_dependency, parent=provider)
+                            for route_dependency in route_dependencies
+                        )
+                        nodes.extend(self._resolve_recursive(route_dependencies, seen=seen))
+                    if parameter not in seen:
+                        nodes.extend(self._resolve_recursive([provider], seen=seen))
+
+                seen.add(parameter)
+
+        return nodes
+
+
+def _extract_routes_from_supply(supply: Supply) -> list[Dependency]:
+    if supply.is_multiprovider:
+        inner = supply._value[0]
+        if isinstance(inner, APIRouter):
+            return [
+                APIRouteDependency(route, block_name=supply.block_name)
+                for route in inner.routes
+                if isinstance(route, APIRoute)
+            ]
+    return []
+
+
+class APIRouteDependency(Dependency):
+    """
+    This is a pseudo-dependency that is only used when calling FastAPIEngin.graph() in
+    order to provide richer metadata to the Node.
+
+    This class should never be constructed in application code.
+    """
+
+    def __init__(self, route: APIRoute, block_name: str | None = None) -> None:
+        """
+        Warning: this should never be constructed in application code.
+        """
+        self._route = route
+        self._signature = inspect.signature(route.endpoint)
+        self._block_name = block_name
+
+    @property
+    def route(self) -> APIRoute:
+        return self._route
+
+    @property
+    def parameter_types(self) -> list[TypeId]:
+        parameters = list(self._signature.parameters.values())
+        if not parameters:
+            return []
+        if parameters[0].name == "self":
+            parameters.pop(0)
+        return [
+            type_id_of(typing.get_args(param.annotation)[0])
+            for param in parameters
+            if self._is_injected_param(param)
+        ]
+
+    @staticmethod
+    def _is_injected_param(param: Parameter) -> bool:
+        if typing.get_origin(param.annotation) != typing.Annotated:
+            return False
+        args = typing.get_args(param.annotation)
+        if len(args) != 2:
+            return False
+        return isinstance(args[1], Depends) and hasattr(args[1], "__engin__")
+
+    @property
+    def name(self) -> str:
+        methods = ",".join(self._route.methods)
+        return f"{methods} {self._route.path}"

{engin-0.0.8 → engin-0.0.10}/src/engin/scripts/graph.py

@@ -8,8 +8,10 @@ from http.server import BaseHTTPRequestHandler
 from time import sleep
 from typing import Any
 
-from engin import Engin
-from engin._dependency import Dependency, Provide
+from engin import Engin, Entrypoint, Invoke
+from engin._dependency import Dependency, Provide, Supply
+from engin.ext.asgi import ASGIEngin
+from engin.ext.fastapi import APIRouteDependency
 
 # mute logging from importing of files + engin's debug logging.
 logging.disable()
@@ -18,9 +20,6 @@ args = ArgumentParser(
     prog="engin-graph",
     description="Creates a visualisation of your application's dependencies",
 )
-args.add_argument(
-    "-e", "--exclude", help="a list of packages or module to exclude", default=["engin"]
-)
 args.add_argument(
     "app",
     help=(
@@ -37,7 +36,6 @@ def serve_graph() -> None:
     parsed = args.parse_args()
 
     app = parsed.app
-    excluded_modules = parsed.exclude
 
     try:
         module_name, engin_name = app.split(":", maxsplit=1)
@@ -60,13 +58,19 @@ def serve_graph() -> None:
 
     # transform dependencies into mermaid syntax
     dependencies = [
-        f"{_render_node(node['parent'])} --> {_render_node(node['node'])}"
+        f"{_render_node(node.parent)} --> {_render_node(node.node)}"
         for node in nodes
-        if node["parent"] is not None
-        and not _should_exclude(node["node"].module, excluded_modules)
+        if node.parent is not None
     ]
 
-    html = _GRAPH_HTML.replace("%%DATA%%", "\n".join(dependencies)).encode("utf8")
+    html = (
+        _GRAPH_HTML.replace("%%DATA%%", "\n".join(dependencies))
+        .replace(
+            "%%LEGEND%%",
+            ASGI_ENGIN_LEGEND if isinstance(instance, ASGIEngin) else DEFAULT_LEGEND,
+        )
+        .encode("utf8")
+    )
 
     class Handler(BaseHTTPRequestHandler):
         def do_GET(self) -> None:
@@ -93,24 +97,66 @@ def serve_graph() -> None:
         print("Exiting the server...")
 
 
+_BLOCK_IDX: dict[str, int] = {}
+_SEEN_BLOCKS: list[str] = []
+
+
 def _render_node(node: Dependency) -> str:
+    node_id = id(node)
+    md = ""
+    style = ""
+
+    # format block name
+    if n := node.block_name:
+        md += f"_{n}_\n"
+        if n not in _BLOCK_IDX:
+            _BLOCK_IDX[n] = len(_SEEN_BLOCKS) % 8
+            _SEEN_BLOCKS.append(n)
+        style = f":::b{_BLOCK_IDX[n]}"
+
+    if isinstance(node, Supply):
+        md += f"{node.return_type_id}"
+        return f'{node_id}("`{md}`"){style}'
     if isinstance(node, Provide):
-        return str(node.return_type_id)
+        md += f"{node.return_type_id}"
+        return f'{node_id}["`{md}`"]{style}'
+    if isinstance(node, Entrypoint):
+        entrypoint_type = node.parameter_types[0]
+        md += f"{entrypoint_type}"
+        return f'{node_id}[/"`{md}`"\\]{style}'
+    if isinstance(node, Invoke):
+        md += f"{node.func_name}"
+        return f'{node_id}[/"`{md}`"/]{style}'
+    if isinstance(node, APIRouteDependency):
+        md += f"{node.name}"
+        return f'{node_id}[["`{md}`"]]{style}'
     else:
-        return node.name
-
-
-def _should_exclude(module: str, excluded: list[str]) -> bool:
-    return any(module.startswith(e) for e in excluded)
+        return f'{node_id}["`{node.name}`"]{style}'
 
 
 _GRAPH_HTML = """
 <!doctype html>
 <html lang="en">
   <body>
+    <div style="border-style:outset">
+        <p>LEGEND</p>
+        <pre class="mermaid">
+          graph LR
+            %%LEGEND%%
+            classDef b0 fill:#7fc97f;
+        </pre>
+    </div>
     <pre class="mermaid">
       graph TD
           %%DATA%%
+          classDef b0 fill:#7fc97f;
+          classDef b1 fill:#beaed4;
+          classDef b2 fill:#fdc086;
+          classDef b3 fill:#ffff99;
+          classDef b4 fill:#386cb0;
+          classDef b5 fill:#f0027f;
+          classDef b6 fill:#bf5b17;
+          classDef b7 fill:#666666;
     </pre>
     <script type="module">
       import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
@@ -120,3 +166,9 @@ _GRAPH_HTML = """
   </body>
 </html>
 """
+
+DEFAULT_LEGEND = (
+    "0[/Invoke/] ~~~ 1[/Entrypoint\\] ~~~ 2[Provide] ~~~ 3(Supply)"
+    ' ~~~ 4["`Block Grouping`"]:::b0'
+)
+ASGI_ENGIN_LEGEND = DEFAULT_LEGEND + " ~~~ 5[[API Route]]"

{engin-0.0.8 → engin-0.0.10}/uv.lock

@@ -128,7 +128,7 @@ wheels = [
 
 [[package]]
 name = "engin"
-version = "0.0.8"
+version = "0.0.10"
 source = { editable = "." }
 
 [package.dev-dependencies]

engin-0.0.8/docs/engin.md

@@ -1 +0,0 @@
-::: engin.Engin

engin-0.0.8/examples/fastapi/app.py

@@ -1,25 +0,0 @@
-from fastapi import FastAPI
-from pydantic_settings import BaseSettings
-
-from engin import Block, invoke, provide
-
-
-class AppConfig(BaseSettings):
-    debug: bool = False
-
-
-class AppBlock(Block):
-    @provide
-    def app_factory(self, app_config: AppConfig) -> FastAPI:
-        return FastAPI(debug=app_config.debug)
-
-    @provide
-    def default_config(self) -> AppConfig:
-        return AppConfig()
-
-    @invoke
-    def add_health_endpoint(self, app: FastAPI) -> None:
-        async def health() -> dict[str, bool]:
-            return {"ok": True}
-
-        app.add_api_route(path="/health", endpoint=health)

engin-0.0.8/src/engin/_graph.py

@@ -1,39 +0,0 @@
-from collections.abc import Iterable
-from typing import TypedDict
-
-from engin._dependency import Dependency, Provide
-from engin._type_utils import TypeId
-
-
-class Node(TypedDict):
-    node: Dependency
-    parent: Dependency | None
-
-
-class DependencyGrapher:
-    def __init__(self, providers: dict[TypeId, Provide | list[Provide]]) -> None:
-        self._providers: dict[TypeId, Provide | list[Provide]] = providers
-
-    def resolve(self, roots: Iterable[Dependency]) -> list[Node]:
-        seen: set[TypeId] = set()
-        nodes: list[Node] = []
-
-        for root in roots:
-            for parameter in root.parameter_types:
-                if parameter in seen:
-                    continue
-
-                seen.add(parameter)
-                provider = self._providers[parameter]
-
-                # multiprovider
-                if isinstance(provider, list):
-                    for p in provider:
-                        nodes.append({"node": p, "parent": root})
-                        nodes.extend(self.resolve([p]))
-                # single provider
-                else:
-                    nodes.append({"node": provider, "parent": root})
-                    nodes.extend(self.resolve([provider]))
-
-        return nodes

engin-0.0.8/src/engin/ext/fastapi.py

@@ -1,38 +0,0 @@
-from typing import ClassVar, TypeVar
-
-from engin import Engin, Invoke, Option
-from engin.ext.asgi import ASGIEngin
-
-try:
-    from fastapi import FastAPI
-    from fastapi.params import Depends
-    from starlette.requests import HTTPConnection
-except ImportError as err:
-    raise ImportError(
-        "fastapi package must be installed to use the fastapi extension"
-    ) from err
-
-__all__ = ["FastAPIEngin", "Inject"]
-
-
-def _attach_engin(
-    app: FastAPI,
-    engin: Engin,
-) -> None:
-    app.state.engin = engin
-
-
-class FastAPIEngin(ASGIEngin):
-    _LIB_OPTIONS: ClassVar[list[Option]] = [*ASGIEngin._LIB_OPTIONS, Invoke(_attach_engin)]
-    _asgi_type = FastAPI
-
-
-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)
-
-    return Depends(inner)