engin 0.1.0rc1__tar.gz → 0.1.0rc3__tar.gz

{engin-0.1.0rc1 → engin-0.1.0rc3}/.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.1.0rc1 → engin-0.1.0rc3}/CHANGELOG.md

@@ -13,6 +13,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 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`.
 
 
 ## [0.0.20] - 2025-06-18

{engin-0.1.0rc1 → engin-0.1.0rc3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: engin
-Version: 0.1.0rc1
+Version: 0.1.0rc3
 Summary: An async-first modular application framework
 Project-URL: Homepage, https://github.com/invokermain/engin
 Project-URL: Documentation, https://engin.readthedocs.io/en/latest/
@@ -33,13 +33,13 @@ Engin is a lightweight application framework powered by dependency injection, it
 you build and maintain large monoliths and many microservices.
 
 
-## Features
+## Feature
 
-The Engin framework includes:
+The Engin framework gives you:
 
 - 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.
+- Zero boiler-plate code reuse across applications.
 - Integrations for other frameworks such as FastAPI.
 - Full async support.
 - CLI commands to aid local development.
@@ -47,7 +47,7 @@ The Engin framework includes:
 
 ## Installation
 
-Engin is available on PyPI, install using your favourite dependency manager:
+Engin is available on PyPI, install it using your favourite dependency manager:
 
 - `pip install engin`
 - `poetry add engin`
@@ -55,13 +55,13 @@ Engin is available on PyPI, install using your favourite dependency manager:
 
 ## Example
 
-A small example which shows some of the runtime features of Engin. This application
-makes a http request and then performs a shutdown.
+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, Provide, Supervisor
+from engin import Engin, Invoke, Lifecycle, OnException, Provide, Supervisor
 
 
 def httpx_client_factory(lifecycle: Lifecycle) -> AsyncClient:
@@ -76,13 +76,17 @@ 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")
+    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)
 
-    # 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))
@@ -97,6 +101,15 @@ With logs enabled this will output:
 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
 ```
@@ -106,4 +119,4 @@ INFO:engin:shutdown complete
 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.
+They are both great projects, go check them out.

{engin-0.1.0rc1 → engin-0.1.0rc3}/README.md

@@ -14,13 +14,13 @@ Engin is a lightweight application framework powered by dependency injection, it
 you build and maintain large monoliths and many microservices.
 
 
-## Features
+## Feature
 
-The Engin framework includes:
+The Engin framework gives you:
 
 - 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.
+- Zero boiler-plate code reuse across applications.
 - Integrations for other frameworks such as FastAPI.
 - Full async support.
 - CLI commands to aid local development.
@@ -28,7 +28,7 @@ The Engin framework includes:
 
 ## Installation
 
-Engin is available on PyPI, install using your favourite dependency manager:
+Engin is available on PyPI, install it using your favourite dependency manager:
 
 - `pip install engin`
 - `poetry add engin`
@@ -36,13 +36,13 @@ Engin is available on PyPI, install using your favourite dependency manager:
 
 ## Example
 
-A small example which shows some of the runtime features of Engin. This application
-makes a http request and then performs a shutdown.
+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, Provide, Supervisor
+from engin import Engin, Invoke, Lifecycle, OnException, Provide, Supervisor
 
 
 def httpx_client_factory(lifecycle: Lifecycle) -> AsyncClient:
@@ -57,13 +57,17 @@ 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")
+    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)
 
-    # 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))
@@ -78,6 +82,15 @@ With logs enabled this will output:
 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
 ```
@@ -87,4 +100,4 @@ INFO:engin:shutdown complete
 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.
+They are both great projects, go check them out.

engin-0.1.0rc3/docs/cli.md

@@ -0,0 +1,149 @@
+# 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
+
+    Available providers:
+      • str
+      • engin._assembler.Assembler
+      • engin._lifecycle.Lifecycle
+    ```
+
+### 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.1.0rc1 → engin-0.1.0rc3}/docs/concepts/blocks.md

@@ -49,8 +49,8 @@ await 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
+    compisitional approach can help you build and manage larger applications.
 
 
 ## Defining Providers & Invocations in the Block
