engin 0.1.0b2__tar.gz → 0.1.0b4__tar.gz

{engin-0.1.0b2 → engin-0.1.0b4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: engin
-Version: 0.1.0b2
+Version: 0.1.0b4
 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.1.0b2 → engin-0.1.0b4}/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.0b2 → engin-0.1.0b4}/docs/concepts/invocations.md

@@ -1,13 +1,13 @@
 # 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, 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.
 

engin-0.1.0b4/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.0b4/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.0b2 → engin-0.1.0b4}/mkdocs.yaml

@@ -33,8 +33,8 @@ nav:
       - 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:

{engin-0.1.0b2 → engin-0.1.0b4}/pyproject.toml

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

{engin-0.1.0b2 → engin-0.1.0b4}/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

{engin-0.1.0b2 → engin-0.1.0b4}/src/engin/_engin.py

@@ -188,7 +188,25 @@ class Engin:
         started to return so it is safe to use immediately after.
         """
         self._async_context_run_task = asyncio.create_task(self.run())
-        await self._start_complete_event.wait()
+        wait_tasks = [
+            asyncio.create_task(self._start_complete_event.wait()),
+            asyncio.create_task(self._stop_complete_event.wait()),
+        ]
+        await asyncio.wait(
+            [
+                self._async_context_run_task,  # if a provider errors this will return first
+                *wait_tasks,
+            ],
+            return_when=asyncio.FIRST_COMPLETED,
+        )
+        for task in wait_tasks:
+            task.cancel()
+
+        # raise the exception from the startup during run
+        if self._async_context_run_task.done():
+            startup_exception = self._async_context_run_task.exception()
+            if startup_exception is not None:
+                raise startup_exception
 
     async def stop(self) -> None:
         """

{engin-0.1.0b2 → engin-0.1.0b4}/tests/acceptance/test_error_in_start_up.py

@@ -36,6 +36,13 @@ async def test_error_in_startup_handled_when_run():
     assert not B_LIFECYCLE_STATE
 
 
+async def test_error_in_startup_handled_when_start():
+    engin = Engin(Invoke(a), Invoke(b))
+
+    await asyncio.wait_for(engin.start(), timeout=0.5)
+    assert not B_LIFECYCLE_STATE
+
+
 async def test_error_in_startup_asgi():
     def asgi_type() -> ASGIType:
         return Starlette()

{engin-0.1.0b2 → engin-0.1.0b4}/tests/test_assembler.py

@@ -22,15 +22,17 @@ async def test_assembler():
 
 
 async def test_assembler_with_multiproviders():
-    assembler = Assembler([Provide(make_many_int), Provide(make_many_int_alt)])
+    # catch any non-deterministic ordering bugs
+    for _ in range(10):
+        assembler = Assembler([Provide(make_many_int), Provide(make_many_int_alt)])
 
-    def assert_all(many_ints: list[int]):
-        expected_ints = [*make_many_int(), *make_many_int_alt()]
-        assert sorted(many_ints) == sorted(expected_ints)
+        def assert_all(many_ints: list[int]):
+            expected_ints = [*make_many_int(), *make_many_int_alt()]
+            assert many_ints == expected_ints
 
-    assembled_dependency = await assembler.assemble(Invoke(assert_all))
+        assembled_dependency = await assembler.assemble(Invoke(assert_all))
 
-    await assembled_dependency()
+        await assembled_dependency()
 
 
 async def test_assembler_providers_only_called_once():

{engin-0.1.0b2 → engin-0.1.0b4}/uv.lock

@@ -211,7 +211,7 @@ toml = [
 
 [[package]]
 name = "engin"
-version = "0.1.0b2"
+version = "0.1.0b3"
 source = { editable = "." }
 dependencies = [
     { name = "anyio" },

engin-0.1.0b2/docs/index.md

@@ -1,62 +0,0 @@
-# Engin 🏎️
-
-Engin is a lightweight application framework powered by dependency injection, it helps
-you build both large monoliths and multiple 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
-    ```
-
-## 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())
-```
-