redis-message-queue 8.2.1__tar.gz → 8.2.2__tar.gz

{redis_message_queue-8.2.1 → redis_message_queue-8.2.2}/.gitignore

@@ -90,7 +90,7 @@ ipython_config.py
 # pyenv
 #   For a library or package, you might want to ignore these files since the code is
 #   intended to run in multiple environments; otherwise, check them in:
-# .python-version
+.python-version
 
 # pipenv
 #   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
@@ -141,6 +141,15 @@ venv.bak/
 .dmypy.json
 dmypy.json
 
+# Ruff
+.ruff_cache/
+
+# Coverage tooling output
+lcov.info
+
+# PyPI upload config — credentials, never commit
+.pypirc
+
 # Pyre type checker
 .pyre/
 

{redis_message_queue-8.2.1 → redis_message_queue-8.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: redis-message-queue
-Version: 8.2.1
+Version: 8.2.2
 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.1,<9.0.0"
+pip install "redis-message-queue>=8.2.2,<9.0.0"
 ```
 
 Requires Redis server >= 6.2.
@@ -45,6 +45,7 @@ Redis must be running locally first: use `redis-server` or
 `docker run -p 6379:6379 redis:7`.
 
 ```python
+import json
 from redis import Redis
 from redis_message_queue import RedisMessageQueue
 
@@ -58,7 +59,8 @@ queue = RedisMessageQueue(
 queue.publish({"id": "msg-1", "text": "hello"})
 with queue.process_message() as message:
     if message is not None:
-        print(f"got {message['text']}")
+        payload = json.loads(message)
+        print(f"got {payload['text']}")
 # Expected output: got hello
 ```
 
@@ -69,13 +71,15 @@ with queue.process_message() as message:
 > synchronous. If your handler is `async def`, returns a coroutine, or returns
 > any other awaitable, use `redis_message_queue.asyncio.RedisMessageQueue`.
 > The sync context manager does not inspect the handler's return value; an
-> unawaited coroutine can be dropped while the message is acked. An ergonomic
-> callback API that detects this is planned for v8.1.
+> unawaited coroutine can be dropped while the message is acked. For sync
+> callback-style handlers, use `process_message_callback(handler)`: it checks
+> for awaitable returns before acking and raises `TypeError` if one is returned.
 
 ### Async quickstart
 
 ```python
 import asyncio
+import json
 from redis.asyncio import Redis
 from redis_message_queue.asyncio import RedisMessageQueue
 
@@ -89,7 +93,8 @@ async def main():
     )
     await queue.publish({"id": "msg-1", "text": "hello"})
     async with queue.process_message() as message:
-        print(f"got {message['text']}")
+        payload = json.loads(message)
+        print(f"got {payload['text']}")
     await client.aclose()
 
 asyncio.run(main())  # Expected output: got hello
@@ -225,7 +230,9 @@ so concurrent publishers cannot race above the configured cap. Overload policies
 - `drop_oldest` removes the oldest pending message (`RPOP`) before enqueueing the
   new message. This is silent data loss by design; deduplication markers for
   dropped messages are not removed, so a dropped duplicate may still be
-  suppressed until its dedup TTL expires.
+  suppressed until its dedup TTL expires. The current event contract emits
+  `publish/success` for the new message, but no separate `on_event` signal for
+  the dropped message.
 - `block` retries the atomic check until space opens or
   `pending_overload_block_timeout_seconds` elapses (default: 1.0), then raises
   `QueueBackpressureError`.
@@ -497,6 +504,14 @@ gateway = RedisGateway(
 queue = RedisMessageQueue("q", gateway=gateway)
 ```
 
+When `gateway=` is supplied, queue-level constructor defaults are not copied
+into the gateway. For example, `RedisMessageQueue(..., gateway=gateway)`
+leaves visibility timeout and dead-letter routing disabled unless
+`message_visibility_timeout_seconds` and `max_delivery_count` are configured on
+the gateway itself. Passing the queue-level default values
+`visibility_timeout_seconds=300` or `max_delivery_count=10` with `gateway=`
+does not transfer those settings to the gateway.
+
 The retry knobs configure an internal `tenacity` strategy: exponential
 backoff with jitter, retry on transient Redis errors only, capped at
 `retry_budget_seconds`. The budget is monotonic elapsed time from the first attempt (including attempt duration), not inter-attempt delay; it is unaffected by Python-host NTP jumps. A single attempt that takes longer than the budget results in zero retries. Setting `retry_budget_seconds=0` disables retry
@@ -729,8 +744,8 @@ queue = RedisMessageQueue("jobs", client=client, on_event=on_event)
 ```
 
 Events cover publish, dedup hits, claim/empty polls, reclaim, ack/nack,
-completed/failed cleanup, DLQ moves, heartbeat renewal, stale leases, cleanup
-and trim failures, and retry attempts. Callback exceptions are logged and
+completed/failed cleanup, DLQ moves, heartbeat renewal, stale leases, drain,
+cleanup and trim failures, and retry attempts. Callback exceptions are logged and
 reported with `RuntimeWarning`, but never propagate into queue operations.
 `on_event` is telemetry only: use it for metrics, tracing, and logging, not for
 sagas, follow-up writes, billing callbacks, or other correctness-critical
@@ -823,6 +838,23 @@ Pre-commit and mid-flight exceptions:
   despite the exception. Treat them as "operation did not succeed from the
   caller's perspective", not "Redis did not commit".
 
+#### Drain events
+
+`drain()` and `close()` on the sync queue, and `drain()` and `aclose()` on the
+async queue, emit `drain` events:
+
+- `drain/start` when the queue-local drain flag is set.
+- `drain/success` when pending claim IDs were recovered or no gateway drain
+  hook is present.
+- `drain/skipped` when the queue was already drained and the cached successful
+  result is returned.
+- `drain/failure` when pending claim recovery times out or otherwise leaves
+  unresolved claim IDs.
+
+Drain events use `timeout_seconds` for the caller-supplied timeout,
+`pending_claim_ids` for the number of unresolved local claim IDs when known,
+and `exception_type` / `error` on failure.
+
 #### Intentionally silent paths
 
 The following operations have no `on_event` surface by design:
@@ -837,9 +869,11 @@ The following operations have no `on_event` surface by design:
   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.
-- **`drain()` / `close()` / `aclose()` lifecycle:** explicit shutdown
-  operations do not emit lifecycle events. Pending-claim-drain recovery work
-  counts as `claim_reclaim` events when reached.
+- **`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
+  `publish/success`, but there is no separate drop event for the discarded
+  message in the current feature set.
 - **Non-claim-loop retry attempts:** tenacity retries in deduplicated publish,
   ack/remove, move-to-completed/failed, and lease renewal collapse into the
   terminal operation's failure event. There is no per-attempt event for those
@@ -1038,7 +1072,7 @@ v6.0.0 is a non-breaking-defaults release that adds new public APIs. v5 code con
 
 - `max_pending_length=N` caps pending-list depth; with `pending_overload_policy="raise"` (default) producers see `QueueBackpressureError` when the cap is hit; `"block"` waits up to `pending_overload_block_timeout_seconds`; `"drop_oldest"` evicts silently, so use it only when data loss is acceptable.
 - `queue.drain(timeout=...)` (sync) and `await queue.aclose(timeout=...)` (async) are explicit graceful-shutdown hooks. They refuse new claims and recover pending claim IDs but do not cancel in-flight handlers; join or await your worker separately.
-- `on_event=callback` receives a `QueueEvent` dataclass for every publish/claim/ack/reclaim/dedup/cleanup lifecycle event. Use it for metrics, tracing, and structured logging. See [`examples/production/observability.py`](examples/production/observability.py) for the adapter pattern.
+- `on_event=callback` receives a `QueueEvent` dataclass for publish/claim/ack/reclaim/dedup/cleanup/drain lifecycle events. Use it for metrics, tracing, and structured logging. See [`examples/production/observability.py`](examples/production/observability.py) for the adapter pattern.
 - See [`examples/production/backpressure.py`](examples/production/backpressure.py) and [`examples/production/graceful_shutdown.py`](examples/production/graceful_shutdown.py) for sync production patterns, with async siblings under [`examples/production/asyncio/`](examples/production/asyncio/).
 
 > When using a pre-fork app server (gunicorn `--preload`, uvicorn workers that import the app at master startup), call `make_queue()` from your worker startup hook - NOT at module import. See [Fork safety](#fork-safety-and-pre-fork-servers) for why.

{redis_message_queue-8.2.1 → redis_message_queue-8.2.2}/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.1,<9.0.0"
+pip install "redis-message-queue>=8.2.2,<9.0.0"
 ```
 
 Requires Redis server >= 6.2.
@@ -22,6 +22,7 @@ Redis must be running locally first: use `redis-server` or
 `docker run -p 6379:6379 redis:7`.
 
 ```python
+import json
 from redis import Redis
 from redis_message_queue import RedisMessageQueue
 
@@ -35,7 +36,8 @@ queue = RedisMessageQueue(
 queue.publish({"id": "msg-1", "text": "hello"})
 with queue.process_message() as message:
     if message is not None:
-        print(f"got {message['text']}")
+        payload = json.loads(message)
+        print(f"got {payload['text']}")
 # Expected output: got hello
 ```
 
@@ -46,13 +48,15 @@ with queue.process_message() as message:
 > synchronous. If your handler is `async def`, returns a coroutine, or returns
 > any other awaitable, use `redis_message_queue.asyncio.RedisMessageQueue`.
 > The sync context manager does not inspect the handler's return value; an
-> unawaited coroutine can be dropped while the message is acked. An ergonomic
-> callback API that detects this is planned for v8.1.
+> unawaited coroutine can be dropped while the message is acked. For sync
+> callback-style handlers, use `process_message_callback(handler)`: it checks
+> for awaitable returns before acking and raises `TypeError` if one is returned.
 
 ### Async quickstart
 
 ```python
 import asyncio
+import json
 from redis.asyncio import Redis
 from redis_message_queue.asyncio import RedisMessageQueue
 
@@ -66,7 +70,8 @@ async def main():
     )
     await queue.publish({"id": "msg-1", "text": "hello"})
     async with queue.process_message() as message:
-        print(f"got {message['text']}")
+        payload = json.loads(message)
+        print(f"got {payload['text']}")
     await client.aclose()
 
 asyncio.run(main())  # Expected output: got hello
@@ -202,7 +207,9 @@ so concurrent publishers cannot race above the configured cap. Overload policies
 - `drop_oldest` removes the oldest pending message (`RPOP`) before enqueueing the
   new message. This is silent data loss by design; deduplication markers for
   dropped messages are not removed, so a dropped duplicate may still be
-  suppressed until its dedup TTL expires.
+  suppressed until its dedup TTL expires. The current event contract emits
+  `publish/success` for the new message, but no separate `on_event` signal for
+  the dropped message.
 - `block` retries the atomic check until space opens or
   `pending_overload_block_timeout_seconds` elapses (default: 1.0), then raises
   `QueueBackpressureError`.
@@ -474,6 +481,14 @@ gateway = RedisGateway(
 queue = RedisMessageQueue("q", gateway=gateway)
 ```
 
+When `gateway=` is supplied, queue-level constructor defaults are not copied
+into the gateway. For example, `RedisMessageQueue(..., gateway=gateway)`
+leaves visibility timeout and dead-letter routing disabled unless
+`message_visibility_timeout_seconds` and `max_delivery_count` are configured on
+the gateway itself. Passing the queue-level default values
+`visibility_timeout_seconds=300` or `max_delivery_count=10` with `gateway=`
+does not transfer those settings to the gateway.
+
 The retry knobs configure an internal `tenacity` strategy: exponential
 backoff with jitter, retry on transient Redis errors only, capped at
 `retry_budget_seconds`. The budget is monotonic elapsed time from the first attempt (including attempt duration), not inter-attempt delay; it is unaffected by Python-host NTP jumps. A single attempt that takes longer than the budget results in zero retries. Setting `retry_budget_seconds=0` disables retry
@@ -706,8 +721,8 @@ queue = RedisMessageQueue("jobs", client=client, on_event=on_event)
 ```
 
 Events cover publish, dedup hits, claim/empty polls, reclaim, ack/nack,
-completed/failed cleanup, DLQ moves, heartbeat renewal, stale leases, cleanup
-and trim failures, and retry attempts. Callback exceptions are logged and
+completed/failed cleanup, DLQ moves, heartbeat renewal, stale leases, drain,
+cleanup and trim failures, and retry attempts. Callback exceptions are logged and
 reported with `RuntimeWarning`, but never propagate into queue operations.
 `on_event` is telemetry only: use it for metrics, tracing, and logging, not for
 sagas, follow-up writes, billing callbacks, or other correctness-critical
@@ -800,6 +815,23 @@ Pre-commit and mid-flight exceptions:
   despite the exception. Treat them as "operation did not succeed from the
   caller's perspective", not "Redis did not commit".
 
+#### Drain events
+
+`drain()` and `close()` on the sync queue, and `drain()` and `aclose()` on the
+async queue, emit `drain` events:
+
+- `drain/start` when the queue-local drain flag is set.
+- `drain/success` when pending claim IDs were recovered or no gateway drain
+  hook is present.
+- `drain/skipped` when the queue was already drained and the cached successful
+  result is returned.
+- `drain/failure` when pending claim recovery times out or otherwise leaves
+  unresolved claim IDs.
+
+Drain events use `timeout_seconds` for the caller-supplied timeout,
+`pending_claim_ids` for the number of unresolved local claim IDs when known,
+and `exception_type` / `error` on failure.
+
 #### Intentionally silent paths
 
 The following operations have no `on_event` surface by design:
@@ -814,9 +846,11 @@ The following operations have no `on_event` surface by design:
   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.
-- **`drain()` / `close()` / `aclose()` lifecycle:** explicit shutdown
-  operations do not emit lifecycle events. Pending-claim-drain recovery work
-  counts as `claim_reclaim` events when reached.
+- **`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
+  `publish/success`, but there is no separate drop event for the discarded
+  message in the current feature set.
 - **Non-claim-loop retry attempts:** tenacity retries in deduplicated publish,
   ack/remove, move-to-completed/failed, and lease renewal collapse into the
   terminal operation's failure event. There is no per-attempt event for those
@@ -1015,7 +1049,7 @@ v6.0.0 is a non-breaking-defaults release that adds new public APIs. v5 code con
 
 - `max_pending_length=N` caps pending-list depth; with `pending_overload_policy="raise"` (default) producers see `QueueBackpressureError` when the cap is hit; `"block"` waits up to `pending_overload_block_timeout_seconds`; `"drop_oldest"` evicts silently, so use it only when data loss is acceptable.
 - `queue.drain(timeout=...)` (sync) and `await queue.aclose(timeout=...)` (async) are explicit graceful-shutdown hooks. They refuse new claims and recover pending claim IDs but do not cancel in-flight handlers; join or await your worker separately.
-- `on_event=callback` receives a `QueueEvent` dataclass for every publish/claim/ack/reclaim/dedup/cleanup lifecycle event. Use it for metrics, tracing, and structured logging. See [`examples/production/observability.py`](examples/production/observability.py) for the adapter pattern.
+- `on_event=callback` receives a `QueueEvent` dataclass for publish/claim/ack/reclaim/dedup/cleanup/drain lifecycle events. Use it for metrics, tracing, and structured logging. See [`examples/production/observability.py`](examples/production/observability.py) for the adapter pattern.
 - See [`examples/production/backpressure.py`](examples/production/backpressure.py) and [`examples/production/graceful_shutdown.py`](examples/production/graceful_shutdown.py) for sync production patterns, with async siblings under [`examples/production/asyncio/`](examples/production/asyncio/).
 
 > When using a pre-fork app server (gunicorn `--preload`, uvicorn workers that import the app at master startup), call `make_queue()` from your worker startup hook - NOT at module import. See [Fork safety](#fork-safety-and-pre-fork-servers) for why.

{redis_message_queue-8.2.1 → redis_message_queue-8.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "redis-message-queue"
-version = "8.2.1"
+version = "8.2.2"
 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.1"
+current_version = "8.2.2"
 parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
 serialize = ["{major}.{minor}.{patch}"]
 search = "{current_version}"
@@ -84,6 +84,12 @@ line-length = 120
 select = ["E", "F", "I", "W"]
 ignore = ["E731"]
 
+[tool.mypy]
+python_version = "3.12"
+files = ["redis_message_queue/"]
+explicit_package_bases = true
+show_error_codes = true
+
 [tool.pytest.ini_options]
 asyncio_default_fixture_loop_scope = "function"
 filterwarnings = [

{redis_message_queue-8.2.1 → redis_message_queue-8.2.2}/redis_message_queue/_redis_gateway.py

@@ -301,8 +301,8 @@ class RedisGateway(AbstractRedisGateway):
 
     def _emit_event(
         self,
-        operation: EventOperation,
-        outcome: EventOutcome,
+        operation: EventOperation | str,
+        outcome: EventOutcome | str,
         *,
         message_id: str | None = None,
         claim_id: str | None = None,
@@ -328,7 +328,7 @@ class RedisGateway(AbstractRedisGateway):
 
     def _emit_repeated_event(
         self,
-        operation: EventOperation,
+        operation: EventOperation | str,
         attempts: list[_MessageAttemptEvent],
         *,
         destination_queue: str | None = None,

{redis_message_queue-8.2.1 → redis_message_queue-8.2.2}/redis_message_queue/asyncio/_redis_gateway.py

@@ -275,8 +275,8 @@ class RedisGateway(AbstractRedisGateway):
 
     async def _emit_event(
         self,
-        operation: EventOperation,
-        outcome: EventOutcome,
+        operation: EventOperation | str,
+        outcome: EventOutcome | str,
         *,
         message_id: str | None = None,
         claim_id: str | None = None,
@@ -302,7 +302,7 @@ class RedisGateway(AbstractRedisGateway):
 
     async def _emit_repeated_event(
         self,
-        operation: EventOperation,
+        operation: EventOperation | str,
         attempts: list[_MessageAttemptEvent],
         *,
         destination_queue: str | None = None,

{redis_message_queue-8.2.1 → redis_message_queue-8.2.2}/redis_message_queue/asyncio/redis_message_queue.py

@@ -11,7 +11,6 @@ from typing import AsyncIterator, Awaitable, Callable, Literal, Optional, TypeVa
 import redis.asyncio
 import redis.exceptions
 
-from redis_message_queue._callable_utils import is_async_callable
 from redis_message_queue._config import (
     DEFAULT_PENDING_OVERLOAD_BLOCK_TIMEOUT_SECONDS,
     validate_dedup_configuration,
@@ -332,8 +331,12 @@ def _derive_dead_letter_queue(name: str, key_separator: str) -> str:
     return f"{name}{key_separator}{_AUTO_DEAD_LETTER_QUEUE_SUFFIX}"
 
 
-def _bind_dead_letter_gateway_to_queue(gateway: AbstractRedisGateway, queue_pending_key: str) -> None:
-    """Reject reuse of a dead-letter-enabled gateway across different queues.
+def _bind_dead_letter_gateway_to_queue(
+    gateway: AbstractRedisGateway,
+    queue_pending_key: str,
+    queue_processing_key: str,
+) -> None:
+    """Validate and bind a dead-letter-enabled gateway to this queue.
 
     The check is not thread-safe: constructing ``RedisMessageQueue`` instances
     concurrently on multiple threads with the same DLQ-enabled gateway can
@@ -346,6 +349,12 @@ def _bind_dead_letter_gateway_to_queue(gateway: AbstractRedisGateway, queue_pend
     if max_delivery_count is None:
         return
 
+    if gateway.dead_letter_queue in (queue_pending_key, queue_processing_key):
+        raise ConfigurationError(
+            "'dead_letter_queue' must be distinct from the queue's pending and processing Redis keys. "
+            "Use a separate Redis list key for poison messages."
+        )
+
     bound_pending_key = getattr(gateway, _GATEWAY_BOUND_PENDING_QUEUE_ATTR, None)
     if bound_pending_key is None:
         setattr(gateway, _GATEWAY_BOUND_PENDING_QUEUE_ATTR, queue_pending_key)
@@ -451,7 +460,7 @@ class _LeaseHeartbeat:
                 stacklevel=2,
             )
 
-    async def _emit(self, operation: EventOperation, outcome: EventOutcome, **kwargs: object) -> None:
+    async def _emit(self, operation: EventOperation | str, outcome: EventOutcome | str, **kwargs: object) -> None:
         if self._emit_event is not None:
             await self._emit_event(operation, outcome, **kwargs)
 
@@ -597,6 +606,11 @@ class RedisMessageQueue:
         auto-derived dead-letter queue. Set it to ``None`` for unlimited
         redelivery.
 
+        When ``gateway=`` is supplied, queue-level defaults are not transferred
+        to the gateway. Configure lease, dead-letter, and backpressure settings
+        such as ``message_visibility_timeout_seconds``, ``max_delivery_count``,
+        and ``max_pending_length`` on the gateway itself.
+
         ``deduplication=True`` requires ``get_deduplication_key`` to be a
         callable that returns a non-empty string. Use a stable logical ID for
         the deduplication keyspace.
@@ -636,11 +650,11 @@ class RedisMessageQueue:
         ``GracefulInterruptHandler()`` for prompt Ctrl-C / termination handling
         in polling waits. ``on_heartbeat_failure`` is a zero-argument callable
         or coroutine callable invoked when lease renewal fails. ``on_event`` is
-        telemetry only: an async callback receiving best-effort QueueEvent
-        lifecycle notifications. Callback failures are logged and converted to
-        RuntimeWarning without influencing ack/nack or any other message
-        outcome. Do not use it for correctness-critical callbacks or follow-up
-        writes.
+        telemetry only: a callable returning an awaitable and receiving
+        best-effort QueueEvent lifecycle notifications. Callback failures are
+        logged and converted to RuntimeWarning without influencing ack/nack or
+        any other message outcome. Do not use it for correctness-critical
+        callbacks or follow-up writes.
         """
         self.key = QueueKeyManager(name, key_separator=key_separator)
         if not isinstance(deduplication, bool):
@@ -742,8 +756,6 @@ class RedisMessageQueue:
             )
         if on_event is not None and not callable(on_event):
             raise TypeError(f"'on_event' must be callable, got {type(on_event).__name__}.")
-        if on_event is not None and not is_async_callable(on_event):
-            raise TypeError("'on_event' must be an async callable.")
         self._queue_name = name
         self._on_event = on_event
         # Queue-local soft-drain flag. See sync queue ``_draining`` docstring
@@ -825,7 +837,7 @@ class RedisMessageQueue:
                     "'max_pending_length' cannot be provided alongside 'gateway'."
                     " Configure publish backpressure on the gateway directly instead."
                 )
-            _bind_dead_letter_gateway_to_queue(gateway, self.key.pending)
+            _bind_dead_letter_gateway_to_queue(gateway, self.key.pending, self.key.processing)
             self._max_delivery_count = None
             self._redis = gateway
         elif client is None:
@@ -867,8 +879,8 @@ class RedisMessageQueue:
 
     async def _emit_event(
         self,
-        operation: EventOperation,
-        outcome: EventOutcome,
+        operation: EventOperation | str,
+        outcome: EventOutcome | str,
         *,
         message_id: str | None = None,
         claim_id: str | None = None,

{redis_message_queue-8.2.1 → redis_message_queue-8.2.2}/redis_message_queue/redis_message_queue.py

@@ -273,8 +273,12 @@ def _derive_dead_letter_queue(name: str, key_separator: str) -> str:
     return f"{name}{key_separator}{_AUTO_DEAD_LETTER_QUEUE_SUFFIX}"
 
 
-def _bind_dead_letter_gateway_to_queue(gateway: AbstractRedisGateway, queue_pending_key: str) -> None:
-    """Reject reuse of a dead-letter-enabled gateway across different queues.
+def _bind_dead_letter_gateway_to_queue(
+    gateway: AbstractRedisGateway,
+    queue_pending_key: str,
+    queue_processing_key: str,
+) -> None:
+    """Validate and bind a dead-letter-enabled gateway to this queue.
 
     The check is not thread-safe: constructing ``RedisMessageQueue`` instances
     concurrently on multiple threads with the same DLQ-enabled gateway can
@@ -287,6 +291,12 @@ def _bind_dead_letter_gateway_to_queue(gateway: AbstractRedisGateway, queue_pend
     if max_delivery_count is None:
         return
 
+    if gateway.dead_letter_queue in (queue_pending_key, queue_processing_key):
+        raise ConfigurationError(
+            "'dead_letter_queue' must be distinct from the queue's pending and processing Redis keys. "
+            "Use a separate Redis list key for poison messages."
+        )
+
     bound_pending_key = getattr(gateway, _GATEWAY_BOUND_PENDING_QUEUE_ATTR, None)
     if bound_pending_key is None:
         setattr(gateway, _GATEWAY_BOUND_PENDING_QUEUE_ATTR, queue_pending_key)
@@ -407,7 +417,7 @@ class _LeaseHeartbeat:
                 stacklevel=2,
             )
 
-    def _emit(self, operation: EventOperation, outcome: EventOutcome, **kwargs: object) -> None:
+    def _emit(self, operation: EventOperation | str, outcome: EventOutcome | str, **kwargs: object) -> None:
         if self._emit_event is not None:
             self._emit_event(operation, outcome, **kwargs)
 
@@ -549,6 +559,11 @@ class RedisMessageQueue:
         auto-derived dead-letter queue. Set it to ``None`` for unlimited
         redelivery.
 
+        When ``gateway=`` is supplied, queue-level defaults are not transferred
+        to the gateway. Configure lease, dead-letter, and backpressure settings
+        such as ``message_visibility_timeout_seconds``, ``max_delivery_count``,
+        and ``max_pending_length`` on the gateway itself.
+
         ``deduplication=True`` requires ``get_deduplication_key`` to be a
         callable that returns a non-empty string. Use a stable logical ID for
         the deduplication keyspace.
@@ -786,7 +801,7 @@ class RedisMessageQueue:
                     "'max_pending_length' cannot be provided alongside 'gateway'."
                     " Configure publish backpressure on the gateway directly instead."
                 )
-            _bind_dead_letter_gateway_to_queue(gateway, self.key.pending)
+            _bind_dead_letter_gateway_to_queue(gateway, self.key.pending, self.key.processing)
             self._max_delivery_count = None
             self._redis = gateway
         elif client is None:
@@ -827,8 +842,8 @@ class RedisMessageQueue:
 
     def _emit_event(
         self,
-        operation: EventOperation,
-        outcome: EventOutcome,
+        operation: EventOperation | str,
+        outcome: EventOutcome | str,
         *,
         message_id: str | None = None,
         claim_id: str | None = None,
@@ -1031,8 +1046,9 @@ class RedisMessageQueue:
         does not inspect handler return values; if your handler returns a
         coroutine or other awaitable, the awaitable can be dropped while the
         message is acked. Use ``redis_message_queue.asyncio.RedisMessageQueue``
-        for async handlers. An ergonomic callback API that detects this is
-        planned for v8.1.
+        for async handlers. For sync callback-style handlers, use
+        ``process_message_callback(handler)`` so awaitable returns are detected
+        before acking.
 
         If the process is killed mid-handler, the claimed message and lease
         metadata remain in Redis until a later consumer claim triggers