Skip to content

aioartemis

asyncio-native AMQP 1.0 client for ActiveMQ Artemis, built for running behind load balancers and failing over between nodes.

It wraps Qpid Proton, the reference AMQP 1.0 implementation, and runs its event loop on a thread of its own, so heartbeats keep flowing even while your event loop is busy.

Installation

pip install aioartemis

Python 3.12 or newer is required. aioartemis itself is pure Python, but its AMQP engine, python-qpid-proton, is published only as a source distribution: installing it compiles C code and links it against the system's OpenSSL. Install the build dependencies first:

System Build dependencies
Debian, Ubuntu apt-get install build-essential pkg-config libssl-dev
Alpine apk add build-base pkgconf openssl-dev
macOS (Homebrew) brew install pkg-config openssl@3

Elsewhere you need a C compiler, pkg-config and the OpenSSL development headers; a Python installed by the system package manager may also need its development headers (python3-dev). At run time only the OpenSSL library is needed (libssl3, or libssl3t64 on newer Debian and Ubuntu), so a Docker image can build in one stage and run in a slimmer one.

Without the OpenSSL headers, TLS is silently left out

If pkg-config cannot find OpenSSL, python-qpid-proton still installs, but without TLS: amqp:// works, amqps:// does not, and Client refuses amqps:// URLs with a RuntimeError. Check what you got:

python -c "import proton; print(proton.SSL.present())"

To fix it, install the dependencies above and rebuild without the build cache, which would otherwise hand back the wheel built without TLS:

pip install --force-reinstall --no-cache-dir python-qpid-proton
# or, with uv:
uv cache clean python-qpid-proton && uv sync --reinstall-package python-qpid-proton

Sending and receiving

import asyncio
from contextlib import suppress

from aioartemis import Client, DeliveryLost


async def main() -> None:
    urls = ["amqp://artemis-1:5672", "amqp://artemis-2:5672"]
    async with Client(urls, user="app", password="secret") as client:
        await client.send("orders", {"id": 42})

        async with client.subscribe("orders", prefetch=10) as orders:
            async for message in orders:
                print(message.body)
                # The connection dropped since the message arrived: the broker
                # redelivers it, so there is nothing left to settle.
                with suppress(DeliveryLost):
                    await message.accept()


asyncio.run(main())

send returns once the broker has accepted the message. Every received message stays unsettled until you call one of its four settling methods:

Method Use it when The broker then
accept() the message was processed removes it
nack() processing failed, it may work later redelivers it, counting a failed attempt
release() you did not process it, e.g. on shutdown redelivers it, counting nothing
reject() the message can never be processed moves it to the dead-letter address at once

All four raise DeliveryLost when the connection the message came over has dropped since. The broker then redelivers the message, so a consumer loop should carry on, as above, instead of letting the error end the subscription.

Next

The client logs on the aioartemis logger: every lost connection at INFO; at WARNING a node that refuses the credentials after a successful login, and an engine thread that did not stop on close; a crashed engine thread at ERROR.