async-task-kit 0.1.2__tar.gz → 0.1.14__tar.gz

{async_task_kit-0.1.2 → async_task_kit-0.1.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: async-task-kit
-Version: 0.1.2
+Version: 0.1.14
 Summary: A powerful async task processing kit based on RabbitMQ with Coroutine, Thread, and Process support.
 Author-email: realwrtoff <realwrtoff@gmail.com>
 Classifier: Programming Language :: Python :: 3
@@ -175,6 +175,54 @@ if __name__ == "__main__":
     asyncio.run(publish())
 ```
 
+### 5. RabbitMQ Client API
+
+`RabbitMQ` 提供连接池、`push` / `pop`、延迟重试队列，以及 `queue_length` 查询队列深度。
+
+#### `queue_length`
+
+```python
+from async_task_kit import RabbitMQ
+
+rmq = RabbitMQ("amqp://guest:guest@localhost/")
+await rmq.init()
+
+length = await rmq.queue_length("my_demo_queue")
+if length == RabbitMQ.QUEUE_LENGTH_UNAVAILABLE:
+    # -1：连不上或队列不存在，稍后重试
+    ...
+elif length == 0:
+    # 队列存在且为空
+    ...
+else:
+    # 当前消息数
+    ...
+
+await rmq.close()
+```
+
+| 返回值 | 含义 |
+|--------|------|
+| `>= 0` | 队列真实消息数（`0` = 空队列） |
+| `-1` (`QUEUE_LENGTH_UNAVAILABLE`) | 连接失败、队列不存在或其它异常，应重试 |
+
+实现要点：
+
+- 使用 **`passive=True`** 声明：只查询已存在的队列，**不会**自动创建空队列。
+- 断连时会关闭旧连接池并自动重建（与 `push` / `pop` 一致）。
+
+#### `pop` 的 `durable` 参数
+
+`pop` 在取消息前会 `declare_queue`。`push` 默认以 **`durable=True`** 创建队列（重启后队列仍在），因此 `pop` 默认同样传 `durable=True`，保证声明参数与已有队列一致，避免 RabbitMQ 返回 `PRECONDITION_FAILED`。
+
+若你的队列是非持久化的，调用时需显式传入：
+
+```python
+await rmq.pop("my_queue", durable=False)
+```
+
+`queue_length` 使用 passive 模式，无需传 `durable`。
+
 ## License
 
 MIT

{async_task_kit-0.1.2 → async_task_kit-0.1.14}/README.md

@@ -159,6 +159,54 @@ if __name__ == "__main__":
     asyncio.run(publish())
 ```
 
+### 5. RabbitMQ Client API
+
+`RabbitMQ` 提供连接池、`push` / `pop`、延迟重试队列，以及 `queue_length` 查询队列深度。
+
+#### `queue_length`
+
+```python
+from async_task_kit import RabbitMQ
+
+rmq = RabbitMQ("amqp://guest:guest@localhost/")
+await rmq.init()
+
+length = await rmq.queue_length("my_demo_queue")
+if length == RabbitMQ.QUEUE_LENGTH_UNAVAILABLE:
+    # -1：连不上或队列不存在，稍后重试
+    ...
+elif length == 0:
+    # 队列存在且为空
+    ...
+else:
+    # 当前消息数
+    ...
+
+await rmq.close()
+```
+
+| 返回值 | 含义 |
+|--------|------|
+| `>= 0` | 队列真实消息数（`0` = 空队列） |
+| `-1` (`QUEUE_LENGTH_UNAVAILABLE`) | 连接失败、队列不存在或其它异常，应重试 |
+
+实现要点：
+
+- 使用 **`passive=True`** 声明：只查询已存在的队列，**不会**自动创建空队列。
+- 断连时会关闭旧连接池并自动重建（与 `push` / `pop` 一致）。
+
+#### `pop` 的 `durable` 参数
+
+`pop` 在取消息前会 `declare_queue`。`push` 默认以 **`durable=True`** 创建队列（重启后队列仍在），因此 `pop` 默认同样传 `durable=True`，保证声明参数与已有队列一致，避免 RabbitMQ 返回 `PRECONDITION_FAILED`。
+
+若你的队列是非持久化的，调用时需显式传入：
+
+```python
+await rmq.pop("my_queue", durable=False)
+```
+
+`queue_length` 使用 passive 模式，无需传 `durable`。
+
 ## License
 
 MIT

{async_task_kit-0.1.2 → async_task_kit-0.1.14}/async_task_kit/consumer/coroutine.py

@@ -18,6 +18,7 @@ class CoroutineConsumer(BaseConsumer):
         concurrency: int = 1,
         max_retry: int = 3,
         retry_delay: int = 30,
+        rmq: RabbitMQ | None = None,
     ):
         self.amqp_url = amqp_url
         self.queue_name = queue_name
