engin 0.1.0rc2__tar.gz → 0.2.0a1__tar.gz

{engin-0.1.0rc2 → engin-0.2.0a1}/.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.0rc2 → engin-0.2.0a1}/CHANGELOG.md

@@ -5,11 +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] - UNRELEASED
+## UNRELEASED
 
 ### Added
 
-- Supervisor class which can safely supervise long running tasks.
+- `Supevisor` now has a shutdown hook option for supervised tasks.
+
+### Changed
+
+- `Provide` now raises a helpful error message when it is called with a static value
+  suggesting to use `Supply` instead.
+
+
+## [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.
@@ -19,6 +31,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - 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.0rc2 → engin-0.2.0a1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: engin
-Version: 0.1.0rc2
+Version: 0.2.0a1
 Summary: An async-first modular application framework
 Project-URL: Homepage, https://github.com/invokermain/engin
 Project-URL: Documentation, https://engin.readthedocs.io/en/latest/
@@ -39,7 +39,7 @@ 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.
+- Zero boilerplate code reuse across applications.
 - Integrations for other frameworks such as FastAPI.
 - Full async support.
 - CLI commands to aid local development.

{engin-0.1.0rc2 → engin-0.2.0a1}/README.md

@@ -20,7 +20,7 @@ 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.
+- Zero boilerplate code reuse across applications.
 - Integrations for other frameworks such as FastAPI.
 - Full async support.
 - CLI commands to aid local development.

{engin-0.1.0rc2 → engin-0.2.0a1}/docs/cli.md

@@ -71,11 +71,6 @@ engin check myapp.main:engin
     ❌ Missing providers found:
       • httpx.AsyncClient
       • DatabaseConfig
-
-    Available providers:
-      • str
-      • engin._assembler.Assembler
-      • engin._lifecycle.Lifecycle
     ```
 
 ### engin inspect

{engin-0.1.0rc2 → engin-0.2.0a1}/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.
+    compositional approach can help you build and manage larger applications.
 
 
 ## Defining Providers & Invocations in the Block

{engin-0.1.0rc2 → engin-0.2.0a1}/docs/concepts/engin.md

@@ -9,7 +9,8 @@ The Engin class manages your application's complete lifecycle, when ran it will:
 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.
+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
@@ -17,15 +18,14 @@ The Engin class manages your application's complete lifecycle, when ran it will:
 Instantiate an Engin with any combination of options, i.e. providers, invocations, and blocks:
 
 ```python
-from engin import Engin, Provide, Invoke, Supervisor
-
+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(build_service), Entrypoint(MyService))
+engin = Engin(Provide(my_service_factory), Entrypoint(MyService))
 ```
 
 ## Running your application
@@ -41,7 +41,7 @@ your application:
 ```python
 import asyncio
 
-await asyncio.run(engin.run())
+asyncio.run(engin.run())
 ```
 
 

{engin-0.1.0rc2 → engin-0.2.0a1}/docs/concepts/invocations.md

@@ -4,7 +4,7 @@ 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.
+parameters, but they should always return None as the return value will not be used by Engin.
 
 As part of the Engin's startup sequence, all declared invocations will be called
 sequentially in the order they were registered.
@@ -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.1.0rc2 → engin-0.2.0a1}/docs/concepts/lifecycle.md

@@ -8,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
 
@@ -47,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`:
@@ -58,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
@@ -79,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
 
@@ -96,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.

{engin-0.1.0rc2 → engin-0.2.0a1}/docs/concepts/providers.md

@@ -1,6 +1,6 @@
 # Providers
 
-Providers are the factories of your application, they are reponsible for the construction
+Providers are the factories of your application, they are responsible for the construction
 of the objects that your application needs.
 
 Remember, the Engin only calls the providers that are necessary to run your application.
