redis-message-queue 8.2.8__tar.gz → 8.2.9__tar.gz

{redis_message_queue-8.2.8 → redis_message_queue-8.2.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: redis-message-queue
-Version: 8.2.8
+Version: 8.2.9
 Summary: Python message queuing with Redis and message deduplication
 Project-URL: Homepage, https://github.com/Elijas/redis-message-queue
 Project-URL: Repository, https://github.com/Elijas/redis-message-queue
@@ -34,7 +34,7 @@ Description-Content-Type: text/markdown
 **Lightweight Python message queuing with Redis and built-in publish-side deduplication.** Deduplicate publishes within a TTL window, with optional crash recovery — across any number of producers and consumers.
 
 ```bash
-pip install "redis-message-queue>=8.2.8,<9.0.0"
+pip install "redis-message-queue>=8.2.9,<9.0.0"
 ```
 
 Requires Redis server >= 6.2.
@@ -848,6 +848,11 @@ Pre-commit and mid-flight exceptions:
   exceptions. Under an ambiguous lost response, Redis may have committed
   despite the exception. Treat them as "operation did not succeed from the
   caller's perspective", not "Redis did not commit".
+- Visibility-timeout claim-store write failures raise
+  `ClaimStoreFailedError` and emit `claim/failure`. When the compensating
+  return-to-pending write succeeds, the payload is back in pending; if
+  return-to-pending also fails, the payload remains in processing so there is
+  still a live queue copy.
 
 #### Drain events
 
@@ -875,11 +880,6 @@ The following operations have no `on_event` surface by design:
   preserves queue safety on Cluster `CROSSSLOT` rejection but cannot be
   observed through `on_event`. Operators watching key-TTL behavior or Redis
   slow logs can detect orphans.
-- **VT claim-store OOM compensation:** if the visibility-timeout Lua script
-  cannot store the claim result, it removes the message from processing, pushes
-  it back to pending, and returns `false`. Python translates that into
-  `claim_empty/skipped`, the same shape as an empty poll. This is intentional
-  fail-safe behavior; the message is not lost.
 - **`drop_oldest` evictions:** when publish backpressure uses
   `pending_overload_policy="drop_oldest"`, the oldest pending message is
   discarded before the new message is enqueued. The successful enqueue emits
@@ -890,14 +890,22 @@ The following operations have no `on_event` surface by design:
   terminal operation's failure event. There is no per-attempt event for those
   paths.
 
-The public exception hierarchy is rooted at `RedisMessageQueueError`.
-Configuration value/combinations raise `ConfigurationError` (also a
-`ValueError`), custom gateway contract violations raise `GatewayContractError`
-(also a `TypeError`), and Lua `redis.error_reply(...)` failures raise
-`LuaScriptError` (also a redis-py `ResponseError`). Publish overload raises
-`QueueBackpressureError`; publish after explicit drain raises
-`QueueDrainedError`. `CleanupFailedError` and `RetryBudgetExhaustedError` are
-reserved categories for cleanup and retry surfaces.
+The public exception hierarchy is rooted at `RedisMessageQueueError`. The
+current exported queue-owned exception classes are:
+
+- `RedisMessageQueueError` (base)
+  - `ClaimStoreFailedError` - visibility-timeout claim metadata could not be stored
+  - `ConfigurationError` - invalid constructor args; also a `ValueError`
+  - `DrainFailedError` - drain pending-claim recovery failed
+  - `GatewayContractError` - custom gateway protocol violation; also a `TypeError`
+  - `LuaScriptError` - Lua `redis.error_reply(...)`; also a redis-py `ResponseError`
+  - `MalformedStoredMessageError` - stored value is not a valid RMQ envelope
+  - `PayloadTooLargeError` - serialized payload exceeds `max_payload_bytes`; also a `ValueError`
+  - `PayloadTooDeepError` - payload nesting exceeds `max_payload_depth`; also a `ValueError`
+  - `QueueBackpressureError` - `pending_overload_policy="raise"` rejected enqueue
+  - `QueueDrainedError` - `publish()` called after explicit drain/aclose
+  - `CleanupFailedError` - cleanup after handler completion failed
+  - `RetryBudgetExhaustedError` - Redis retry budget exhausted; also a redis-py `RedisError`
 
 ## Known limitations
 

{redis_message_queue-8.2.8 → redis_message_queue-8.2.9}/README.md

@@ -11,7 +11,7 @@
 **Lightweight Python message queuing with Redis and built-in publish-side deduplication.** Deduplicate publishes within a TTL window, with optional crash recovery — across any number of producers and consumers.
 
 ```bash
-pip install "redis-message-queue>=8.2.8,<9.0.0"
+pip install "redis-message-queue>=8.2.9,<9.0.0"
 ```
 
 Requires Redis server >= 6.2.
@@ -825,6 +825,11 @@ Pre-commit and mid-flight exceptions:
   exceptions. Under an ambiguous lost response, Redis may have committed
   despite the exception. Treat them as "operation did not succeed from the
   caller's perspective", not "Redis did not commit".
+- Visibility-timeout claim-store write failures raise
+  `ClaimStoreFailedError` and emit `claim/failure`. When the compensating
+  return-to-pending write succeeds, the payload is back in pending; if
+  return-to-pending also fails, the payload remains in processing so there is
+  still a live queue copy.
 
 #### Drain events
 
@@ -852,11 +857,6 @@ The following operations have no `on_event` surface by design:
   preserves queue safety on Cluster `CROSSSLOT` rejection but cannot be
   observed through `on_event`. Operators watching key-TTL behavior or Redis
   slow logs can detect orphans.
-- **VT claim-store OOM compensation:** if the visibility-timeout Lua script
-  cannot store the claim result, it removes the message from processing, pushes
-  it back to pending, and returns `false`. Python translates that into
-  `claim_empty/skipped`, the same shape as an empty poll. This is intentional
-  fail-safe behavior; the message is not lost.
 - **`drop_oldest` evictions:** when publish backpressure uses
   `pending_overload_policy="drop_oldest"`, the oldest pending message is
   discarded before the new message is enqueued. The successful enqueue emits
@@ -867,14 +867,22 @@ The following operations have no `on_event` surface by design:
   terminal operation's failure event. There is no per-attempt event for those
   paths.
 
-The public exception hierarchy is rooted at `RedisMessageQueueError`.
-Configuration value/combinations raise `ConfigurationError` (also a
-`ValueError`), custom gateway contract violations raise `GatewayContractError`
-(also a `TypeError`), and Lua `redis.error_reply(...)` failures raise
-`LuaScriptError` (also a redis-py `ResponseError`). Publish overload raises
-`QueueBackpressureError`; publish after explicit drain raises
-`QueueDrainedError`. `CleanupFailedError` and `RetryBudgetExhaustedError` are
-reserved categories for cleanup and retry surfaces.
+The public exception hierarchy is rooted at `RedisMessageQueueError`. The
+current exported queue-owned exception classes are:
+
+- `RedisMessageQueueError` (base)
+  - `ClaimStoreFailedError` - visibility-timeout claim metadata could not be stored
+  - `ConfigurationError` - invalid constructor args; also a `ValueError`
+  - `DrainFailedError` - drain pending-claim recovery failed
+  - `GatewayContractError` - custom gateway protocol violation; also a `TypeError`
+  - `LuaScriptError` - Lua `redis.error_reply(...)`; also a redis-py `ResponseError`
+  - `MalformedStoredMessageError` - stored value is not a valid RMQ envelope
+  - `PayloadTooLargeError` - serialized payload exceeds `max_payload_bytes`; also a `ValueError`
+  - `PayloadTooDeepError` - payload nesting exceeds `max_payload_depth`; also a `ValueError`
+  - `QueueBackpressureError` - `pending_overload_policy="raise"` rejected enqueue
+  - `QueueDrainedError` - `publish()` called after explicit drain/aclose
+  - `CleanupFailedError` - cleanup after handler completion failed
+  - `RetryBudgetExhaustedError` - Redis retry budget exhausted; also a redis-py `RedisError`
 
 ## Known limitations
 

{redis_message_queue-8.2.8 → redis_message_queue-8.2.9}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "redis-message-queue"
-version = "8.2.8"
+version = "8.2.9"
 description = "Python message queuing with Redis and message deduplication"
 authors = [{ name = "Elijas", email = "4084885+Elijas@users.noreply.github.com" }]
 readme = "README.md"
@@ -48,7 +48,7 @@ default-groups = ["dev", "test"]
 ##############################
 
 [tool.bumpversion]
-current_version = "8.2.8"
+current_version = "8.2.9"
 parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
 serialize = ["{major}.{minor}.{patch}"]
 search = "{current_version}"

{redis_message_queue-8.2.8 → redis_message_queue-8.2.9}/redis_message_queue/asyncio/redis_message_queue.py

@@ -87,6 +87,12 @@ def _warning_exception_name(exc: BaseException) -> str:
     return type(exc).__name__
 
 
+def _warn_runtime_warning(message: str, *, stacklevel: int) -> None:
+    with warnings.catch_warnings():
+        warnings.simplefilter("always", RuntimeWarning)
+        warnings.warn(message, RuntimeWarning, stacklevel=stacklevel + 1)
+
+
 def _find_non_string_dict_keys(value: object) -> list[object]:
     non_str_keys: list[object] = []
     seen: set[int] = set()
@@ -1273,7 +1279,7 @@ class RedisMessageQueue:
                         message_id=message_id,
                         lease_token_hash=lease_token_hash,
                     )