@@ -26,7 +27,8 @@ class CoroutineConsumer(BaseConsumer):
         self.max_retry = max_retry
         self.retry_delay = retry_delay
 
-        self._rmq = RabbitMQ(amqp_url)
+        self._owns_rmq = rmq is None
+        self._rmq = rmq or RabbitMQ(amqp_url)
         self._stop_event = asyncio.Event()
 
     async def start(self):
@@ -93,5 +95,6 @@ class CoroutineConsumer(BaseConsumer):
 
     async def stop(self):
         self._stop_event.set()
-        await self._rmq.close()
-        logger.info(f"[CoroutineConsumer] stopped | queue={self.queue_name}")
+        if self._owns_rmq:
+            await self._rmq.close()
+        logger.info(f"[CoroutineConsumer] stopped | queue={self.queue_name}")

{async_task_kit-0.1.2 → async_task_kit-0.1.14}/async_task_kit/consumer/process.py

@@ -104,4 +104,4 @@ class ProcessConsumer(BaseConsumer):
 
     async def stop(self):
         self._stop_event.set()
-        logger.info(f"[ProcessConsumer] stopped | queue={self.queue_name}")
+        logger.info(f"[ProcessConsumer] stopped | queue={self.queue_name}")

{async_task_kit-0.1.2 → async_task_kit-0.1.14}/async_task_kit/consumer/thread.py

@@ -104,4 +104,4 @@ class ThreadConsumer(BaseConsumer):
 
     async def stop(self):
         self._stop_event.set()
-        logger.info(f"[ThreadConsumer] stopped | queue={self.queue_name}")
+        logger.info(f"[ThreadConsumer] stopped | queue={self.queue_name}")

{async_task_kit-0.1.2 → async_task_kit-0.1.14}/async_task_kit/core/rabbitmq.py

@@ -12,6 +12,7 @@ from aio_pika.exceptions import (
     ChannelClosed,
     AMQPError
 )
+from aiormq.exceptions import ChannelInvalidStateError
 from aio_pika.pool import Pool
 
 logger = logging.getLogger(__name__)
@@ -29,7 +30,11 @@ class BasicQueue(ABC):
     @abstractmethod
     async def pop(self, queue_name: str,** kwargs: Any) -> Any:
         raise NotImplementedError
-
+    
+    @abstractmethod
+    async def queue_length(self, queue_name: str) -> int:
+        raise NotImplementedError
+    
     @abstractmethod
     async def ack(self, message: Any) -> None:
         raise NotImplementedError
@@ -50,6 +55,7 @@ class RabbitMQ(BasicQueue):
     DEFAULT_DEAD_LETTER_DAYS = 7
     DEFAULT_DELAY_SECONDS = 30
     DEFAULT_POP_TIMEOUT = 1.0
+    QUEUE_LENGTH_UNAVAILABLE = -1
 
     def __init__(
         self,
@@ -58,6 +64,7 @@ class RabbitMQ(BasicQueue):
         channel_size: int = DEFAULT_CHANNEL_SIZE,
         heartbeat: int = 60,
         max_retry_count: int = DEFAULT_MAX_RETRY_COUNT,
+        
     ):
         self.rabbit_url = rabbit_url
         self.pool_size = pool_size
@@ -92,6 +99,23 @@ class RabbitMQ(BasicQueue):
                 logger.error(f"[RabbitMQ] 初始化失败: {e}", exc_info=True)
                 raise
 
