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

{queue_func-0.2.1 → queue_func-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: queue-func
-Version: 0.2.1
+Version: 0.2.3
 Summary: Async coroutine functions as queue-backed tasks (QueueFunc).
 License: Apache-2.0
 License-File: LICENSE
@@ -17,7 +17,7 @@ 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: Changelog, https://github.com/sekil9529/queue-func/blob/master/CHANGELOG.md
 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
@@ -26,30 +26,36 @@ Description-Content-Type: text/markdown
 
 # queue-func
 
-把 **`async def` 协程** 变成可 **`push`** 的队列任务：在 asyncio 里投递、消费，并按通道控制并发与背压。
+[![Coverage Status](https://coveralls.io/repos/github/sekil9529/queue-func/badge.svg?branch=master)](https://coveralls.io/github/sekil9529/queue-func)
+[![tests](https://github.com/sekil9529/queue-func/actions/workflows/tests.yml/badge.svg)](https://github.com/sekil9529/queue-func/actions?query=workflow%3Atests)
+[![Latest Version](https://img.shields.io/pypi/v/queue-func.svg)](https://pypi.org/project/queue-func/)
+[![Wheel](https://img.shields.io/pypi/wheel/queue-func.svg)](https://pypi.org/project/queue-func/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/queue-func.svg)](https://pypi.org/project/queue-func/)
+[![License](https://img.shields.io/pypi/l/queue-func.svg)](https://pypi.org/project/queue-func/)
 
-仓库：[github.com/sekil9529/queue-func](https://github.com/sekil9529/queue-func)。版本记录见 [Changelog.rst](Changelog.rst)。
+把一个 `async def` 收成队列任务：`push` 投递，消费者在同一个事件循环里执行。
 
-> **需要 Python 3.12 及以上。** 任务入口必须是协程函数，普通函数不能作为任务。
+仓库示例在 [examples/](examples/)。版本记录见 [CHANGELOG.md](CHANGELOG.md)。
+
+> 需要 Python 3.12 及以上。任务必须是协程函数。
 >
-> RabbitMQ 后端需要另装可选依赖，底层使用 [aio-pika](https://github.com/mosquito/aio-pika) `^9.6`。
+> RabbitMQ 后端是可选依赖，底层用 [aio-pika](https://github.com/mosquito/aio-pika) `^9.6`。
 
 ## 特点
 
-- 完全在 asyncio 里运行。消费者在同一事件循环里按上限并发执行任务，可以和 FastAPI / Starlette 放在一个进程里。
-- 一条链路是序列化、投递、反序列化、执行。启停由通道或 `QueueFuncRuntime` 显式管理。
-- 每个 `QueueFunc` 有自己的队列和消费并发上限。`QueueFuncRuntime` 可以同时跑多段流水线，各段互不影响。
-- 序列化器的 `pack` / `unpack` 决定队列里的数据结构。
-- 通过 `register_backend` 接入新的队列后端。
+- 进程内 `asyncio.Queue` 和 RabbitMQ 两种后端，装饰器都是 `@queue`。
+- 每个任务有自己的队列、序列化和消费并发上限。
+- `QueueFuncRuntime` 把多段任务按下游先启动、上游后停止的顺序一起管。
+- `start` 会等到消费者开始收消息再返回。
+- 装饰之后仍可以直接 `await` 调用，不经过队列。
 
-## 当前后端
+## 启动和停止
 
-| 后端 | 说明 |
-|------|------|
-| `Backend.QUEUE` | 进程内 `asyncio.Queue` |
-| `Backend.RABBIT_AIO_PIKA` | RabbitMQ，安装可选依赖 `rabbit` |
+`broker.start_consumer()` 创建消费任务，并等到它开始收消息。内存队列是已经堵在 `get()` 上；RabbitMQ 是队列已经订阅上。
+
+`stop` 先标上停止，再等手头这次收消息结束。空闲时最多再等一个 `consume_timeout`。还没取走的 RabbitMQ 消息留在代理上。
 
-内存队列的消息留在进程里，序列化默认是 `raw`（队列中仍是 `(args, kwargs)`）。RabbitMQ 默认用 orjson，队列中是 `bytes`。
+RabbitMQ 在消息交给消费池之后确认。处理函数出错不会把消息退回队列。`push` 会等发布确认，超时抛出 `queue_func.PublishTimeoutError`。
 
 ## 安装
 
@@ -63,7 +69,7 @@ pip install queue-func
 pip install "queue-func[rabbit]"
 ```
 
-从仓库安装（开发）：
+从仓库安装：
 
 ```shell
 git clone https://github.com/sekil9529/queue-func.git
@@ -73,6 +79,8 @@ poetry install -E rabbit
 
 ## 用法
 
+从 `queue_func.factory` 引入 `queue`、`Backend`、`QueueFuncRuntime`。
+
 ### 进程内队列
 
 ```python
@@ -96,9 +104,9 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
-`push` 就是 `broker.publish`。不传 `timeout` 时用配置里的 `publish_timeout`；传入数字只作用于这一次。`None` 表示不限时。超时抛出 `queue_func.PublishTimeoutError`。
+`push` 就是 `broker.publish`。不传 `timeout` 时用配置里的 `publish_timeout`；传入数字只对这一次有效。`None` 表示不限时。
 
-装饰之后仍可直接调用，不经过队列：
+直接调用：
 
 ```python
 await process_order(1)
@@ -106,7 +114,7 @@ await process_order(1)
 
 ### 多段流水线
 
-`QueueFuncRuntime.start()` 按列表反序启动消费者，下游先就绪。`stop()` 先逐个停止消费者，再停止全部生产者。
+`QueueFuncRuntime.start()` 按列表反序启动，下游先就绪。`stop()` 先逐个停消费者，再停全部生产者。
 
 ```python
 import asyncio
@@ -134,7 +142,7 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
-三段链式示例（含日志）：
+三段链式示例：
 
 ```shell
 poetry run python examples/demo_queue.py
@@ -142,11 +150,9 @@ poetry run python examples/demo_queue.py
 
 ### RabbitMQ
 
-`url` 和 `queue_name` 必填。`enable_declare_queue=True` 时，队列不存在会创建。默认交换机名是 `""`，路由键默认用队列名。`push` 会等待发布确认；`publish_timeout` 是这次确认的超时。
-
-消息交给消费池之后就确认。处理函数出错不会把消息退回队列。`stop` 会设上停止标志，当前这次拉取结束（空闲时最多再等一个 `consume_timeout`）后退出；还没取走的消息留在 RabbitMQ 上。
+`url` 和 `queue_name` 必填。`enable_declare_queue=True` 时，队列不存在会创建。默认交换机名是 `""`，路由键默认用队列名。已经存在的队列再声明时，持久化等参数必须和代理上的一致。
 
-同一个 `QueueFunc` 的生产者和消费者可以分进程运行。只投递的进程把 `enable_consumer` 设为 `False`。
+只投递、不消费的进程把 `enable_consumer` 设为 `False`。
 
 ```python
 import asyncio
@@ -159,6 +165,7 @@ from queue_func.factory import Backend, queue
     url="amqp://guest:guest@127.0.0.1/",
     queue_name="process_order",
     enable_declare_queue=True,
+    consume_timeout=0.5,
 )
 async def process_order(order_id: int) -> None:
     print(order_id)
@@ -187,19 +194,20 @@ poetry run python examples/demo_rabbit_aio_pika.py
 | 参数 | 作用 |
 |------|------|
 | `consumer_pool_maxsize` | 同时执行的协程数，默认 200 |
-| `consume_timeout` | 一次拉取的等待时间，默认 2 秒 |
+| `consume_timeout` | 一次等消息的时间，默认 2 秒 |
 | `publish_timeout` | 投递等待上限，默认不限 |
 | `maxsize` | 仅内存队列，`asyncio.Queue` 容量，默认 200 |
-| `serializer_cls` | 队列中的数据结构 |
+| `serializer_cls` | 队列中的数据结构。内存队列默认 `raw`，RabbitMQ 默认 orjson |
 | `prefetch_count` | 仅 RabbitMQ，未确认消息窗口 |
 | `delivery_mode` | 仅 RabbitMQ，默认持久化 |
 | `exchange_name` / `routing_key` | 仅 RabbitMQ |
+| `queue_durable` | 仅 RabbitMQ，声明队列时是否持久化，默认否 |
 
-其余字段见 `queue_func.config.queue.Config` 和 `queue_func.config.rabbit_aio_pika.Config`。
+其余字段见 `queue_func.backends.queue.config.Config` 和 `queue_func.backends.rabbit_aio_pika.config.Config`。
 
-## 架构
+## 一条任务里有什么
 
-一个 `@queue` 装饰的协程就是一条队列。`push` 投到它自己这条队列上。
+`@queue` 装饰的协程就是一条队列。`push` 投到它自己这条队列上。
 
 - **Broker** 组装生产者、消费者和双方共用的资源，并提供启停与投递。
 - **Producer** 序列化后把数据写入队列。
@@ -218,36 +226,20 @@ flowchart TB
   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
+poetry run pytest
 ```
 
-`pytest.ini` 会生成覆盖率页面（`htmlcov/`）和 `report.html`。
+单元测试使用假的 RabbitMQ 连接，不要求本机有代理。`examples/demo_rabbit_aio_pika.py` 需要本机 `guest` / `guest`、端口 `5672`。
+
+`pytest.ini` 会写出覆盖率页面 `htmlcov/` 和 `report.html`。
 
 ## 版本
 
-遵循[语义化版本](https://semver.org/lang/zh-CN/)。变更记录在 [Changelog.rst](Changelog.rst)。
+遵循[语义化版本](https://semver.org/lang/zh-CN/)。变更记录在 [CHANGELOG.md](CHANGELOG.md)。
 
 ## 许可证
 

queue_func-0.2.3/README.md

@@ -0,0 +1,220 @@
+# queue-func
+
+[![Coverage Status](https://coveralls.io/repos/github/sekil9529/queue-func/badge.svg?branch=master)](https://coveralls.io/github/sekil9529/queue-func)
+[![tests](https://github.com/sekil9529/queue-func/actions/workflows/tests.yml/badge.svg)](https://github.com/sekil9529/queue-func/actions?query=workflow%3Atests)
+[![Latest Version](https://img.shields.io/pypi/v/queue-func.svg)](https://pypi.org/project/queue-func/)
+[![Wheel](https://img.shields.io/pypi/wheel/queue-func.svg)](https://pypi.org/project/queue-func/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/queue-func.svg)](https://pypi.org/project/queue-func/)
+[![License](https://img.shields.io/pypi/l/queue-func.svg)](https://pypi.org/project/queue-func/)
+
+把一个 `async def` 收成队列任务：`push` 投递，消费者在同一个事件循环里执行。
+
+仓库示例在 [examples/](examples/)。版本记录见 [CHANGELOG.md](CHANGELOG.md)。
+
+> 需要 Python 3.12 及以上。任务必须是协程函数。
+>
+> RabbitMQ 后端是可选依赖，底层用 [aio-pika](https://github.com/mosquito/aio-pika) `^9.6`。
+
+## 特点
+
+- 进程内 `asyncio.Queue` 和 RabbitMQ 两种后端，装饰器都是 `@queue`。
+- 每个任务有自己的队列、序列化和消费并发上限。
+- `QueueFuncRuntime` 把多段任务按下游先启动、上游后停止的顺序一起管。
+- `start` 会等到消费者开始收消息再返回。
+- 装饰之后仍可以直接 `await` 调用，不经过队列。
+
+## 启动和停止
+
+`broker.start_consumer()` 创建消费任务，并等到它开始收消息。内存队列是已经堵在 `get()` 上；RabbitMQ 是队列已经订阅上。
+
+`stop` 先标上停止，再等手头这次收消息结束。空闲时最多再等一个 `consume_timeout`。还没取走的 RabbitMQ 消息留在代理上。
+
+RabbitMQ 在消息交给消费池之后确认。处理函数出错不会把消息退回队列。`push` 会等发布确认，超时抛出 `queue_func.PublishTimeoutError`。
+
+## 安装
+
+```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
+```
+
+## 用法
+
+从 `queue_func.factory` 引入 `queue`、`Backend`、`QueueFuncRuntime`。
+
+### 进程内队列
+
+```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` 表示不限时。
+
+直接调用：
+
+```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` 时，队列不存在会创建。默认交换机名是 `""`，路由键默认用队列名。已经存在的队列再声明时，持久化等参数必须和代理上的一致。
+
+只投递、不消费的进程把 `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,
+    consume_timeout=0.5,
+)
+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` | 队列中的数据结构。内存队列默认 `raw`，RabbitMQ 默认 orjson |
+| `prefetch_count` | 仅 RabbitMQ，未确认消息窗口 |
+| `delivery_mode` | 仅 RabbitMQ，默认持久化 |
+| `exchange_name` / `routing_key` | 仅 RabbitMQ |
+| `queue_durable` | 仅 RabbitMQ，声明队列时是否持久化，默认否 |
+
+其余字段见 `queue_func.backends.queue.config.Config` 和 `queue_func.backends.rabbit_aio_pika.config.Config`。
+
+## 一条任务里有什么
+
+`@queue` 装饰的协程就是一条队列。`push` 投到它自己这条队列上。
+
+- **Broker** 组装生产者、消费者和双方共用的资源，并提供启停与投递。
+- **Producer** 序列化后把数据写入队列。
+- **Consumer** 取出数据，反序列化后交给消费池。
+- **PoolExecutor** 按并发上限执行业务协程。
+
+```mermaid
+flowchart TB
+  PUSH["投递"] --> B["通道"]
+  B --> PRO["生产者"]
+  B -.->|启停| CON["消费者"]
+
+  PRO -->|序列化| Q[("队列")]
+  Q -->|反序列化| CON
+  CON --> POOL["消费池"]
+  POOL --> FN["业务协程"]
+```
+
+## 测试
+
+```shell
+poetry install -E rabbit
+poetry run pytest
+```
+
+单元测试使用假的 RabbitMQ 连接，不要求本机有代理。`examples/demo_rabbit_aio_pika.py` 需要本机 `guest` / `guest`、端口 `5672`。
+
+`pytest.ini` 会写出覆盖率页面 `htmlcov/` 和 `report.html`。
+
+## 版本
+
+遵循[语义化版本](https://semver.org/lang/zh-CN/)。变更记录在 [CHANGELOG.md](CHANGELOG.md)。
+
+## 许可证
+
+Apache-2.0

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

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "queue-func"
-version = "0.2.1"
+version = "0.2.3"
 description = "Async coroutine functions as queue-backed tasks (QueueFunc)."
 authors = ["liuseki <liuseki@163.com>"]
 license = "Apache-2.0"
@@ -11,7 +11,7 @@ documentation = "https://github.com/sekil9529/queue-func#readme"
 packages = [{ include = "queue_func" }]
 
 [tool.poetry.urls]
-Changelog = "https://github.com/sekil9529/queue-func/blob/master/Changelog.rst"
+Changelog = "https://github.com/sekil9529/queue-func/blob/master/CHANGELOG.md"
 Issues = "https://github.com/sekil9529/queue-func/issues"
 
 [tool.poetry.dependencies]

queue_func-0.2.1/queue_func/broker/queue.py → queue_func-0.2.3/queue_func/backends/queue/broker.py

@@ -4,13 +4,13 @@ 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
+from queue_func.backends.queue.resource import Resource
+from queue_func.core.broker import BaseBroker as _BaseBroker
+from queue_func.backends.queue.producer import Producer
+from queue_func.backends.queue.consumer import Consumer
 
 if t.TYPE_CHECKING:
-    from queue_func.config.queue import Config
+    from queue_func.backends.queue.config import Config
 
 
 class Broker(_BaseBroker["Config", Message]):

queue_func-0.2.1/queue_func/factory/builders/queue.py → queue_func-0.2.3/queue_func/backends/queue/build.py

@@ -6,7 +6,7 @@ from queue_func.factory.backend import Backend
 from queue_func.factory.registry import register_backend
 
 if t.TYPE_CHECKING:
-    from queue_func.broker.base import BaseBroker
+    from queue_func.core.broker import BaseBroker
 
 
 @register_backend(Backend.QUEUE)
@@ -14,7 +14,7 @@ def build_queue_broker(
         coro: t.Callable[..., t.Coroutine],
         **kwargs: t.Any) -> "BaseBroker[t.Any, t.Any]":
 
-    from queue_func.broker.queue import Broker
-    from queue_func.config.queue import Config
+    from queue_func.backends.queue.broker import Broker
+    from queue_func.backends.queue.config import Config
 
     return Broker(Config(coro=coro, **kwargs))

queue_func-0.2.1/queue_func/config/queue.py → queue_func-0.2.3/queue_func/backends/queue/config.py

@@ -3,8 +3,8 @@
 import typing as t
 from pydantic.dataclasses import dataclass as pyd_dataclass
 
-from queue_func.config.utils import ExtraIgnoreConfig
-from queue_func.config.general import Config as _Config
+from queue_func.core.config import Config as _Config
+from queue_func.core.config import ExtraIgnoreConfig
 from queue_func.serializer.base import BaseSerializer
 from queue_func.serializer.raw import Serializer
 

queue_func-0.2.1/queue_func/consumer/queue.py → queue_func-0.2.3/queue_func/backends/queue/consumer.py

@@ -4,9 +4,9 @@ import asyncio
 import typing as t
 
 from queue_func.serializer.base import Message
-from queue_func.shared_resource.queue import Resource
+from queue_func.backends.queue.resource import Resource
 from queue_func.pool_executor.base import BasePoolExecutor
-from queue_func.consumer.base import BaseConsumer as _BaseConsumer
+from queue_func.core.consumer import BaseConsumer as _BaseConsumer
 
 
 class Consumer(_BaseConsumer[Message, Resource]):
@@ -14,6 +14,7 @@ class Consumer(_BaseConsumer[Message, Resource]):
     async def _consume(self) -> None:
 
         while (not self._stopped) or (not self._resource.queue.empty()):
+            self._mark_running()
             try:
                 message: Message = await asyncio.wait_for(
                     self._resource.queue.get(),

queue_func-0.2.1/queue_func/producer/queue.py → queue_func-0.2.3/queue_func/backends/queue/producer.py

@@ -4,8 +4,8 @@ import asyncio
 
 from queue_func.errors import PublishTimeoutError
 from queue_func.serializer.base import Message
-from queue_func.producer.base import BaseProducer
-from queue_func.shared_resource.queue import Resource
+from queue_func.core.producer import BaseProducer
+from queue_func.backends.queue.resource import Resource
 
 
 class Producer(BaseProducer[Message, Resource]):

queue_func-0.2.1/queue_func/shared_resource/queue.py → queue_func-0.2.3/queue_func/backends/queue/resource.py

@@ -3,7 +3,7 @@
 import asyncio
 
 from queue_func.serializer.base import Message, BaseSerializer
-from queue_func.shared_resource.base import BaseResource as _Base
+from queue_func.core.resource import BaseResource as _Base
 
 
 class Resource(_Base[Message]):

queue_func-0.2.1/queue_func/broker/rabbit_aio_pika.py → queue_func-0.2.3/queue_func/backends/rabbit_aio_pika/broker.py

@@ -2,13 +2,13 @@
 
 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
+from queue_func.core.broker import BaseBroker as _BaseBroker
+from queue_func.backends.rabbit_aio_pika.consumer import Consumer
+from queue_func.backends.rabbit_aio_pika.producer import Producer
+from queue_func.backends.rabbit_aio_pika.resource import Resource
 
 if t.TYPE_CHECKING:
-    from queue_func.config.rabbit_aio_pika import Config
+    from queue_func.backends.rabbit_aio_pika.config import Config
 
 
 class Broker(_BaseBroker["Config", bytes]):

queue_func-0.2.1/queue_func/factory/builders/rabbit_aio_pika.py → queue_func-0.2.3/queue_func/backends/rabbit_aio_pika/build.py

@@ -6,7 +6,7 @@ from queue_func.factory.backend import Backend
 from queue_func.factory.registry import register_backend
 
 if t.TYPE_CHECKING:
-    from queue_func.broker.base import BaseBroker
+    from queue_func.core.broker import BaseBroker
 
 
 @register_backend(Backend.RABBIT_AIO_PIKA)
@@ -15,8 +15,8 @@ def build_rabbit_aio_pika_broker(
         **kwargs: t.Any) -> "BaseBroker[t.Any, t.Any]":
 
     try:
-        from queue_func.broker.rabbit_aio_pika import Broker
-        from queue_func.config.rabbit_aio_pika import Config
+        from queue_func.backends.rabbit_aio_pika.broker import Broker
+        from queue_func.backends.rabbit_aio_pika.config import Config
     except ImportError as exc:
         raise ImportError(
             "Backend.RABBIT_AIO_PIKA requires aio-pika. "

queue_func-0.2.1/queue_func/config/rabbit_aio_pika.py → queue_func-0.2.3/queue_func/backends/rabbit_aio_pika/config.py

@@ -4,8 +4,8 @@ from enum import unique, StrEnum, IntEnum
 
 from pydantic.dataclasses import dataclass as pyd_dataclass
 
-from queue_func.config.utils import ExtraIgnoreConfig
-from queue_func.config.general import Config as _Config
+from queue_func.core.config import Config as _Config
+from queue_func.core.config import ExtraIgnoreConfig
 
 
 @unique

queue_func-0.2.1/queue_func/consumer/rabbit_aio_pika.py → queue_func-0.2.3/queue_func/backends/rabbit_aio_pika/consumer.py

@@ -3,9 +3,9 @@
 import asyncio
 import typing as t
 
-from queue_func.consumer.base import BaseConsumer as _BaseConsumer
+from queue_func.core.consumer import BaseConsumer as _BaseConsumer
 from queue_func.pool_executor.base import BasePoolExecutor
-from queue_func.shared_resource.rabbit_aio_pika import Resource
+from queue_func.backends.rabbit_aio_pika.resource import Resource
 
 if t.TYPE_CHECKING:
     from aio_pika.abc import AbstractIncomingMessage, AbstractQueue
@@ -55,6 +55,7 @@ class Consumer(_BaseConsumer[bytes, Resource]):
         await self._ensure_queue()
         while not self._stopped:
             async with self._queue.iterator(timeout=self._consume_timeout) as queue_iter:
+                self._mark_running()
                 try:
                     message: "AbstractIncomingMessage"
                     async for message in queue_iter:

queue_func-0.2.1/queue_func/producer/rabbit_aio_pika.py → queue_func-0.2.3/queue_func/backends/rabbit_aio_pika/producer.py

@@ -5,10 +5,10 @@ import typing as t
 
 import aio_pika
 
-from queue_func.config.rabbit_aio_pika import DeliveryMode, ExchangeName
+from queue_func.backends.rabbit_aio_pika.config import DeliveryMode, ExchangeName
 from queue_func.errors import PublishTimeoutError
-from queue_func.producer.base import BaseProducer
-from queue_func.shared_resource.rabbit_aio_pika import Resource
+from queue_func.core.producer import BaseProducer
+from queue_func.backends.rabbit_aio_pika.resource import Resource
 
 if t.TYPE_CHECKING:
     from aio_pika.abc import AbstractChannel, AbstractExchange

queue_func-0.2.1/queue_func/shared_resource/rabbit_aio_pika.py → queue_func-0.2.3/queue_func/backends/rabbit_aio_pika/resource.py

@@ -6,7 +6,7 @@ import typing as t
 import aio_pika
 
 from queue_func.utils.deco import before
-from queue_func.shared_resource.base import BaseResource as _Base
+from queue_func.core.resource import BaseResource as _Base
 from queue_func.serializer.base import Message, BaseSerializer
 
 if t.TYPE_CHECKING:

queue_func-0.2.1/queue_func/broker/base.py → queue_func-0.2.3/queue_func/core/broker.py

@@ -4,12 +4,12 @@ import abc
 import typing as t
 
 from queue_func.serializer.base import Message
-from queue_func.shared_resource.base import Resource
+from queue_func.core.resource import Resource
 
 if t.TYPE_CHECKING:
-    from queue_func.config.general import Config
-    from queue_func.producer.base import BaseProducer
-    from queue_func.consumer.base import BaseConsumer
+    from queue_func.core.config import Config
+    from queue_func.core.producer import BaseProducer
+    from queue_func.core.consumer import BaseConsumer
 
 
 ConfigType = t.TypeVar("ConfigType", bound="Config")

queue_func-0.2.1/queue_func/config/general.py → queue_func-0.2.3/queue_func/core/config.py

@@ -2,15 +2,23 @@
 
 import typing as t
 
+from pydantic.config import ConfigDict
 from pydantic.dataclasses import dataclass as pyd_dataclass
 
-from queue_func.config.utils import ExtraIgnoreConfig
 from queue_func.serializer.base import BaseSerializer
 from queue_func.serializer.orjson_ser import Serializer
 from queue_func.pool_executor.base import BasePoolExecutor
 from queue_func.pool_executor.general import PoolExecutor
 
 
+ExtraIgnoreConfig = ConfigDict(
+    extra="ignore",
+    validate_assignment=True,
+    arbitrary_types_allowed=True,
+    coerce_numbers_to_str=True,
+)
+
+
 @pyd_dataclass(frozen=True, kw_only=True, config=ExtraIgnoreConfig)
 class Config:
 

queue_func-0.2.1/queue_func/consumer/base.py → queue_func-0.2.3/queue_func/core/consumer.py

@@ -8,7 +8,7 @@ import typing as t
 from functools import wraps
 
 from queue_func.serializer.base import Message
-from queue_func.shared_resource.base import Resource
+from queue_func.core.resource import Resource
 from queue_func.pool_executor.base import BasePoolExecutor
 from queue_func.utils.hook import OnceHooks
 
@@ -24,6 +24,7 @@ class BaseConsumer(t.Generic[Message, Resource], metaclass=abc.ABCMeta):
         "_startup",
         "_shutdown",
         "_stopped",
+        "_running",
         "_logger",
     )
 
@@ -42,6 +43,7 @@ class BaseConsumer(t.Generic[Message, Resource], metaclass=abc.ABCMeta):
         self._pool_executor = self._init_pool_executor(pool_executor_cls, pool_maxsize)
         self._consume_timeout = consume_timeout
         self._stopped = False
+        self._running = asyncio.Event()
         self._startup = OnceHooks()
         self._shutdown = OnceHooks()
         self._logger = logging.getLogger(__name__)
@@ -84,6 +86,12 @@ class BaseConsumer(t.Generic[Message, Resource], metaclass=abc.ABCMeta):
             self._startup.register(self._run_until_stopped(self._consume))
             self._register_shutdown()
             await self._startup.start()
+            await self._running.wait()
+
+    def _mark_running(self) -> None:
+        """消费者已经开始收消息。``consume`` 等到这里才返回。"""
+
+        self._running.set()
 
     @abc.abstractmethod
     async def _consume(self) -> None:  # pragma: no cover

queue_func-0.2.1/queue_func/producer/base.py → queue_func-0.2.3/queue_func/core/producer.py

@@ -3,7 +3,7 @@
 import abc
 import typing as t
 
-from queue_func.shared_resource.base import Resource
+from queue_func.core.resource import Resource
 from queue_func.serializer.base import Message
 from queue_func.utils.hook import OnceHooks
 from queue_func.utils.waiter import IdleWaiter

{queue_func-0.2.1 → queue_func-0.2.3}/queue_func/factory/builders/__init__.py

@@ -2,8 +2,8 @@
 
 """Import builder modules so they register with :func:`register_backend`."""
 
-from queue_func.factory.builders import queue as queue
-from queue_func.factory.builders import rabbit_aio_pika as rabbit_aio_pika
+from queue_func.backends.queue import build as queue
+from queue_func.backends.rabbit_aio_pika import build as rabbit_aio_pika
 
 __all__ = (
     "queue",

{queue_func-0.2.1 → queue_func-0.2.3}/queue_func/factory/deco.py

@@ -2,14 +2,14 @@
 
 import typing as t
 
-from queue_func.config.rabbit_aio_pika import DeliveryMode, ExchangeName
+from queue_func.backends.rabbit_aio_pika.config import DeliveryMode, ExchangeName
 from queue_func.factory import builders as _builders  # noqa: F401 — register backends
 from queue_func.factory.backend import Backend
 from queue_func.factory.registry import build_broker
 
 if t.TYPE_CHECKING:
-    from queue_func.broker.base import BaseBroker
-    from queue_func.config.general import Config as GeneralConfig
+    from queue_func.core.broker import BaseBroker
+    from queue_func.core.config import Config as GeneralConfig
     from queue_func.pool_executor.base import BasePoolExecutor
     from queue_func.serializer.base import BaseSerializer
 

{queue_func-0.2.1 → queue_func-0.2.3}/queue_func/factory/registry.py

@@ -5,7 +5,7 @@ import typing as t
 from queue_func.factory.backend import Backend
 
 if t.TYPE_CHECKING:
-    from queue_func.broker.base import BaseBroker
+    from queue_func.core.broker import BaseBroker
 
 __all__ = (
     "register_backend",

queue_func-0.2.1/README.md

@@ -1,228 +0,0 @@
-# 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/queue_func/config/utils.py

@@ -1,15 +0,0 @@
-# coding: utf-8
-
-from pydantic.config import ConfigDict
-
-__all__ = (
-    "ExtraIgnoreConfig",
-)
-
-
-ExtraIgnoreConfig = ConfigDict(
-    extra="ignore",
-    validate_assignment=True,
-    arbitrary_types_allowed=True,
-    coerce_numbers_to_str=True,
-)

queue_func-0.2.1/queue_func/utils/__init__.py

@@ -1 +0,0 @@
-# coding: utf-8