engin 0.0.2__tar.gz → 0.0.4__tar.gz

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

@@ -0,0 +1,35 @@
+name: Check
+
+on:
+  push:
+
+jobs:
+  check:
+    name: python
+    runs-on: ubuntu-latest
+
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: "pyproject.toml"
+
+      - name: Install the project
+        run: uv sync --all-extras --dev
+
+      - name: Quality
+        run: uv run poe check
+
+      - name: Test
+        run: uv run poe test

{engin-0.0.2 → engin-0.0.4}/.github/workflows/publish.yaml

@@ -2,6 +2,8 @@ name: Publish
 
 on:
   workflow_dispatch:
+  release:
+    types: [created]
 
 jobs:
   publish-to-pypi:
@@ -15,10 +17,15 @@ jobs:
       - uses: actions/checkout@v4
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v3
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
 
       - name: Set up Python
-        run: uv python install
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: "pyproject.toml"
 
       - name: Build the Project
         run: uv build

engin-0.0.4/.readthedocs.yaml

@@ -0,0 +1,25 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version, and other tools you might need
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+  jobs:
+    create_environment:
+       - asdf plugin add uv
+       - asdf install uv latest
+       - asdf global uv latest
+       - uv venv
+    install:
+       - uv sync --group docs
+    build:
+       html:
+          - NO_COLOR=1 uv run mkdocs build -f mkdocs.yaml --strict --site-dir $READTHEDOCS_OUTPUT/html
+
+mkdocs:
+  configuration: mkdocs.yaml

engin-0.0.4/CHANGELOG.md

@@ -0,0 +1,47 @@
+# 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.4] - 2025-01-27
+
+### Changed
+
+- Invocations, startups tasks and shutdown tasks are now all run sequentially.
+- Improved error handling, if an Invocation errors, or a Lifecycle startup tasks errors
+  then the Engin will exit. Whilst errors in shutdown tasks are logged and ignored. 
+- Improved error messaging when Invocations or Lifecycle tasks error.
+- Removed non-public methods from the Lifecycle class, and renamed `register_context` to
+  `append`.
+
+
+## [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.4/PKG-INFO

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: engin
+Version: 0.0.4
+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.
+
+**Documentation**: https://engin.readthedocs.io/
+
+## Features ✨
+
+- **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.
+- **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
+  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`
+
+## 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.4/README.md

@@ -0,0 +1,53 @@
+# Engin 🏎️
+
+Engin is a zero-dependency application framework for modern Python.
+
+**Documentation**: https://engin.readthedocs.io/
+
+## Features ✨
+
+- **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.
+- **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
+  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`
+
+## 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.4/docs/engin.md

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

engin-0.0.4/docs/index.md

