API reference
aioartemis
asyncio AMQP 1.0 client for ActiveMQ Artemis with failover across nodes.
Client
Client(
urls: list[str],
*,
user: str | None = None,
password: str | None = None,
heartbeat: float | None = 10.0,
connect_timeout: float = 30.0,
open_timeout: float = 10.0,
close_timeout: float = 5.0,
reconnect_base: float = 0.1,
reconnect_max: float = 10.0,
shuffle: bool = True,
auth_retry_window: float | None = None,
)
asyncio AMQP 1.0 client for ActiveMQ Artemis with failover across nodes.
Use it once, as an async context manager: entering connects, leaving closes. The client belongs to the event loop it was entered in, and runs the AMQP engine on a thread of its own with a single connection to one node at a time. Delivery is at-least-once; see the Delivery guarantees page.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
urls
|
list[str]
|
Every node to use, as |
required |
user
|
str | None
|
User name for SASL authentication. |
None
|
password
|
str | None
|
Password for SASL authentication. Over |
None
|
heartbeat
|
float | None
|
AMQP idle timeout in seconds: a connection that carries no
traffic for this long is considered dead. |
10.0
|
connect_timeout
|
float
|
Seconds |
30.0
|
open_timeout
|
float
|
Seconds a single node may take to open a connection before the client gives up on it and tries the next one. |
10.0
|
close_timeout
|
float
|
Seconds closing waits for the broker to confirm before dropping the connection. |
5.0
|
reconnect_base
|
float
|
Seconds of the first backoff step between passes over the nodes. |
0.1
|
reconnect_max
|
float
|
Cap of the backoff, in seconds. A connection must also stay up this long before the backoff resets. |
10.0
|
shuffle
|
bool
|
Shuffle |
True
|
auth_retry_window
|
float | None
|
Seconds after start during which a refused first login
is retried like an unreachable node, for brokers whose authentication
backend (LDAP, ...) refuses valid credentials while it restarts.
|
None
|
Raises:
| Type | Description |
|---|---|
ValueError
|
|
RuntimeError
|
An |
is_connected
property
is_connected: bool
Whether a connection to a node is open right now.
connected_url
property
connected_url: str | None
URL of the node of the current connection, or of the last one while
reconnecting; None before the first connection.
last_error
property
last_error: str | None
Why the last connection attempt failed or the last connection dropped.
aclose
async
aclose() -> None
Close the client; leaving async with does this. Idempotent.
Sends still waiting to be transmitted fail with ClientClosed, sends
awaiting the broker's answer with ConnectionLost, and subscriptions
with ClientClosed. Waits at most close_timeout plus two seconds.
send
async
send(
address: str,
body: Any,
*,
properties: dict[str, Any] | None = None,
message_id: Any = None,
durable: bool = True,
routing: Routing = "queue",
) -> Any
Send a message and wait until the broker has accepted it.
While the client is reconnecting the message waits in a local queue, which
is not bounded; cancel the call (e.g. with asyncio.timeout) to give up on
it. A message already handed to the broker cannot be recalled by
cancelling.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
address
|
str
|
The Artemis address to send to. |
required |
body
|
Any
|
The AMQP body: |
required |
properties
|
dict[str, Any] | None
|
AMQP application properties. |
None
|
message_id
|
Any
|
Id for consumers to deduplicate by; a UUID by default.
Pass the same id when retrying after |
None
|
durable
|
bool
|
Ask the broker to persist the message. |
True
|
routing
|
Routing
|
|
'queue'
|
Returns:
| Type | Description |
|---|---|
Any
|
The message id. |
Raises:
| Type | Description |
|---|---|
ConnectionLost
|
The outcome is unknown; retry with the same id. |
SendRejected
|
The broker refused the message. |
SendReleased
|
The broker did not take the message; safe to resend. |
LinkRefused
|
The broker refused the link for this address. |
ClientClosed
|
The client was closed. |
AuthenticationFailed
|
The client failed to log in. |
EngineFailed
|
The engine thread died. |
TypeError
|
AMQP cannot encode the body. |
subscribe
async
subscribe(
address: str,
*,
prefetch: int = 10,
routing: Routing = "queue",
) -> AsyncGenerator[Subscription, None]
Receive messages from an address; use as
async with client.subscribe(...) as subscription.
Entering waits until the broker attaches the link, which while the client
is reconnecting lasts until it is back; bound it with asyncio.timeout if
that matters. The subscription is re-attached after every failover, but
not after the broker detaches it. Leaving closes it; messages not yet
settled are redelivered by the broker.
With routing="topic" the broker keeps a queue for the subscription only
while it is attached: messages published while the client is
reconnecting are not delivered to it.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
address
|
str
|
The Artemis address (queue) to receive from. |
required |
prefetch
|
int
|
How many messages may be delivered but not yet settled. |
10
|
routing
|
Routing
|
|
'queue'
|
Raises:
| Type | Description |
|---|---|
LinkRefused
|
The broker refused the subscription. |
ClientClosed
|
The client was closed. |
ValueError
|
|
IncomingMessage
dataclass
IncomingMessage(
body: Any,
properties: dict[str, Any],
message_id: Any,
delivery_count: int,
_client: Client,
_received: Received,
)
A received message. It stays unsettled, counting against the subscription's
prefetch, until one of accept, reject, nack or release is called.
Each of those settles the message locally and queues the outcome for the
broker; it returns without waiting for the broker to see it. If the connection
drops in between, the broker redelivers the message, so processing must
tolerate duplicates even after a successful accept.
Attributes:
| Name | Type | Description |
|---|---|---|
body |
Any
|
The decoded AMQP body ( |
properties |
dict[str, Any]
|
The application properties, empty if there are none. |
message_id |
Any
|
The AMQP message id. Messages sent by this library always
carry one; messages from other producers may have |
delivery_count |
int
|
How many earlier deliveries of this message failed:
0 on the first delivery, incremented by |
All four methods raise DeliveryLost if the message was already settled or
came over a connection or subscription that is gone.
body
instance-attribute
body: Any
properties
instance-attribute
properties: dict[str, Any]
message_id
instance-attribute
message_id: Any
delivery_count
instance-attribute
delivery_count: int
accept
async
accept() -> None
The message was processed; the broker removes it from the queue.
reject
async
reject() -> None
The message can never be processed. Artemis moves it straight to the
address's dead-letter address, ignoring max-delivery-attempts, or drops
it when none is configured. For a failure that may pass, use nack.
nack
async
nack() -> None
Processing failed: redeliver the message, counting a failed attempt, so
the broker's max-delivery-attempts and dead-letter address apply.
release
async
release() -> None
Hand the message back unprocessed (e.g. on shutdown) without counting an attempt. A message released over and over is never dead-lettered.
Subscription
Subscription(client: Client)
Messages received for one Client.subscribe call.
Iterate with async for, or call get. Iteration never ends by itself: leave
it with break, by cancelling, or through the error the subscription fails
with: LinkRefused if the broker detaches it, ClientClosed when the client
closes, EngineFailed if the engine dies.
Messages that arrived over a connection that has since dropped are never handed out: they can no longer be settled and the broker redelivers them.
get
async
get() -> IncomingMessage
Wait for the next message.
Raises:
| Type | Description |
|---|---|
LinkRefused
|
The broker detached the subscription. |
ClientClosed
|
The client was closed. |
EngineFailed
|
The engine thread died. |
qsize
qsize() -> int
Number of messages ready to be returned by get without waiting.
empty
empty() -> bool
Whether get would have to wait.
ArtemisError
Bases: Exception
Base class of the errors this library raises.
AuthenticationFailed
Bases: ArtemisError
The credentials were refused before the client ever logged in.
Raised by async with Client(...); the client cannot be used afterwards. A
node that refuses the credentials after a successful login is treated as a
failed node instead and the client fails over past it.
ClientClosed
Bases: ArtemisError
The client has been closed: raised by calls made after Client.aclose, by
sends still waiting to be transmitted and by subscriptions when it closes,
and by async with Client(...) when aclose interrupts the connecting.
ConnectionLost
ConnectionLost(message: str, message_id: Any = None)
Bases: ArtemisError
The outcome of a send is unknown: the connection dropped (or the client was closed) after the message was handed to the broker but before the broker settled it. It may or may not have been delivered.
Retry with the same message_id so that consumers can discard the duplicate.
Attributes:
| Name | Type | Description |
|---|---|---|
message_id |
The id of the message whose outcome is unknown. |
message_id
instance-attribute
message_id = message_id
DeliveryLost
Bases: ArtemisError
A received message can no longer be settled: it was already settled, or the connection or subscription it came over is gone, in which case the broker redelivers it.
EngineFailed
Bases: ArtemisError
The thread running the AMQP engine died of an unexpected error; the client
cannot be used any more. The error is logged on the aioartemis logger.
LinkRefused
Bases: ArtemisError
The broker refused or detached the link for an address, for example because the address does not exist or access is denied.
Pending sends to the address fail with it, and the next send to the address
tries a new link. A subscription fails with it, either on entering or later
from Subscription.get, and is not re-attached.
SendRejected
Bases: ArtemisError
The broker refused the message; the reason is in the error text. Resending it unchanged will most likely fail the same way.
SendReleased
Bases: ArtemisError
The broker did not process the message and did not deliver it; it is safe to send it again.