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

redis_message_queue-8.2.2/.gitignore

@@ -0,0 +1,167 @@
+.DS_Store
+
+# Claude Code
+.claude/
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+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
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Ruff
+.ruff_cache/
+
+# Coverage tooling output
+lcov.info
+
+# PyPI upload config — credentials, never commit
+.pypirc
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/

redis_message_queue-8.2.0/README.md → redis_message_queue-8.2.2/PKG-INFO

@@ -1,6 +1,29 @@
+Metadata-Version: 2.4
+Name: redis-message-queue
+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
+Project-URL: Issues, https://github.com/Elijas/redis-message-queue/issues
+Author-email: Elijas <4084885+Elijas@users.noreply.github.com>
+License: MIT
+License-File: LICENSE
+Keywords: deduplication,message-queue,redis,task-queue
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Distributed Computing
+Requires-Python: <4.0,>=3.12
+Requires-Dist: redis<8.0.0,>=5.0.1
+Requires-Dist: tenacity>=8.1.0
+Description-Content-Type: text/markdown
+
 # redis-message-queue
 
-[![PyPI Version](https://img.shields.io/badge/v8.0.1-version?color=43cd0f&style=flat&label=pypi)](https://pypi.org/project/redis-message-queue)
+[![PyPI Version](https://img.shields.io/pypi/v/redis-message-queue?color=43cd0f&style=flat&label=pypi)](https://pypi.org/project/redis-message-queue)
 [![PyPI Downloads](https://img.shields.io/pypi/dm/redis-message-queue?color=43cd0f&style=flat&label=downloads)](https://pypistats.org/packages/redis-message-queue)
 [![License: MIT](https://img.shields.io/badge/License-MIT-43cd0f.svg?style=flat&label=license)](LICENSE)
 [![Maintained: yes](https://img.shields.io/badge/yes-43cd0f.svg?style=flat&label=maintained)](https://github.com/Elijas/redis-message-queue/issues)
@@ -11,7 +34,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.0.0,<9.0.0"
+pip install "redis-message-queue>=8.2.2,<9.0.0"
 ```
 
 Requires Redis server >= 6.2.
@@ -22,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
 
@@ -35,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
 ```
 
@@ -46,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
 
@@ -66,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
@@ -202,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`.
@@ -474,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
@@ -706,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
@@ -800,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:
@@ -814,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
@@ -1015,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.
@@ -1064,13 +1121,13 @@ Try the [examples](https://github.com/Elijas/redis-message-queue/tree/main/examp
 
 ```bash
 # Two publishers
-poetry run python -m examples.send_messages
-poetry run python -m examples.send_messages
+uv run python -m examples.send_messages
+uv run python -m examples.send_messages
 
 # Three consumers
-poetry run python -m examples.receive_messages
-poetry run python -m examples.receive_messages
-poetry run python -m examples.receive_messages
+uv run python -m examples.receive_messages
+uv run python -m examples.receive_messages
+uv run python -m examples.receive_messages
 ```
 
 ![GitHub Repo stars](https://img.shields.io/github/stars/elijas/redis-message-queue?style=flat&color=fcfcfc&labelColor=white&logo=github&logoColor=black&label=stars)

redis_message_queue-8.2.0/PKG-INFO → redis_message_queue-8.2.2/README.md

@@ -1,32 +1,6 @@
-Metadata-Version: 2.4
-Name: redis-message-queue
-Version: 8.2.0
-Summary: Python message queuing with Redis and message deduplication
-License: MIT
-License-File: LICENSE
-Keywords: redis,message-queue,deduplication,task-queue
-Author: Elijas
-Author-email: 4084885+Elijas@users.noreply.github.com
-Requires-Python: >=3.12,<4.0
-Classifier: Development Status :: 5 - Production/Stable
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Classifier: Topic :: Software Development :: Libraries
-Classifier: Topic :: System :: Distributed Computing
-Requires-Dist: redis (>=5.0.0,<8.0.0)
-Requires-Dist: tenacity (>=8.1.0)
-Project-URL: Homepage, https://github.com/Elijas/redis-message-queue
-Project-URL: Issues, https://github.com/Elijas/redis-message-queue/issues
-Project-URL: Repository, https://github.com/Elijas/redis-message-queue
-Description-Content-Type: text/markdown
-
 # redis-message-queue
 
-[![PyPI Version](https://img.shields.io/badge/v8.0.1-version?color=43cd0f&style=flat&label=pypi)](https://pypi.org/project/redis-message-queue)
+[![PyPI Version](https://img.shields.io/pypi/v/redis-message-queue?color=43cd0f&style=flat&label=pypi)](https://pypi.org/project/redis-message-queue)
 [![PyPI Downloads](https://img.shields.io/pypi/dm/redis-message-queue?color=43cd0f&style=flat&label=downloads)](https://pypistats.org/packages/redis-message-queue)
 [![License: MIT](https://img.shields.io/badge/License-MIT-43cd0f.svg?style=flat&label=license)](LICENSE)
 [![Maintained: yes](https://img.shields.io/badge/yes-43cd0f.svg?style=flat&label=maintained)](https://github.com/Elijas/redis-message-queue/issues)
@@ -37,7 +11,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.0.0,<9.0.0"
+pip install "redis-message-queue>=8.2.2,<9.0.0"
 ```
 
 Requires Redis server >= 6.2.
@@ -48,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
 
@@ -61,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
 ```
 
@@ -72,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
 
@@ -92,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
@@ -228,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`.
@@ -500,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
@@ -732,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
@@ -826,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:
@@ -840,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
@@ -1041,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.
@@ -1090,14 +1098,13 @@ Try the [examples](https://github.com/Elijas/redis-message-queue/tree/main/examp
 
 ```bash
 # Two publishers
-poetry run python -m examples.send_messages
-poetry run python -m examples.send_messages
+uv run python -m examples.send_messages
+uv run python -m examples.send_messages
 
 # Three consumers
-poetry run python -m examples.receive_messages
-poetry run python -m examples.receive_messages
-poetry run python -m examples.receive_messages
+uv run python -m examples.receive_messages
+uv run python -m examples.receive_messages
+uv run python -m examples.receive_messages
 ```
 
 ![GitHub Repo stars](https://img.shields.io/github/stars/elijas/redis-message-queue?style=flat&color=fcfcfc&labelColor=white&logo=github&logoColor=black&label=stars)
-

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

@@ -1,11 +1,11 @@
-[tool.poetry]
+[project]
 name = "redis-message-queue"
-version = "8.2.0"
+version = "8.2.2"
 description = "Python message queuing with Redis and message deduplication"
-authors = ["Elijas <4084885+Elijas@users.noreply.github.com>"]
+authors = [{ name = "Elijas", email = "4084885+Elijas@users.noreply.github.com" }]
 readme = "README.md"
-license = "MIT"
-include = ["redis_message_queue/py.typed"]
+license = { text = "MIT" }
+license-files = ["LICENSE"]
 keywords = ["redis", "message-queue", "deduplication", "task-queue"]
 classifiers = [
     "Development Status :: 5 - Production/Stable",
@@ -16,26 +16,65 @@ classifiers = [
     "Topic :: Software Development :: Libraries",
     "Topic :: System :: Distributed Computing",
 ]
+requires-python = ">=3.12,<4.0"
+dependencies = [
+    "redis>=5.0.1,<8.0.0",
+    "tenacity>=8.1.0",
+]
 
-[tool.poetry.urls]
+[project.urls]
 Homepage = "https://github.com/Elijas/redis-message-queue"
 Repository = "https://github.com/Elijas/redis-message-queue"
 Issues = "https://github.com/Elijas/redis-message-queue/issues"
 
-[tool.poetry.dependencies]
-python = "^3.12"
-redis = ">=5.0.0,<8.0.0"
-tenacity = ">=8.1.0"
+[dependency-groups]
+dev = [
+    "bump-my-version>=1.1.2",
+    "mypy",
+    "ruff",
+]
+test = [
+    "fakeredis[lua]",
+    "pytest",
+    "pytest-asyncio",
+    "pytest-cov",
+]
+
+[tool.uv]
+default-groups = ["dev", "test"]
 
-[tool.poetry.group.test.dependencies]
-pytest = "*"
-pytest-asyncio = "*"
-pytest-cov = "*"
-fakeredis = {version = "*", extras = ["lua"]}
+##############################
+### BUMP VERSION
+##############################
+
+[tool.bumpversion]
+current_version = "8.2.2"
+parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
+serialize = ["{major}.{minor}.{patch}"]
+search = "{current_version}"
+replace = "{new_version}"
+regex = false
+ignore_missing_version = false
+ignore_missing_files = false
+tag = false
+sign_tags = false
+tag_name = "v{new_version}"
+tag_message = "Bump version: {current_version} -> {new_version}"
+allow_dirty = true
+commit = true
+message = "chore(release): bump version from {current_version} to {new_version}"
+moveable_tags = []
+commit_args = ""
+setup_hooks = []
+pre_commit_hooks = []
+post_commit_hooks = []
 
 [build-system]
-requires = ["poetry-core"]
-build-backend = "poetry.core.masonry.api"
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build]
+packages = ["redis_message_queue"]
 
 [tool.ruff]
 target-version = "py312"
@@ -45,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.0 → 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.0 → 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.0 → 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.0 → 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