-                    warnings.warn(_STALE_LEASE_NACK_WARNING, RuntimeWarning, stacklevel=2)
+                    _warn_runtime_warning(_STALE_LEASE_NACK_WARNING, stacklevel=2)
             except BaseException as cleanup_exc:
                 # The handler exception is the user-visible failure; cleanup failure is secondary.
                 logger.exception("Failed to clean up message from processing queue")
@@ -1286,10 +1292,9 @@ class RedisMessageQueue:
                     error=cleanup_exc,
                     duration_ms=_duration_ms(cleanup_started_at),
                 )
-                warnings.warn(
+                _warn_runtime_warning(
                     f"Cleanup raised after handler exception ({_warning_exception_name(cleanup_exc)}); "
                     "see logs for both tracebacks",
-                    RuntimeWarning,
                     stacklevel=2,
                 )
             raise
@@ -1349,7 +1354,7 @@ class RedisMessageQueue:
                     message_id=message_id,
                     lease_token_hash=lease_token_hash,
                 )
-                warnings.warn(_STALE_LEASE_ACK_WARNING, RuntimeWarning, stacklevel=2)
+                _warn_runtime_warning(_STALE_LEASE_ACK_WARNING, stacklevel=2)
             finished_without_error = True
         finally:
             if lease_heartbeat is not None:
