engin 0.1.0a2__tar.gz → 0.1.0b3__tar.gz

{engin-0.1.0a2 → engin-0.1.0b3}/CHANGELOG.md

@@ -11,6 +11,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Supervisor class which can safely supervise long running tasks.
 
+### Changed
+
+- `ASGIEngin.run()` now raises an error to prevent incorrect usage.
+
 
 ## [0.0.20] - 2025-06-18
 

engin-0.1.0b3/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: engin
+Version: 0.1.0b3
+Summary: An async-first modular application framework
+Project-URL: Homepage, https://github.com/invokermain/engin
+Project-URL: Documentation, https://engin.readthedocs.io/en/latest/
+Project-URL: Repository, https://github.com/invokermain/engin.git
+Project-URL: Changelog, https://github.com/invokermain/engin/blob/main/CHANGELOG.md
+License-Expression: MIT
+License-File: LICENSE
+Keywords: Application Framework,Dependency Injection
+Requires-Python: >=3.10
+Requires-Dist: anyio>=4
+Requires-Dist: exceptiongroup>=1
+Provides-Extra: cli
+Requires-Dist: typer>=0.15; extra == 'cli'
+Description-Content-Type: text/markdown
+
+# Engin 🏎️
+
+[![codecov](https://codecov.io/gh/invokermain/engin/graph/badge.svg?token=4PJOIMV6IB)](https://codecov.io/gh/invokermain/engin)
+
+---
+
+**Documentation**: [https://engin.readthedocs.io/](https://engin.readthedocs.io/)
+
+**Source Code**: [https://github.com/invokermain/engin](https://github.com/invokermain/engin)
+
+---
+
+Engin is a lightweight application framework powered by dependency injection, it helps
+you build and maintain large monoliths and many microservices.
+
+
+## Features
+
+The Engin framework includes:
+
+- A fully-featured dependency injection system.
+- A robust application runtime with lifecycle hooks and supervised background tasks.
+- Zero boiler-plate code reuse across multiple applications.
+- Integrations for other frameworks such as FastAPI.
+- Full async support.
+- CLI commands to aid local development.
+
+
+## Installation
+
+Engin is available on PyPI, install using your favourite dependency manager:
+
+- `pip install engin`
+- `poetry add engin`
+- `uv add engin`
+
+## Example
+
+A small example which shows some of the runtime features of Engin. This application
+makes a http request and then performs a shutdown.
+
+```python
+import asyncio
+from httpx import AsyncClient
+from engin import Engin, Invoke, Lifecycle, Provide, Supervisor
+
+
+def httpx_client_factory(lifecycle: Lifecycle) -> AsyncClient:
+    # create our http client
+    client = AsyncClient()
+    # this will open and close the AsyncClient as part of the application's lifecycle
+    lifecycle.append(client)
+    return client
+
+
+async def main(
+    httpx_client: AsyncClient,
+    supervisor: Supervisor,
+) -> None:
+    async def http_request():
+        await httpx_client.get("https://httpbin.org/get")
+        # one we've made the http request shutdown the application
+        raise asyncio.CancelledError("Forcing shutdown")
+
+    # supervise the http request as part of the application's lifecycle
+    supervisor.supervise(http_request)
+
+# define our modular application
+engin = Engin(Provide(httpx_client_factory), Invoke(main))
+
+# run it!
+asyncio.run(engin.run())
+```
+
+With logs enabled this will output:
+
+```shell
+INFO:engin:starting engin
+INFO:engin:startup complete
+INFO:httpx:HTTP Request: GET https://httpbin.org/get "HTTP/1.1 200 OK"
+INFO:engin:stopping engin
+INFO:engin:shutdown complete
+```
+
+## Inspiration
+
+Engin is heavily 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).
+
+They are both great projects, check them out.

engin-0.1.0b3/README.md

@@ -0,0 +1,90 @@
+# Engin 🏎️
+
+[![codecov](https://codecov.io/gh/invokermain/engin/graph/badge.svg?token=4PJOIMV6IB)](https://codecov.io/gh/invokermain/engin)
+
+---
+
+**Documentation**: [https://engin.readthedocs.io/](https://engin.readthedocs.io/)
+
+**Source Code**: [https://github.com/invokermain/engin](https://github.com/invokermain/engin)
+
+---
+
+Engin is a lightweight application framework powered by dependency injection, it helps
+you build and maintain large monoliths and many microservices.
+
+
+## Features
+
+The Engin framework includes:
+
+- A fully-featured dependency injection system.
+- A robust application runtime with lifecycle hooks and supervised background tasks.
+- Zero boiler-plate code reuse across multiple applications.
+- Integrations for other frameworks such as FastAPI.
+- Full async support.
+- CLI commands to aid local development.
+
+
+## Installation
+
+Engin is available on PyPI, install using your favourite dependency manager:
+
+- `pip install engin`
+- `poetry add engin`
+- `uv add engin`
+
+## Example
+
+A small example which shows some of the runtime features of Engin. This application
+makes a http request and then performs a shutdown.
+
+```python
+import asyncio
+from httpx import AsyncClient
+from engin import Engin, Invoke, Lifecycle, Provide, Supervisor
+
+
+def httpx_client_factory(lifecycle: Lifecycle) -> AsyncClient:
+    # create our http client
+    client = AsyncClient()
+    # this will open and close the AsyncClient as part of the application's lifecycle
+    lifecycle.append(client)
+    return client
+
+
+async def main(
+    httpx_client: AsyncClient,
+    supervisor: Supervisor,
+) -> None:
+    async def http_request():
+        await httpx_client.get("https://httpbin.org/get")
+        # one we've made the http request shutdown the application
+        raise asyncio.CancelledError("Forcing shutdown")
+
+    # supervise the http request as part of the application's lifecycle
+    supervisor.supervise(http_request)
+
+# define our modular application
+engin = Engin(Provide(httpx_client_factory), Invoke(main))
+
+# run it!
+asyncio.run(engin.run())
+```
+
+With logs enabled this will output:
+
+```shell
+INFO:engin:starting engin
+INFO:engin:startup complete
+INFO:httpx:HTTP Request: GET https://httpbin.org/get "HTTP/1.1 200 OK"
+INFO:engin:stopping engin
+INFO:engin:shutdown complete
+```
+
+## Inspiration
+
+Engin is heavily 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).
+
+They are both great projects, check them out.

{engin-0.1.0a2 → engin-0.1.0b3}/docs/concepts/engin.md

@@ -1,6 +1,6 @@
 # The Engin
 
-The Engin is a self-contained modular application.
+The Engin is your self-contained modular application.
 
 When ran the Engin takes care of the complete application lifecycle:
 

{engin-0.1.0a2 → engin-0.1.0b3}/docs/concepts/invocations.md

@@ -1,19 +1,19 @@
 # Invocations
 
-Invocations define the behaviour of your application, therefore without any Invocations
+Invocations define the behaviour of your application, without any Invocations
 your application will not do anything.
 
-Like providers invocations are functions that take one or more dependencies as parameters,
-and they should always return None as the return value will not used by the Engin.
+Like providers, invocations are functions that take one or more dependencies as
+parameters, but they should always return None as the return value will not used by Engin.
 
-As part of the Engin's startup, all declared invocations will be called sequentially in
-the order they were registered.
+As part of the Engin's startup sequence, all declared invocations will be called
+sequentially in the order they were registered.
 
 Invocations can be used to define behaviour in two ways.
 
 **Implicit: Provider Lifecycle**
 
-Invocations are always called therefore their dependencies are always assembled. This
+Invocations are always called and therefore their dependencies are always assembled. This
 means that any providers with lifecycles will register their lifecycles with the
 application if directly or indirectly used by an invocation.
 

{engin-0.1.0a2 → engin-0.1.0b3}/docs/concepts/lifecycle.md

@@ -1,5 +1,3 @@
-from contextlib import asynccontextmanager
-
 # Lifecycle
 
 Certain types of object naturally have some form of startup and shutdown behaviour

engin-0.1.0b3/docs/index.md

@@ -0,0 +1,86 @@
+# Engin 🏎️
+
+Engin is a lightweight application framework powered by dependency injection, it helps
+you build and maintain large monoliths and many microservices.
+
+
+## Features
+
+The Engin framework includes:
+
+- A fully-featured dependency injection system.
+- A robust application runtime with lifecycle hooks and supervised background tasks.
+- Zero boiler-plate code reuse across multiple applications.
+- Integrations for other frameworks such as FastAPI.
+- Full async support.
+- CLI commands to aid local development.
+
+
+## Installation
+
+=== "uv"
+
+    ```shell
+    uv add engin
+    ```
+
+=== "poetry"
+
+    ```shell
+    poetry add engin
+    ```
+
+=== "pip"
+
+    ```shell
+    pip install engin
+    ```
+
+## Example
+
+A small example which shows some of the runtime features of Engin. This application
+makes a http request and then performs a shutdown.
+
+```python
+import asyncio
+from httpx import AsyncClient
+from engin import Engin, Invoke, Lifecycle, Provide, ShutdownSwitch, Supervisor
+
+
+def httpx_client_factory(lifecycle: Lifecycle) -> AsyncClient:
+    # create our http client
+    client = AsyncClient()
+    # this will open and close the AsyncClient as part of the application's lifecycle
+    lifecycle.append(client)
+    return client
+
+
+async def main(
+    httpx_client: AsyncClient,
+    shutdown: ShutdownSwitch,
+    supervisor: Supervisor,
+) -> None:
+    async def http_request():
+        await httpx_client.get("https://httpbin.org/get")
+        # one we've made the http request shutdown the application
+        shutdown.set()
+
+    # supervise the http request as part of the application's lifecycle
+    supervisor.supervise(http_request)
+
+# define our modular application
+engin = Engin(Provide(httpx_client_factory), Invoke(main))
+
+# run it!
+asyncio.run(engin.run())
+```
+
+With logs enabled this will output:
+
+```shell
+INFO:engin:starting engin
+INFO:engin:startup complete
+INFO:httpx:HTTP Request: GET https://httpbin.org/get "HTTP/1.1 200 OK"
+INFO:engin:stopping engin
+INFO:engin:shutdown complete
+```

engin-0.1.0b3/docs/tutorial.md

@@ -0,0 +1,15 @@
+# Tutorial
+
+In this tutorial we will build a small toy application from scratch.
+
+Our application will publish random numbers to a Valkey stream, and then consume them and
+update a running total.
+
+## 1. Create a Valkey client
+
+```python
+from valkey import Valkey
+
+def valkey_client() -> Valkey:
+    ...
+```

{engin-0.1.0a2 → engin-0.1.0b3}/mkdocs.yaml

@@ -7,7 +7,7 @@ theme:
     custom_dir: 'docs/overrides'
     features:
       - navigation.instant
-      - navigation.tabs
+      - content.code.copy
     palette:
       - scheme: 'default'
         media: '(prefers-color-scheme: light)'
@@ -27,15 +27,14 @@ 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"
       - Blocks: "concepts/blocks.md"
-  - Guides:
-      - FastAPI: "guides/fastapi.md"
+  - Integrations:
+      - FastAPI: "integrations/fastapi.md"
   - Reference: "reference.md"
 
 extra_javascript:
@@ -60,6 +59,7 @@ plugins:
         inventories:
           - url: https://docs.python.org/3/objects.inv
             domains: [py, std]
+- search
 
 watch:
   - src
@@ -71,9 +71,13 @@ markdown_extensions:
   - pymdownx.blocks.caption
   - pymdownx.details
   - pymdownx.highlight:
-      anchor_linenums: true
-      line_spans: __span
-      pygments_lang_class: true
+        anchor_linenums: true
+        line_spans: __span
+        pygments_lang_class: true
   - pymdownx.inlinehilite
-  - pymdownx.snippets
+  - pymdownx.snippets:
+      base_path: [!relative $config_dir]
+      check_paths: true
   - pymdownx.superfences
+  - pymdownx.tabbed:
+      alternate_style: true

{engin-0.1.0a2 → engin-0.1.0b3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "engin"
-version = "0.1.0a2"
+version = "0.1.0b3"
 description = "An async-first modular application framework"
 readme = "README.md"
 requires-python = ">=3.10"

{engin-0.1.0a2 → engin-0.1.0b3}/src/engin/__init__.py

@@ -4,7 +4,6 @@ from engin._dependency import Entrypoint, Invoke, Provide, Supply
 from engin._engin import Engin
 from engin._lifecycle import Lifecycle
 from engin._option import Option
-from engin._shutdown import ShutdownSwitch
 from engin._supervisor import OnException, Supervisor
 from engin._type_utils import TypeId
 
@@ -18,7 +17,6 @@ __all__ = [
     "OnException",
     "Option",
     "Provide",
-    "ShutdownSwitch",
     "Supervisor",
     "Supply",
     "TypeId",

{engin-0.1.0a2 → engin-0.1.0b3}/src/engin/_assembler.py

@@ -65,7 +65,7 @@ class Assembler:
         self._multiproviders: dict[TypeId, list[Provide[list[Any]]]] = defaultdict(list)
         self._assembled_outputs: dict[TypeId, Any] = {}
         self._lock = asyncio.Lock()
-        self._graph_cache: dict[TypeId, set[Provide]] = defaultdict(set)
+        self._graph_cache: dict[TypeId, list[Provide]] = defaultdict(list)
 
         for provider in providers:
             type_id = provider.return_type_id
@@ -206,10 +206,10 @@ class Assembler:
             if provider.scope == scope:
                 self._assembled_outputs.pop(type_id, None)
 
-    def _resolve_providers(self, type_id: TypeId, resolved: set[TypeId]) -> set[Provide]:
+    def _resolve_providers(self, type_id: TypeId, resolved: set[TypeId]) -> Iterable[Provide]:
         """
         Resolves the chain of providers required to satisfy the provider of a given type.
-        Ordering of the return value is very important!
+        Ordering of the return value is very important here!
         """
         if type_id in self._graph_cache:
             return self._graph_cache[type_id]
@@ -231,13 +231,15 @@ class Assembler:
                 raise LookupError(msg)
 
         # providers that must be satisfied to satisfy the root level providers
-        resolved_providers = {
+        resolved_providers = [
             child_provider
             for root_provider in root_providers
             for root_provider_param in root_provider.parameter_type_ids
             for child_provider in self._resolve_providers(root_provider_param, resolved)
             if root_provider_param not in resolved
-        } | set(root_providers)
+        ]
+
+        resolved_providers.extend(root_providers)
 
         resolved.add(type_id)
         self._graph_cache[type_id] = resolved_providers