redqueue 0.11.1__tar.gz → 0.12.0__tar.gz

{redqueue-0.11.1 → redqueue-0.12.0}/CHANGELOG.md

@@ -7,24 +7,71 @@ All notable public release changes are documented here.
 Development versions are tracked separately from formal release versions.
 开发版本与正式版本分开管理。
 
-## [0.11.1] - 2026-06-21
+## [0.12.0] - 2026-06-23
+
+### Added
+
+- Added the `redqueue` CLI and `python -m redqueue` module entry point for
+  developer debugging.
+- Added CLI commands for Redis compatibility checks, queue statistics, message
+  publish, consume with optional ack/nack/retry, delayed scheduling, due
+  release, and dead-letter inspection.
+- Added deterministic JSON CLI output and user-facing JSON validation errors.
+- Added CLI unit tests with injected fake Redis and queue clients.
 
 ### Fixed
 
-- Fixed resource cleanup in sync and async `from_url()` when Redis capability
-  detection, configuration validation, or backend initialization fails after the
-  client created an owned Redis connection.
-- Added explicit `owns_redis` override support to sync and async `from_url()`
-  for advanced ownership control.
+- Normalized `BRPOPLPUSH` timeout values to integer seconds for Redis versions
+  older than 6.2, improving Redis 5.x List consume compatibility.
+
+### 新增
+
+- 新增 `redqueue` CLI 和 `python -m redqueue` 模块入口，方便开发者调试。
+- 新增 Redis 兼容性检查、队列统计、消息发布、消费并可选 ack/nack/retry、
+  延迟调度、到期释放和死信查看命令。
+- CLI 输出稳定 JSON，并提供面向用户的 JSON 参数校验错误。
+- 新增基于 fake Redis 和 fake queue client 的 CLI 单元测试。
 
 ### 修复
 
-- 修复同步和异步 `from_url()` 在自动创建 Redis 连接后，如果 Redis 能力探测、
-  配置校验或后端初始化失败，已创建连接未释放的问题。
-- 同步和异步 `from_url()` 新增显式 `owns_redis` 覆盖支持，用于高级资源所有权
-  控制。
+- 对 Redis 6.2 以下版本使用 `BRPOPLPUSH` 时，将 timeout 规范为整数秒，
+  提升 Redis 5.x List 消费兼容性。
+
+## [0.11.2] - 2026-06-21
 
-## [0.11.0] - 2026-06-21
+### Fixed
+
+- Fixed cleanup for directly constructed sync clients when owned Redis backend
+  initialization fails.
+- Fixed cleanup for directly constructed async clients when lazy backend
+  initialization fails.
+- Made sync and async client `close()` idempotent for owned Redis clients.
+
+### 修复
+
+- 修复直接构造同步客户端时，如果 owned Redis 的后端初始化失败，Redis client
+  未释放的问题。
+- 修复直接构造异步客户端时，如果懒加载后端初始化失败，Redis client 未释放的问题。
+- 同步和异步客户端的 `close()` 对 owned Redis client 变为幂等。
+
+## [0.11.1] - 2026-06-21
+
+### Fixed
+
+- Fixed resource cleanup in sync and async `from_url()` when Redis capability
+  detection, configuration validation, or backend initialization fails after the
+  client created an owned Redis connection.
+- Added explicit `owns_redis` override support to sync and async `from_url()`
+  for advanced ownership control.
+
+### 修复
+
+- 修复同步和异步 `from_url()` 在自动创建 Redis 连接后，如果 Redis 能力探测、
+  配置校验或后端初始化失败，已创建连接未释放的问题。
+- 同步和异步 `from_url()` 新增显式 `owns_redis` 覆盖支持，用于高级资源所有权
+  控制。
+
+## [0.11.0] - 2026-06-21
 
 ### Added
 

