redqueue 0.11.0__tar.gz → 0.11.2__tar.gz

{redqueue-0.11.0 → redqueue-0.11.2}/CHANGELOG.md

@@ -4,8 +4,42 @@ All notable public release changes are documented here.
 
 所有公开发布版本的重要变更都会记录在此文件中。
 
-Development versions are tracked separately from formal release versions.
-开发版本与正式版本分开管理。
+Development versions are tracked separately from formal release versions.
+开发版本与正式版本分开管理。
+
+## [0.11.2] - 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
 

{redqueue-0.11.0 → redqueue-0.11.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: redqueue
-Version: 0.11.0
+Version: 0.11.2
 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

{redqueue-0.11.0 → redqueue-0.11.2}/docs/API.md

@@ -1,8 +1,8 @@
 # RedQueue API / RedQueue API 文档
 
-This document describes the public API available in RedQueue `0.11.0`.
-
-本文档描述 RedQueue `0.11.0` 的公开 API。
+This document describes the public API available in RedQueue `0.11.2`.
+
+本文档描述 RedQueue `0.11.2` 的公开 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`

{redqueue-0.11.0 → redqueue-0.11.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "redqueue"
-version = "0.11.0"
+version = "0.11.2"
 description = "Redis-backed Python message queue library with List, Streams, delayed tasks, and monitoring."
 readme = "README.md"
 requires-python = ">=3.9"

{redqueue-0.11.0 → redqueue-0.11.2}/src/redqueue/_version.py

@@ -3,4 +3,4 @@
 
 """Package version."""
 
-__version__ = "0.11.0"
+__version__ = "0.11.2"

{redqueue-0.11.0 → redqueue-0.11.2}/src/redqueue/async_client.py

@@ -56,11 +56,12 @@ class AsyncQueueClient:
         """
 
         self.config = config
-        self.redis = redis
-        self.capabilities = capabilities
-        self._owns_redis = owns_redis
-        self.backend: AsyncListBackend | AsyncStreamBackend | None = None
-        self.delay_backend: AsyncDelayBackend | None = None
+        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(
             MonitoringEvent(
                 type=MonitoringEventType.CLIENT_CREATED,
@@ -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.
@@ -101,26 +103,46 @@ class AsyncQueueClient:
 
         redis = options.pop("redis", None)
         pool_options = options.pop("pool_options", None) or {}
-        owns_redis = False
+        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
-        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
+                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,
@@ -299,21 +321,20 @@ class AsyncQueueClient:
 
         await (await self._ensure_backend()).requeue_dead(message)
 
-    async def close(self) -> None:
-        """Close the async Redis client when this client owns it."""
-
-        if not self._owns_redis:
-            return
-
-        close = getattr(self.redis, "aclose", None) or getattr(
-            self.redis,
-            "close",
-            None,
-        )
-        if close is not None:
-            result = close()
-            if hasattr(result, "__await__"):
-                await result
+    async def close(self) -> None:
+        """Close the async Redis client when this client owns it."""
+
+        if self._closed or not self._owns_redis:
+            return
+
+        close = getattr(self.redis, "aclose", None) or getattr(
+            self.redis,
+            "close",
+            None,
+        )
+        if close is not None:
+            await self._call_close(close)
+        self._closed = True
 
     async def __aenter__(self) -> AsyncQueueClient:
         """Enter an asynchronous resource-management context."""
@@ -343,31 +364,55 @@ class AsyncQueueClient:
 
         if self.backend is not None:
             return self.backend
-        if self.config.backend_type is BackendType.LIST:
-            if self.redis is None:
-                raise TypeError("redis client is required for async List backend")
-            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
-        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
-        raise NotImplementedError(
-            f"backend {self.config.backend_type.value!r} is not implemented"
-        )
-
-    async def _ensure_delay_backend(self) -> AsyncDelayBackend:
+        if self.config.backend_type is BackendType.LIST:
+            if self.redis is None:
+                raise TypeError("redis client is required for async List backend")
+            capabilities = self.capabilities
+            if capabilities is None:
+                raise TypeError("Redis capabilities are required before backend use")
+            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")
+            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."""
 
         if self.delay_backend is not None:

{redqueue-0.11.0 → redqueue-0.11.2}/src/redqueue/client.py

@@ -61,15 +61,20 @@ class QueueClient:
             RedisCompatibilityError: If Redis lacks a required command family.
         """
 
-        self.config = config
-        self.redis = redis
-        self.capabilities = capabilities
-        self._owns_redis = owns_redis
-        self.backend = self._create_backend()
-        self.delay_backend = self._create_delay_backend()
-        self.config.monitoring.emit(
-            MonitoringEvent(
-                type=MonitoringEventType.CLIENT_CREATED,
+        self.config = config
+        self.redis = redis
+        self.capabilities = capabilities
+        self._owns_redis = owns_redis
+        self._closed = False
+        try:
+            self.backend = self._create_backend()
+            self.delay_backend = self._create_delay_backend()
+        except Exception:
+            self.close()
+            raise
+        self.config.monitoring.emit(
+            MonitoringEvent(
+                type=MonitoringEventType.CLIENT_CREATED,
                 queue=config.queue,
                 backend=config.backend_type.value,
             )
@@ -94,8 +99,8 @@ class QueueClient:
             connection_manager: Optional connection manager used to create a
                 client from a shared pool.
             **options: Additional ``QueueConfig`` options. Tests may also pass
-                ``redis``, ``capabilities``, or ``pool_options`` to bypass or
-                customize connection creation.
+                ``redis``, ``capabilities``, ``pool_options``, or
+                ``owns_redis`` to bypass or customize connection creation.
 
         Returns:
             A ready-to-use synchronous ``QueueClient``.
@@ -109,23 +114,46 @@ class QueueClient:
 
         redis = options.pop("redis", None)
         pool_options = options.pop("pool_options", None) or {}
-        owns_redis = False
+        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
-        capabilities = options.pop("capabilities", None) or detect_capabilities(
-            cast(RedisInfoClient, redis)
-        )
-        config = QueueConfig(queue=queue, backend=backend, **options)
-        return cls(
-            config=config,
-            redis=redis,
-            capabilities=capabilities,
-            owns_redis=owns_redis,
-        )
+                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 = detect_capabilities(cast(RedisInfoClient, redis))
+            except Exception:
+                if owns_redis:
+                    close = getattr(redis, "close", None)
+                    if close is not None:
+                        close()
+                raise
+        try:
+            config = QueueConfig(queue=queue, backend=backend, **options)
+        except Exception:
+            if owns_redis:
+                close = getattr(redis, "close", None)
+                if close is not None:
+                    close()
+            raise
+        return cls(
+            config=config,
+            redis=redis,
+            capabilities=capabilities,
+            owns_redis=owns_redis,
+        )
 
     def publish(
         self,
@@ -305,15 +333,16 @@ class QueueClient:
 
         self.backend.requeue_dead(message)
 
-    def close(self) -> None:
-        """Close the Redis client when this client owns it."""
-
-        if not self._owns_redis:
-            return
-
-        close = getattr(self.redis, "close", None)
-        if close is not None:
-            close()
+    def close(self) -> None:
+        """Close the Redis client when this client owns it."""
+
+        if self._closed or not self._owns_redis:
+            return
+
+        close = getattr(self.redis, "close", None)
+        if close is not None:
+            close()
+        self._closed = True
 
     def __enter__(self) -> QueueClient:
         """Enter a synchronous resource-management context."""

{redqueue-0.11.0 → redqueue-0.11.2}/tests/test_project_skeleton.py

@@ -50,7 +50,7 @@ from tests.fakes import (
 
 class ProjectSkeletonTests(unittest.TestCase):
     def test_version_is_current_dev_version(self) -> None:
-        self.assertEqual(__version__, "0.11.0")
+        self.assertEqual(__version__, "0.11.2")
 
     def test_queue_config_accepts_and_normalizes_backend(self) -> None:
         config = QueueConfig(queue=" emails ", backend="stream")
@@ -592,7 +592,7 @@ class ProjectSkeletonTests(unittest.TestCase):
 
         self.assertNotIn("close", redis.commands)
 
-    def test_sync_client_context_closes_owned_redis(self) -> None:
+    def test_sync_client_context_closes_owned_redis(self) -> None:
         redis = FakeListRedis()
 
         with QueueClient(
@@ -601,8 +601,37 @@ class ProjectSkeletonTests(unittest.TestCase):
             capabilities=RedisCapabilities(RedisVersion(7, 0, 0)),
         ):
             pass
-
-        self.assertIn("close", redis.commands)
+
+        self.assertIn("close", redis.commands)
+
+    def test_sync_client_close_is_idempotent(self) -> None:
+        redis = FakeListRedis()
+        client = QueueClient(
+            QueueConfig(queue="emails"),
+            redis=redis,
+            capabilities=RedisCapabilities(RedisVersion(7, 0, 0)),
+        )
+
+        client.close()
+        client.close()
+
+        self.assertEqual(redis.commands.count("close"), 1)
+
+    def test_sync_client_closes_owned_redis_when_backend_init_fails(self) -> None:
+        class ClosableStreamRedis(FakeStreamRedis):
+            def close(self) -> None:
+                self.commands.append("close")
+
+        redis = ClosableStreamRedis()
+
+        with self.assertRaises(RedisCompatibilityError):
+            QueueClient(
+                QueueConfig(queue="events", backend="stream"),
+                redis=redis,
+                capabilities=RedisCapabilities(RedisVersion(4, 0, 14)),
+            )
+
+        self.assertIn("close", redis.commands)
 
     def test_async_client_can_leave_injected_redis_open(self) -> None:
         async def run() -> FakeAsyncListRedis:
@@ -620,7 +649,7 @@ class ProjectSkeletonTests(unittest.TestCase):
 
         self.assertNotIn("aclose", redis.commands)
 
-    def test_async_client_context_closes_owned_redis(self) -> None:
+    def test_async_client_context_closes_owned_redis(self) -> None:
         async def run() -> FakeAsyncListRedis:
             redis = FakeAsyncListRedis()
             async with AsyncQueueClient(
@@ -632,8 +661,44 @@ class ProjectSkeletonTests(unittest.TestCase):
             return redis
 
         redis = asyncio.run(run())
-
-        self.assertIn("aclose", redis.commands)
+
+        self.assertIn("aclose", redis.commands)
+
+    def test_async_client_close_is_idempotent(self) -> None:
+        async def run() -> FakeAsyncListRedis:
+            redis = FakeAsyncListRedis()
+            client = AsyncQueueClient(
+                QueueConfig(queue="jobs"),
+                redis=redis,
+                capabilities=RedisCapabilities(RedisVersion(7, 0, 0)),
+            )
+            await client.close()
+            await client.close()
+            return redis
+
+        redis = asyncio.run(run())
+
+        self.assertEqual(redis.commands.count("aclose"), 1)
+
+    def test_async_client_closes_owned_redis_when_backend_init_fails(self) -> None:
+        async def run() -> FakeAsyncStreamRedis:
+            class ClosableAsyncStreamRedis(FakeAsyncStreamRedis):
+                async def aclose(self) -> None:
+                    self.commands.append("aclose")
+
+            redis = ClosableAsyncStreamRedis()
+            client = AsyncQueueClient(
+                QueueConfig(queue="events", backend="stream"),
+                redis=redis,
+                capabilities=RedisCapabilities(RedisVersion(4, 0, 14)),
+            )
+            with self.assertRaises(RedisCompatibilityError):
+                await client.consume(timeout=1)
+            return redis
+
+        redis = asyncio.run(run())
+
+        self.assertIn("aclose", redis.commands)
 
     def test_connection_managers_create_pooled_clients(self) -> None:
         manager = RedisConnectionManager(
@@ -685,6 +750,56 @@ class ProjectSkeletonTests(unittest.TestCase):
         finally:
             manager.close()
 
+    def test_sync_from_url_closes_owned_redis_when_initialization_fails(self) -> None:
+        class OwnedRedis(FakeListRedis):
+            def info(self, section: str | None = None) -> dict[str, str]:
+                return {"redis_version": "7.0.0"}
+
+        redis = OwnedRedis()
+
+        with self.assertRaises(QueueConfigError):
+            QueueClient.from_url(
+                "redis://127.0.0.1:6379/0",
+                queue="bad queue",
+                redis=redis,
+                owns_redis=True,
+            )
+
+        self.assertIn("close", redis.commands)
+
+    def test_sync_from_url_leaves_injected_redis_open_when_init_fails(self) -> None:
+        class InjectedRedis(FakeListRedis):
+            def info(self, section: str | None = None) -> dict[str, str]:
+                return {"redis_version": "7.0.0"}
+
+        redis = InjectedRedis()
+
+        with self.assertRaises(QueueConfigError):
+            QueueClient.from_url(
+                "redis://127.0.0.1:6379/0",
+                queue="bad queue",
+                redis=redis,
+            )
+
+        self.assertNotIn("close", redis.commands)
+
+    def test_sync_from_url_closes_owned_redis_when_capability_probe_fails(self) -> None:
+        class BrokenInfoRedis(FakeListRedis):
+            def info(self, section: str | None = None) -> dict[str, str]:
+                raise TimeoutError("redis unavailable")
+
+        redis = BrokenInfoRedis()
+
+        with self.assertRaises(BackendUnavailableError):
+            QueueClient.from_url(
+                "redis://127.0.0.1:6379/0",
+                queue="emails",
+                redis=redis,
+                owns_redis=True,
+            )
+
+        self.assertIn("close", redis.commands)
+
     def test_async_connection_manager_creates_pooled_clients(self) -> None:
         async def run() -> None:
             manager = AsyncRedisConnectionManager(
@@ -740,6 +855,65 @@ class ProjectSkeletonTests(unittest.TestCase):
 
         asyncio.run(run())
 
+    def test_async_from_url_closes_owned_redis_when_initialization_fails(self) -> None:
+        class OwnedAsyncRedis(FakeAsyncListRedis):
+            async def info(self, section: str | None = None) -> dict[str, str]:
+                return {"redis_version": "7.0.0"}
+
+        async def run() -> FakeAsyncListRedis:
+            redis = OwnedAsyncRedis()
+            with self.assertRaises(QueueConfigError):
+                await AsyncQueueClient.from_url(
+                    "redis://127.0.0.1:6379/0",
+                    queue="bad queue",
+                    redis=redis,
+                    owns_redis=True,
+                )
+            return redis
+
+        redis = asyncio.run(run())
+
+        self.assertIn("aclose", redis.commands)
+
+    def test_async_from_url_leaves_injected_redis_open_when_init_fails(self) -> None:
+        class InjectedAsyncRedis(FakeAsyncListRedis):
+            async def info(self, section: str | None = None) -> dict[str, str]:
+                return {"redis_version": "7.0.0"}
+
+        async def run() -> FakeAsyncListRedis:
+            redis = InjectedAsyncRedis()
+            with self.assertRaises(QueueConfigError):
+                await AsyncQueueClient.from_url(
+                    "redis://127.0.0.1:6379/0",
+                    queue="bad queue",
+                    redis=redis,
+                )
+            return redis
+
+        redis = asyncio.run(run())
+
+        self.assertNotIn("aclose", redis.commands)
+
+    def test_async_from_url_closes_owned_redis_on_probe_failure(self) -> None:
+        class BrokenInfoAsyncRedis(FakeAsyncListRedis):
+            async def info(self, section: str | None = None) -> dict[str, str]:
+                raise TimeoutError("redis unavailable")
+
+        async def run() -> FakeAsyncListRedis:
+            redis = BrokenInfoAsyncRedis()
+            with self.assertRaises(BackendUnavailableError):
+                await AsyncQueueClient.from_url(
+                    "redis://127.0.0.1:6379/0",
+                    queue="jobs",
+                    redis=redis,
+                    owns_redis=True,
+                )
+            return redis
+
+        redis = asyncio.run(run())
+
+        self.assertIn("aclose", redis.commands)
+
     def test_async_list_backend_ack_uses_original_serialized_payload(self) -> None:
         class NonDeterministicSerializer:
             content_type = "application/x-redqueue-test"