engin 0.0.dev1__tar.gz → 0.0.2__tar.gz

engin-0.0.2/.github/workflows/check.yaml

@@ -0,0 +1,30 @@
+name: Check
+
+on:
+  push:
+
+jobs:
+  publish-to-pypi:
+    name: python
+    runs-on: ubuntu-latest
+
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Set up Python
+        run: uv python install
+
+      - name: Ruff
+        run:  uv run ruff check src tests
+
+      - name: Mypy
+        run: uv run mypy src
+
+      - name: Test
+        run: uv run pytest tests

engin-0.0.2/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+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.2] - 2025-01-10
+
+### Added
+
+- The `ext` sub-package is now explicitly exported in the package `__init__.py`
+
+
+## [0.0.1] - 2024-12-12
+
+### Added
+
+- Initial release

engin-0.0.2/PKG-INFO

@@ -0,0 +1,56 @@
+Metadata-Version: 2.4
+Name: engin
+Version: 0.0.2
+Summary: An async-first modular application framework
+License-File: LICENSE
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# Engin 🏎️
+
+Engin is a zero-dependency application framework for modern Python.
+
+## Features ✨
+
+- **Lightweight**: Engin has no dependencies.
+- **Async First**: Engin provides first-class support for applications. 
+- **Dependency Injection**: Engin promotes a modular decoupled architecture in your application.
+- **Lifecycle Management**: Engin provides an simple, portable approach for implememting
+  startup and shutdown tasks.
+- **Ecosystem Compatability**: seamlessly integrate with frameworks such as FastAPI without
+  having to migrate your dependencies.
+- **Code Reuse**: Engin's modular components work great as packages and distributions. Allowing
+  low boiler-plate code reuse within your Organisation.
+
+## Installation
+
+Engin is available on PyPI, install using your favourite dependency manager:
+
+- **pip**:`pip install engin`
+- **poetry**: `poetry add engin`
+- **uv**: `uv add engin`
+
+## Getting Started
+
+A minimal example:
+
+```python
+import asyncio
+
+from httpx import AsyncClient
+
+from engin import Engin, Invoke, Provide
+
+
+def httpx_client() -> AsyncClient:
+    return AsyncClient()
+
+
+async def main(http_client: AsyncClient) -> None:
+    print(await http_client.get("https://httpbin.org/get"))
+
+engin = Engin(Provide(httpx_client), Invoke(main))
+
+asyncio.run(engin.run())
+```
+

engin-0.0.2/README.md

@@ -0,0 +1,48 @@
+# Engin 🏎️
+
+Engin is a zero-dependency application framework for modern Python.
+
+## Features ✨
+
+- **Lightweight**: Engin has no dependencies.
+- **Async First**: Engin provides first-class support for applications. 
+- **Dependency Injection**: Engin promotes a modular decoupled architecture in your application.
+- **Lifecycle Management**: Engin provides an simple, portable approach for implememting
+  startup and shutdown tasks.
+- **Ecosystem Compatability**: seamlessly integrate with frameworks such as FastAPI without
+  having to migrate your dependencies.
+- **Code Reuse**: Engin's modular components work great as packages and distributions. Allowing
+  low boiler-plate code reuse within your Organisation.
+
+## Installation
+
+Engin is available on PyPI, install using your favourite dependency manager:
+
+- **pip**:`pip install engin`
+- **poetry**: `poetry add engin`
+- **uv**: `uv add engin`
+
+## Getting Started
+
+A minimal example:
+
+```python
+import asyncio
+
+from httpx import AsyncClient
+
+from engin import Engin, Invoke, Provide
+
+
+def httpx_client() -> AsyncClient:
+    return AsyncClient()
+
+
+async def main(http_client: AsyncClient) -> None:
+    print(await http_client.get("https://httpbin.org/get"))
+
+engin = Engin(Provide(httpx_client), Invoke(main))
+
+asyncio.run(engin.run())
+```
+

engin-0.0.2/examples/fastapi/app.py

@@ -0,0 +1,25 @@
+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():
+            return {"ok": True}
+
+        app.add_api_route(path="/health", endpoint=health)

engin-0.0.2/examples/fastapi/main.py

@@ -0,0 +1,14 @@
+import logging
+
+import uvicorn
+
+from engin import Supply
+from engin.extensions.fastapi import FastAPIEngin
+from examples.fastapi.app import AppBlock, AppConfig
+from examples.fastapi.routes.cats.block import CatBlock
+
+logging.basicConfig(level=logging.DEBUG)
+
+app = FastAPIEngin(AppBlock(), CatBlock(), Supply(AppConfig(debug=True)))
+
+uvicorn.run(app)

engin-0.0.2/examples/fastapi/routes/cats/adapters/repository.py