{redqueue-0.11.1 → redqueue-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: redqueue
-Version: 0.11.1
+Version: 0.12.0
 Summary: Redis-backed Python message queue library with List, Streams, delayed tasks, and monitoring.
 Project-URL: Homepage, https://github.com/SpringMirror-pear/redqueue
 Project-URL: Repository, https://github.com/SpringMirror-pear/redqueue.git
@@ -50,6 +50,7 @@ https://github.com/SpringMirror-pear/redqueue.git
 - Delayed tasks based on Redis Sorted Set.
 - Sync client `QueueClient` and async client `AsyncQueueClient`.
 - Redis connection pool managers for shared sync and async resources.
+- `redqueue` CLI for local debugging and operational checks.
 - Unified exception hierarchy with structured context.
 - Monitoring events for publish, consume, ack, nack, retry, dead letter, delay,
   and backend errors.
@@ -80,12 +81,51 @@ Redis:
 pip install redqueue
 ```
 
+The package installs a `redqueue` command. You can also run it with
+`python -m redqueue` from a source checkout.
+
 For local development:
 
 ```bash
 python -m pip install -r requirements.txt
 ```
 
+## CLI
+
+Check Redis compatibility:
+
+```bash
+redqueue check --url redis://127.0.0.1:6379/0
+```
+
+Inspect queue counts:
+
+```bash
+redqueue stats --url redis://127.0.0.1:6379/0 --queue emails
+```
+
+Publish and consume messages:
+
+```bash
+redqueue publish --queue emails --payload '{"to":"user@example.com"}'
+redqueue consume --queue emails --timeout 1 --ack
+```
+
+Delayed task debugging:
+
+```bash
+redqueue delay --queue emails --payload '{"to":"later@example.com"}' --delay-seconds 60
+redqueue schedule-due --queue emails --limit 100
+```
+
+Dead-letter inspection:
+
+```bash
+redqueue dead-letters --queue emails --limit 20
+```
+
+All command output is JSON so it can be piped into scripts or log processors.
+
 ## Quick Start
 
 Synchronous List queue:

{redqueue-0.11.1 → redqueue-0.12.0}/README-zh-CN.md

@@ -14,9 +14,10 @@ https://github.com/SpringMirror-pear/redqueue.git
   `BRPOPLPUSH`。
 - 基于 Redis Streams 的消费组后端，Streams 要求 Redis `>=5.0`。
 - 基于 Redis Sorted Set 的延迟任务。
-- 同步客户端 `QueueClient` 与异步客户端 `AsyncQueueClient`。
-- 支持同步和异步 Redis 连接池管理器，方便多个客户端共享连接池。
-- 带结构化上下文的统一异常体系。
+- 同步客户端 `QueueClient` 与异步客户端 `AsyncQueueClient`。
+- 支持同步和异步 Redis 连接池管理器，方便多个客户端共享连接池。
+- 提供 `redqueue` CLI，用于本地调试和运行时检查。
+- 带结构化上下文的统一异常体系。
 - 针对发布、消费、确认、拒绝、重试、死信、延迟和后端错误的监控事件。
 - 通过 `INFO server` 探测 Redis 能力。
 - Apache License 2.0。
@@ -41,17 +42,56 @@ Redis：
 
 ## 安装
 
-```bash
-pip install redqueue
-```
-
-本地开发：
+```bash
+pip install redqueue
+```
+
+安装后会提供 `redqueue` 命令。从源码目录调试时也可以使用
+`python -m redqueue`。
+
+本地开发：
 
 ```bash
-python -m pip install -r requirements.txt
-```
-
-## 快速开始
+python -m pip install -r requirements.txt
+```
+
+## CLI
+
+检查 Redis 兼容性：
+
+```bash
+redqueue check --url redis://127.0.0.1:6379/0
+```
+
+查看队列统计：
+
+```bash
+redqueue stats --url redis://127.0.0.1:6379/0 --queue emails
+```
+
+发布和消费消息：
+
+```bash
+redqueue publish --queue emails --payload '{"to":"user@example.com"}'
+redqueue consume --queue emails --timeout 1 --ack
+```
+
+调试延迟任务：
+
+```bash
+redqueue delay --queue emails --payload '{"to":"later@example.com"}' --delay-seconds 60
+redqueue schedule-due --queue emails --limit 100
+```
+
+查看死信：
+
+```bash
+redqueue dead-letters --queue emails --limit 20
+```
+
+所有命令都输出 JSON，方便接入脚本和日志处理流程。
+
+## 快速开始
 
 同步 List 队列：
 

{redqueue-0.11.1 → redqueue-0.12.0}/README.md

@@ -15,9 +15,10 @@ https://github.com/SpringMirror-pear/redqueue.git
   fallback on older compatible Redis versions.
 - Redis Streams backend with consumer groups. Streams require Redis `>=5.0`.
 - Delayed tasks based on Redis Sorted Set.
-- Sync client `QueueClient` and async client `AsyncQueueClient`.
-- Redis connection pool managers for shared sync and async resources.
-- Unified exception hierarchy with structured context.
+- Sync client `QueueClient` and async client `AsyncQueueClient`.
+- Redis connection pool managers for shared sync and async resources.
+- `redqueue` CLI for local debugging and operational checks.
+- Unified exception hierarchy with structured context.
 - Monitoring events for publish, consume, ack, nack, retry, dead letter, delay,
   and backend errors.
 - Redis capability detection from `INFO server`.
@@ -43,17 +44,56 @@ Redis:
 
 ## Installation
 
-```bash
-pip install redqueue
-```
-
-For local development:
+```bash
+pip install redqueue
+```
+
+The package installs a `redqueue` command. You can also run it with
+`python -m redqueue` from a source checkout.
+
+For local development:
 
 ```bash
-python -m pip install -r requirements.txt
-```
-
-## Quick Start
+python -m pip install -r requirements.txt
+```
+
+## CLI
+
+Check Redis compatibility:
+
+```bash
+redqueue check --url redis://127.0.0.1:6379/0
+```
+
+Inspect queue counts:
+
+```bash
+redqueue stats --url redis://127.0.0.1:6379/0 --queue emails
+```
+
+Publish and consume messages:
+
+```bash
+redqueue publish --queue emails --payload '{"to":"user@example.com"}'
+redqueue consume --queue emails --timeout 1 --ack
+```
+
+Delayed task debugging:
+
+```bash
+redqueue delay --queue emails --payload '{"to":"later@example.com"}' --delay-seconds 60
+redqueue schedule-due --queue emails --limit 100
+```
+
+Dead-letter inspection:
+
+```bash
+redqueue dead-letters --queue emails --limit 20
+```
+
+All command output is JSON so it can be piped into scripts or log processors.
+
+## Quick Start
 
 Synchronous List queue:
 
@@ -195,7 +235,7 @@ RedQueue uses a lightweight Git Flow model:
 ## Documentation
 
 - Chinese README: [README-zh-CN.md](README-zh-CN.md)
-- API: [docs/API.md](docs/API.md)
+- API: [docs/API.md](docs/API.md)
 - Examples: [examples/README.md](examples/README.md)
 - Changelog: [CHANGELOG.md](CHANGELOG.md)
 - Release process: [docs/RELEASE.md](docs/RELEASE.md)
@@ -205,7 +245,7 @@ RedQueue uses a lightweight Git Flow model:
 
 ## Examples
 
-The `examples/` directory contains runnable scripts for synchronous List queues,
+The `examples/` directory contains runnable scripts for synchronous List queues,
 asynchronous List queues, Streams, delayed tasks, monitoring hooks, custom
 serializers, and Redis compatibility checks.
 

{redqueue-0.11.1 → redqueue-0.12.0}/docs/API.md

@@ -1,8 +1,8 @@
 # RedQueue API / RedQueue API 文档
 
-This document describes the public API available in RedQueue `0.11.1`.
+This document describes the public API available in RedQueue `0.12.0`.
 
-本文档描述 RedQueue `0.11.1` 的公开 API。
+本文档描述 RedQueue `0.12.0` 的公开 API。
 
 ## Clients / 客户端
 
@@ -25,6 +25,8 @@ client = QueueClient.from_url(
 Methods / 方法：
 
 - `from_url(url, *, queue, backend="list", connection_manager=None, **options) -> QueueClient`
+  - Advanced options include `pool_options`, injected `redis`, injected
+    `capabilities`, and `owns_redis`.
 - `publish(payload, *, delay=None, headers=None, message_id=None) -> str`
 - `consume(*, timeout=None, batch_size=1) -> Message | list[Message] | None`
 - `ack(message) -> None`
@@ -57,6 +59,8 @@ client = await AsyncQueueClient.from_url(
 Methods / 方法：
 
 - `await from_url(url, *, queue, backend="list", connection_manager=None, **options) -> AsyncQueueClient`
+  - Advanced options include `pool_options`, injected `redis`, injected
+    `capabilities`, and `owns_redis`.
 - `await publish(payload, *, delay=None, headers=None, message_id=None) -> str`
 - `await consume(*, timeout=None, batch_size=1) -> Message | list[Message] | None`
 - `await ack(message) -> None`
@@ -299,14 +303,45 @@ Monitoring events do not include business payload by default.
 
 监控事件默认不包含业务 payload。
 
-## Redis Capability Detection / Redis 能力探测
-
-- `RedisVersion`
-- `RedisCapabilities`
-- `extract_redis_version(info)`
-- `detect_capabilities(client)`
-- `detect_capabilities_async(client)`
-
-Streams are rejected with `RedisCompatibilityError` when Redis is below `5.0`.
-
-当 Redis 低于 `5.0` 时，启用 Streams 会抛出 `RedisCompatibilityError`。
+## Redis Capability Detection / Redis 能力探测
+
+- `RedisVersion`
+- `RedisCapabilities`
+- `extract_redis_version(info)`
+- `detect_capabilities(client)`
+- `detect_capabilities_async(client)`
+
+Streams are rejected with `RedisCompatibilityError` when Redis is below `5.0`.
+
+当 Redis 低于 `5.0` 时，启用 Streams 会抛出 `RedisCompatibilityError`。
+
+## CLI / 命令行工具
+
+RedQueue `0.12.0` provides a `redqueue` console command and a
+`python -m redqueue` module entry point for developer diagnostics.
+
+RedQueue `0.12.0` 提供 `redqueue` 控制台命令和 `python -m redqueue`
+模块入口，用于开发者调试。
+
+Commands / 命令：
+
+- `redqueue check --url redis://127.0.0.1:6379/0`
+- `redqueue stats --queue emails [--backend list|stream]`
+- `redqueue publish --queue emails --payload '{"to":"user@example.com"}'`
+- `redqueue consume --queue emails [--ack|--nack|--retry]`
+- `redqueue delay --queue emails --payload '{"to":"later@example.com"}' --delay-seconds 60`
+- `redqueue schedule-due --queue emails --limit 100`
+- `redqueue dead-letters --queue emails --limit 20`
+
+Common options / 通用选项：
+
+- `--url`: Redis URL. Defaults to `redis://127.0.0.1:6379/0`.
+- `--queue`: RedQueue queue name.
+- `--backend`: `list` or `stream`.
+- `--namespace`: Redis key namespace. Defaults to `rq`.
+- `--consumer-group`: Streams consumer group. Defaults to `redqueue`.
+- `--consumer-name`: Optional Streams consumer name.
+
+Payload and headers are JSON strings. Command responses are stable JSON objects.
+
+Payload 和 headers 使用 JSON 字符串。命令响应为稳定 JSON 对象。

{redqueue-0.11.1 → redqueue-0.12.0}/pyproject.toml

@@ -2,9 +2,9 @@
 requires = ["hatchling==1.30.1"]
 build-backend = "hatchling.build"
 
-[project]
-name = "redqueue"
-version = "0.11.1"
+[project]
+name = "redqueue"
+version = "0.12.0"
 description = "Redis-backed Python message queue library with List, Streams, delayed tasks, and monitoring."
 readme = "README.md"
 requires-python = ">=3.9"
@@ -33,13 +33,16 @@ dependencies = [
   "redis==6.4.0",
 ]
 
-[project.urls]
-Homepage = "https://github.com/SpringMirror-pear/redqueue"
-Repository = "https://github.com/SpringMirror-pear/redqueue.git"
-Issues = "https://github.com/SpringMirror-pear/redqueue/issues"
-
-[project.optional-dependencies]
-dev = [
+[project.urls]
+Homepage = "https://github.com/SpringMirror-pear/redqueue"
+Repository = "https://github.com/SpringMirror-pear/redqueue.git"
+Issues = "https://github.com/SpringMirror-pear/redqueue/issues"
+
+[project.scripts]
+redqueue = "redqueue.cli:main"
+
+[project.optional-dependencies]
+dev = [
   "pytest==9.1.1; python_version >= '3.10'",
   "pytest-asyncio==1.4.0; python_version >= '3.10'",
   "ruff==0.15.18",

redqueue-0.12.0/src/redqueue/__main__.py

@@ -0,0 +1,9 @@
+# SPDX-License-Identifier: Apache-2.0
+# Author: SpringMirror-pear
+
+"""Module entry point for ``python -m redqueue``."""
+
+from redqueue.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{redqueue-0.11.1 → redqueue-0.12.0}/src/redqueue/_version.py

@@ -3,4 +3,4 @@
 
 """Package version."""
 
-__version__ = "0.11.1"
+__version__ = "0.12.0"

{redqueue-0.11.1 → redqueue-0.12.0}/src/redqueue/async_client.py

@@ -59,6 +59,7 @@ class AsyncQueueClient:
         self.redis = redis
         self.capabilities = capabilities
         self._owns_redis = owns_redis
+        self._closed = False
         self.backend: AsyncListBackend | AsyncStreamBackend | None = None
         self.delay_backend: AsyncDelayBackend | None = None
         self.config.monitoring.emit(
@@ -88,7 +89,8 @@ class AsyncQueueClient:
             connection_manager: Optional async connection manager used to create
                 a client from a shared pool.
             **options: Additional ``QueueConfig`` options. Tests may also pass
-                ``redis``, ``capabilities``, or ``pool_options``.
+                ``redis``, ``capabilities``, ``pool_options``, or
+                ``owns_redis``.
 
         Returns:
             An initialized ``AsyncQueueClient`` with its primary backend ready.
@@ -99,50 +101,48 @@ class AsyncQueueClient:
             QueueConfigError: If configuration values are invalid.
         """
 
-        redis = options.pop("redis", None)
-        pool_options = options.pop("pool_options", None) or {}
-        explicit_owns_redis = options.pop("owns_redis", None)
-        owns_redis = (
-            bool(explicit_owns_redis)
-            if explicit_owns_redis is not None
-            else False
-        )
-        if redis is None:
-            if connection_manager is not None:
-                redis = connection_manager.redis()
-            else:
-                redis = Redis.from_url(url, **pool_options)
-                owns_redis = (
-                    True
-                    if explicit_owns_redis is None
-                    else bool(explicit_owns_redis)
-                )
-        try:
-            capabilities = options.pop(
-                "capabilities",
-                None,
-            ) or await detect_capabilities_async(cast(AsyncRedisInfoClient, redis))
-            config = QueueConfig(queue=queue, backend=backend, **options)
-            client = cls(
-                config=config,
-                redis=redis,
-                capabilities=capabilities,
-                owns_redis=owns_redis,
-            )
-            await client._ensure_backend()
-            return client
-        except Exception:
-            if owns_redis:
-                close = getattr(redis, "aclose", None) or getattr(
-                    redis,
-                    "close",
-                    None,
-                )
-                if close is not None:
-                    result = close()
-                    if hasattr(result, "__await__"):
-                        await result
-            raise
+        redis = options.pop("redis", None)
+        pool_options = options.pop("pool_options", None) or {}
+        explicit_owns_redis = options.pop("owns_redis", None)
+        owns_redis = (
+            bool(explicit_owns_redis)
+            if explicit_owns_redis is not None
+            else False
+        )
+        if redis is None:
+            if connection_manager is not None:
+                redis = connection_manager.redis()
+            else:
+                redis = Redis.from_url(url, **pool_options)
+                owns_redis = (
+                    True
+                    if explicit_owns_redis is None
+                    else bool(explicit_owns_redis)
+                )
+        capabilities = options.pop("capabilities", None)
+        if capabilities is None:
+            try:
+                capabilities = await detect_capabilities_async(
+                    cast(AsyncRedisInfoClient, redis)
+                )
+            except Exception:
+                if owns_redis:
+                    await cls._close_redis(redis)
+                raise
+        try:
+            config = QueueConfig(queue=queue, backend=backend, **options)
+        except Exception:
+            if owns_redis:
+                await cls._close_redis(redis)
+            raise
+        client = cls(
+            config=config,
+            redis=redis,
+            capabilities=capabilities,
+            owns_redis=owns_redis,
+        )
+        await client._ensure_backend()
+        return client
 
     async def publish(
         self,
@@ -324,7 +324,7 @@ class AsyncQueueClient:
     async def close(self) -> None:
         """Close the async Redis client when this client owns it."""
 
-        if not self._owns_redis:
+        if self._closed or not self._owns_redis:
             return
 
         close = getattr(self.redis, "aclose", None) or getattr(
@@ -333,9 +333,8 @@ class AsyncQueueClient:
             None,
         )
         if close is not None:
-            result = close()
-            if hasattr(result, "__await__"):
-                await result
+            await self._call_close(close)
+        self._closed = True
 
     async def __aenter__(self) -> AsyncQueueClient:
         """Enter an asynchronous resource-management context."""
@@ -371,24 +370,48 @@ class AsyncQueueClient:
             capabilities = self.capabilities
             if capabilities is None:
                 raise TypeError("Redis capabilities are required before backend use")
-            self.backend = AsyncListBackend(self.redis, self.config, capabilities)
-            return self.backend
+            try:
+                self.backend = AsyncListBackend(self.redis, self.config, capabilities)
+                return self.backend
+            except Exception:
+                await self.close()
+                raise
         if self.config.backend_type is BackendType.STREAM:
             if self.redis is None:
                 raise TypeError("redis client is required for async Streams backend")
             capabilities = self.capabilities
             if capabilities is None:
                 raise TypeError("Redis capabilities are required before backend use")
-            self.backend = await AsyncStreamBackend.create(
-                self.redis,
-                self.config,
-                capabilities,
-            )
-            return self.backend
+            try:
+                self.backend = await AsyncStreamBackend.create(
+                    self.redis,
+                    self.config,
+                    capabilities,
+                )
+                return self.backend
+            except Exception:
+                await self.close()
+                raise
         raise NotImplementedError(
             f"backend {self.config.backend_type.value!r} is not implemented"
         )
 
+    @staticmethod
+    async def _close_redis(redis: Any) -> None:
+        """Close an async Redis-like object if it exposes a close method."""
+
+        close = getattr(redis, "aclose", None) or getattr(redis, "close", None)
+        if close is not None:
+            await AsyncQueueClient._call_close(close)
+
+    @staticmethod
+    async def _call_close(close: Any) -> None:
+        """Call a sync or async close method."""
+
+        result = close()
+        if hasattr(result, "__await__"):
+            await result
+
     async def _ensure_delay_backend(self) -> AsyncDelayBackend:
         """Return the initialized async delay scheduler, creating it when needed."""