@@ -74,7 +74,6 @@ greeter = await engin.assembler.build(Greeter)
 greeter.greet("Bob")  # hello, Bob!
 ```
 
-
 ## Providers are only called when required
 
 The Assembler will only call a provider when the type is requested, directly or indirectly
@@ -186,4 +185,89 @@ engin = Engin(Supply("hello"))
 a_string = await engin.assembler.build(str)
 
 print(a_string)  # hello
-```
+```
+
+## Overriding providers from the same package
+
+Sometimes you need to replace an existing provider for the same type. If both providers
+originate from the same Python package, overrides must be explicit by setting
+`override=True` on the replacement provider. This prevents accidental overrides.
+
+```python
+from engin import Engin, Provide, Supply
+
+
+def make_number() -> int:
+    return 1
+
+
+def make_number_override() -> int:
+    return 2
+
+
+engin = Engin(
+    Provide(make_number),
+    # Explicitly override the previous provider from the same package
+    Provide(make_number_override, override=True),
+)
+
+# this will return 2
+await engin.assembler.build(int)
+```
+
+You can also use `override=True` with `Supply`, and with the `@provide` decorator inside `Block`
+classes: `@provide(override=True)`.
+
+!!!tip
+
+    Overriding providers from a different package is allowed implicitly. Explicit overrides are
+    only required when replacing a provider defined in the same package. Adding or overriding a
+    provider clears previously assembled values so subsequent builds use the new provider.
+
+    Multiproviders (providers that return lists) are not replaced; new ones are always appended.
+
+
+## Provider scopes
+
+Providers can be associated with a named scope. A scoped provider can only be used while that
+scope is active, and its cached value is cleared when the scope exits.
+
+To set a scope, pass `scope="..."` to `Provide`, or use the `@provide(scope=...)` decorator
+when defining providers inside a `Block`.
+
+```python
+from engin import Engin, Provide
+import time
+
+
+def make_timestamp() -> int:
+    return time.time_ns()
+
+
+# Register a provider that is only valid in the "request" scope
+engin = Engin(Provide(make_timestamp, scope="request"))
+
+# Outside the scope this will raise an error
+# await engin.assembler.build(int)  # NotInScopeError
+
+# Within the scope the value can be built and is cached for the duration
+with engin.assembler.scope("request"):
+    t1 = await engin.assembler.build(int)
+    t2 = await engin.assembler.build(int)
+    assert t1 == t2  # cached within the active scope
+
+# After leaving the scope, the scoped cache is cleared
+# await engin.assembler.build(int)  # NotInScopeError
+```
+
+Scopes compose via a stack. Nested scopes can be entered with additional
+`with engin.assembler.scope("..."):` contexts. When a scope exits, any values produced by
+providers in that scope are removed from the cache, while values produced by
+unscoped providers remain cached.
+
+!!!note
+
+    In web applications built with `ASGIEngin`, each request is automatically wrapped in
+    `with engin.assembler.scope("request"):`. Marking providers with `scope="request"` yields
+    per-request values that are reused within the same request and discarded at the end of the
+    request.

{engin-0.1.0rc2 → engin-0.2.0a1}/docs/concepts/supervisor.md

@@ -62,3 +62,15 @@ supervisor.supervise(
     on_exception=OnException.IGNORE
 )
 ```
+
+## Task Shutdown Hook
+
+When the Engin is shutdown (e.g. when receiving a SIGTERM) the Supervisor will cancel all
+supervised tasks using the underlying async backend cancellation mechanism, for
+example by raising a `CancellationError` for `asyncio` projects. This is OK for the
+majority of cases, however some supervised tasks might manage their own shutdown procedure
+and do not handle cancellation well. For these cases the `Supervisor` exposes a
+`shutdown_hook` which will be called just before the task is cancelled.
+
+To set a `shutdown_hook` simply pass in the relevant parameter when calling
+`Supervisor.supervise`.

{engin-0.1.0rc2 → engin-0.2.0a1}/docs/index.md

@@ -10,7 +10,7 @@ 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.
+- Zero boilerplate code reuse across applications.
 - Integrations for other frameworks such as FastAPI.
 - Full async support.
 - CLI commands to aid local development.

{engin-0.1.0rc2 → engin-0.2.0a1}/docs/integrations/fastapi.md

@@ -1,6 +1,6 @@
 # FastAPI
 
-Engin ships with a FastAPI integration that is available under the `engin.ext.fastapi`
+Engin ships with a FastAPI integration that is available under the `engin.extensions.fastapi`
 module. The integration allows one to write idiomatic FastAPI code whilst leveraging Engin
 for Dependency Injection and modularising the application.
 
@@ -37,7 +37,7 @@ instance that you provided.
 !!!tip
 
     It is also easy to integrate Engin with an existing FastAPI application by using the
-    `engin_to_lifespan` function in the `engin.ext.asgi` module.
+    `engin_to_lifespan` function in the `engin.extensions.asgi` module.
 
 
 ## Dependency Injection
