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

rabbitmq_amqp_python_client-2.0.0b1/.dockerignore

@@ -0,0 +1,15 @@
+.git
+.github
+.venv
+.mypy_cache
+.pytest_cache
+.ruff_cache
+.idea
+.claude
+__pycache__
+*.pyc
+dist
+build
+*.egg-info
+tests
+.ci

{rabbitmq_amqp_python_client-2.0.0a1 → rabbitmq_amqp_python_client-2.0.0b1}/.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.0b1}/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.0b1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: rabbitmq-amqp-python-client
-Version: 2.0.0a1
+Version: 2.0.0-beta.1
 Summary: A from-scratch AMQP 1.0 client for RabbitMQ, built directly against the wire protocol.
 Author: RabbitMQ Team
 License: Apache-2.0
@@ -18,13 +18,23 @@ Description-Content-Type: text/markdown
 
 RabbitMQ AMQP 1.0 Python client version 2.x for RabbitMQ 4.x.
 
-This client version built from scratch. The primary reason for this rewrite is to remove the dependency on the `qpid-proton` C library present in version 1, providing a fully native Python client. 
+This client version built from scratch.</br> 
+The primary reason for this rewrite is to remove the dependency on the `qpid-proton` C library present in version 1.0, providing a fully native Python client, see [here](https://github.com/rabbitmq/rabbitmq-amqp-python-client/discussions/123). 
 This client is inspired by the Java and .NET AMQP 1.0 clients, aiming to deliver the same behavior and user experience across ecosystems.
 
 The client is different from 1.0 and not compatible, so read the documentation before updating the client.
 
 
-## Installation
+## Install 
+
+The client is distributed via [`PIP`](https://pypi.org/project/rabbitmq-amqp-python-client/):
+```bash
+ pip install rabbitmq-amqp-python-client==2.0.0ax
+```
+
+
+
+## Build from source
 
 ```sh
 python3 -m venv .venv
@@ -42,7 +52,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 +94,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 +108,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.0b1}/README.md

@@ -2,13 +2,23 @@
 
 RabbitMQ AMQP 1.0 Python client version 2.x for RabbitMQ 4.x.
 
-This client version built from scratch. The primary reason for this rewrite is to remove the dependency on the `qpid-proton` C library present in version 1, providing a fully native Python client. 
+This client version built from scratch.</br> 
+The primary reason for this rewrite is to remove the dependency on the `qpid-proton` C library present in version 1.0, providing a fully native Python client, see [here](https://github.com/rabbitmq/rabbitmq-amqp-python-client/discussions/123). 
 This client is inspired by the Java and .NET AMQP 1.0 clients, aiming to deliver the same behavior and user experience across ecosystems.
 
 The client is different from 1.0 and not compatible, so read the documentation before updating the client.
 
 
-## Installation
+## Install 
+
+The client is distributed via [`PIP`](https://pypi.org/project/rabbitmq-amqp-python-client/):
+```bash
+ pip install rabbitmq-amqp-python-client==2.0.0ax
+```
+
+
+
+## Build from source
 
 ```sh
 python3 -m venv .venv
@@ -26,7 +36,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 +78,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 +92,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.0b1}/docs/examples/README.md

@@ -18,11 +18,15 @@ one layer at a time, and the rest build on them.
 | [`publisher_example.py`](publisher_example.py) | The three targets a publisher can have — a queue, an exchange plus a routing key, and none at all. The anonymous publisher sends to two different addresses over one link by setting `properties.to` per message, and a publish to an unbound routing key shows a `RELEASED` outcome, which is not an error. |
 | [`consumer_example.py`](consumer_example.py) | A `message_handler` that accepts and counts every delivery, `unsettled_message_count` while it does, and `pause()`/`unpause()` as flow control: messages published while paused stay queued and arrive the moment credit is restored. |
 | [`auto_reconnection.py`](auto_reconnection.py) | A connection surviving a forced socket drop: publishers and consumers built before the drop keep working afterwards, and `RecoveryConfiguration(topology=True)` re-declares the topology the broker lost. |
-| [`console_application.py`](console_application.py) | The whole client end to end — declare, publish, consume, report — as a scriptable smoke test with meaningful exit codes. `--help` lists its options. |
+| [`console_application.py`](console_application.py) | The whole client end to end — declare, publish, consume, report — as a scriptable smoke test with meaningful exit codes. `--help` lists its options, every one of which also has an `AMQP_*` environment-variable override; see [`docker/`](docker/) for running it as a container configured entirely that way. |
+| [`reliable.py`](reliable.py) | Modeled on [rabbitmq-amqp-go-client's own `reliable` example](https://github.com/rabbitmq/rabbitmq-amqp-go-client/tree/main/docs/examples/reliable): a publisher and a consumer built once on a quorum queue and left running while a broker disconnect/reconnect can happen at any point without either being rebuilt, with every publish outcome classified and periodic stats logged throughout. Configured entirely through environment variables, no command-line flags; see [`docker/reliable/`](docker/reliable/) for running it as a container. |
 | [`performance_test.py`](performance_test.py) | A throughput/latency generator: many publishers and consumers on one or more connections, with periodic rate and latency reporting. |
 | [`presettled_consumer_example.py`](presettled_consumer_example.py) | At-most-once consumption: `settle_strategy(ConsumerSettleStrategy.PRESETTLED)` attaches with `snd-settle-mode = settled`, so the broker settles every delivery itself, the handler never touches its `Context`, and `unsettled_message_count` stays at `0` for the consumer's whole life — including across a forced disconnect that auto-reconnection recovers from. |
 | [`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.0b1}/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.0b1}/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.0b1}/docs/examples/console_application.py

@@ -10,12 +10,21 @@ both confirmed and consumed, so this doubles as a scriptable smoke test::
     python3 docs/examples/console_application.py --messages 500 --queue-type quorum
     python3 docs/examples/console_application.py --help
 
+Every flag also has an ``AMQP_*`` environment variable that sets its default
+(a flag given on the command line always wins); see each flag's ``--help``
+text for its variable's name. That is what lets docs/examples/docker/Dockerfile
+run this script as a container configured entirely through ``docker run -e``,
+with nothing broker-specific baked into the image::
+
+    docker build -f docs/examples/docker/Dockerfile -t console-application .
+    docker run --rm -e AMQP_HOST=rabbitmq -e AMQP_MESSAGES=500 console-application
+
 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:
@@ -33,6 +42,7 @@ from __future__ import annotations
 
 import argparse
 import logging
+import os
 import ssl
 import sys
 import threading
@@ -44,12 +54,15 @@ from pathlib import Path
 from typing import TYPE_CHECKING, TextIO
 
 # Make the client importable when this example is run straight from a checkout,
-# with neither the package installed nor PYTHONPATH set.
-_SOURCE_ROOT = Path(__file__).resolve().parents[2]
-if _SOURCE_ROOT.is_dir() and str(_SOURCE_ROOT) not in sys.path:
+# with neither the package installed nor PYTHONPATH set. Guarded by a length
+# check because a containerized copy of this script (see docs/examples/docker/)
+# lives too shallow in the image's filesystem for a third parent to exist.
+_RESOLVED_PARENTS = Path(__file__).resolve().parents
+_SOURCE_ROOT = _RESOLVED_PARENTS[2] if len(_RESOLVED_PARENTS) > 2 else None
+if _SOURCE_ROOT is not None and _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 +77,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) ----------------------------------------------------
 
@@ -93,6 +106,79 @@ QUEUE_TYPES = (QUEUE_TYPE_CLASSIC, QUEUE_TYPE_QUORUM, QUEUE_TYPE_STREAM)
 #: Prefix of the queue name generated when ``--queue`` is not given.
 GENERATED_QUEUE_PREFIX = "console-app-"
 
+# --- environment overrides (§2) -----------------------------------------
+#
+# Every flag below also reads an ``AMQP_*`` environment variable as its
+# default, before argparse's own default applies; a flag given on the command
+# line always wins. This is what lets docs/examples/docker/Dockerfile
+# configure a run entirely through ``docker run -e``, with no broker detail
+# baked into the image.
+
+_ENV_TRUE_VALUES = frozenset({"1", "true", "yes", "on"})
+_ENV_FALSE_VALUES = frozenset({"0", "false", "no", "off"})
+
+
+def _env_str(name: str, default: str) -> str:
+    """Return the string environment variable ``name``, or ``default`` if unset."""
+    return os.environ.get(name, default)
+
+
+def _env_optional_int(name: str) -> int | None:
+    """Return ``name`` parsed as an int, or ``None`` if unset.
+
+    Raises:
+        OptionsError: If ``name`` is set but is not a valid integer.
+    """
+    value = os.environ.get(name)
+    if value is None:
+        return None
+    try:
+        return int(value)
+    except ValueError:
+        raise OptionsError(f"{name}={value!r} is not a valid integer") from None
+
+
+def _env_int(name: str, default: int) -> int:
+    """Return ``name`` parsed as an int, or ``default`` if unset."""
+    value = _env_optional_int(name)
+    return default if value is None else value
+
+
+def _env_float(name: str, default: float) -> float:
+    """Return ``name`` parsed as a float, or ``default`` if unset.
+
+    Raises:
+        OptionsError: If ``name`` is set but is not a valid float.
+    """
+    value = os.environ.get(name)
+    if value is None:
+        return default
+    try:
+        return float(value)
+    except ValueError:
+        raise OptionsError(f"{name}={value!r} is not a valid float") from None
+
+
+def _env_bool(name: str, default: bool) -> bool:
+    """Return the boolean ``name`` is set to, or ``default`` if unset.
+
+    Accepts ``1``/``true``/``yes``/``on`` and ``0``/``false``/``no``/``off``,
+    case-insensitively.
+
+    Raises:
+        OptionsError: If ``name`` is set to anything else.
+    """
+    value = os.environ.get(name)
+    if value is None:
+        return default
+    normalized = value.strip().lower()
+    if normalized in _ENV_TRUE_VALUES:
+        return True
+    if normalized in _ENV_FALSE_VALUES:
+        return False
+    raise OptionsError(f"{name}={value!r} is not a valid boolean (true/false, yes/no, on/off, 1/0)")
+
+
 # --- timing -------------------------------------------------------------
 
 #: How long the drain wait blocks per poll before re-reading the counters.
@@ -169,8 +255,19 @@ def build_parser() -> argparse.ArgumentParser:
 
     Returns:
         A parser whose defaults match :class:`Options`', except for ``--queue``,
-        which is generated per run by :func:`parse_args`.
+        which is generated per run by :func:`parse_args`. Every default is first
+        read from its ``AMQP_*`` environment variable, falling back to
+        :class:`Options`' own default when that variable is unset.
+
+    Raises:
+        OptionsError: If an ``AMQP_*`` environment variable is set to a value
+            its flag cannot accept — the same rejection :func:`parse_args`
+            raises for a bad command-line value, just discovered earlier.
     """
+    queue_type_default = _env_str("AMQP_QUEUE_TYPE", QUEUE_TYPE_CLASSIC)
+    if queue_type_default not in QUEUE_TYPES:
+        raise OptionsError(f"AMQP_QUEUE_TYPE={queue_type_default!r} must be one of {', '.join(QUEUE_TYPES)}")
+
     parser = argparse.ArgumentParser(
         prog="console_application.py",
         description="Publish and consume messages against one RabbitMQ queue, then report what happened.",
@@ -179,52 +276,87 @@ def build_parser() -> argparse.ArgumentParser:
         "-n",
         "--messages",
         type=int,
-        default=DEFAULT_MESSAGE_COUNT,
-        help="how many messages to publish (default: %(default)s); 0 is rejected",
+        default=_env_int("AMQP_MESSAGES", DEFAULT_MESSAGE_COUNT),
+        help="how many messages to publish (default: %(default)s, env: AMQP_MESSAGES); 0 is rejected",
     )
     parser.add_argument(
         "--queue-type",
         choices=QUEUE_TYPES,
-        default=QUEUE_TYPE_CLASSIC,
-        help="which queue sub-builder declares the queue (default: %(default)s)",
+        default=queue_type_default,
+        help="which queue sub-builder declares the queue (default: %(default)s, env: AMQP_QUEUE_TYPE)",
+    )
+    parser.add_argument(
+        "--queue",
+        default=_env_str("AMQP_QUEUE", ""),
+        help="queue name (default: a generated console-app-* name, env: AMQP_QUEUE)",
+    )
+    parser.add_argument(
+        "--keep-queue",
+        action="store_true",
+        default=_env_bool("AMQP_KEEP_QUEUE", False),
+        help="do not delete the queue during teardown (env: AMQP_KEEP_QUEUE)",
     )
-    parser.add_argument("--queue", default="", help="queue name (default: a generated console-app-* name)")
-    parser.add_argument("--keep-queue", action="store_true", help="do not delete the queue during teardown")
     parser.add_argument(
         "--consume-timeout",
         type=float,
-        default=DEFAULT_CONSUME_TIMEOUT_SECONDS,
-        help="seconds to wait for consumption to catch up (default: %(default)s)",
+        default=_env_float("AMQP_CONSUME_TIMEOUT", DEFAULT_CONSUME_TIMEOUT_SECONDS),
+        help="seconds to wait for consumption to catch up (default: %(default)s, env: AMQP_CONSUME_TIMEOUT)",
     )
     parser.add_argument(
         "--publish-timeout",
         type=float,
-        default=DEFAULT_PUBLISH_TIMEOUT_SECONDS,
-        help="per-call publish timeout, in seconds (default: %(default)s)",
+        default=_env_float("AMQP_PUBLISH_TIMEOUT", DEFAULT_PUBLISH_TIMEOUT_SECONDS),
+        help="per-call publish timeout, in seconds (default: %(default)s, env: AMQP_PUBLISH_TIMEOUT)",
     )
     parser.add_argument(
         "--stats-interval",
         type=float,
-        default=DEFAULT_STATS_INTERVAL_SECONDS,
-        help="seconds between periodic stats blocks (default: %(default)s)",
+        default=_env_float("AMQP_STATS_INTERVAL", DEFAULT_STATS_INTERVAL_SECONDS),
+        help="seconds between periodic stats blocks (default: %(default)s, env: AMQP_STATS_INTERVAL)",
+    )
+    parser.add_argument(
+        "--host",
+        default=_env_str("AMQP_HOST", "localhost"),
+        help="broker host (default: %(default)s, env: AMQP_HOST)",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=_env_optional_int("AMQP_PORT"),
+        help="broker port (default: 5672, or 5671 with --tls; env: AMQP_PORT)",
+    )
+    parser.add_argument(
+        "--user",
+        default=_env_str("AMQP_USER", "guest"),
+        help="SASL PLAIN username (default: %(default)s, env: AMQP_USER)",
+    )
+    parser.add_argument(
+        "--password",
+        default=_env_str("AMQP_PASSWORD", "guest"),
+        help="SASL PLAIN password (default: %(default)s, env: AMQP_PASSWORD)",
+    )
+    parser.add_argument(
+        "--vhost",
+        default=_env_str("AMQP_VHOST", "/"),
+        help="virtual host (default: %(default)s, env: AMQP_VHOST)",
+    )
+    parser.add_argument(
+        "--tls",
+        action="store_true",
+        default=_env_bool("AMQP_TLS", False),
+        help="wrap the connection in TLS (env: AMQP_TLS)",
     )
-    parser.add_argument("--host", default="localhost", help="broker host (default: %(default)s)")
-    parser.add_argument("--port", type=int, default=None, help="broker port (default: 5672, or 5671 with --tls)")
-    parser.add_argument("--user", default="guest", help="SASL PLAIN username (default: %(default)s)")
-    parser.add_argument("--password", default="guest", help="SASL PLAIN password (default: %(default)s)")
-    parser.add_argument("--vhost", default="/", help="virtual host (default: %(default)s)")
-    parser.add_argument("--tls", action="store_true", help="wrap the connection in TLS")
     parser.add_argument(
         "--recovery",
         action=argparse.BooleanOptionalAction,
-        default=True,
-        help="auto-reconnect after an unexpected disconnect (default: enabled)",
+        default=_env_bool("AMQP_RECOVERY", True),
+        help="auto-reconnect after an unexpected disconnect (default: enabled, env: AMQP_RECOVERY)",
     )
     parser.add_argument(
         "--recovery-topology",
         action=argparse.BooleanOptionalAction,
-        default=False,
-        help="redeclare recorded topology after a reconnect (default: disabled)",
+        default=_env_bool("AMQP_RECOVERY_TOPOLOGY", False),
+        help="redeclare recorded topology after a reconnect (default: disabled, env: AMQP_RECOVERY_TOPOLOGY)",
     )
     return parser
 
@@ -475,7 +607,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.0b1}/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.0b1/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()