engin 0.0.1__tar.gz → 0.0.3__tar.gz

engin-0.0.3/CHANGELOG.md

@@ -0,0 +1,34 @@
+# 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.3] - 2025-01-15
+
+### Added
+
+- Blocks can now provide options via the `options` class variable. This allows packaged
+  Blocks to easily expose Providers and Invocations as normal functions whilst allowing
+  them to be part of a Block as well. This makes usage of the Block optional which makes
+  it more flexible for end users.
+- Added missing type hints and enabled mypy strict mode.
+
+### Fixed
+
+- Engin now performs Lifecycle shutdown.
+
+## [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.3/PKG-INFO

@@ -0,0 +1,56 @@
+Metadata-Version: 2.4
+Name: engin
+Version: 0.0.3
+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.3/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.1 → engin-0.0.3}/examples/fastapi/app.py

@@ -19,6 +19,7 @@ class AppBlock(Block):
 
     @invoke
     def add_health_endpoint(self, app: FastAPI) -> None:
-        @app.get("/health")
         async def health():
             return {"ok": True}
+
+        app.add_api_route(path="/health", endpoint=health)

{engin-0.0.1 → engin-0.0.3}/examples/fastapi/main.py

@@ -3,7 +3,7 @@ import logging
 import uvicorn
 
 from engin import Supply
-from engin.extensions.fastapi import FastAPIEngin
+from engin.ext.fastapi import FastAPIEngin
 from examples.fastapi.app import AppBlock, AppConfig
 from examples.fastapi.routes.cats.block import CatBlock
 

{engin-0.0.1 → engin-0.0.3}/examples/fastapi/routes/cats/api.py

@@ -3,7 +3,7 @@ from typing import Annotated
 from fastapi import APIRouter
 from pydantic import BaseModel
 
-from engin.extensions.fastapi import Inject
+from engin.ext.fastapi import Inject
 from examples.fastapi.routes.cats.domain import Cat, CatPersonality
 from examples.fastapi.routes.cats.ports import CatRepository
 

{engin-0.0.1 → engin-0.0.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "engin"
-version = "0.0.1"
+version = "0.0.3"
 description = "An async-first modular application framework"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -37,3 +37,9 @@ log_cli = true
 log_cli_level = "DEBUG"
 asyncio_mode = "auto"
 asyncio_default_fixture_loop_scope = "session"
+
+[tool.mypy]
+strict = true
+disable_error_code = [
+    "type-arg", # allow generic types without type arguments
+]

{engin-0.0.1 → engin-0.0.3}/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
@@ -16,6 +17,7 @@ __all__ = [
     "Option",
     "Provide",
     "Supply",
+    "ext",
     "invoke",
     "provide",
 ]

{engin-0.0.1 → engin-0.0.3}/src/engin/_assembler.py

@@ -4,7 +4,7 @@ from collections import defaultdict
 from collections.abc import Collection, Iterable
 from dataclasses import dataclass
 from inspect import BoundArguments, Signature
-from typing import Any, Generic, TypeVar
+from typing import Any, Generic, TypeVar, cast
 
 from engin._dependency import Dependency, Provide, Supply
 from engin._exceptions import AssemblyError
@@ -113,7 +113,7 @@ 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]
+            return cast(T, self._dependencies[type_id])
         if type_id.multi:
             out = []
             for provider in self._multiproviders[type_id]:

{engin-0.0.1 → engin-0.0.3}/src/engin/_block.py

@@ -1,5 +1,6 @@
 import inspect
 from collections.abc import Iterable, Iterator
+from typing import ClassVar
 
 from engin._dependency import Func, Invoke, Provide
 
@@ -15,11 +16,10 @@ def invoke(func: Func) -> Func:
 
 
 class Block(Iterable[Provide | Invoke]):
-    _name: str
-    _options: list[Provide | Invoke]
+    options: ClassVar[list[Provide | Invoke]] = []
 
     def __init__(self, /, block_name: str | None = None) -> None:
-        self._options: list[Provide | Invoke] = []
+        self._options: list[Provide | Invoke] = self.options[:]
         self._name = block_name or f"{type(self).__name__}"
         for _, method in inspect.getmembers(self):
             if opt := getattr(method, "_opt", None):

{engin-0.0.1 → engin-0.0.3}/src/engin/_dependency.py

