rabbitmq-amqp-python-client 2.0.0a1__tar.gz → 2.0.0a3__tar.gz

{rabbitmq_amqp_python_client-2.0.0a1 → rabbitmq_amqp_python_client-2.0.0a3}/.github/workflows/publish-pypi.yaml

@@ -25,14 +25,13 @@ jobs:
       id-token: write
     steps:
       - uses: actions/checkout@v3
-      - name: build with poetry
-        env:
-          REPO: ${{ inputs.pypi_repository_url }}
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: build
         run: |
-          curl -sSL https://install.python-poetry.org | python3 -
-          export PATH="/home/runner/.local/bin:$PATH"
-          poetry config repositories.test-pypi $REPO
-          poetry build
+          python3 -m pip install build
+          python3 -m build
       # retrieve your distributions here
       - name: Publish package distributions to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1

{rabbitmq_amqp_python_client-2.0.0a1 → rabbitmq_amqp_python_client-2.0.0a3}/Makefile

@@ -21,7 +21,7 @@ lint:
 	$(PYTHON) -m ruff format --check .
 
 typecheck:
-	$(PYTHON) -m mypy src
+	$(PYTHON) -m mypy rabbitmq_amqp_python_client
 	MYPYPATH=. $(PYTHON) -m mypy docs/examples
 
 build:

