Prepare the package for publication

* Add a changelog
* Remove the dubious behavior to allow coroutines in gather
* Export gather and pause from the queueio module
* Add the publish workflow

Author: ryanhiebert

.github/workflows/publish.yml

@@ -0,0 +1,17 @@
+name: Publish to PyPI
+on:
+  release:
+    types:
+      - published
+
+jobs:
+  publish:
+    permissions:
+      id-token: write
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

CHANGELOG.md

@@ -0,0 +1,32 @@
+Changelog
+=========
+
+All notable changes to this project will be documented in this file.
+
+The format is loosely based on [Keep a Changelog](https://keepachangelog.com).
+
+[0.2.0] - 2025-11-22
+--------------------
+
+### Acknowledgement
+
+Thank you to Nick Anderegg for allowing me to use the queueio name for this project.
+
+### Added
+
+- `routine` decorator to declare sync or async functions as background routines.
+- `activate` context manager to activate the queueio system.
+- `pause` to coordinate a pause of a routine to queueio.
+- `gather` to run multiple routines concurrently and gather the results.
+- `Routine.submit()` method to submit a routine invocation to the queue.
+- Configuration in the `tool.queueio` section of `pyproject.toml`.
+  - `pika` configures the pika library to connect to the AMQP broker.
+  - `register` configures the modules that declare routines.
+- `QUEUEIO_PIKA` environment variable
+  to override the `pika` configuration in `pyproject.toml`.
+- `queueio sync` command to synchronize queues to the broker.
+- `queueio run` command to run the queueio worker.
+- The queuespec syntax to `queue run` to consume multiple queues with shared capacity.
+- `queueio monitor` command to monitor activity in the queueio system.
+
+[0.2.0]: https://github.com/ryanhiebert/queueio/releases/tag/0.2

README.md

@@ -21,9 +21,9 @@ Create your routines:
 # basic.py
 from time import sleep
 
+from queueio import gather
+from queueio import pause
 from queueio import routine
-from queueio.gather import gather
-from queueio.pause import pause
 
 
 @routine(name="blocking", queue="queueio")
@@ -77,7 +77,7 @@ with activate():
 Then run the worker to process submitted routines:
 
 ```sh
-queueio run queueio=3
+queueio run queueio=4
 ```
 
 Monitor the status of active routine invocations:
@@ -89,8 +89,8 @@ queueio monitor
 Stability
 ---------
 
-This is a new project.
-The design of the public API is under active development and will change.
-Release notes will provide clear upgrade instructions,
+The design of the public API is under active development
+and is likely to change with any release.
+Release notes will provide upgrade instructions,
 but backward compatibility and deprecation warnings
 will not generally be implemented.

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "queueio"
-version = "0.2"
+version = "0.2.0"
 description = "Python background queues with an async twist"
 readme = "README.md"
 license = "MIT"

queueio/__init__.py

@@ -1,5 +1,7 @@
 from contextlib import contextmanager
 
+from .gather import gather as gather
+from .pause import pause as pause
 from .queueio import QueueIO as RealQueueIO
 from .registry import routine as routine
 

queueio/gather.py

@@ -1,23 +1,19 @@
-from collections.abc import Awaitable
 from collections.abc import Iterable
 from concurrent.futures import Future
 from typing import Any
 from typing import overload
 
-from .suspend import suspend
 from .suspension import Suspension
 
 
 class Gather[T](Suspension[T]):
-    def __init__(self, awaitables: Iterable[Awaitable[Any]]):
+    def __init__(self, suspensions: Iterable[Suspension[Any]]):
         super().__init__()
-        self.__awaitables = awaitables
+        self.__suspensions = suspensions
 
     def submit(self) -> Future[T]:
         gathered = Future()
-        futures = [
-            suspension.submit() for suspension in map(suspend, self.__awaitables)
-        ]
+        futures = [suspension.submit() for suspension in self.__suspensions]
 
         # concurrent.futures.Future doesn't give us a way to be notified
         # when a future is running, so we can't reasonably determine when
@@ -56,26 +52,26 @@ def on_done(future):
         return gathered
 
 
-A = Awaitable
+S = Suspension
 
 
 @overload
-def gather[T1](a: A[T1], /) -> Gather[tuple[T1]]: ...
+def gather[T1](s: S[T1], /) -> Gather[tuple[T1]]: ...
 @overload
-def gather[T1, T2](a1: A[T1], a2: A[T2], /) -> Gather[tuple[T1, T2]]: ...
+def gather[T1, T2](s1: S[T1], s2: S[T2], /) -> Gather[tuple[T1, T2]]: ...
 @overload
 def gather[T1, T2, T3](
-    a1: A[T1], a2: A[T2], a3: A[T3], /
+    s1: S[T1], s2: S[T2], s3: S[T3], /
 ) -> Gather[tuple[T1, T2, T3]]: ...
 @overload
 def gather[T1, T2, T3, T4](
-    a1: A[T1], a2: A[T2], a3: A[T3], a4: A[T4], /
+    s1: S[T1], s2: S[T2], s3: S[T3], s4: S[T4], /
 ) -> Gather[tuple[T1, T2, T3, T4]]: ...
 @overload
 def gather[T1, T2, T3, T4, T5](
-    a1: A[T1], a2: A[T2], a3: A[T3], a4: A[T4], a5: A[T5], /
+    s1: S[T1], s2: S[T2], s3: S[T3], s4: S[T4], s5: S[T5], /
 ) -> Gather[tuple[T1, T2, T3, T4, T5]]: ...
 
 
-def gather(*awaitables: Awaitable[Any]) -> Gather[Any]:
-    return Gather(awaitables)
+def gather(*suspensions: Suspension[Any]) -> Gather[Any]:
+    return Gather(suspensions)

queueio/samples/basic.py

@@ -2,9 +2,9 @@
 
 from time import sleep
 
+from queueio import gather
+from queueio import pause
 from queueio import routine
-from queueio.gather import gather
-from queueio.pause import pause
 
 
 @routine(name="blocking", queue="queueio")

queueio/samples/expanded.py

@@ -41,5 +41,5 @@ async def irregular():
     print("irregular sleep ended. Starting queueio pause.")
     await pause(0.4)
     print("queueio pause ended")
-    await gather(regular(7, 2), pause(0.5), abstract(8, 1))
+    await gather(regular(7, 2), pause(0.5))
     return await abstract(2, 5)