@@ -25,7 +25,7 @@ Func: TypeAlias = (
 _SELF = object()
 
 
-def _noop(*args, **kwargs) -> None: ...
+def _noop(*args: Any, **kwargs: Any) -> None: ...
 
 
 class Dependency(ABC, Generic[P, T]):

{engin-0.0.1 → engin-0.0.3}/src/engin/_engin.py

@@ -32,15 +32,13 @@ class Engin:
     def assembler(self) -> Assembler:
         return self._assembler
 
-    async def run(self):
+    async def run(self) -> None:
         await self.start()
 
-        # lifecycle startup
-
         # wait till stop signal recieved
         await self._stop_event.wait()
 
-        # lifecycle shutdown
+        await self.stop()
 
     async def start(self) -> None:
         LOG.info("starting engin")
@@ -57,8 +55,10 @@ class Engin:
 
     async def stop(self) -> None:
         self._stop_event.set()
+        lifecycle = await self._assembler.get(Lifecycle)
+        await lifecycle.shutdown()
 
-    def _destruct_options(self, options: Iterable[Option]):
+    def _destruct_options(self, options: Iterable[Option]) -> None:
         for opt in options:
             if isinstance(opt, Block):
                 self._destruct_options(opt)

{engin-0.0.1 → engin-0.0.3}/src/engin/_lifecycle.py

@@ -4,12 +4,12 @@ from contextlib import AbstractAsyncContextManager, AsyncExitStack
 
 class Lifecycle:
     def __init__(self) -> None:
-        self._on_startup: list[Callable] = []
-        self._on_shutdown: list[Callable] = []
+        self._on_startup: list[Callable[..., None]] = []
+        self._on_shutdown: list[Callable[..., None]] = []
         self._context_managers: list[AbstractAsyncContextManager] = []
         self._stack: AsyncExitStack = AsyncExitStack()
 
-    def register_context(self, cm: AbstractAsyncContextManager):
+    def register_context(self, cm: AbstractAsyncContextManager) -> None:
         self._context_managers.append(cm)
 
     async def startup(self) -> None:

{engin-0.0.1 → engin-0.0.3}/src/engin/ext/asgi.py

@@ -1,16 +1,16 @@
 import traceback
-import typing
-from typing import ClassVar, Protocol, TypeAlias
+from collections.abc import Awaitable, Callable, MutableMapping
+from typing import Any, ClassVar, Protocol, TypeAlias
 
 from engin import Engin, Option
 
 __all__ = ["ASGIEngin", "ASGIType"]
 
 
-_Scope: TypeAlias = typing.MutableMapping[str, typing.Any]
-_Message: TypeAlias = typing.MutableMapping[str, typing.Any]
-_Receive: TypeAlias = typing.Callable[[], typing.Awaitable[_Message]]
-_Send: TypeAlias = typing.Callable[[_Message], typing.Awaitable[None]]
+_Scope: TypeAlias = MutableMapping[str, Any]
+_Message: TypeAlias = MutableMapping[str, Any]
+_Receive: TypeAlias = Callable[[], Awaitable[_Message]]
+_Send: TypeAlias = Callable[[_Message], Awaitable[None]]
 
 
 class ASGIType(Protocol):
@@ -54,5 +54,5 @@ class _Rereceive:
     def __init__(self, message: _Message) -> None:
         self._message = message
 
-    async def __call__(self, *args, **kwargs) -> _Message:
+    async def __call__(self, *args: Any, **kwargs: Any) -> _Message:
         return self._message

{engin-0.0.1 → engin-0.0.3}/tests/test_engin.py

@@ -1,8 +1,11 @@
+import asyncio
+from contextlib import asynccontextmanager
 from datetime import datetime
+from typing import Iterable
 
 import pytest
 
-from engin import AssemblyError, Engin, Entrypoint, Invoke, Provide
+from engin import AssemblyError, Engin, Entrypoint, Invoke, Lifecycle, Provide
 from tests.deps import ABlock
 
 
@@ -73,3 +76,51 @@ async def test_engin_with_entrypoint():
     await engin.start()
 
     assert provider_called
+
+
+async def test_engin_with_lifecycle():
+    state = 0
+
+    @asynccontextmanager
+    async def lifespan_task() -> Iterable[None]:
+        nonlocal state
+        state = 1
+        yield
+        state = 2
+
+    def foo(lifecycle: Lifecycle) -> None:
+        lifecycle.register_context(lifespan_task())
+
+    engin = Engin(Invoke(foo))
+
+    await engin.start()
+    assert state == 1
+
+    await engin.stop()
+    assert state == 2
+
+
+async def test_engin_with_lifecycle_using_run():
+    state = 0
+
+    @asynccontextmanager
+    async def lifespan_task() -> Iterable[None]:
+        nonlocal state
+        state = 1
+        yield
+        state = 2
+
+    def foo(lifecycle: Lifecycle) -> None:
+        lifecycle.register_context(lifespan_task())
+
+    engin = Engin(Invoke(foo))
+
+    async def _stop_task():
+        await asyncio.sleep(0.25)
+        # lifecycle should have started by now
+        assert state == 1
+        await engin.stop()
+
+    await asyncio.gather(engin.run(), _stop_task())
+    # lifecycle should have stopped by now
+    assert state == 2