Refine and validate the example in the README

Author: ryanhiebert

README.md

@@ -18,36 +18,48 @@ pip install queueio
 Create your routines:
 
 ```python
-# sample.py
+# basic.py
+from time import sleep as time_sleep
+
 from queueio import QueueIO
 from queueio import routine
 from queueio.gather import gather
 from queueio.sleep import sleep
-from time import sleep as time_sleep
 
 
 @routine(name="blocking", queue="queueio")
 def blocking():
-    pass
+    time_sleep(0.1)  # Regular blocking call
+
 
 @routine(name="yielding", queue="queueio")
 async def yielding(iterations: int):
-    pass
+    # Do them two at a time
+    for _ in range(iterations // 2):
+        await gather(blocking(), blocking())
+        await sleep(0.2)  # Release processing capacity
+    if iterations % 2 == 1:
+        await blocking()
 
 
 if __name__ == "__main__":
-    QueueIO().submit(yielding())  
+    q = QueueIO()
+    try:
+        q.submit(yielding(7))
+    finally:
+        q.shutdown()
+
 ```
 
 Add the configuration to your `pyproject.toml`:
 
 ```toml
 [tool.queueio]
 # Configure RabbitMQ
-broker = 'pika://guest:guest@localhost:5672/'
-journal = 'pika://guest:guest@localhost:5672/'
+broker = "pika://guest:guest@localhost:5672/"
+journal = "pika://guest:guest@localhost:5672/"
 # Register the modules that the worker should load to find your routines
-register = ["sample"]
+register = ["basic"]
 ```
 
 The broker and journal can be configured with environment variables
@@ -61,7 +73,7 @@ QUEUEIO_JOURNAL='amqp://guest:guest@localhost:5672/'
 Run your script to submit the routine to run on a worker:
 
 ```sh
-python sample.py
+python basic.py
 ```
 
 Then run the worker to process submitted routines:
@@ -83,4 +95,4 @@ This is a new project.
 The design of the public API is under active development and subject to change.
 Release notes will provide clear upgrade instructions,
 but backward compatibility and deprecation warnings
-will not generally be implemented.
+will not generally be implemented.

pyproject.toml

@@ -30,8 +30,12 @@ select = ["E", "F", "UP", "B", "SIM", "I"]
 
 [tool.ruff.lint.isort]
 force-single-line = true
+
 [tool.queueio]
-register = ["queueio.sample"]
+register = [
+    "queueio.samples.basic",
+    "queueio.samples.expanded",
+]
 broker = "pika://localhost:5672"
 journal = "pika://localhost:5672"
 

queueio/queueio_test.py

@@ -192,7 +192,7 @@ def test_queueio_with_valid_config(tmp_path):
         version = "0.1.0"
 
         [tool.queueio]
-        register = ["queueio.sample"]
+        register = ["queueio.samples.expanded"]
         broker = "pika://localhost:5672"
         journal = "pika://localhost:5672"
         """

queueio/samples/__init__.py

@@ -0,0 +1,31 @@
+# This file should exactly mirror the example in README.md
+
+from time import sleep as time_sleep
+
+from queueio import QueueIO
+from queueio import routine
+from queueio.gather import gather
+from queueio.sleep import sleep
+
+
+@routine(name="blocking", queue="queueio")
+def blocking():
+    time_sleep(0.1)  # Regular blocking call
+
+
+@routine(name="yielding", queue="queueio")
+async def yielding(iterations: int):
+    # Do them two at a time
+    for _ in range(iterations // 2):
+        await gather(blocking(), blocking())
+        await sleep(0.2)  # Release processing capacity
+    if iterations % 2 == 1:
+        await blocking()
+
+
+if __name__ == "__main__":
+    q = QueueIO()
+    try:
+        q.submit(yielding(7))
+    finally:
+        q.shutdown()

queueio/samples/basic.py

@@ -0,0 +1,41 @@
+import subprocess
+import sys
+
+import pytest
+
+from queueio import QueueIO
+from queueio.invocation import InvocationCompleted
+
+from .basic import yielding
+
+
+@pytest.mark.timeout(10)
+def test_integration():
+    queueio = QueueIO()
+
+    try:
+        queueio.purge(queue="queueio")
+        events = queueio.subscribe({InvocationCompleted})
+        invocation = yielding(7)
+        queueio.submit(invocation)
+
+        proc = subprocess.Popen(
+            [sys.executable, "-m", "queueio", "worker", "queueio=1"],
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+        )
+        try:
+            while event := events.get():
+                if event.id == invocation.id:
+                    break
+        finally:
+            if proc.poll() is None:
+                proc.terminate()
+                try:
+                    proc.wait(timeout=5)
+                except subprocess.TimeoutExpired:
+                    proc.kill()
+                    proc.wait()
+
+    finally:
+        queueio.shutdown()

queueio/samples/basic_test.py

@@ -1,10 +1,10 @@
 from contextlib import suppress
 from time import sleep as time_sleep
 
+from queueio import QueueIO
 from queueio import routine
-
-from .gather import gather
-from .sleep import sleep
+from queueio.gather import gather
+from queueio.sleep import sleep
 
 
 @routine(name="regular", queue="queueio")
@@ -44,3 +44,11 @@ async def irregular():
     print("queueio sleep ended")
     await gather(regular(7, 2), sleep(0.5), abstract(8, 1))
     return await abstract(2, 5)
+
+
+if __name__ == "__main__":
+    q = QueueIO()
+    try:
+        q.submit(irregular())
+    finally:
+        q.shutdown()

queueio/sample.py queueio/samples/expanded.pyqueueio/sample.py renamed to queueio/samples/expanded.py

@@ -5,7 +5,8 @@
 
 from queueio import QueueIO
 from queueio.invocation import InvocationCompleted
-from queueio.sample import irregular
+
+from .expanded import irregular
 
 
 @pytest.mark.timeout(10)