@@ -0,0 +1,18 @@
+from examples.fastapi.routes.cats.domain import Cat
+from examples.fastapi.routes.cats.ports import CatRepository
+
+
+class InMemoryCatRepository(CatRepository):
+    def __init__(self) -> None:
+        self._cats: dict[int, Cat] = {}
+
+    def get(self, cat_id: int) -> Cat:
+        if cat_id in self._cats:
+            return self._cats[cat_id]
+        raise LookupError(f"No cat found for id: {cat_id}")
+
+    def set(self, cat: Cat) -> None:
+        self._cats[cat.id] = cat
+
+    def next_id(self) -> int:
+        return len(self._cats)

engin-0.0.2/examples/fastapi/routes/cats/api.py

@@ -0,0 +1,42 @@
+from typing import Annotated
+
+from fastapi import APIRouter
+from pydantic import BaseModel
+
+from engin.ext.fastapi import Inject
+from examples.fastapi.routes.cats.domain import Cat, CatPersonality
+from examples.fastapi.routes.cats.ports import CatRepository
+
+router = APIRouter(prefix="/cats")
+
+
+@router.get("/{cat_id}")
+async def get_cat(
+    cat_id: int,
+    repository: Annotated[CatRepository, Inject(CatRepository)],
+) -> Cat:
+    return repository.get(cat_id=cat_id)
+
+
+class CatPostModel(BaseModel):
+    name: str
+    breed: str
+    age: float
+    personality: CatPersonality
+
+
+@router.post("/")
+async def get_cat(
+    cat: CatPostModel,
+    repository: Annotated[CatRepository, Inject(CatRepository)],
+) -> int:
+    cat_id = repository.next_id()
+    cat = Cat(
+        id=cat_id,
+        name=cat.name,
+        personality=cat.personality,
+        age=cat.age,
+        breed=cat.breed,
+    )
+    repository.set(cat=cat)
+    return cat_id

engin-0.0.2/examples/fastapi/routes/cats/block.py

@@ -0,0 +1,16 @@
+from fastapi import FastAPI
+
+from engin import Block, invoke, 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):
+    @provide
+    def cat_repository(self) -> CatRepository:
+        return InMemoryCatRepository()
+
+    @invoke
+    def attach_router(self, app: FastAPI) -> None:
+        app.include_router(router)

engin-0.0.2/examples/fastapi/routes/cats/domain.py

@@ -0,0 +1,18 @@
+from enum import Enum
+
+from pydantic import BaseModel, ConfigDict
+
+
+class CatPersonality(Enum):
+    CUTE = "CUTE"
+    EVIL = "EVIL"
+
+
+class Cat(BaseModel):
+    model_config = ConfigDict(use_enum_values=True)
+
+    id: int
+    name: str
+    breed: str
+    age: float
+    personality: CatPersonality

engin-0.0.2/examples/fastapi/routes/cats/ports.py

@@ -0,0 +1,14 @@
+from abc import abstractmethod
+
+from examples.fastapi.routes.cats.domain import Cat
+
+
+class CatRepository:
+    @abstractmethod
+    def get(self, cat_id: int) -> Cat: ...
+
+    @abstractmethod
+    def set(self, cat: Cat) -> None: ...
+
+    @abstractmethod
+    def next_id(self) -> int: ...