@@ -0,0 +1,29 @@
+# Introduction
+
+Engin is a zero-dependency application framework for modern Python.
+
+Engin is inspired by [Uber's Fx framework for Go](https://github.com/uber-go/fx) and the
+[Injector framework for Python](https://github.com/python-injector/injector).
+
+## Why use Engin?
+
+- **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.
+- **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
+  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`

engin-0.0.4/docs/js/readthedocs.js

@@ -0,0 +1,32 @@
+document.addEventListener("DOMContentLoaded", function(event) {
+// Trigger Read the Docs' search addon instead of Material MkDocs default
+document.querySelector(".md-search__input").addEventListener("focus", (e) => {
+        const event = new CustomEvent("readthedocs-search-show");
+        document.dispatchEvent(event);
+    });
+});
+
+// Use CustomEvent to generate the version selector
+document.addEventListener(
+        "readthedocs-addons-data-ready",
+        function (event) {
+        const config = event.detail.data();
+        const versioning = `
+<div class="md-version">
+<button class="md-version__current" aria-label="Select version">
+    ${config.versions.current.slug}
+</button>
+
+<ul class="md-version__list">
+${ config.versions.active.map(
+    (version) => `
+    <li class="md-version__item">
+    <a href="${ version.urls.documentation }" class="md-version__link">
+        ${ version.slug }
+    </a>
+            </li>`).join("\n")}
+</ul>
+</div>`;
+
+    document.querySelector(".md-header__topic").insertAdjacentHTML("beforeend", versioning);
+});

engin-0.0.4/docs/overrides/main.html

@@ -0,0 +1,6 @@
+{% extends "base.html" %}
+
+{% block site_meta %}
+{{ super() }}
+<meta name="readthedocs-addons-api-version" content="1" />
+{% endblock %}

{engin-0.0.2 → engin-0.0.4}/examples/asgi/app.py

@@ -5,8 +5,8 @@ from starlette.requests import Request
 from starlette.responses import JSONResponse, Response
 from starlette.routing import Mount, Route
 
-from engin import Block, invoke, provide
-from engin.extensions.asgi import ASGIType
+from engin import Block, provide
+from engin.ext.asgi import ASGIType
 
 
 class AppConfig(BaseSettings):

{engin-0.0.2 → engin-0.0.4}/examples/asgi/common/db/adapaters/memory.py

@@ -5,7 +5,7 @@ from examples.asgi.common.db.ports import DatabaseInterface
 
 class InMemoryDatabase(DatabaseInterface):
     def __init__(self) -> None:
-        self._data = {}
+        self._data: dict[str, Any] = {}
 
     def get(self, key: str) -> Any:
         return self._data.get(key)

{engin-0.0.2 → engin-0.0.4}/examples/asgi/common/starlette/endpoint.py

@@ -1,5 +1,4 @@
 from abc import ABC, abstractmethod
-from collections.abc import Iterable
 from typing import ClassVar
 
 from starlette.exceptions import HTTPException
@@ -14,7 +13,7 @@ class Endpoint(ABC):
     HTTPEndpoint does not allow you to control class initialisation.
     """
 
-    ALLOWED_METHODS: ClassVar[Iterable[str]] = (
+    ALLOWED_METHODS: ClassVar[list[str]] = [
         "GET",
         "HEAD",
         "POST",
@@ -22,7 +21,7 @@ class Endpoint(ABC):
         "PATCH",
         "DELETE",
         "OPTIONS",
-    )
+    ]
 
     @abstractmethod
     async def exec(self, request: Request) -> Response: ...

{engin-0.0.2 → engin-0.0.4}/examples/asgi/features/cats/api/get.py

@@ -1,4 +1,4 @@
-import json
+from typing import ClassVar
 
 from starlette.requests import Request
 from starlette.responses import JSONResponse, Response
@@ -9,7 +9,7 @@ from examples.asgi.features.cats.domain import Cat
 
 
 class GetCatEndpoint(Endpoint):
-    ALLOWED_METHODS = ("GET",)
+    ALLOWED_METHODS: ClassVar[list[str]] = ["GET"]
 
     def __init__(self, db: DatabaseInterface) -> None:
         self._db = db

{engin-0.0.2 → engin-0.0.4}/examples/asgi/features/cats/api/post.py

@@ -1,3 +1,5 @@
+from typing import ClassVar
+
 from pydantic import ValidationError
 from starlette.requests import Request
 from starlette.responses import Response
@@ -8,7 +10,7 @@ from examples.asgi.features.cats.domain import Cat
 
 
 class PostCatEndpoint(Endpoint):
-    ALLOWED_METHODS = ("POST",)
+    ALLOWED_METHODS: ClassVar[list[str]] = ["POST"]
 
     def __init__(self, db: DatabaseInterface) -> None:
         self._db = db

{engin-0.0.2 → engin-0.0.4}/examples/asgi/main.py

@@ -3,7 +3,7 @@ import logging
 import uvicorn
 
 from engin import Supply
-from engin.extensions.asgi import ASGIEngin
+from engin.ext.asgi import ASGIEngin
 from examples.asgi.app import AppBlock, AppConfig
 from examples.asgi.common.db.block import DatabaseBlock
 from examples.asgi.features.cats.block import CatBlock

{engin-0.0.2 → engin-0.0.4}/examples/fastapi/app.py

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

{engin-0.0.2 → engin-0.0.4}/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.2 → engin-0.0.4}/examples/fastapi/routes/cats/api.py

@@ -26,17 +26,17 @@ class CatPostModel(BaseModel):
 
 
 @router.post("/")
-async def get_cat(
+async def post_cat(
     cat: CatPostModel,
     repository: Annotated[CatRepository, Inject(CatRepository)],
 ) -> int:
     cat_id = repository.next_id()
-    cat = Cat(
+    cat_domain = Cat(
         id=cat_id,
         name=cat.name,
         personality=cat.personality,
         age=cat.age,
         breed=cat.breed,
     )
-    repository.set(cat=cat)
+    repository.set(cat=cat_domain)
     return cat_id

{engin-0.0.2 → engin-0.0.4}/examples/simple/main.py

@@ -1,9 +1,12 @@
 import asyncio
+import logging
 
 from httpx import AsyncClient
 
 from engin import Engin, Invoke, Provide
 
+logging.basicConfig(level=logging.DEBUG)
+
 
 def new_httpx_client() -> AsyncClient:
     return AsyncClient()

engin-0.0.4/mkdocs.yaml

@@ -0,0 +1,57 @@
+site_name: Engin
+site_description: A lightweight application framework for modern Python.
+site_url: !ENV READTHEDOCS_CANONICAL_URL
+
+theme:
+    name: 'material'
+    custom_dir: 'docs/overrides'
+    palette:
+      - scheme: 'default'
+        media: '(prefers-color-scheme: light)'
+        toggle:
+          icon: 'material/lightbulb'
+          name: "Switch to dark mode"
+      - scheme: 'slate'
+        media: '(prefers-color-scheme: dark)'
+        primary: 'blue'
+        toggle:
+          icon: 'material/lightbulb-outline'
+          name: 'Switch to light mode'
+
+repo_name: invokermain/engin
+repo_url: https://github.com/invokermain/engin/
+edit_uri: ""
+
+extra_javascript:
+  - js/readthedocs.js
+
+plugins:
+- mkdocstrings:
+    default_handler: python
+    handlers:
+      python:
+        paths: [.]
+        options:
+          members_order: source
+          separate_signature: true
+          filters: ["!^_"]
+          docstring_options:
+            ignore_init_summary: true
+          merge_init_into_class: true
+          show_signature_annotations: true
+          signature_crossrefs: true
+        import:
+          - url: https://docs.python.org/3/objects.inv
+            domains: [py, std]
+
+watch:
+  - src
+
+markdown_extensions:
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.superfences

engin-0.0.4/pyproject.toml

@@ -0,0 +1,91 @@
+[project]
+name = "engin"
+version = "0.0.4"
+description = "An async-first modular application framework"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = []
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+
+[tool.uv]
+dev-dependencies = [
+    "fastapi>=0.115.6",
+    "httpx>=0.27.2",
+    "mypy>=1",
+    "poethepoet>=0.32.1",
+    "pydantic-settings>=2.6.0",
+    "pydantic>=2.9.2",
+    "pytest-asyncio>=0.24.0",
+    "pytest>=8",
+    "ruff>=0",
+    "starlette>=0.39.2",
+    "uvicorn>=0.31.1",
+]
+
+
+[dependency-groups]
+docs = [
+    "mkdocs-material>=9.5.50",
+    "mkdocstrings[python]>=0.27.0",
+]
+
+
+[tool.ruff]
+line-length = 95
+target-version = "py310"
+
+
+[tool.ruff.lint]
+select = [
+    "ANN", "ASYNC", "B", "C4", "DTZ", "E", "F", "I", "INP", "LOG", "PERF", "PIE", "PT",
+    "PTH", "Q", "UP", "R", "RUF", "S", "SIM", "TCH", "T20", "W"
+]
+ignore = [
+    "ANN401",
+    "PERF203", # `try`-`except` within a loop incurs performance overhead
+    "RET505", # Unnecessary `else` after `return` statement
+    "RET506", # Unnecessary `else` after `raise` statement
+]
+
+[tool.ruff.lint.per-file-ignores]
+"**/src/*" = ["PT"]
+"**/tests/*" = ["S", "ANN"]
+"**/examples/*" = ["T201"]
+
+
+[tool.pytest.ini_options]
+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
+]
+
+
+[tool.poe.tasks]
+format.default_item_type = "cmd"
+format.sequence = [
+    "ruff format src tests examples",
+    "ruff check --select I --fix src tests examples"
+]
+
+check.default_item_type = "cmd"
+check.sequence = [
+    "ruff format --check src tests examples",
+    "ruff check src tests examples",
+    "mypy src examples",
+]
+
+fix.default_item_type = "cmd"
+fix.sequence = ["ruff check src tests --fix"]
+
+test = "pytest -s tests"

{engin-0.0.2 → engin-0.0.4}/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.2 → engin-0.0.4}/src/engin/_block.py

@@ -1,29 +1,29 @@
 import inspect
 from collections.abc import Iterable, Iterator
+from typing import ClassVar
 
 from engin._dependency import Func, Invoke, Provide
 
 
 def provide(func: Func) -> Func:
-    func._opt = Provide(func)  # type: ignore[union-attr]
+    func._opt = Provide(func)  # type: ignore[attr-defined]
     return func
 
 
 def invoke(func: Func) -> Func:
-    func._opt = Invoke(func)  # type: ignore[union-attr]
+    func._opt = Invoke(func)  # type: ignore[attr-defined]
     return 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):
-                if not isinstance(opt, (Provide, Invoke)):
+                if not isinstance(opt, Provide | Invoke):
                     raise RuntimeError("Block option is not an instance of Provide or Invoke")
                 opt.set_block_name(self._name)
                 self._options.append(opt)