+    async def _invalidate_pools(self) -> None:
+        """断连或 close 时关闭 pool，下次 init() 会重建。"""
+        async with self._init_lock:
+            self._ready.clear()
+            channel_pool = self._channel_pool
+            connection_pool = self._connection_pool
+            self._channel_pool = None
+            self._connection_pool = None
+
+        for pool, label in ((channel_pool, "channel"), (connection_pool, "connection")):
+            if pool is None:
+                continue
+            try:
+                await pool.close()
+            except Exception as e:
+                logger.warning(f"[RabbitMQ] 关闭旧 {label} pool 失败: {e}")
+
     async def _get_connection(self) -> aio_pika.abc.AbstractRobustConnection:
         try:
             return await aio_pika.connect_robust(
@@ -118,41 +142,80 @@ class RabbitMQ(BasicQueue):
         count = int(kwargs.get("count", 0))
         durable = kwargs.get("durable", True)
 
-        async with self._channel_pool.acquire() as channel:
-            if 0 < count < self.max_retry_count:
-                rk = await self._setup_delay_queue(channel, queue_name,** kwargs)
-            elif count >= self.max_retry_count:
-                rk = await self._setup_dead_letter_queue(channel, queue_name, **kwargs)
-            else:
-                rk = await self._setup_normal_queue(channel, queue_name, durable)
-
-            msg = self._create_message(data, count)
-            await channel.default_exchange.publish(msg, routing_key=rk)
-            logger.debug(f"[PUSH] queue={queue_name} count={count}")
-            return msg
+        try:
+            async with self._channel_pool.acquire() as channel:
+                if 0 < count < self.max_retry_count:
+                    rk = await self._setup_delay_queue(channel, queue_name,** kwargs)
+                elif count >= self.max_retry_count:
+                    rk = await self._setup_dead_letter_queue(channel, queue_name, **kwargs)
+                else:
+                    rk = await self._setup_normal_queue(channel, queue_name, durable)
+
+                msg = self._create_message(data, count)
+                await channel.default_exchange.publish(msg, routing_key=rk)
+                logger.debug(f"[PUSH] queue={queue_name} count={count}")
+                return msg
+        except (ConnectionClosed, ChannelClosed):
+            logger.warning("[PUSH] 连接断开，准备重连")
+            await self._invalidate_pools()
+            return None
+        except ChannelInvalidStateError:
+            logger.warning("[PUSH] 信道 RPC 异常，准备重建 pool")
+            await self._invalidate_pools()
+            return None
+        except Exception as e:
+            logger.error(f"[PUSH] 异常 queue={queue_name}: {e}", exc_info=True)
+            return None
 
     async def pop(self, queue_name: str,** kwargs: Any) -> Optional[aio_pika.abc.AbstractIncomingMessage]:
         if self._closed:
             return None
 
         await self.init()
+        # durable 须与 push 声明队列时一致（默认 True），否则 re-declare 可能 PRECONDITION_FAILED
         durable = kwargs.get("durable", True)
 
         try:
             async with self._channel_pool.acquire() as channel:
                 queue = await channel.declare_queue(queue_name, durable=durable)
-                return await asyncio.wait_for(
-                    queue.get(), timeout=self.DEFAULT_POP_TIMEOUT
+                # 使用 aio_pika 自带 timeout，勿用 asyncio.wait_for 取消 get（会关闭 channel）
+                return await queue.get(
+                    timeout=self.DEFAULT_POP_TIMEOUT,
+                    fail=False,
                 )
         except (QueueEmpty, asyncio.TimeoutError):
             return None
-        except (ConnectionClosed, ChannelClosed):
-            logger.warning("[POP] 连接断开，准备重连")
-            self._ready.clear()
+        except (ConnectionClosed, ChannelClosed, ChannelInvalidStateError):
+            logger.warning("[POP] 连接/信道异常，准备重建 pool")
+            await self._invalidate_pools()
             return None
         except Exception as e:
             logger.error(f"[POP] 异常 queue={queue_name}: {e}", exc_info=True)
             return None
+    
+    async def queue_length(self, queue_name: str) -> int:
+        """Return queue message count, or QUEUE_LENGTH_UNAVAILABLE (-1) on failure."""
+        if self._closed:
+            return self.QUEUE_LENGTH_UNAVAILABLE
+
+        try:
+            await self.init()
+            async with self._channel_pool.acquire() as channel:
+                # passive：只查询已存在队列，不创建；队列不存在则 ChannelClosed → -1
+                queue = await channel.declare_queue(queue_name, passive=True)
+                count = queue.declaration_result.message_count
+                return count if count is not None else 0
+        except (ConnectionClosed, ChannelClosed):
+            logger.warning("[QUEUE_LENGTH] 连接断开，准备重连")
+            await self._invalidate_pools()
+            return self.QUEUE_LENGTH_UNAVAILABLE
+        except ChannelInvalidStateError:
+            logger.warning("[QUEUE_LENGTH] 信道 RPC 异常，准备重建 pool")
+            await self._invalidate_pools()
+            return self.QUEUE_LENGTH_UNAVAILABLE
+        except Exception as e:
+            logger.error(f"[QUEUE_LENGTH] 异常 queue={queue_name}: {e}", exc_info=True)
+            return self.QUEUE_LENGTH_UNAVAILABLE
 
     async def ack(self, message: aio_pika.abc.AbstractIncomingMessage) -> None:
         try:
@@ -217,13 +280,5 @@ class RabbitMQ(BasicQueue):
         if self._closed:
             return
         self._closed = True
-        self._ready.clear()
-
-        try:
-            if self._channel_pool:
-                await self._channel_pool.close()
-            if self._connection_pool:
-                await self._connection_pool.close()
-            logger.info("[RabbitMQ] 已关闭")
-        except Exception as e:
-            logger.error(f"[关闭失败] {e}")
+        await self._invalidate_pools()
+        logger.info("[RabbitMQ] 已关闭")

{async_task_kit-0.1.2 → async_task_kit-0.1.14}/async_task_kit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: async-task-kit
-Version: 0.1.2
+Version: 0.1.14
 Summary: A powerful async task processing kit based on RabbitMQ with Coroutine, Thread, and Process support.
 Author-email: realwrtoff <realwrtoff@gmail.com>
 Classifier: Programming Language :: Python :: 3
@@ -175,6 +175,54 @@ if __name__ == "__main__":
     asyncio.run(publish())
 ```
 
+### 5. RabbitMQ Client API
+
+`RabbitMQ` 提供连接池、`push` / `pop`、延迟重试队列，以及 `queue_length` 查询队列深度。
+
+#### `queue_length`
+
+```python
+from async_task_kit import RabbitMQ
+
+rmq = RabbitMQ("amqp://guest:guest@localhost/")
+await rmq.init()
+
+length = await rmq.queue_length("my_demo_queue")
+if length == RabbitMQ.QUEUE_LENGTH_UNAVAILABLE:
+    # -1：连不上或队列不存在，稍后重试
+    ...
+elif length == 0:
+    # 队列存在且为空
+    ...
+else:
+    # 当前消息数
+    ...
+
+await rmq.close()
+```
+
+| 返回值 | 含义 |
+|--------|------|
+| `>= 0` | 队列真实消息数（`0` = 空队列） |
+| `-1` (`QUEUE_LENGTH_UNAVAILABLE`) | 连接失败、队列不存在或其它异常，应重试 |
+
+实现要点：
+
+- 使用 **`passive=True`** 声明：只查询已存在的队列，**不会**自动创建空队列。
+- 断连时会关闭旧连接池并自动重建（与 `push` / `pop` 一致）。
+
+#### `pop` 的 `durable` 参数
+
+`pop` 在取消息前会 `declare_queue`。`push` 默认以 **`durable=True`** 创建队列（重启后队列仍在），因此 `pop` 默认同样传 `durable=True`，保证声明参数与已有队列一致，避免 RabbitMQ 返回 `PRECONDITION_FAILED`。
+
+若你的队列是非持久化的，调用时需显式传入：
+
+```python
+await rmq.pop("my_queue", durable=False)
+```
+
+`queue_length` 使用 passive 模式，无需传 `durable`。
+
 ## License
 
 MIT

{async_task_kit-0.1.2 → async_task_kit-0.1.14}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "async-task-kit"
-version = "0.1.2"
+version = "0.1.14"
 description = "A powerful async task processing kit based on RabbitMQ with Coroutine, Thread, and Process support."
 readme = "README.md"
 requires-python = ">=3.12"