engin 0.1.0rc3__tar.gz → 0.2.0a1__tar.gz

{engin-0.1.0rc3 → 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.0rc3 → engin-0.2.0a1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: engin
-Version: 0.1.0rc3
+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.0rc3 → 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.0rc3 → 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.0rc3 → 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.0rc3 → 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.0rc3 → 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.0rc3 → 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.0rc3 → 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.0rc3 → 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.0rc3 → 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.0rc3 → 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.1.0rc3 → engin-0.2.0a1}/docs/tutorial/2_create_a_publisher.md

@@ -24,22 +24,30 @@ class Publisher:
 
 !!! 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
+    [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 engin. We can do this by making a simple factory function
-below the `Publisher`.
+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)
 ```
 
-This isn't enough though as we need to tell the engin how to run the publisher as well. We want
-our engin to call `Publisher.run` when the application is run, we can do that by using the
-`Supervisor` type which is always provided by Engin.
+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:
@@ -58,7 +66,7 @@ def publisher_factory(valkey: Valkey, supervisor: Supervisor) -> Publisher:
     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 the engin.
+`Provide` marker class which allows us to "provide" a dependency to our application.
 
 ```python title="app.py"
 # ... existing code ...
@@ -69,7 +77,9 @@ 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.
+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
@@ -78,7 +88,7 @@ def valkey_client_factory() -> Valkey:
     return Valkey.from_url("valkey://localhost:6379")
 ```
 
-And let's provide this factory to the engin.
+And let's provide this dependency to the application as well.
 
 ```python title="app.py"
 # ... existing code ...
@@ -88,4 +98,4 @@ 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.

engin-0.2.0a1/docs/tutorial/4_refactor_valkey_client.md

@@ -0,0 +1,100 @@
+In the last section we saw an exception when shutting down our application.
+
+```
+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
+```
+
+Analysing this we can infer that the `Valkey` client is trying to close itself as its been
+garbage collected, but the application is already shutdown so its too late.
+
+If we look at the `valkey-py` docs we see this line.
+
+> Using asyncio Valkey requires an explicit disconnect of the connection since there is no
+> asyncio deconstructor magic method.
+
+So we want to call `aclose()` on the `Valkey` client when the application is shutting down.
+Luckily this type of concern is quite common and Engin provides another built-in dependency to
+help manage this, the `Lifecycle`.
+
+Let's update our `valkey_client_factory` to handle this lifecycle concern.
+
+```python title="valkey_client.py"
+from engin import Lifecycle
+from valkey.asyncio import Valkey
+
+def valkey_client_factory(lifecycle: Lifecycle) -> Valkey:
+    client = Valkey.from_url("valkey://localhost:6379")
+
+    # close the client when the app is shutting down
+    lifecycle.hook(on_stop=client.aclose)
+
+    return client
+```
+
+Now when we run the application we will not see any errors.
+
+While we are here we can continue to improve the factory by making the connection url
+configurable. We can use `pydantic-settings` for this by defining a `ValkeyConfig` class and
+creating a factory for it.
+
+```python title="valkey_client.py"
+from engin import Lifecycle
+from pydantic_settings import BaseSettings
+from valkey.asyncio import Valkey
+
+class ValkeyConfig(BaseSettings):
+    valkey_url: str = "..."
+
+def valkey_config() -> ValkeyConfig:
+    return ValkeyConfig()
+
+def valkey_client_factory(config: ValkeyConfig, lifecycle: Lifecycle) -> Valkey:
+    client = Valkey.from_url(config.valkey_url)
+    lifecycle.hook(on_stop=client.aclose)
+    return client
+```
+
+To keep our code organized, we can group related dependencies into a "block". We can then
+register the block with our application instead, this makes sure that all Valkey related
+dependencies are always registered.
+
+We can create a block by inheriting from the `Block` type. Factory functions become
+methods in the block marked with decorator equivalents of the marker types we saw before to,
+e.g. `Provide` & `Invoke` become `@provide` & `@invoke`.
+
+```python title="valkey_client.py"
+from engin import Block, provide
+
+class ValkeyBlock(Block):
+    @provide
+    def config_factory(self) -> ValkeyConfig:
+        return ValkeyConfig()
+
+    @provide
+    def client_factory(config: ValkeyConfig, lifecycle: Lifecycle) -> Valkey:
+        client = Valkey.from_url(config.valkey_url)
+        lifecycle.hook(on_stop=client.aclose)
+        return client
+```
+
+Now, we can update our `engin` to use the `ValkeyBlock`.
+
+```python title="app.py"
+# ... existing code ...
+
+engin = Engin(
+    ValkeyBlock,
+    Provide(publisher_factory),
+    Entrypoint(Publisher),
+)
+```

engin-0.2.0a1/docs/tutorial/index.md

@@ -0,0 +1,8 @@
+# Tutorial
+
+In this tutorial we will build a small toy application that publishes random numbers to a
+Valkey stream. This will be enough to cover most of the features of Engin.
+
+The final code can be found as
+[an example](https://github.com/invokermain/engin/tree/main/examples/tutorial) in the Github
+repo.

{engin-0.1.0rc3 → engin-0.2.0a1}/examples/tutorial/app.py

@@ -2,18 +2,15 @@ import asyncio
 import logging
 
 from engin import Engin, Entrypoint, Provide
-from examples.tutorial.consumer import Consumer, consumer_factory
 from examples.tutorial.publisher import Publisher, publisher_factory
 from examples.tutorial.valkey_client import ValkeyBlock
 
 logging.basicConfig(level=logging.INFO)
 
 engin = Engin(
-    ValkeyBlock(),
+    ValkeyBlock,
     Provide(publisher_factory),
-    Provide(consumer_factory),
     Entrypoint(Publisher),
-    Entrypoint(Consumer),
 )
 
 

{engin-0.1.0rc3 → engin-0.2.0a1}/mkdocs.yaml

@@ -7,6 +7,8 @@ theme:
     custom_dir: 'docs/overrides'
     features:
       - content.code.copy
+      - navigation.expand
+      - navigation.footer
       - navigation.instant
       - navigation.indexes
     palette:
@@ -33,8 +35,7 @@ nav:
       - "Setup an Empty Application": "tutorial/1_empty_application.md"
       - "Create the Publisher": "tutorial/2_create_a_publisher.md"
       - "Run the Application": "tutorial/3_run_the_application.md"
-      - "Create the Consumer": "tutorial/4_create_the_consumer.md"
-      - "Refactor the Valkey client": "tutorial/5_refactor_valkey_client.md"
+      - "Refactor the Valkey client": "tutorial/4_refactor_valkey_client.md"
   - Concepts:
       - Engin: "concepts/engin.md"
       - Providers: "concepts/providers.md"