engin 0.0.20__tar.gz → 0.1.0__tar.gz

{engin-0.0.20 → engin-0.1.0}/.github/workflows/benchmark.yaml

@@ -4,6 +4,9 @@ on:
   push:
     branches: [main]
 
+env:
+  UV_FROZEN: "1"
+
 jobs:
   benchmark-main:
     runs-on: ubuntu-latest

{engin-0.0.20 → engin-0.1.0}/.github/workflows/check.yaml

@@ -3,6 +3,9 @@ name: Check
 on:
   push:
 
+env:
+  UV_FROZEN: "1"
+
 jobs:
   check:
     name: python
@@ -40,6 +43,7 @@ jobs:
         run: uv run poe ci-test
 
       - name: Upload coverage reports to Codecov
+        if: matrix.os == 'ubuntu-latest'
         uses: codecov/codecov-action@v5
         with:
           token: ${{ secrets.CODECOV_TOKEN }}

{engin-0.0.20 → engin-0.1.0}/.gitignore

@@ -163,3 +163,5 @@ cython_debug/
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 .idea/
+
+scrap/**

{engin-0.0.20 → engin-0.1.0}/CHANGELOG.md

@@ -5,6 +5,23 @@ 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.1.0] - 2025-08-16
+
+### Added
+
+- `Supervisor` class which can safely supervise long running tasks.
+- A new cli option `engin check` that validates whether you have any missing providers. 
+- Support for specifying `default-instance` in your `pyproject.toml` under `[tool.engin]`
+  which is used as a default value for the `app` parameter when using the cli.
+- A new exception class: `TypeNotProvidedError`.
+
+### Changed
+
+- If a Provider is missing during Assembly, the Assembler now raises `TypeNotProvidedError`
+  instead of a `LookupError`.
+- `engin graph` has improved visualisations and options.
+- `engin check` does not list all available providers anymore.
+
 
 ## [0.0.20] - 2025-06-18
 

engin-0.1.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: engin
+Version: 0.1.0
+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: tomli>=2.0; (python_version < '3.11') and 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.
+
+
+## Feature
+
+The Engin framework gives you:
+
+- A fully-featured dependency injection system.
+- A robust application runtime with lifecycle hooks and supervised background tasks.
+- Zero boilerplate code reuse across applications.
+- Integrations for other frameworks such as FastAPI.
+- Full async support.
+- CLI commands to aid local development.
+
+
+## Installation
+
+Engin is available on PyPI, install it using your favourite dependency manager:
+
+- `pip install engin`
+- `poetry add engin`
+- `uv add engin`
+
+## Example
+
+A small example which shows some of the features of Engin. This application
+makes 3 http requests and shuts itself down.
+
+```python
+import asyncio
+from httpx import AsyncClient
+from engin import Engin, Invoke, Lifecycle, OnException, 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_requests_task():
+        # simulate a background task
+        for x in range(3):
+            await httpx_client.get("https://httpbin.org/get")
+            await asyncio.sleep(1.0)
+        # raise an error to shutdown the application, normally you wouldn't do this!
+        raise RuntimeError("Forcing shutdown")
+
+    # supervise the http requests as part of the application's lifecycle
+    supervisor.supervise(http_requests_task, on_exception=OnException.SHUTDOWN)
+
+
+# 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:httpx:HTTP Request: GET https://httpbin.org/get "HTTP/1.1 200 OK"
+INFO:httpx:HTTP Request: GET https://httpbin.org/get "HTTP/1.1 200 OK"
+ERROR:engin:supervisor task 'http_requests_task' raised RuntimeError, starting shutdown
+Traceback (most recent call last):
+  File "C:\dev\python\engin\src\engin\_supervisor.py", line 58, in __call__
+    await self.factory()
+  File "C:\dev\python\engin\readme_example.py", line 29, in http_requests_task
+    raise RuntimeError("Forcing shutdown")
+RuntimeError: Forcing shutdown
+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, go check them out.

engin-0.1.0/README.md

@@ -0,0 +1,103 @@
+# 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.
+
+
+## Feature
+
+The Engin framework gives you:
+
+- A fully-featured dependency injection system.
+- A robust application runtime with lifecycle hooks and supervised background tasks.
+- Zero boilerplate code reuse across applications.
+- Integrations for other frameworks such as FastAPI.
+- Full async support.
+- CLI commands to aid local development.
+
+
+## Installation
+
+Engin is available on PyPI, install it using your favourite dependency manager:
+
+- `pip install engin`
+- `poetry add engin`
+- `uv add engin`
+
+## Example
+
+A small example which shows some of the features of Engin. This application
+makes 3 http requests and shuts itself down.
+
+```python
+import asyncio
+from httpx import AsyncClient
+from engin import Engin, Invoke, Lifecycle, OnException, 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_requests_task():
+        # simulate a background task
+        for x in range(3):
+            await httpx_client.get("https://httpbin.org/get")
+            await asyncio.sleep(1.0)
+        # raise an error to shutdown the application, normally you wouldn't do this!
+        raise RuntimeError("Forcing shutdown")
+
+    # supervise the http requests as part of the application's lifecycle
+    supervisor.supervise(http_requests_task, on_exception=OnException.SHUTDOWN)
+
+
+# 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:httpx:HTTP Request: GET https://httpbin.org/get "HTTP/1.1 200 OK"
+INFO:httpx:HTTP Request: GET https://httpbin.org/get "HTTP/1.1 200 OK"
+ERROR:engin:supervisor task 'http_requests_task' raised RuntimeError, starting shutdown
+Traceback (most recent call last):
+  File "C:\dev\python\engin\src\engin\_supervisor.py", line 58, in __call__
+    await self.factory()
+  File "C:\dev\python\engin\readme_example.py", line 29, in http_requests_task
+    raise RuntimeError("Forcing shutdown")
+RuntimeError: Forcing shutdown
+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, go check them out.

engin-0.1.0/docs/cli.md

@@ -0,0 +1,144 @@
+# CLI Commands
+
+Engin provides a set of CLI commands to aid with application development. To use these commands,
+you need to install Engin with the `cli` extra, which can safely be treated as a
+development only dependency.
+
+```shell
+uv add engin[cli]
+```
+
+!!! tip
+    
+    It is recommended to configure a default instance in your `pyproject.toml`.
+    
+    ```toml
+    [tool.engin]
+    default-instance = "myapp.main:engin"
+    ```
+    
+    When configured, you can run any CLI command without the app argument:
+    
+    ```shell
+    # Uses the default instance from pyproject.toml
+    engin check
+    
+    # Passing an explicit instance always overrides the default instance
+    engin check myapp.main:engin
+    ```
+
+## Commands
+
+- `engin check`: checks for missing providers.
+- `engin inspect`: show metadata about providers.
+- `engin graph`: visualise your dependency graph.
+
+### engin check
+
+Checks that all dependencies in your Engin instance are satisfied.
+
+If there are any missing providers it will return with exit code 1.
+
+Note, this command only validates there are providers for all dependencies required by
+invocations, any dependencies built dynamically at runtime via the Assembler will not be
+checked for as these cannot be statically analysed.
+
+#### Usage
+```shell
+engin check [OPTIONS]
+```
+
+#### Options
+
+- `--app`: the path to your application in the format `<module>:<attribute>`, e.g. `myapp.main:engin`. Not
+   required if you set a `default-instance` in your `pyproject.toml`.
+
+#### Example
+
+```shell
+engin check myapp.main:engin
+```
+
+=== "Success"
+
+    ```
+    ✅ All dependencies are satisfied!
+    ```
+
+=== "Missing Dependencies"
+
+    ```
+    ❌ Missing providers found:
+      • httpx.AsyncClient
+      • DatabaseConfig
+    ```
+
+### engin inspect
+
+Shows detailed metadata for providers in your Engin instance. You can filter providers by type
+or module.
+
+#### Usage
+```shell
+engin inspect [OPTIONS]
+```
+
+#### Options
+
+- `--app`: the path to your application in the format `<module>:<attribute>`, e.g. `myapp.main:engin`. Not
+   required if you set a `default-instance` in your `pyproject.toml`.
+- `--type`: filter providers by return type name. Note that multiproviders take the form of `type[]`.
+- `--module`: filter providers by the return type's module.
+- `--verbose`: enable verbose output.
+
+#### Example
+
+```shell
+engin inspect myapp.main:engin --module httpx
+```
+
+=== "Output"
+    
+    ```
+    Found 1 matching provider
+    ┌─────────────────────────────────────────────────────────────────────────┐
+    │ name           │ Provide(factory=httpx_client, type=AsyncClient)  │
+    │ scope          │ N/A                                              │
+    │ func           │ httpx_client                                     │
+    │ block          │ N/A                                              │
+    │ source module  │ myapp.main                                       │
+    │ source package │ myapp                                            │
+    └─────────────────────────────────────────────────────────────────────────┘
+    ```
+
+### engin graph
+
+Creates a visual representation of your application's dependency graph.
+
+This starts a local web server which displays an interactive graph of your dependencies.
+
+#### Usage
+```shell
+engin graph [OPTIONS]
+```
+
+#### Options
+
+- `--app`: the path to your application in the format `<module>:<attribute>`, e.g. `myapp.main:engin`. Not
+   required if you set a `default-instance` in your `pyproject.toml`.
+
+#### Example
+
+```shell
+engin graph myapp.main:engin
+```
+
+=== "Visualisation"
+
+    ![engin-graph-output.png](engin-graph-output.png)
+
+=== "Console"
+
+    ```
+    Serving dependency graph on http://localhost:8123
+    ```

{engin-0.0.20 → engin-0.1.0}/docs/concepts/blocks.md

@@ -27,10 +27,11 @@ Blocks have a class attribute named `options` which can be used to include exist
 options.
 
 ```python
+import asyncio
 from engin import Engin, Block, Invoke, Provide, Supply
 
 
-def print_string(self, string: str) -> None:
+def print_string(string: str) -> None:
    print(string)
 
    
@@ -44,13 +45,13 @@ class ExampleBlock(Block):
 # register it as a provider with the Engin
 engin = Engin(ExampleBlock())
 
-await engin.run()  # prints 'hello'
+asyncio.run(engin.run())  # prints 'hello'
 ```
 
 !!!tip
 
-Blocks are themselves valid options, so Blocks can include other Blocks as options. This
-compisitional approach can help you build and manage larger applications.
+    Blocks are themselves valid options, so Blocks can include other Blocks as options. This
+    compositional approach can help you build and manage larger applications.
 
 
 ## Defining Providers & Invocations in the Block
@@ -77,6 +78,6 @@ class ExampleBlock(Block):
 
 !!!note
 
-The `self` parameter in these methods is replaced with an empty object at runtime so
-should not be used. Blocks do not need to be instantiated to be passed to Engin as an
-option.
+    The `self` parameter in these methods is replaced with an empty object at runtime so
+    should not be used. Blocks do not need to be instantiated to be passed to Engin as an
+    option.

engin-0.1.0/docs/concepts/engin.md

@@ -0,0 +1,62 @@
+# The Engin
+
+An Engin instance is a self-contained application.
+
+The Engin class manages your application's complete lifecycle, when ran it will:
+
+1. Assemble the dependencies required by your invocations.
+2. Runs all given invocations sequentially in the order they were passed in to the Engin. 
+3. Run all lifecycle startup tasks that were registered by assembled dependencies sequentially.
+4. Start any supervised background tasks.
+5. Wait for a shutdown signal, SIGINT or SIGTERM, or for a supervised task to cause a shutdown.
+6. Stop any supervised background tasks that are still running.
+7. Run all corresponding lifecycle shutdown tasks in the reverse order to the startup order.
+
+
+## Creating an Engin
+
+Instantiate an Engin with any combination of options, i.e. providers, invocations, and blocks:
+
+```python
+from engin import Engin, Entrypoint, Provide, Supervisor
+
+def my_service_factory(supervisor: Supervisor) -> MyService:
+    my_service = MyService()
+    supervisor.supervise(my_service.run)
+    return my_service
+
+engin = Engin(Provide(my_service_factory), Entrypoint(MyService))
+```
+
+## Running your application
+
+### `engin.run()`
+
+The recommended way to run your application.
+
+This will not return until the application is stopped and shutdown has been performed. As it
+listens for signals and handles cancellation this should be the top-most function called in
+your application:
+
+```python
+import asyncio
+
+asyncio.run(engin.run())
+```
+
+
+### `engin.start()` and `engin.stop()`
+
+For advanced scenarios where you need more control over the application lifecycle:
+
+```python
+# Start the application in the background
+await engin.start()
+
+# Do other work...
+
+# Gracefully stop the application  
+await engin.stop()
+```
+
+This approach can be useful when writing tests for an Engin application.

{engin-0.0.20 → engin-0.1.0}/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 be 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.
 
@@ -113,7 +113,7 @@ Invocations can use any types as long as they have the matching providers.
 
 ```python
 import asyncio
-from engin import Engin, Invoke
+from engin import Engin, Invoke, Provide
 
 # define a constructor
 def name_factory() -> str:
@@ -123,7 +123,7 @@ def print_hello(name: str) -> None:
    print(f"hello {name}!")
 
 # register it as a invocation with the Engin
-engin = Engin(Provide(name_factory()), Invoke(hello_world))
+engin = Engin(Provide(name_factory), Invoke(print_hello))
 
 # run your application
 asyncio.run(engin.run())  # hello Dmitrii!

{engin-0.0.20 → engin-0.1.0}/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
@@ -10,13 +8,13 @@ connection pool on startup, and gracefully release the connections on shutdown.
 Doing this yourself can be tricky and is application dependent: most will not have any
 special support for this and will expect you to manage your lifecycle concerns in your
 entrypoint function, leading to unwieldy code in larger applications, whilst other
-types application might expected you to translate the lifecyle tasks into something they
+types application might expected you to translate the lifecycle tasks into something they
 offer, e.g. an ASGI server would expect you to manage this via its lifespan. In both cases
 you end up managing lifecycle in a completely different place to where you declare your
 objects, which make the codebase more complicated to understand.
 
 Luckily, engin makes declaring lifecycle tasks a breeze, and it can be done in the same
-provider that build your object keeping your code nicely collocated.
+provider that builds your object keeping your code nicely collocated.
 
 ## The Lifecycle type
 
@@ -49,9 +47,9 @@ def httpx_client(lifecycle: Lifecycle) -> AsyncClient:
     return client
 ```
 
-### 2. Explict startup & shutdown methods
+### 2. Explicit startup & shutdown methods
 
-If your type exposes meathods that must be called as part of the lifecycle, e.g. `start()`
+If your type exposes methods that must be called as part of the lifecycle, e.g. `start()`
 & `stop()`, then `lifecycle.hook(on_start=..., on_stop=...)` is the way.
 
 Let's look at an example using `piccolo.engine.PostgresEngin`:
@@ -60,12 +58,12 @@ Let's look at an example using `piccolo.engine.PostgresEngin`:
 from engin import Lifecycle
 from piccolo.engine import PostgresEngine
 
-def postgres_engine(lifecyle: Lifecycle) -> PostgresEngine:
+def postgres_engine(lifecycle: Lifecycle) -> PostgresEngine:
     db_engine = PostgresEngine(...)  # fill in actual connection details
 
-    lifecyle.hook(
-        on_start=db_engine.start_connection_pool(),
-        on_stop=db_engine.close_connection_pool(),
+    lifecycle.hook(
+        on_start=db_engine.start_connection_pool,
+        on_stop=db_engine.close_connection_pool,
     )
 
     return db_engine
@@ -81,6 +79,7 @@ therefore we want to manage it as a task.
 
 ```python
 import asyncio
+from contextlib import asynccontextmanager
 from engin import Lifecycle
 from some_package import BlockingAsyncWorker
 
@@ -98,3 +97,7 @@ def blocking_worker(lifecycle: Lifecycle) -> BlockingWorker:
 
     return worker
 ```
+
+!!! note
+
+    The above case is only given as a reference, running background tasks should be done via the `Supervisor` depedency.