{engin-0.0.dev1 → engin-0.0.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "engin"
-version = "0.0.dev1"
+version = "0.0.2"
 description = "An async-first modular application framework"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -12,6 +12,7 @@ build-backend = "hatchling.build"
 
 [tool.uv]
 dev-dependencies = [
+    "fastapi>=0.115.6",
     "httpx>=0.27.2",
     "mypy>=1",
     "pydantic-settings>=2.6.0",

{engin-0.0.dev1 → engin-0.0.2}/src/engin/__init__.py

@@ -1,3 +1,4 @@
+from engin import ext
 from engin._assembler import Assembler
 from engin._block import Block, invoke, provide
 from engin._dependency import Entrypoint, Invoke, Provide, Supply
@@ -8,14 +9,15 @@ from engin._lifecycle import Lifecycle
 __all__ = [
     "Assembler",
     "AssemblyError",
+    "Block",
     "Engin",
     "Entrypoint",
     "Invoke",
     "Lifecycle",
-    "Block",
     "Option",
     "Provide",
     "Supply",
+    "ext",
     "invoke",
     "provide",
 ]

{engin-0.0.dev1 → engin-0.0.2}/src/engin/_assembler.py

@@ -49,7 +49,7 @@ class Assembler:
         if not providers:
             if type_id.multi:
                 LOG.warning(f"no provider for '{type_id}' defaulting to empty list")
-                providers = [(Supply([], type_hint=list[type_id.type]))]
+                providers = [(Supply([], type_hint=list[type_id.type]))]  # type: ignore[name-defined]
             else:
                 raise LookupError(f"No Provider registered for dependency '{type_id}'")
 
@@ -112,15 +112,20 @@ class Assembler:
 
     async def get(self, type_: type[T]) -> T:
         type_id = type_id_of(type_)
+        if type_id in self._dependencies:
+            return self._dependencies[type_id]
         if type_id.multi:
             out = []
             for provider in self._multiproviders[type_id]:
                 assembled_dependency = await self.assemble(provider)
                 out.extend(await assembled_dependency())
-            return out
+            self._dependencies[type_id] = out
+            return out  # type: ignore[return-value]
         else:
             assembled_dependency = await self.assemble(self._providers[type_id])
-            return await assembled_dependency()
+            value = await assembled_dependency()
+            self._dependencies[type_id] = value
+            return value  # type: ignore[return-value]
 
     def has(self, type_: type[T]) -> bool:
         return type_id_of(type_) in self._providers

{engin-0.0.dev1 → engin-0.0.2}/src/engin/_engin.py

@@ -21,7 +21,7 @@ class Engin:
     _LIB_OPTIONS: ClassVar[list[Option]] = [Provide(Lifecycle)]
 
     def __init__(self, *options: Option) -> None:
-        self._providers: dict[TypeId, Provide] = {}
+        self._providers: dict[TypeId, Provide] = {TypeId.from_type(Engin): Provide(self._self)}
         self._invokables: list[Invoke] = []
         self._stop_event = Event()
 
@@ -35,13 +35,9 @@ class Engin:
     async def run(self):
         await self.start()
 
-        # lifecycle startup
-
         # wait till stop signal recieved
         await self._stop_event.wait()
 
-        # lifecycle shutdown
-
     async def start(self) -> None:
         LOG.info("starting engin")
         assembled_invocations: list[AssembledDependency] = [
@@ -87,3 +83,6 @@ class Engin:
             LOG.debug(f"ENTRYPOINT  {type_id!s:<35}")
         elif isinstance(opt, Invoke):
             LOG.debug(f"INVOKE      {opt.name:<35}")
+
+    def _self(self) -> "Engin":
+        return self

{engin-0.0.dev1/src/engin/extensions → engin-0.0.2/src/engin/ext}/asgi.py

@@ -1,6 +1,6 @@
 import traceback
 import typing
-from typing import Protocol, TypeAlias
+from typing import ClassVar, Protocol, TypeAlias
 
 from engin import Engin, Option
 
@@ -18,13 +18,16 @@ class ASGIType(Protocol):
 
 
 class ASGIEngin(Engin, ASGIType):
+    _asgi_type: ClassVar[type[ASGIType]] = ASGIType  # type: ignore[type-abstract]
     _asgi_app: ASGIType
 
     def __init__(self, *options: Option) -> None:
         super().__init__(*options)
 
-        if not self._assembler.has(ASGIType):
-            raise LookupError("A provider for `ASGIType` was expected, none found")
+        if not self._assembler.has(self._asgi_type):
+            raise LookupError(
+                f"A provider for `{self._asgi_type.__name__}` was expected, none found"
+            )
 
     async def __call__(self, scope: _Scope, receive: _Receive, send: _Send) -> None:
         if scope["type"] == "lifespan":
@@ -44,7 +47,7 @@ class ASGIEngin(Engin, ASGIType):
 
     async def _startup(self) -> None:
         await self.start()
-        self._asgi_app = await self._assembler.get(ASGIType)
+        self._asgi_app = await self._assembler.get(self._asgi_type)
 
 
 class _Rereceive:

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

@@ -0,0 +1,42 @@
+import typing
+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:
+    raise ImportError("fastapi must be installed to use the corresponding extension")
+
+
+if typing.TYPE_CHECKING:
+    from fastapi import FastAPI
+    from fastapi.params import Depends
+
+__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)]  # type: ignore[arg-type]
+    _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)

{engin-0.0.dev1 → engin-0.0.2}/tests/test_assembler.py

@@ -25,3 +25,23 @@ async def test_assembler_with_multiproviders():
     assembled_dependency = await assembler.assemble(Invoke(assert_all))
 
     await assembled_dependency()
+
+
+async def test_assembler_providers_only_called_once():
+    _count = 0
+
+    def count() -> int:
+        nonlocal _count
+        _count += 1
+        return _count
+
+    def assert_singleton(some: int) -> None:
+        assert some == 1
+
+    assembler = Assembler([Provide(count)])
+
+    assembled_dependency = await assembler.assemble(Invoke(assert_singleton))
+    await assembled_dependency()
+
+    assembled_dependency = await assembler.assemble(Invoke(assert_singleton))
+    await assembled_dependency()