queue-func 0.1.2__tar.gz → 0.2.1__tar.gz

queue_func-0.2.1/PKG-INFO

@@ -0,0 +1,255 @@
+Metadata-Version: 2.4
+Name: queue-func
+Version: 0.2.1
+Summary: Async coroutine functions as queue-backed tasks (QueueFunc).
+License: Apache-2.0
+License-File: LICENSE
+Author: liuseki
+Author-email: liuseki@163.com
+Requires-Python: >=3.12,<4.0
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Provides-Extra: rabbit
+Requires-Dist: aio-pika (>=9.6,<10.0) ; extra == "rabbit"
+Requires-Dist: orjson
+Requires-Dist: pydantic (>=2.14.1,<3.0.0)
+Project-URL: Changelog, https://github.com/sekil9529/queue-func/blob/master/Changelog.rst
+Project-URL: Documentation, https://github.com/sekil9529/queue-func#readme
+Project-URL: Homepage, https://github.com/sekil9529/queue-func
+Project-URL: Issues, https://github.com/sekil9529/queue-func/issues
+Project-URL: Repository, https://github.com/sekil9529/queue-func
+Description-Content-Type: text/markdown
+
+# queue-func
+
+把 **`async def` 协程** 变成可 **`push`** 的队列任务：在 asyncio 里投递、消费，并按通道控制并发与背压。
+
+仓库：[github.com/sekil9529/queue-func](https://github.com/sekil9529/queue-func)。版本记录见 [Changelog.rst](Changelog.rst)。
+
+> **需要 Python 3.12 及以上。** 任务入口必须是协程函数，普通函数不能作为任务。
+>
+> RabbitMQ 后端需要另装可选依赖，底层使用 [aio-pika](https://github.com/mosquito/aio-pika) `^9.6`。
+
+## 特点
+
+- 完全在 asyncio 里运行。消费者在同一事件循环里按上限并发执行任务，可以和 FastAPI / Starlette 放在一个进程里。
+- 一条链路是序列化、投递、反序列化、执行。启停由通道或 `QueueFuncRuntime` 显式管理。
+- 每个 `QueueFunc` 有自己的队列和消费并发上限。`QueueFuncRuntime` 可以同时跑多段流水线，各段互不影响。
+- 序列化器的 `pack` / `unpack` 决定队列里的数据结构。
+- 通过 `register_backend` 接入新的队列后端。
+
+## 当前后端
+
+| 后端 | 说明 |
+|------|------|
+| `Backend.QUEUE` | 进程内 `asyncio.Queue` |
+| `Backend.RABBIT_AIO_PIKA` | RabbitMQ，安装可选依赖 `rabbit` |
+
+内存队列的消息留在进程里，序列化默认是 `raw`（队列中仍是 `(args, kwargs)`）。RabbitMQ 默认用 orjson，队列中是 `bytes`。
+
+## 安装
+
+```shell
+pip install queue-func
+```
+
+使用 RabbitMQ：
+
+```shell
+pip install "queue-func[rabbit]"
+```
+
+从仓库安装（开发）：
+
+```shell
+git clone https://github.com/sekil9529/queue-func.git
+cd queue-func
+poetry install -E rabbit
+```
+
+## 用法
+
+### 进程内队列
+
+```python
+import asyncio
+
+from queue_func.factory import Backend, queue
+
+
+@queue(Backend.QUEUE, consume_timeout=0.5, maxsize=1000)
+async def process_order(order_id: int) -> None:
+    print(order_id)
+
+
+async def main() -> None:
+    await process_order.broker.start_consumer()
+    await process_order.push(args=(42,))
+    await process_order.broker.stop_consumer()
+    await process_order.broker.join_consumer()
+
+
+asyncio.run(main())
+```
+
+`push` 就是 `broker.publish`。不传 `timeout` 时用配置里的 `publish_timeout`；传入数字只作用于这一次。`None` 表示不限时。超时抛出 `queue_func.PublishTimeoutError`。
+
+装饰之后仍可直接调用，不经过队列：
+
+```python
+await process_order(1)
+```
+
+### 多段流水线
+
+`QueueFuncRuntime.start()` 按列表反序启动消费者，下游先就绪。`stop()` 先逐个停止消费者，再停止全部生产者。
+
+```python
+import asyncio
+
+from queue_func.factory import Backend, QueueFuncRuntime, queue
+
+
+@queue(Backend.QUEUE, consumer_pool_maxsize=4)
+async def task_b(job: str) -> None:
+    print(job)
+
+
+@queue(Backend.QUEUE, consumer_pool_maxsize=2)
+async def task_a(job: str) -> None:
+    await task_b.push(args=(job,))
+
+
+async def main() -> None:
+    runtime = QueueFuncRuntime([task_a, task_b])
+    await runtime.start()
+    await task_a.push(args=("job-1",))
+    await runtime.stop()
+
+
+asyncio.run(main())
+```
+
+三段链式示例（含日志）：
+
+```shell
+poetry run python examples/demo_queue.py
+```
+
+### RabbitMQ
+
+`url` 和 `queue_name` 必填。`enable_declare_queue=True` 时，队列不存在会创建。默认交换机名是 `""`，路由键默认用队列名。`push` 会等待发布确认；`publish_timeout` 是这次确认的超时。
+
+消息交给消费池之后就确认。处理函数出错不会把消息退回队列。`stop` 会设上停止标志，当前这次拉取结束（空闲时最多再等一个 `consume_timeout`）后退出；还没取走的消息留在 RabbitMQ 上。
+
+同一个 `QueueFunc` 的生产者和消费者可以分进程运行。只投递的进程把 `enable_consumer` 设为 `False`。
+
+```python
+import asyncio
+
+from queue_func.factory import Backend, queue
+
+
+@queue(
+    Backend.RABBIT_AIO_PIKA,
+    url="amqp://guest:guest@127.0.0.1/",
+    queue_name="process_order",
+    enable_declare_queue=True,
+)
+async def process_order(order_id: int) -> None:
+    print(order_id)
+
+
+async def main() -> None:
+    await process_order.broker.start_consumer()
+    await process_order.push(args=(42,))
+    await process_order.broker.stop_consumer()
+    await process_order.broker.join_consumer()
+    await process_order.broker.stop_producer()
+    await process_order.broker.join_producer()
+
+
+asyncio.run(main())
+```
+
+本地 RabbitMQ（`127.0.0.1:5672`，`guest` / `guest`）上的链式示例：
+
+```shell
+poetry run python examples/demo_rabbit_aio_pika.py
+```
+
+常用参数：
+
+| 参数 | 作用 |
+|------|------|
+| `consumer_pool_maxsize` | 同时执行的协程数，默认 200 |
+| `consume_timeout` | 一次拉取的等待时间，默认 2 秒 |
+| `publish_timeout` | 投递等待上限，默认不限 |
+| `maxsize` | 仅内存队列，`asyncio.Queue` 容量，默认 200 |
+| `serializer_cls` | 队列中的数据结构 |
+| `prefetch_count` | 仅 RabbitMQ，未确认消息窗口 |
+| `delivery_mode` | 仅 RabbitMQ，默认持久化 |
+| `exchange_name` / `routing_key` | 仅 RabbitMQ |
+
+其余字段见 `queue_func.config.queue.Config` 和 `queue_func.config.rabbit_aio_pika.Config`。
+
+## 架构
+
+一个 `@queue` 装饰的协程就是一条队列。`push` 投到它自己这条队列上。
+
+- **Broker** 组装生产者、消费者和双方共用的资源，并提供启停与投递。
+- **Producer** 序列化后把数据写入队列。
+- **Consumer** 取出数据，反序列化后交给消费池。
+- **PoolExecutor** 按并发上限执行业务协程。
+
+```mermaid
+flowchart TB
+  PUSH["投递"] --> B["通道"]
+  B --> PRO["生产者"]
+  B -.->|启停| CON["消费者"]
+
+  PRO -->|序列化| Q[("队列")]
+  Q -->|反序列化| CON
+  CON --> POOL["消费池"]
+  POOL --> FN["业务协程"]
+```
+
+## 项目结构
+
+```
+queue_func/
+├── broker/
+├── producer/
+├── consumer/
+├── serializer/       # raw、orjson
+├── shared_resource/
+├── config/
+├── factory/          # @queue、QueueFunc、QueueFuncRuntime
+├── pool_executor/
+└── utils/
+examples/
+├── demo_queue.py
+└── demo_rabbit_aio_pika.py
+```
+
+## 开发与测试
+
+```shell
+poetry install -E rabbit
+pytest
+```
+
+`pytest.ini` 会生成覆盖率页面（`htmlcov/`）和 `report.html`。
+
+## 版本
+
+遵循[语义化版本](https://semver.org/lang/zh-CN/)。变更记录在 [Changelog.rst](Changelog.rst)。
+
+## 许可证
+
+Apache-2.0
+

queue_func-0.2.1/README.md

@@ -0,0 +1,228 @@
+# queue-func
+
+把 **`async def` 协程** 变成可 **`push`** 的队列任务：在 asyncio 里投递、消费，并按通道控制并发与背压。
+
+仓库：[github.com/sekil9529/queue-func](https://github.com/sekil9529/queue-func)。版本记录见 [Changelog.rst](Changelog.rst)。
+
+> **需要 Python 3.12 及以上。** 任务入口必须是协程函数，普通函数不能作为任务。
+>
+> RabbitMQ 后端需要另装可选依赖，底层使用 [aio-pika](https://github.com/mosquito/aio-pika) `^9.6`。
+
+## 特点
+
+- 完全在 asyncio 里运行。消费者在同一事件循环里按上限并发执行任务，可以和 FastAPI / Starlette 放在一个进程里。
+- 一条链路是序列化、投递、反序列化、执行。启停由通道或 `QueueFuncRuntime` 显式管理。
+- 每个 `QueueFunc` 有自己的队列和消费并发上限。`QueueFuncRuntime` 可以同时跑多段流水线，各段互不影响。
+- 序列化器的 `pack` / `unpack` 决定队列里的数据结构。
+- 通过 `register_backend` 接入新的队列后端。
+
+## 当前后端
+
+| 后端 | 说明 |
+|------|------|
+| `Backend.QUEUE` | 进程内 `asyncio.Queue` |
+| `Backend.RABBIT_AIO_PIKA` | RabbitMQ，安装可选依赖 `rabbit` |
+
+内存队列的消息留在进程里，序列化默认是 `raw`（队列中仍是 `(args, kwargs)`）。RabbitMQ 默认用 orjson，队列中是 `bytes`。
+
+## 安装
+
+```shell
+pip install queue-func
+```
+
+使用 RabbitMQ：
+
+```shell
+pip install "queue-func[rabbit]"
+```
+
+从仓库安装（开发）：
+
+```shell
+git clone https://github.com/sekil9529/queue-func.git
+cd queue-func
+poetry install -E rabbit
+```
+
+## 用法
+
+### 进程内队列
+
+```python
+import asyncio
+
+from queue_func.factory import Backend, queue
+
+
+@queue(Backend.QUEUE, consume_timeout=0.5, maxsize=1000)
+async def process_order(order_id: int) -> None:
+    print(order_id)
+
+
+async def main() -> None:
+    await process_order.broker.start_consumer()
+    await process_order.push(args=(42,))
+    await process_order.broker.stop_consumer()
+    await process_order.broker.join_consumer()
+
+
+asyncio.run(main())
+```
+
+`push` 就是 `broker.publish`。不传 `timeout` 时用配置里的 `publish_timeout`；传入数字只作用于这一次。`None` 表示不限时。超时抛出 `queue_func.PublishTimeoutError`。
+
+装饰之后仍可直接调用，不经过队列：
+
+```python
+await process_order(1)
+```
+
+### 多段流水线
+
+`QueueFuncRuntime.start()` 按列表反序启动消费者，下游先就绪。`stop()` 先逐个停止消费者，再停止全部生产者。
+
+```python
+import asyncio
+
+from queue_func.factory import Backend, QueueFuncRuntime, queue
+
+
+@queue(Backend.QUEUE, consumer_pool_maxsize=4)
+async def task_b(job: str) -> None:
+    print(job)
+
+
+@queue(Backend.QUEUE, consumer_pool_maxsize=2)
+async def task_a(job: str) -> None:
+    await task_b.push(args=(job,))
+
+
+async def main() -> None:
+    runtime = QueueFuncRuntime([task_a, task_b])
+    await runtime.start()
+    await task_a.push(args=("job-1",))
+    await runtime.stop()
+
+
+asyncio.run(main())
+```
+
+三段链式示例（含日志）：
+
+```shell
+poetry run python examples/demo_queue.py
+```
+
+### RabbitMQ
+
+`url` 和 `queue_name` 必填。`enable_declare_queue=True` 时，队列不存在会创建。默认交换机名是 `""`，路由键默认用队列名。`push` 会等待发布确认；`publish_timeout` 是这次确认的超时。
+
+消息交给消费池之后就确认。处理函数出错不会把消息退回队列。`stop` 会设上停止标志，当前这次拉取结束（空闲时最多再等一个 `consume_timeout`）后退出；还没取走的消息留在 RabbitMQ 上。
+
+同一个 `QueueFunc` 的生产者和消费者可以分进程运行。只投递的进程把 `enable_consumer` 设为 `False`。
+
+```python
+import asyncio
+
+from queue_func.factory import Backend, queue
+
+
+@queue(
+    Backend.RABBIT_AIO_PIKA,
+    url="amqp://guest:guest@127.0.0.1/",
+    queue_name="process_order",
+    enable_declare_queue=True,
+)
+async def process_order(order_id: int) -> None:
+    print(order_id)
+
+
+async def main() -> None:
+    await process_order.broker.start_consumer()
+    await process_order.push(args=(42,))
+    await process_order.broker.stop_consumer()
+    await process_order.broker.join_consumer()
+    await process_order.broker.stop_producer()
+    await process_order.broker.join_producer()
+
+
+asyncio.run(main())
+```
+
+本地 RabbitMQ（`127.0.0.1:5672`，`guest` / `guest`）上的链式示例：
+
+```shell
+poetry run python examples/demo_rabbit_aio_pika.py
+```
+
+常用参数：
+
+| 参数 | 作用 |
+|------|------|
+| `consumer_pool_maxsize` | 同时执行的协程数，默认 200 |
+| `consume_timeout` | 一次拉取的等待时间，默认 2 秒 |
+| `publish_timeout` | 投递等待上限，默认不限 |
+| `maxsize` | 仅内存队列，`asyncio.Queue` 容量，默认 200 |
+| `serializer_cls` | 队列中的数据结构 |
+| `prefetch_count` | 仅 RabbitMQ，未确认消息窗口 |
+| `delivery_mode` | 仅 RabbitMQ，默认持久化 |
+| `exchange_name` / `routing_key` | 仅 RabbitMQ |
+
+其余字段见 `queue_func.config.queue.Config` 和 `queue_func.config.rabbit_aio_pika.Config`。
+
+## 架构
+
+一个 `@queue` 装饰的协程就是一条队列。`push` 投到它自己这条队列上。
+
+- **Broker** 组装生产者、消费者和双方共用的资源，并提供启停与投递。
+- **Producer** 序列化后把数据写入队列。
+- **Consumer** 取出数据，反序列化后交给消费池。
+- **PoolExecutor** 按并发上限执行业务协程。
+
+```mermaid
+flowchart TB
+  PUSH["投递"] --> B["通道"]
+  B --> PRO["生产者"]
+  B -.->|启停| CON["消费者"]
+
+  PRO -->|序列化| Q[("队列")]
+  Q -->|反序列化| CON
+  CON --> POOL["消费池"]
+  POOL --> FN["业务协程"]
+```
+
+## 项目结构
+
+```
+queue_func/
+├── broker/
+├── producer/
+├── consumer/
+├── serializer/       # raw、orjson
+├── shared_resource/
+├── config/
+├── factory/          # @queue、QueueFunc、QueueFuncRuntime
+├── pool_executor/
+└── utils/
+examples/
+├── demo_queue.py
+└── demo_rabbit_aio_pika.py
+```
+
+## 开发与测试
+
+```shell
+poetry install -E rabbit
+pytest
+```
+
+`pytest.ini` 会生成覆盖率页面（`htmlcov/`）和 `report.html`。
+
+## 版本
+
+遵循[语义化版本](https://semver.org/lang/zh-CN/)。变更记录在 [Changelog.rst](Changelog.rst)。
+
+## 许可证
+
+Apache-2.0

{queue_func-0.1.2 → queue_func-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "queue-func"
-version = "0.1.2"
+version = "0.2.1"
 description = "Async coroutine functions as queue-backed tasks (QueueFunc)."
 authors = ["liuseki <liuseki@163.com>"]
 license = "Apache-2.0"
@@ -18,6 +18,10 @@ Issues = "https://github.com/sekil9529/queue-func/issues"
 python = "^3.12"
 orjson = "*"
 pydantic = "^2.14.1"
+aio-pika = { version = "^9.6", optional = true }
+
+[tool.poetry.extras]
+rabbit = ["aio-pika"]
 
 [[tool.poetry.source]]
 name = "aliyun"
@@ -28,6 +32,7 @@ priority = "primary"
 pytest = "*"
 pytest-cov = "*"
 pytest-html = "*"
+aio-pika = "^9.6"
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

{queue_func-0.1.2 → queue_func-0.2.1}/queue_func/broker/base.py

@@ -3,7 +3,8 @@
 import abc
 import typing as t
 
-from queue_func.serializer.base import BaseSerializer, Message
+from queue_func.serializer.base import Message
+from queue_func.shared_resource.base import Resource
 
 if t.TYPE_CHECKING:
     from queue_func.config.general import Config
@@ -22,33 +23,12 @@ class BaseBroker(t.Generic[ConfigType, Message], metaclass=abc.ABCMeta):
     """
 
     __slots__ = (
-        "_config",
-        "_serializer",
         "_producer",
         "_consumer",
     )
 
-    def __init__(self, config: ConfigType):
-
-        self._config = config
-        self._serializer: type[BaseSerializer[Message]] = self._config.serializer_cls
-        self._producer = self._create_producer()
-        self._consumer = self._create_consumer()
-
-    @abc.abstractmethod
-    def _create_producer(self) -> "BaseProducer[Message]":
-
-        pass
-
-    @abc.abstractmethod
-    def _create_consumer(self) -> "BaseConsumer[Message]":
-
-        pass
-
-    @property
-    def serializer(self) -> type[BaseSerializer[Message]]:
-
-        return self._serializer
+    _producer: "BaseProducer"
+    _consumer: "BaseConsumer"
 
     async def publish(
             self,

queue_func-0.2.1/queue_func/broker/queue.py

@@ -0,0 +1,34 @@
+# coding: utf-8
+
+import asyncio
+import typing as t
+
+from queue_func.serializer.base import Message
+from queue_func.shared_resource.queue import Resource
+from queue_func.broker.base import BaseBroker as _BaseBroker
+from queue_func.producer.queue import Producer
+from queue_func.consumer.queue import Consumer
+
+if t.TYPE_CHECKING:
+    from queue_func.config.queue import Config
+
+
+class Broker(_BaseBroker["Config", Message]):
+    """内存队列通道。队列由这里创建，再交给 Producer 和 Consumer。"""
+
+    def __init__(self, config: "Config"):
+        resource = Resource(
+            serializer_cls=config.serializer_cls,
+            maxsize=config.maxsize)
+        self._producer = Producer(
+            resource=resource,
+            publish_timeout=config.publish_timeout,
+        )
+        self._consumer = Consumer(
+            resource=resource,
+            coro=config.coro,
+            enable_consumer=config.enable_consumer,
+            consume_timeout=config.consume_timeout,
+            pool_executor_cls=config.consumer_pool_executor_cls,
+            pool_maxsize=config.consumer_pool_maxsize,
+        )

queue_func-0.2.1/queue_func/broker/rabbit_aio_pika.py

@@ -0,0 +1,47 @@
+# coding: utf-8
+
+import typing as t
+
+from queue_func.broker.base import BaseBroker as _BaseBroker
+from queue_func.consumer.rabbit_aio_pika import Consumer
+from queue_func.producer.rabbit_aio_pika import Producer
+from queue_func.shared_resource.rabbit_aio_pika import Resource
+
+if t.TYPE_CHECKING:
+    from queue_func.config.rabbit_aio_pika import Config
+
+
+class Broker(_BaseBroker["Config", bytes]):
+    """RabbitMQ 通道。一条连接上分开发布和消费，再交给 Producer 和 Consumer。"""
+
+    def __init__(self, config: "Config"):
+
+        resource = Resource(
+            serializer_cls=config.serializer_cls,
+            url=config.url,
+            queue_name=config.queue_name,
+            enable_declare_queue=config.enable_declare_queue,
+            queue_durable=config.queue_durable,
+            queue_exclusive=config.queue_exclusive,
+            queue_passive=config.queue_passive,
+            queue_auto_delete=config.queue_auto_delete,
+            queue_arguments=config.queue_arguments,
+        )
+        self._producer = Producer(
+            resource=resource,
+            publish_timeout=config.publish_timeout,
+            exchange_name=config.exchange_name,
+            routing_key=config.routing_key,
+            delivery_mode=config.delivery_mode,
+        )
+        self._consumer = Consumer(
+            resource=resource,
+            prefetch_count=config.prefetch_count,
+            prefetch_size=config.prefetch_size,
+            global_qos=config.global_qos,
+            coro=config.coro,
+            enable_consumer=config.enable_consumer,
+            consume_timeout=config.consume_timeout,
+            pool_executor_cls=config.consumer_pool_executor_cls,
+            pool_maxsize=config.consumer_pool_maxsize,
+        )

{queue_func-0.1.2 → queue_func-0.2.1}/queue_func/config/general.py

@@ -11,18 +11,18 @@ from queue_func.pool_executor.base import BasePoolExecutor
 from queue_func.pool_executor.general import PoolExecutor
 
 
-@pyd_dataclass(frozen=True, config=ExtraIgnoreConfig)
+@pyd_dataclass(frozen=True, kw_only=True, config=ExtraIgnoreConfig)
 class Config:
 
-    # consumer
+    ## shared resource
+    serializer_cls: type[BaseSerializer] = Serializer
+
+    ## consumer
     coro: t.Callable[[...], t.Coroutine]
     enable_consumer: bool = True
     consume_timeout: float = 2.0
     consumer_pool_executor_cls: type[BasePoolExecutor] = PoolExecutor
     consumer_pool_maxsize: int = 200
 
-    # broker
-    serializer_cls: type[BaseSerializer] = Serializer
-
-    # producer
+    ## producer
     publish_timeout: float | None = None

{queue_func-0.1.2 → queue_func-0.2.1}/queue_func/config/queue.py

@@ -12,6 +12,6 @@ from queue_func.serializer.raw import Serializer
 @pyd_dataclass(frozen=True, config=ExtraIgnoreConfig)
 class Config(_Config):
 
-    # broker
+    ## shared resource
     maxsize: int = 200
     serializer_cls: type[BaseSerializer] = Serializer