@@ -1438,9 +1443,8 @@ class RedisMessageQueue:
                     exception_type=type(exc).__name__,
                     error=exc,
                 )
-                warnings.warn(
+                _warn_runtime_warning(
                     f"Failed to trim queue {destination_queue} ({type(exc).__name__}); list may exceed max_*_length",
-                    RuntimeWarning,
                     stacklevel=3,
                 )
 

{redis_message_queue-8.2.8 → redis_message_queue-8.2.9}/redis_message_queue/redis_message_queue.py

@@ -100,6 +100,12 @@ def _warning_exception_name(exc: BaseException) -> str:
     return type(exc).__name__
 
 
+def _warn_runtime_warning(message: str, *, stacklevel: int) -> None:
+    with warnings.catch_warnings():
+        warnings.simplefilter("always", RuntimeWarning)
+        warnings.warn(message, RuntimeWarning, stacklevel=stacklevel + 1)
+
+
 def _find_non_string_dict_keys(value: object) -> list[object]:
     non_str_keys: list[object] = []
     seen: set[int] = set()
@@ -339,12 +345,16 @@ def _close_or_cancel_awaitable(awaitable: object) -> None:
         try:
             close()
             return
+        except asyncio.CancelledError:
+            pass
         except Exception:
             pass
     cancel = getattr(awaitable, "cancel", None)
     if callable(cancel):
         try:
             cancel()
+        except asyncio.CancelledError:
+            pass
         except Exception:
             pass
 
@@ -1235,7 +1245,7 @@ class RedisMessageQueue:
                         message_id=message_id,
                         lease_token_hash=lease_token_hash,
                     )
-                    warnings.warn(_STALE_LEASE_NACK_WARNING, RuntimeWarning, stacklevel=2)
+                    _warn_runtime_warning(_STALE_LEASE_NACK_WARNING, stacklevel=2)
             except BaseException as cleanup_exc:
                 # The handler exception is the user-visible failure; cleanup failure is secondary.
                 logger.exception("Failed to clean up message from processing queue")
@@ -1248,10 +1258,9 @@ class RedisMessageQueue:
                     error=cleanup_exc,
                     duration_ms=_duration_ms(cleanup_started_at),
                 )
-                warnings.warn(
+                _warn_runtime_warning(
                     f"Cleanup raised after handler exception ({_warning_exception_name(cleanup_exc)}); "
                     "see logs for both tracebacks",
-                    RuntimeWarning,
                     stacklevel=2,
                 )
             raise
@@ -1310,7 +1319,7 @@ class RedisMessageQueue:
                     message_id=message_id,
                     lease_token_hash=lease_token_hash,
                 )
-                warnings.warn(_STALE_LEASE_ACK_WARNING, RuntimeWarning, stacklevel=2)
+                _warn_runtime_warning(_STALE_LEASE_ACK_WARNING, stacklevel=2)
         finally:
             if lease_heartbeat is not None:
                 lease_heartbeat.stop()
@@ -1400,9 +1409,8 @@ class RedisMessageQueue:
                     exception_type=type(exc).__name__,
                     error=exc,
                 )
-                warnings.warn(
+                _warn_runtime_warning(
                     f"Failed to trim queue {destination_queue} ({type(exc).__name__}); list may exceed max_*_length",
-                    RuntimeWarning,
                     stacklevel=3,
                 )