engin 0.1.0rc2__tar.gz → 0.1.0rc3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: engin
-Version: 0.1.0rc2
+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/

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.

engin-0.1.0rc3/docs/tutorial/2_create_a_publisher.md

@@ -0,0 +1,91 @@
+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 engin. We can do this by making a simple factory function
+below the `Publisher`.
+
+```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.
+
+```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 the engin.
+
+```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.
+
+```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 factory to the engin.
+
+```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.1.0rc3/docs/tutorial/3_run_the_application.md

@@ -0,0 +1,26 @@
+Let's try to run our application.
+
+```bash
+$ python examples/tutorial/main.py
+INFO:engin:starting engin
+INFO:engin:startup complete
+INFO:engin:stopping engin
+INFO:engin:shutdown complete
+```
+
+You'll notice that the application starts and then immediately shuts down. This is because we haven't told `engin` to actually *do* anything. We have registered providers, but nothing is using them. The `engin` will only assemble dependencies that are required by an `Invocation` or `Entrypoint`.
+
+To fix this, we'll register the `Publisher` as an `Entrypoint`. This tells the `engin` that the `Publisher` is a core component of our application and should be started.
+
+```python
+# examples/tutorial/main.py
+# ...
+from engin import Entrypoint
+
+engin = Engin(
+    Provide(valkey_client_factory),
+    Entrypoint(Publisher),
+)
+```
+
+Now if you run the application, you will see the publisher running and logging messages.

engin-0.1.0rc3/docs/tutorial/4_create_the_consumer.md

@@ -0,0 +1,37 @@
+
+Next, we'll create a `Consumer` to process the messages from our `Publisher`. This class will read from the `numbers` stream, parse the number from the message, and keep a running total. Just like the `Publisher`, we'll supervise the `run` method to execute it as a background task.
+
+```python
+# examples/tutorial/main.py
+# ...
+
+class Consumer:
+    def __init__(self, valkey: Valkey, supervisor: Supervisor):
+        self._valkey = valkey
+        self._total = 0
+        supervisor.supervise(self.run)
+
+    async def run(self) -> None:
+        logging.info("Consumer starting")
+        await self._valkey.xgroup_create("numbers", "total", mkstream=True)
+        while True:
+            messages = await self._valkey.xreadgroup("total", "consumer", {"numbers": ">"})
+            for _, message in messages:
+                number = int(message[b"number"])
+                self._total += number
+                logging.info(f"Consumed: {number}, Total: {self._total}")
+
+```
+
+Now, we'll also register the `Consumer` as an `Entrypoint`. Since `engin` is an asynchronous framework, it can manage multiple entrypoints concurrently. Both the `Publisher` and `Consumer` will run in the same event loop.
+
+```python
+# examples/tutorial/main.py
+# ...
+
+engin = Engin(
+    Provide(valkey_client_factory),
+    Entrypoint(Publisher),
+    Entrypoint(Consumer),
+)
+```

engin-0.1.0rc3/docs/tutorial/5_refactor_valkey_client.md

@@ -0,0 +1,52 @@
+We'll use `pydantic-settings` to manage our configuration. Let's define a `ValkeyConfig` class.
+
+```python
+# examples/tutorial/_valkey.py
+from pydantic_settings import BaseSettings
+from valkey import Valkey
+
+
+class ValkeyConfig(BaseSettings):
+    valkey_url: str = "..."
+
+
+def valkey_client_factory() -> Valkey:
+    config = ValkeyConfig()
+    return Valkey.from_url(config.valkey_url)
+```
+
+Our application is growing, and the `engin` definition is getting more complex. To keep our code organized, we can group related dependencies into a `Block`. A `Block` is a reusable component that can provide dependencies to the `engin`.
+
+Let's create a `ValkeyBlock` to house our Valkey-related components.
+
+```python
+# examples/tutorial/main.py
+# ...
+from engin import Block, provide
+
+class ValkeyBlock(Block):
+    @provide
+    def valkey_config_factory(self) -> ValkeyConfig:
+        return ValkeyConfig()
+
+    @provide
+    def valkey_client_factory(self, config: ValkeyConfig) -> Valkey:
+        return Valkey.from_url(config.valkey_url)
+```
+
+We've moved the `ValkeyConfig` and `valkey_client_factory` into the `ValkeyBlock` and decorated them with `@provide`. This tells the `engin` that these methods are providers.
+
+Now, we can update our `engin` to use the `ValkeyBlock`.
+
+```python
+# examples/tutorial/main.py
+# ...
+
+engin = Engin(
+    ValkeyBlock(),
+    Entrypoint(Publisher),
+    Entrypoint(Consumer),
+)
+```
+
+Our `engin` is now much cleaner and easier to read. The `ValkeyBlock` encapsulates the details of creating the Valkey client, making our application more modular and maintainable.

engin-0.1.0rc3/docs/tutorial/index.md

@@ -0,0 +1,10 @@
+# Tutorial
+
+In this tutorial we will build a small toy application from scratch.
+
+Our application will publish random numbers to a Valkey stream, and then consume them and
+update a running total. 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/examples/tutorial/app.py

@@ -0,0 +1,21 @@
+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(),
+    Provide(publisher_factory),
+    Provide(consumer_factory),
+    Entrypoint(Publisher),
+    Entrypoint(Consumer),
+)
+
+
+if __name__ == "__main__":
+    asyncio.run(engin.run())

engin-0.1.0rc3/examples/tutorial/consumer.py

@@ -0,0 +1,36 @@
+import logging
+
+from valkey import ResponseError
+from valkey.asyncio import Valkey
+
+from engin import Supervisor
+
+
+class Consumer:
+    def __init__(self, valkey: Valkey) -> None:
+        self._valkey = valkey
+        self._total = 0
+
+    async def run(self) -> None:
+        logging.info("Consumer starting")
+        try:
+            await self._valkey.xgroup_create("numbers", "total", mkstream=True)
+        except ResponseError:
+            pass  # group already exists
+
+        while True:
+            messages = await self._valkey.xreadgroup("total", "consumer", {"numbers": ">"})
+            for _, stream_messages in messages:
+                for _, message in stream_messages:
+                    number = int(message[b"number"])
+                    self._total += number
+                    logging.info(f"Consumed: {number}, Total: {self._total}")
+
+
+def consumer_factory(valkey: Valkey, supervisor: Supervisor) -> Consumer:
+    consumer = Consumer(valkey=valkey)
+
+    # run the consumer as a supervised application task
+    supervisor.supervise(consumer.run)
+
+    return consumer

engin-0.1.0rc3/examples/tutorial/publisher.py

@@ -0,0 +1,28 @@
+import asyncio
+import logging
+import random
+
+from valkey.asyncio import Valkey
+
+from engin import Supervisor
+
+
+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)
+
+
+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

engin-0.1.0rc3/examples/tutorial/valkey_client.py

@@ -0,0 +1,23 @@
+from pydantic_settings import BaseSettings
+from valkey.asyncio import Valkey
+
+from engin import Block, Lifecycle, provide
+
+
+class ValkeyConfig(BaseSettings):
+    valkey_url: str = "valkey://localhost:6379"
+
+
+class ValkeyBlock(Block):
+    @provide
+    def config(self) -> ValkeyConfig:
+        return ValkeyConfig()
+
+    @provide
+    def client(self, config: ValkeyConfig, lifecycle: Lifecycle) -> Valkey:
+        client: Valkey = Valkey.from_url(config.valkey_url)
+
+        # close the client when the app is shutting down
+        lifecycle.hook(on_stop=client.aclose)
+
+        return client

{engin-0.1.0rc2 → engin-0.1.0rc3}/mkdocs.yaml

@@ -6,8 +6,9 @@ theme:
     name: 'material'
     custom_dir: 'docs/overrides'
     features:
-      - navigation.instant
       - content.code.copy
+      - navigation.instant
+      - navigation.indexes
     palette:
       - scheme: 'default'
         media: '(prefers-color-scheme: light)'
@@ -27,6 +28,13 @@ edit_uri: ""
 
 nav:
   - Home: "index.md"
+  - Tutorial:
+      - "tutorial/index.md"
+      - "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"
   - Concepts:
       - Engin: "concepts/engin.md"
       - Providers: "concepts/providers.md"

{engin-0.1.0rc2 → engin-0.1.0rc3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "engin"
-version = "0.1.0rc2"
+version = "0.1.0rc3"
 description = "An async-first modular application framework"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -43,6 +43,7 @@ dev = [
     "pytest-mock>=3.14.0",
     "pytest-benchmark>=5.1.0",
     "websockets>=15.0.1",
+    "valkey>=6.1.0",
 ]
 docs = [
     "mkdocs-material>=9.5.50",
@@ -78,7 +79,7 @@ ignore = [
 "**/src/*" = ["PT"]
 "**/tests/*" = ["S", "ANN"]
 # allow print statements in examples/scripts
-"**/examples/*" = ["T201"]
+"**/examples/*" = ["T201", "LOG015", "S", "SIM105"]
 "**/scripts/*" = ["T201"]
 
 

{engin-0.1.0rc2 → engin-0.1.0rc3}/src/engin/_cli/_check.py

@@ -50,13 +50,6 @@ def check_dependencies(
         for missing_type in sorted_missing:
             console.print(f"  • {missing_type}", style="red")
 
-        available_providers = sorted(
-            str(provider.return_type_id) for provider in assembler.providers
-        )
-        console.print("\nAvailable providers:", style="yellow")
-        for available_type in available_providers:
-            console.print(f"  • {available_type}", style="yellow")
-
         raise typer.Exit(code=1)
     else:
         console.print("✅ All dependencies are satisfied!", style="green bold")

{engin-0.1.0rc2 → engin-0.1.0rc3}/src/engin/_cli/_graph.html

@@ -400,7 +400,7 @@
         }
 
         if (node.style_classes && node.style_classes.length > 0) {
-            styleClasses = `:::${node.style_classes.join(' ')}`;
+            styleClasses = `:::${node.style_classes.join(',')}`;
         }
 
         return shape + styleClasses;

{engin-0.1.0rc2 → engin-0.1.0rc3}/src/engin/_engin.py

@@ -179,7 +179,9 @@ class Engin:
             try:
                 async with supervisor:
                     await self._stop_requested_event.wait()
-                    await self._shutdown()
+
+                # shutdown after stopping supervised tasks
+                await self._shutdown()
             except BaseException:
                 await self._shutdown()
 
@@ -262,6 +264,7 @@ async def _stop_engin_on_signal(stop_requested_event: Event) -> None:
 
         # windows does not support signal_handlers, so this is the workaround
         def ctrlc_handler(sig: int, frame: FrameType | None) -> None:
+            LOG.debug(f"received {signal.SIGINT.name} signal")
             nonlocal should_stop
             if should_stop:
                 raise KeyboardInterrupt("Forced keyboard interrupt")

{engin-0.1.0rc2 → engin-0.1.0rc3}/src/engin/_supervisor.py

@@ -63,7 +63,6 @@ class _SupervisorTask:
                 raise
             except Exception as err:
                 self.last_exception = err
-
                 if self.on_exception == OnException.IGNORE:
                     LOG.warning(
                         f"supervisor task '{self.name}' raised {type(err).__name__} "
@@ -122,6 +121,7 @@ class Supervisor:
         self._task_group = await anyio.create_task_group().__aenter__()
 
         for task in self._tasks:
+            LOG.info(f"supervising task: {task.name}")
             self._task_group.start_soon(task, name=task.name)
 
     async def __aexit__(

{engin-0.1.0rc2 → engin-0.1.0rc3}/tests/cli/test_check.py

@@ -46,7 +46,6 @@ def test_check_missing_dependencies():
     assert result.exit_code == 1
     assert "❌ Missing providers found:" in result.output
     assert "int" in result.output
-    assert "Available providers:" in result.output
 
 
 def test_check_complex_missing_dependencies():