{rabbitmq_amqp_python_client-2.0.0a1 → rabbitmq_amqp_python_client-2.0.0a3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: rabbitmq-amqp-python-client
-Version: 2.0.0a1
+Version: 2.0.0a3
 Summary: A from-scratch AMQP 1.0 client for RabbitMQ, built directly against the wire protocol.
 Author: RabbitMQ Team
 License: Apache-2.0
@@ -42,7 +42,7 @@ pip install -e ".[dev]"
 ## Quick start
 
 ```python
-from src import Connection, ConnectionParameters, Context, Message
+from rabbitmq_amqp_python_client import Connection, ConnectionParameters, Context, Message
 
 connection = Connection(ConnectionParameters())  # localhost:5672, guest/guest
 try:
@@ -84,7 +84,7 @@ PYTHONPATH=. .venv/bin/python docs/examples/basic_connection.py
 make install          # create .venv and install the package with its dev extras
 make format           # ruff format, then ruff check --fix
 make lint             # ruff check and ruff format --check
-make typecheck        # mypy src, in strict mode
+make typecheck        # mypy rabbitmq_amqp_python_client, in strict mode
 make test-unit        # the unit suite; no broker needed
 make test-integration # the integration suite; needs a broker on localhost:5672
 make test             # both suites
@@ -98,7 +98,7 @@ MYPYPATH=. .venv/bin/python -m mypy docs/examples/*.py
 
 ## Project layout
 
-`src/` holds the client: `wire/` is the protocol
+`rabbitmq_amqp_python_client/` holds the client: `wire/` is the protocol
 layer (type codec, frames, performatives, messages, SASL) and knows nothing
 above itself, and `connection.py`, `session.py`, `link.py`, `management.py`,
 `publisher.py`, `consumer.py` and `reconnection.py` build the public API on top

{rabbitmq_amqp_python_client-2.0.0a1 → rabbitmq_amqp_python_client-2.0.0a3}/README.md

@@ -26,7 +26,7 @@ pip install -e ".[dev]"
 ## Quick start
 
 ```python
-from src import Connection, ConnectionParameters, Context, Message
+from rabbitmq_amqp_python_client import Connection, ConnectionParameters, Context, Message
 
 connection = Connection(ConnectionParameters())  # localhost:5672, guest/guest
 try:
@@ -68,7 +68,7 @@ PYTHONPATH=. .venv/bin/python docs/examples/basic_connection.py
 make install          # create .venv and install the package with its dev extras
 make format           # ruff format, then ruff check --fix
 make lint             # ruff check and ruff format --check
-make typecheck        # mypy src, in strict mode
+make typecheck        # mypy rabbitmq_amqp_python_client, in strict mode
 make test-unit        # the unit suite; no broker needed
 make test-integration # the integration suite; needs a broker on localhost:5672
 make test             # both suites
@@ -82,7 +82,7 @@ MYPYPATH=. .venv/bin/python -m mypy docs/examples/*.py
 
 ## Project layout
 
-`src/` holds the client: `wire/` is the protocol
+`rabbitmq_amqp_python_client/` holds the client: `wire/` is the protocol
 layer (type codec, frames, performatives, messages, SASL) and knows nothing
 above itself, and `connection.py`, `session.py`, `link.py`, `management.py`,
 `publisher.py`, `consumer.py` and `reconnection.py` build the public API on top

{rabbitmq_amqp_python_client-2.0.0a1 → rabbitmq_amqp_python_client-2.0.0a3}/docs/examples/README.md

@@ -24,5 +24,8 @@ one layer at a time, and the rest build on them.
 | [`direct_reply_to_example.py`](direct_reply_to_example.py) | Request/reply without a dedicated reply queue: `settle_strategy(ConsumerSettleStrategy.DIRECT_REPLY_TO)` attaches to no queue at all and reads back a broker-generated pseudo-queue address from `consumer.queue`; a request naming it as `properties.reply_to` gets answered by an ordinary queue-bound consumer publishing to that address. The pseudo-queue is session-scoped, so a forced disconnect and auto-reconnection leave the requester with a brand new address, which the script re-reads before sending its second request. |
 | [`rejection_reason_example.py`](rejection_reason_example.py) | Why a publish was refused: a quorum queue with `max_length(5)` and the `reject-publish` overflow strategy returns a `REJECTED` outcome carrying `RejectionDetails.reason` and `.rejected_by_queue` (needs RabbitMQ 4.3+; the script says so when the broker supplies neither). |
 | [`quorum_single_active_consumer.py`](quorum_single_active_consumer.py) | Single active consumer notifications on a quorum queue (needs RabbitMQ 4.3+): two consumers on a queue declared with `single_active_consumer(True)` each register a `single_active_consumer_state_changed` handler, and the broker tells one of them it is active and the other that it is standby. Only the active one receives messages; closing it promotes the standby one, which then starts receiving. |
+| [`delayed_retry_example.py`](delayed_retry_example.py) | Delaying a redelivery on a quorum queue (needs RabbitMQ 4.3+): a queue declared with `delayed_retry_type(QuorumQueueDelayedRetryType.FAILED)`, `delayed_retry_min(...)` and `delayed_retry_max(...)` holds a `context.discard()`-rejected message back for that window before redelivering it, while a `context.requeue()`-released one — a *returned*, not a *failed*, delivery, so `FAILED` does not cover it — comes back immediately. |
+| [`delayed_retry_context_example.py`](delayed_retry_context_example.py) | Per-message delayed retry (needs RabbitMQ 4.3+): `context.delayed_retry(delay)` stamps an `x-opt-delivery-time` annotation on one redelivery, holding it back for that message alone — no queue-level `x-delayed-retry-*` configuration required at all, unlike `delayed_retry_example.py` above. |
+| [`consumer_timeout_example.py`](consumer_timeout_example.py) | Consumer timeout (needs RabbitMQ 4.3+): `quorum().consumer_timeout(...)` sets the `rabbitmq:consumer-timeout` attach property, and `quorum().on_delivery_release(handler)` is called with a `TimeoutContext` when the broker force-releases a delivery held past that timeout — accepting it there is what lifts the broker's block on further delivery to that consumer. |
 | [`stream_filtering.py`](stream_filtering.py) | Reading a stream queue from a chosen offset and narrowing what arrives (needs RabbitMQ 4.2+ for the SQL filter): the same batch of messages is read back three times from `offset(FIRST)` — once with `filter().subject(...).property("region", ...)`, once with the equivalent `filter().sql(...)`, and once with the cheap, probabilistic `filter_values(...)` bloom filter, whose publisher side is just an `x-stream-filter-value` message annotation. The script reports whether the broker really enforces the SQL filter. |
 | [`tls_connection.py`](tls_connection.py) | TLS transport and certificate-based authentication (needs the broker's TLS listener enabled, `.ci/ubuntu/rabbitmq.conf`): one-way TLS with the broker's certificate verified against `.ci/certs/ca_certificate.pem`, then mutual TLS where a client certificate authenticates via SASL EXTERNAL (`sasl_external=True`) instead of a username/password, and finally — clearly separated and explicitly discouraged — a connection with verification disabled entirely. |

{rabbitmq_amqp_python_client-2.0.0a1 → rabbitmq_amqp_python_client-2.0.0a3}/docs/examples/auto_reconnection.py

@@ -27,7 +27,7 @@ import socket
 import time
 import uuid
 
-from src import (
+from rabbitmq_amqp_python_client import (
     AMQPError,
     Connection,
     ConnectionParameters,

{rabbitmq_amqp_python_client-2.0.0a1 → rabbitmq_amqp_python_client-2.0.0a3}/docs/examples/basic_connection.py

@@ -4,12 +4,12 @@ Run against a local broker::
 
     PYTHONPATH=. .venv/bin/python docs/examples/basic_connection.py
 
-Constructing a :class:`~src.Connection` dials the TCP
+Constructing a :class:`~rabbitmq_amqp_python_client.Connection` dials the TCP
 socket, exchanges the protocol header, runs SASL and the ``open`` handshake, and
 starts the frame reader — all before ``__init__`` returns. There is no separate
 ``connect()`` step: a constructed connection is already ``OPEN`` and usable.
 
-The default :class:`~src.ConnectionParameters` describe
+The default :class:`~rabbitmq_amqp_python_client.ConnectionParameters` describe
 exactly what a stock broker offers — ``localhost:5672``, ``guest``/``guest``, the
 ``/`` virtual host — so the no-argument form below is the shortest connection
 this client can make. What the broker sent back in its own ``open`` is readable
@@ -24,7 +24,7 @@ from __future__ import annotations
 
 import logging
 
-from src import Connection, ConnectionParameters
+from rabbitmq_amqp_python_client import Connection, ConnectionParameters
 
 logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)-7s %(name)s: %(message)s")
 logger = logging.getLogger("example")

{rabbitmq_amqp_python_client-2.0.0a1 → rabbitmq_amqp_python_client-2.0.0a3}/docs/examples/console_application.py

@@ -11,11 +11,11 @@ both confirmed and consumed, so this doubles as a scriptable smoke test::
     python3 docs/examples/console_application.py --help
 
 This program adds nothing to the client's public surface: it is built entirely
-out of :class:`~src.Connection`,
-:class:`~src.Management`,
-:class:`~src.Publisher`,
-:class:`~src.Consumer` and
-:class:`~src.RecoveryConfiguration`. It owns exactly one
+out of :class:`~rabbitmq_amqp_python_client.Connection`,
+:class:`~rabbitmq_amqp_python_client.Management`,
+:class:`~rabbitmq_amqp_python_client.Publisher`,
+:class:`~rabbitmq_amqp_python_client.Consumer` and
+:class:`~rabbitmq_amqp_python_client.RecoveryConfiguration`. It owns exactly one
 connection: it is a correctness/smoke-test tool, not a load generator.
 
 Exit codes:
@@ -49,7 +49,7 @@ _SOURCE_ROOT = Path(__file__).resolve().parents[2]
 if _SOURCE_ROOT.is_dir() and str(_SOURCE_ROOT) not in sys.path:
     sys.path.insert(0, str(_SOURCE_ROOT))
 
-from src import (  # noqa: E402 - after the sys.path bootstrap above
+from rabbitmq_amqp_python_client import (  # noqa: E402 - after the sys.path bootstrap above
     AMQPError,
     Connection,
     ConnectionParameters,
@@ -64,7 +64,7 @@ from src import (  # noqa: E402 - after the sys.path bootstrap above
 )
 
 if TYPE_CHECKING:
-    from src.connection import ConnectionState
+    from rabbitmq_amqp_python_client.connection import ConnectionState
 
 # --- exit codes (§7) ----------------------------------------------------
 
@@ -475,7 +475,7 @@ def map_queue_type(options: Options, specification: QueueSpecification) -> Queue
         specification: The builder from ``management.queue(name)``.
 
     Returns:
-        The same builder, ready to :meth:`~src.QueueSpecification.declare`.
+        The same builder, ready to :meth:`~rabbitmq_amqp_python_client.QueueSpecification.declare`.
 
     Raises:
         OptionsError: If ``queue_type`` is not one of :data:`QUEUE_TYPES`.

{rabbitmq_amqp_python_client-2.0.0a1 → rabbitmq_amqp_python_client-2.0.0a3}/docs/examples/consumer_example.py

@@ -8,7 +8,7 @@ A consumer is a receiver link plus a ``message_handler``. The link is granted
 ``initial_credits`` when it attaches, and the client re-grants one credit every
 time a delivery is settled, so at most that many messages are ever outstanding.
 The handler runs on the client's delivery thread and is handed a
-:class:`~src.Context` alongside the message; calling
+:class:`~rabbitmq_amqp_python_client.Context` alongside the message; calling
 ``context.accept()`` settles the delivery as ``accepted``, which is what tells
 the broker it may drop it. ``discard()`` and ``requeue()`` are the other two
 choices, and doing nothing leaves the delivery unsettled — visible as
@@ -28,7 +28,7 @@ import logging
 import queue
 import uuid
 
-from src import (
+from rabbitmq_amqp_python_client import (
     Connection,
     ConnectionParameters,
     Context,

rabbitmq_amqp_python_client-2.0.0a3/docs/examples/consumer_timeout_example.py

@@ -0,0 +1,135 @@
+"""Consumer timeout: ``rabbitmq:consumer-timeout`` and ``on_delivery_release`` (step_130).
+
+Run against a local RabbitMQ 4.3+ broker::
+
+    PYTHONPATH=. .venv/bin/python docs/examples/consumer_timeout_example.py
+
+RabbitMQ limits how long a consumer may hold a delivery unsettled before the
+broker takes it back and blocks further delivery to that link, until the
+client acknowledges the release. This client surfaces that as
+``quorum().consumer_timeout(...)`` (the ``rabbitmq:consumer-timeout`` attach
+property) plus ``quorum().on_delivery_release(handler)``, which is called once
+per delivery the broker force-releases this way — ``handler(context, message)``
+is given a :class:`TimeoutContext`, whose only valid settlement is
+``accept()``, and calling it is what lifts the broker's block.
+
+This script attaches a consumer with a short ``consumer_timeout`` and an
+``on_delivery_release`` handler that logs the release and accepts it,
+publishes one message whose handler deliberately sleeps past that timeout on
+its first delivery (settling normally afterward), observes the release fire
+and unlock the consumer, then publishes a second message and confirms it
+still arrives before closing everything down.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+import uuid
+
+from rabbitmq_amqp_python_client import (
+    Connection,
+    ConnectionParameters,
+    ConsumerError,
+    Context,
+    Message,
+    QueueType,
+    TimeoutContext,
+)
+
+#: The consumer's own rabbitmq:consumer-timeout, in milliseconds and seconds.
+CONSUMER_TIMEOUT_MS = 3_000
+CONSUMER_TIMEOUT_SECONDS = CONSUMER_TIMEOUT_MS / 1_000
+
+#: How long the example waits for something it expects to happen.
+TIMEOUT_SECONDS = 20.0
+
+logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)-7s %(name)s: %(message)s")
+logger = logging.getLogger("example")
+
+
+def consumer_timeout() -> None:
+    """Show a timed-out delivery released by the broker, and the consumer unlocked afterward."""
+    connection = Connection(ConnectionParameters(container_id=f"example-consumer-timeout-{uuid.uuid4().hex[:8]}"))
+    name = f"example-consumer-timeout-{uuid.uuid4().hex[:8]}"
+    try:
+        connection.management().queue(name).type(QueueType.QUORUM).declare()
+        logger.info("declared quorum queue %r", name)
+
+        released: list[tuple[TimeoutContext, Message]] = []
+        second_message: list[Message] = []
+        timeout_triggered = False
+
+        def on_delivery_release(context: TimeoutContext, message: Message) -> None:
+            logger.info(
+                "broker released %r past the %.1fs consumer-timeout; accepting",
+                message.body_as_string(),
+                CONSUMER_TIMEOUT_SECONDS,
+            )
+            context.accept()
+            released.append((context, message))
+
+        def on_message(context: Context, message: Message) -> None:
+            nonlocal timeout_triggered
+            if not timeout_triggered:
+                timeout_triggered = True
+                logger.info(
+                    "holding %r unsettled for %.1fs to trigger the consumer-timeout",
+                    message.body_as_string(),
+                    CONSUMER_TIMEOUT_SECONDS + 2,
+                )
+                time.sleep(CONSUMER_TIMEOUT_SECONDS + 2)
+                try:
+                    context.accept()
+                except ConsumerError:
+                    logger.info("as expected: the broker had already released this delivery")
+                return
+            context.accept()
+            second_message.append(message)
+            logger.info("second message %r arrived and was accepted normally", message.body_as_string())
+
+        consumer = (
+            connection.consumer_builder()
+            .queue(name)
+            .quorum()
+            .consumer_timeout(CONSUMER_TIMEOUT_MS)
+            .on_delivery_release(on_delivery_release)
+            .builder()
+            .message_handler(on_message)
+            .initial_credits(1)
+            .build()
+        )
+        logger.info("consumer attached with rabbitmq:consumer-timeout=%dms", CONSUMER_TIMEOUT_MS)
+
+        try:
+            publisher = connection.publisher_builder().queue(name).build()
+            try:
+                publisher.publish(Message("held-too-long"), timeout=TIMEOUT_SECONDS)
+
+                deadline = time.monotonic() + TIMEOUT_SECONDS
+                while not released and time.monotonic() < deadline:
+                    time.sleep(0.05)
+                if not released:
+                    raise TimeoutError(f"the broker never released the timed-out delivery within {TIMEOUT_SECONDS:g}s")
+                logger.info("on_delivery_release fired; the broker's block on this link should now be lifted")
+
+                publisher.publish(Message("second"), timeout=TIMEOUT_SECONDS)
+                deadline = time.monotonic() + TIMEOUT_SECONDS
+                while not second_message and time.monotonic() < deadline:
+                    time.sleep(0.05)
+                if not second_message:
+                    raise TimeoutError("the consumer was never unlocked: the second message never arrived")
+                logger.info("confirmed: the consumer is unlocked and receiving normally again")
+            finally:
+                publisher.close()
+        finally:
+            consumer.close()
+
+        connection.management().queue(name).delete()
+        logger.info("deleted the queue %r", name)
+    finally:
+        connection.close()
+
+
+if __name__ == "__main__":
+    consumer_timeout()

rabbitmq_amqp_python_client-2.0.0a3/docs/examples/delayed_retry_context_example.py

@@ -0,0 +1,101 @@
+"""Per-message delayed retry: ``context.delayed_retry(...)`` (step_120 §1-§2).
+
+Run against a local RabbitMQ 4.3+ broker::
+
+    PYTHONPATH=. .venv/bin/python docs/examples/delayed_retry_context_example.py
+
+``context.delayed_retry(delay, delivery_failed=False)`` is sugar over
+``context.requeue({"x-opt-delivery-time": now_ms + delay}, delivery_failed)``:
+it stamps a per-message redelivery hint directly on the message being
+requeued, so the queue holds that one redelivery back for at least ``delay``
+before trying again. Unlike ``delayed_retry_example.py``'s queue-level
+``x-delayed-retry-type``/``delayed_retry_min``/``delayed_retry_max`` (which
+apply to every redelivery on that queue, and require the queue to be declared
+with them up front), this mechanism needs **no** queue-level configuration at
+all — it works on a plain quorum queue, and the delay is chosen fresh on each
+call, message by message.
+
+This script declares a plain quorum queue (no ``x-delayed-retry-*``
+arguments), publishes one message, and has the handler call
+``delayed_retry(...)`` on the first delivery and ``accept()`` on the second —
+then measures and reports the elapsed time between the two, which must be at
+least the requested delay.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+import uuid
+
+from rabbitmq_amqp_python_client import (
+    Connection,
+    ConnectionParameters,
+    Context,
+    Message,
+    QueueType,
+)
+
+#: How long the second delivery is held back, in milliseconds and in seconds.
+DELAY_MS = 3_000
+DELAY_SECONDS = DELAY_MS / 1_000
+
+#: How long the example waits for a delivery it expects.
+TIMEOUT_SECONDS = 15.0
+
+logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)-7s %(name)s: %(message)s")
+logger = logging.getLogger("example")
+
+
+def delayed_retry_context() -> None:
+    """Show one message's redelivery held back by its own ``delayed_retry`` call."""
+    connection = Connection(ConnectionParameters(container_id=f"example-delayed-retry-context-{uuid.uuid4().hex[:8]}"))
+    name = f"example-delayed-retry-context-{uuid.uuid4().hex[:8]}"
+    try:
+        # A plain quorum queue: no x-delayed-retry-* arguments at all — the
+        # delay this example asks for comes entirely from the per-message
+        # x-opt-delivery-time annotation delayed_retry() stamps on.
+        connection.management().queue(name).type(QueueType.QUORUM).declare()
+        logger.info("declared plain quorum queue %r (no queue-level delayed-retry configuration)", name)
+
+        arrived_at: list[float] = []
+
+        def on_message(context: Context, message: Message) -> None:
+            arrived_at.append(time.monotonic())
+            if len(arrived_at) == 1:
+                logger.info("first delivery %r; delaying its retry by %dms", message.body_as_string(), DELAY_MS)
+                context.delayed_retry(DELAY_MS)
+            else:
+                logger.info("redelivery %r arrived; accepting", message.body_as_string())
+                context.accept()
+
+        consumer = connection.consumer_builder().queue(name).message_handler(on_message).initial_credits(1).build()
+        try:
+            publisher = connection.publisher_builder().queue(name).build()
+            try:
+                publisher.publish(Message("retry-me"), timeout=TIMEOUT_SECONDS)
+            finally:
+                publisher.close()
+
+            deadline = time.monotonic() + TIMEOUT_SECONDS
+            while len(arrived_at) < 2 and time.monotonic() < deadline:
+                time.sleep(0.05)
+            if len(arrived_at) < 2:
+                raise TimeoutError(f"the redelivery never arrived within {TIMEOUT_SECONDS:g}s")
+
+            elapsed = arrived_at[1] - arrived_at[0]
+            logger.info("the redelivery arrived after %.2fs (requested delay was %.2fs)", elapsed, DELAY_SECONDS)
+            assert elapsed >= DELAY_SECONDS * 0.5, (
+                f"delayed_retry should have held the redelivery back, took {elapsed:.2f}s"
+            )
+        finally:
+            consumer.close()
+
+        connection.management().queue(name).delete()
+        logger.info("deleted the queue %r", name)
+    finally:
+        connection.close()
+
+
+if __name__ == "__main__":
+    delayed_retry_context()

rabbitmq_amqp_python_client-2.0.0a3/docs/examples/delayed_retry_example.py

@@ -0,0 +1,146 @@
+"""Delayed retry on a quorum queue: a redelivery held back instead of instant
+(step_001_management.md §5.4).
+
+Run against a local RabbitMQ 4.3+ broker::
+
+    PYTHONPATH=. .venv/bin/python docs/examples/delayed_retry_example.py
+
+``QuorumQueueSpecification.delayed_retry_type(QuorumQueueDelayedRetryType.FAILED)``,
+paired with ``delayed_retry_min``/``delayed_retry_max``, sets ``x-delayed-retry-type``,
+``x-delayed-retry-min`` and ``x-delayed-retry-max`` on the declare. Once set, the
+queue holds a message aside for that window before redelivering it, rather than
+redelivering it the instant it comes back — but only for the *kind* of return
+the configured type names. Of the outcomes ``Context`` can send
+(step_030_consumers.md §4), only the two that leave a message eligible for
+redelivery at all take part in this: ``context.requeue(delivery_failed=True)``,
+which sends ``modified{delivery-failed=true, undeliverable-here=false}``, is a
+*failed* return; ``context.requeue()`` (``delivery_failed=False``), which sends
+``released``, is a *returned* one. (A terminal ``context.discard()`` — the
+``rejected`` outcome — is always dropped outright and plays no part in this;
+delayed retry only ever holds back a message that was going to be redelivered
+anyway.)
+
+* ``DISABLED`` (the default) never delays either kind;
+* ``ALL`` delays both kinds;
+* ``FAILED`` delays only a *failed* return;
+* ``RETURNED`` delays only a *returned* one.
+
+This script declares a queue with ``FAILED``, and shows both halves of that
+distinction on the same queue: a failed return comes back only after
+``delayed_retry_min`` has passed, while a returned one — not covered by
+``FAILED`` — comes back right away, exactly as it would with delayed retry
+disabled altogether.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+import uuid
+from collections.abc import Callable
+
+from rabbitmq_amqp_python_client import (
+    Connection,
+    ConnectionParameters,
+    Context,
+    ManagementError,
+    Message,
+    QuorumQueueDelayedRetryType,
+)
+from rabbitmq_amqp_python_client.management import STATUS_BAD_REQUEST
+
+#: How long a redelivery is held back, in milliseconds and in seconds.
+DELAYED_RETRY_MS = 3_000
+DELAYED_RETRY_SECONDS = DELAYED_RETRY_MS / 1_000
+
+#: How long the example waits for a delivery it expects.
+TIMEOUT_SECONDS = 15.0
+
+logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)-7s %(name)s: %(message)s")
+logger = logging.getLogger("example")
+
+
+def _consume_one_and_settle(
+    connection: Connection, name: str, settle: Callable[[Context], None]
+) -> tuple[Context, float]:
+    """Attach a fresh consumer, receive the queue's one message, settle it, and
+    return the context that was used plus when the delivery arrived.
+    """
+    delivered: list[tuple[Context, Message, float]] = []
+
+    def on_message(context: Context, message: Message) -> None:
+        delivered.append((context, message, time.monotonic()))
+
+    consumer = connection.consumer_builder().queue(name).message_handler(on_message).initial_credits(1).build()
+    try:
+        deadline = time.monotonic() + TIMEOUT_SECONDS
+        while not delivered and time.monotonic() < deadline:
+            time.sleep(0.05)
+        if not delivered:
+            raise TimeoutError(f"no delivery arrived within {TIMEOUT_SECONDS:g}s")
+        context, message, arrived_at = delivered[0]
+        settle(context)
+        return context, arrived_at
+    finally:
+        consumer.close()
+
+
+def delayed_retry() -> None:
+    """Show a failed return delayed by FAILED, and a returned one that is not."""
+    connection = Connection(ConnectionParameters(container_id=f"example-delayed-retry-{uuid.uuid4().hex[:8]}"))
+    name = f"example-delayed-retry-{uuid.uuid4().hex[:8]}"
+    try:
+        try:
+            (
+                connection.management()
+                .queue(name)
+                .quorum()
+                .delayed_retry_type(QuorumQueueDelayedRetryType.FAILED)
+                .delayed_retry_min(DELAYED_RETRY_MS)
+                .delayed_retry_max(DELAYED_RETRY_MS)
+                .queue()
+                .declare()
+            )
+        except ManagementError as error:
+            if error.status_code != STATUS_BAD_REQUEST:
+                raise
+            logger.warning("this broker does not support x-delayed-retry-* (needs RabbitMQ 4.3+); stopping here")
+            return
+        logger.info("declared %r with delayed_retry_type=FAILED, min=max=%dms", name, DELAYED_RETRY_MS)
+
+        publisher = connection.publisher_builder().queue(name).build()
+        try:
+            publisher.publish(Message("failed-return"), timeout=TIMEOUT_SECONDS)
+            _, failed_at = _consume_one_and_settle(
+                connection, name, lambda context: context.requeue(delivery_failed=True)
+            )
+            logger.info("requeued %r as a failed return; waiting for the delayed redelivery", "failed-return")
+            _, redelivered_at = _consume_one_and_settle(connection, name, lambda context: context.accept())
+            elapsed = redelivered_at - failed_at
+            logger.info(
+                "the failed return came back after %.2fs (delayed_retry_min=%.2fs)", elapsed, DELAYED_RETRY_SECONDS
+            )
+            assert elapsed >= DELAYED_RETRY_SECONDS * 0.5, (
+                f"FAILED should have delayed the failed return, took {elapsed:.2f}s"
+            )
+
+            publisher.publish(Message("returned"), timeout=TIMEOUT_SECONDS)
+            _, returned_at = _consume_one_and_settle(connection, name, lambda context: context.requeue())
+            logger.info("requeued %r as a returned delivery; not covered by FAILED", "returned")
+            _, redelivered_at = _consume_one_and_settle(connection, name, lambda context: context.accept())
+            elapsed = redelivered_at - returned_at
+            logger.info("the returned delivery came back after %.2fs — not delayed", elapsed)
+            assert elapsed < DELAYED_RETRY_SECONDS * 0.5, (
+                f"FAILED should not have delayed the returned delivery, took {elapsed:.2f}s"
+            )
+        finally:
+            publisher.close()
+
+        connection.management().queue(name).delete()
+        logger.info("deleted the queue %r", name)
+    finally:
+        connection.close()
+
+
+if __name__ == "__main__":
+    delayed_retry()

{rabbitmq_amqp_python_client-2.0.0a1 → rabbitmq_amqp_python_client-2.0.0a3}/docs/examples/direct_reply_to_example.py

@@ -12,7 +12,7 @@ dynamically generates a private, per-attach pseudo-queue address
 reply puts that address in an outgoing request's ``properties.reply_to``;
 whoever answers just needs to publish to it — no dedicated, exclusive reply
 queue to declare and clean up per requester. Like a presettled consumer, its
-``Context`` methods all raise :class:`~src.ConsumerError`: the broker considers
+``Context`` methods all raise :class:`~rabbitmq_amqp_python_client.ConsumerError`: the broker considers
 every delivery on this link already settled the instant it sends it.
 
 This script plays both roles, on two separate connections:
@@ -22,7 +22,7 @@ This script plays both roles, on two separate connections:
 * the **responder** (``responder_connection``) declares an ordinary request
   queue, consumes it with a normal ``ExplicitSettle`` consumer, and replies to
   whatever address arrived in the request's ``reply_to`` — an ordinary
-  anonymous :class:`~src.Publisher` (step_020_publishers.md §3.3) also sends
+  anonymous :class:`~rabbitmq_amqp_python_client.Publisher` (step_020_publishers.md §3.3) also sends
   the request itself, targeting the request queue.
 
 Because the pseudo-queue is scoped to the exact connection and session that
@@ -43,7 +43,7 @@ import socket
 import time
 import uuid
 
-from src import (
+from rabbitmq_amqp_python_client import (
     Connection,
     ConnectionParameters,
     ConnectionState,
@@ -55,7 +55,7 @@ from src import (
     RecoveryConfiguration,
     queue_address,
 )
-from src.wire import Properties
+from rabbitmq_amqp_python_client.wire import Properties
 
 #: How long the example waits for a reply it expects.
 TIMEOUT_SECONDS = 15.0

{rabbitmq_amqp_python_client-2.0.0a1 → rabbitmq_amqp_python_client-2.0.0a3}/docs/examples/management_example.py

@@ -14,7 +14,7 @@ request message out and one response message back, correlated by
 The script walks the whole surface once:
 
 1. ``queue(name).declare()`` declares a classic queue and returns a
-   :class:`~src.QueueInfo` parsed from the broker's
+   :class:`~rabbitmq_amqp_python_client.QueueInfo` parsed from the broker's
    answer, so the queue's real settings are readable straight away;
 2. ``exchange(name).type(ExchangeType.TOPIC).declare()`` declares a topic
    exchange;
@@ -26,7 +26,7 @@ The script walks the whole surface once:
 
 Declaring is idempotent as long as the arguments match: re-declaring the same
 queue is a successful no-op, while re-declaring it with different arguments is a
-:class:`~src.ManagementError`.
+:class:`~rabbitmq_amqp_python_client.ManagementError`.
 """
 
 from __future__ import annotations
@@ -34,7 +34,7 @@ from __future__ import annotations
 import logging
 import uuid
 
-from src import (
+from rabbitmq_amqp_python_client import (
     Connection,
     ConnectionParameters,
     ExchangeType,