@@ -77,6 +77,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.0rc3/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. 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, Provide, Invoke, Supervisor
+
+
+def my_service_factory(supervisor: Supervisor) -> MyService:
+    my_service = MyService()
+    supervisor.supervise(my_service.run)
+    return my_service
+
+engin = Engin(Provide(build_service), 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
+
+await 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.1.0rc3/docs/concepts/supervisor.md

@@ -0,0 +1,64 @@
+# Supervisor
+
+The Supervisor manages background tasks for your application.
+
+Background tasks are long-running coroutines that need to run concurrently while your
+application is running. The Supervisor handles starting these tasks, monitoring them for errors,
+and cancelling them when the application is shutting down.
+
+## Using the Supervisor
+
+The Supervisor is automatically provided by the Engin and can be injected into any provider or invocation:
+
+```python
+from engin import Engin, Provide, Supervisor, OnException
+
+
+def background_worker(supervisor: Supervisor) -> WorkerService:
+    worker = WorkerService()
+    
+    # Register the worker's run method as a supervised task
+    supervisor.supervise(worker.run)
+    
+    return worker
+
+
+engin = Engin(Provide(background_worker))
+```
+
+
+## Error Handling
+
+The Supervisor provides three error handling strategies via the `OnException` enum:
+
+### `OnException.SHUTDOWN`
+
+Stops the entire application when the task fails:
+
+```python
+supervisor.supervise(critical_task)  # Will shutdown app on error
+```
+
+This is the default behaviour.
+
+### `OnException.RETRY`
+
+Automatically restarts the task when it fails:
+
+```python
+supervisor.supervise(
+    flaky_network_task,
+    on_exception=OnException.RETRY
+)
+```
+
+### `OnException.IGNORE`
+
+Logs the error but continues running other tasks:
+
+```python
+supervisor.supervise(
+    optional_monitoring_task,
+    on_exception=OnException.IGNORE
+)
+```

engin-0.1.0rc3/docs/index.md

@@ -0,0 +1,98 @@
+# Engin 🏎️
+
+Engin is a lightweight application framework powered by dependency injection, it helps
+you build and maintain large monoliths and microservices.
+
+
+## Features
+
+The Engin framework gives you:
+
+- A fully-featured dependency injection system.
+- A robust application runtime with lifecycle hooks and supervised background tasks.
+- Zero boiler-plate code reuse across 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 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
+```

{engin-0.1.0rc1 → engin-0.1.0rc3}/docs/integrations/fastapi.md

@@ -75,28 +75,24 @@ reusable SQL session per request, we could use a nested dependency:
 from typing import Annotated, AsyncIterable
 
 from engin.extensions.fastapi import Inject
-from fastapi import Depends
 
 
 async def database_session(
-        database: Annotated[Database, Inject(Database)])
-
-    ) -> AsyncIterable[Session]:
+    database: Annotated[Database, Inject(Database)] 
+) -> AsyncIterable[Session]:
     with database.new_session() as session:
         yield session
-    session.commit()
-
-    @ app.post("/{id}")
-    async
+        session.commit() 
 
-    def add_item(session: Annotated[Session, Depends(database_session)]):
-        session.add(MyORMModel(...))
+@app.post("/{id}")
+async def add_item(session: Annotated[Session, Inject(database_session)]):
+    session.add(MyORMModel(...))
 ```
 
 
 ## Attaching Routers to Engin
 
-The usual way to declare an `APIRouter` is as a module level variable, for example:
+The idiomatic way to declare an `APIRouter` is as a module level variable, for example:
 
 ```python title="api.py"
 from fastapi import APIRouter

engin-0.1.0rc3/docs/tutorial/1_empty_application.md

@@ -0,0 +1,37 @@
+Let's start by creating a minimal application using Engin. We do this by instantiating the
+Engin class which will serve as our application runtime.
+
+```python title="app.py"
+import asyncio
+import logging
+
+from engin import Engin
+
+engin = Engin()
+
+if __name__ == "__main__":
+    logging.basicConfig(level=logging.INFO)
+    asyncio.run(engin.run())
+```
+
+If we run the application using `python app.py` we will see the following output:
+
+```
+INFO:engin:starting engin
+INFO:engin:startup complete
+```
+
+And if we stop the application using `ctrl + c` or equivalent we will see:
+
+```
+INFO:engin:stopping engin
+INFO:engin:shutdown complete
+```
+
+Now that we have an empty application, let's give it something to do.
+
+!!! note
+    
+    Engin is typically used for long running application such as Web Servers or an Event
+    Consumers. In these scenarios the engin would run until it receives a SIGINT signal (for
+    example when a new deployment happens) at which point it would shutdown.