engin 0.0.9__tar.gz → 0.0.10__tar.gz

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

@@ -6,6 +6,19 @@ 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: engin
-Version: 0.0.9
+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.9 → 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.9 → 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.9 → 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.9 → 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.9 → engin-0.0.10}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "engin"
-version = "0.0.9"
+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.9 → 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.9 → 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.9 → engin-0.0.10}/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.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.9/docs/engin.md

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