Skip to content

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 amqp://host:port (or one load balancer).

required
user str | None

User name for SASL authentication.

None
password str | None

Password for SASL authentication. Over amqp:// it is sent in clear text.

None
heartbeat float | None

AMQP idle timeout in seconds: a connection that carries no traffic for this long is considered dead. None disables it.

10.0
connect_timeout float

Seconds async with Client(...) waits for the first connection before raising TimeoutError.

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 urls once per client, to spread clients over nodes.

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 AuthenticationFailed at the first refusal. Once logged in, a refusal is always failed over.

None

Raises:

Type Description
ValueError

urls is empty.

RuntimeError

An amqps:// URL was given, but python-qpid-proton was built without OpenSSL.

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: str, bytes, dict, list, numbers, ...

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 ConnectionLost. Artemis itself does not deduplicate by it: for that, also set the _AMQ_DUPL_ID property.

None
durable bool

Ask the broker to persist the message.

True
routing Routing

"queue" (anycast) or "topic" (multicast). Decides how Artemis auto-creates the address.

'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" (anycast, consumers compete) or "topic" (multicast, each subscription gets every message).

'queue'

Raises:

Type Description
LinkRefused

The broker refused the subscription.

ClientClosed

The client was closed.

ValueError

prefetch is below 1.

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 (str, bytes, dict, list, numbers, ...).

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 None.

delivery_count int

How many earlier deliveries of this message failed: 0 on the first delivery, incremented by nack but not by release.

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.