@@ -85,7 +85,7 @@ async def database_session(
         session.commit() 
 
 @app.post("/{id}")
-async def add_item(session: Annotated[Session, Inject(database_session)]):
+async def add_item(session: Annotated[Session, Depends(database_session)]):
     session.add(MyORMModel(...))
 ```
 

engin-0.2.0a1/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.

engin-0.2.0a1/docs/tutorial/2_create_a_publisher.md

@@ -0,0 +1,101 @@
+Let's write our Publisher class next. To simulate some sort of real work we can sleep
+and publish a number in a loop, mimicking a sensor reader for example.
+
+```python title="publisher.py"
+import asyncio
+import logging
+import random
+
+from valkey.asyncio import Valkey
+
+
+class Publisher:
+    def __init__(self, valkey: Valkey) -> None:
+        self._valkey = valkey
+
+    async def run(self) -> None:
+        while True:
+            number = random.randint(-100, 100)
+            logging.info(f"Publishing: {number}")
+            await self._valkey.xadd("numbers", {"number": str(number)})
+            await asyncio.sleep(1)
+
+```
+
+!!! note
+    The Publisher asking for the Valkey instance when being initialised is a form of
+    [Dependency Injection](https://en.wikipedia.org/wiki/Dependency_injection), specifically
+    Constructor injection. Doing this separates out the concerns of configuring the client and
+    using it.
+
+
+Let's register the `Publisher` with our application so we can use it later. We do this by:
+
+1. Creating a factory function which is responsible for creating the `Publisher` instance.
+2. Registering this factory function with our `Engin` instance as a "provider".
+
+We can write a simple factory function below the `Publisher` class. Notice that the factory
+function also asks for the `Valkey` client to be injected. We will provide the `Valkey`
+dependency later and Engin will automatically take care of giving it to the
+`publisher_factory`.
+
+```python
+def publisher_factory(valkey: Valkey) -> Publisher:
+    return Publisher(valkey=valkey)
+```
+
+We need to tell the application how to run the `Publisher` as well. We want Engin to call
+`Publisher.run` when the application is run which we can do by using the `Supervisor`
+dependency. The `Supervisor` is a dependency that is provided by Engin and it can be used to
+supervise long running tasks.
+
+```python
+def publisher_factory(valkey: Valkey, supervisor: Supervisor) -> Publisher:
+    publisher = Publisher(valkey=valkey)
+
+    # run the publisher as a supervised application task
+    supervisor.supervise(publisher.run)
+
+    return publisher
+```
+
+!!! tip
+    
+    Supervised tasks can handle exceptions in different ways, controlled by the `OnException`
+    enum. By default if the supervised task errors then it will cause the engin to shutdown,
+    but you can also choose for the error to be ignored or the task to be restarted.
+
+Now we just need to register our `publisher_factory` with the engin. We can do this using the
+`Provide` marker class which allows us to "provide" a dependency to our application.
+
+```python title="app.py"
+# ... existing code ...
+from engin import Provide
+from examples.tutorial.publisher import publisher_factory
+
+
+engin = Engin(Provide(publisher_factory))
+```
+
+Our `Publisher` requires a `Valkey` client, so let's create a factory for that too, we can
+hardcode the url to make this simple for now.
+
+
+```python title="valkey_client.py"
+from valkey.asyncio import Valkey
+
+def valkey_client_factory() -> Valkey:
+    return Valkey.from_url("valkey://localhost:6379")
+```
+
+And let's provide this dependency to the application as well.
+
+```python title="app.py"
+# ... existing code ...
+from engin import Provide
+from examples.tutorial.publisher import publisher_factory
+from examples.tutorial.valkey_client import valkey_client_factory
+
+
+engin = Engin(Provide(publisher_factory), Provide(valkey_client_factory))
+```

engin-0.2.0a1/docs/tutorial/3_run_the_application.md

@@ -0,0 +1,61 @@
+Let's try to run our application.
+
+```
+INFO:engin:starting engin
+INFO:engin:startup complete
+```
+
+And then stop it.
+
+```
+INFO:engin:stopping engin
+INFO:engin:shutdown complete
+```
+
+Where are the publisher logs? Well we haven't actually told our application to actually *do*
+anything yet. We have registered providers, but nothing is using them. Engin will only assemble
+dependencies that are required by an `Invocation` or `Entrypoint`.
+
+To fix this, we can mark the `Publisher` as an `Entrypoint`. This tells our application that
+the `Publisher` should always be assembled, which will cause the `Publisher.run` method to be
+registered as a supervised task.
+
+```python title="app.py"
+# ... existing code ...
+from examples.tutorial.publisher import Publisher, publisher_factory
+from engin import Entrypoint
+
+engin = Engin(
+    Provide(publisher_factory),
+    Provide(valkey_client_factory),
+    Entrypoint(Publisher),
+)
+```
+
+Now if you run the application, you will see the publisher running and logging messages.
+
+```
+INFO:engin:starting engin
+INFO:engin:startup complete
+INFO:engin:supervising task: Publisher.run
+INFO:root:Publishing: -55
+INFO:root:Publishing: 15
+```
+
+However, when we stop the application we see a weird exception to do with the `Valkey` client.
+
+```
+INFO:engin:stopping engin
+INFO:engin:shutdown complete
+Exception ignored in: <function AbstractConnection.__del__ at 0x0000021E6273B880>
+Traceback (most recent call last):
+  File "C:\dev\python\engin\.venv\Lib\site-packages\valkey\asyncio\connection.py", line 243, in __del__
+  File "C:\dev\python\engin\.venv\Lib\site-packages\valkey\asyncio\connection.py", line 250, in _close
+  File "C:\Users\tutorial\AppData\Roaming\uv\python\cpython-3.13.0-windows-x86_64-none\Lib\asyncio\streams.py", line 352, in close
+  File "C:\Users\tutorial\AppData\Roaming\uv\python\cpython-3.13.0-windows-x86_64-none\Lib\asyncio\proactor_events.py", line 109, in close
+  File "C:\Users\tutorial\AppData\Roaming\uv\python\cpython-3.13.0-windows-x86_64-none\Lib\asyncio\base_events.py", line 829, in call_soon
+  File "C:\Users\tutorial\AppData\Roaming\uv\python\cpython-3.13.0-windows-x86_64-none\Lib\asyncio\base_events.py", line 552, in _check_closed
+RuntimeError: Event loop is closed
+```
+
+Let's take another look at the `Valkey` client factory.