py-amqp

amqp (imported as amqp, distributed from the py-amqp repository) is a low-level, pure Python implementation of the AMQP 0.9.1 wire protocol used by RabbitMQ. It began as a fork of the older amqplib project and has been maintained by the Celery organization since 2012, where it serves as Kombu’s default pure-Python transport when the C-accelerated librabbitmq is unavailable.

The library exposes Connection and Channel objects that map directly onto AMQP’s connection/channel/method model: opening a connection negotiates capabilities and heartbeats with the broker, channels then declare exchanges and queues, publish and consume messages, and handle acknowledgements, publisher confirms, and RabbitMQ-specific extensions like consumer-cancel notifications and exchange-to-exchange bindings.

Because it sits directly beneath Celery and Kombu, amqp is one of the most widely deployed AMQP clients in the Python ecosystem despite rarely being installed by name — most users pull it in transitively as a dependency of a task queue rather than importing it directly.

What You Get

• A Connection class handling the AMQP handshake, authentication (via sasl), heartbeats, and capability negotiation with a broker
• A Channel API covering exchange/queue declaration, binding, publishing (including publisher-confirm mode), and consumer registration
• Support for RabbitMQ protocol extensions: consumer-cancel notifications, publisher confirms, exchange-to-exchange bindings, and authentication-failure notifications
• Low-level frame serialization/deserialization (serialization.py, method_framing.py) for encoding and decoding AMQP methods and content frames
• TCP and SSL transport implementations with socket-option tuning (transport.py)
• Optional Cython-accelerated speedups for the serialization and framing hot paths, enabled via a build-time environment variable

Common Use Cases

• Powering Celery’s and Kombu’s default pure-Python broker transport for task queues backed by RabbitMQ
• Writing custom AMQP producers/consumers that need direct protocol-level control (heartbeats, publisher confirms, channel recovery) rather than a higher-level abstraction
• Building message-driven microservices that publish to or consume from RabbitMQ exchanges and queues
• Implementing publisher-confirm-backed reliable publishing pipelines where delivery acknowledgement matters
• Acting as a drop-in, API-compatible alternative to librabbitmq in environments where the C extension can’t be built

Under The Hood

Architecture The library is organized as a thin protocol stack layered directly on a socket. transport.py owns the raw TCP/SSL connection and frame-level I/O; method_framing.py converts between wire frames and higher-level AMQP methods, buffering multi-frame content messages until a Message (from basic_message.py) is complete; serialization.py handles the byte-level encoding/decoding of AMQP field types; and spec.py defines the protocol’s method and class identifiers generated from the AMQP specification. Connection (in connection.py) and Channel (in channel.py, extending abstract_channel.AbstractChannel) sit on top as the public-facing objects, each wiring send/receive callbacks through the framing layer via vine.promise-based deferreds. This is a deliberately flat, single-purpose architecture: there’s no plugin system or abstraction over AMQP itself, because the whole point of the library is to be the compatibility-preserving, replaceable transport underneath Kombu — changing Connection’s wire-level behavior directly changes what every Celery/Kombu deployment sends over the socket.

Tech Stack amqp is pure Python (96.8% of the codebase) targeting Python 3.9+, with a single runtime dependency on vine (>=5.0.0,<6.0.0) for promise/callback plumbing. Packaging uses classic setuptools (setup.py plus setup.cfg), not a pyproject.toml-based build backend. An optional, environment-gated Cython build (CELERY_ENABLE_SPEEDUPS=true) compiles serialization.py, basic_message.py, method_framing.py, abstract_channel.py, and utils.py into C extensions for a faster hot path, with .pxd files present alongside each of those modules. Development tooling includes tox for multi-environment testing, flake8 for linting, and GitHub Actions workflows (ci.yaml, codeql-analysis.yml) for CI and security scanning; there is no Dockerfile-based runtime, only one used to spin up RabbitMQ for integration tests.

Code Quality Testing uses pytest with roughly 220+ test functions across dedicated t/unit/test_*.py files mirroring each source module (channel, connection, transport, serialization, method framing, sasl, and more), plus a separate t/integration/ suite that exercises a real RabbitMQ broker. Tests rely heavily on unittest.mock (Mock, MagicMock, patch) to isolate the socket layer, which is appropriate for protocol-level code. Error handling is explicit and protocol-aware: a dedicated exceptions.py maps AMQP error codes to typed exception classes (ChannelError, ConnectionError, ResourceError, etc.) via error_for_code, rather than swallowing failures. The codebase uses type hints sparingly (this predates widespread typing adoption in older Celery-ecosystem code) but compensates with extensive docstrings — most public methods on Channel and Connection carry AMQP-spec-derived documentation. CI runs flake8 linting and the full test matrix across supported Python versions.

What Makes It Unique amqp’s distinguishing design choice is being an intentionally low-level, spec-faithful AMQP 0.9.1 implementation that stays API-compatible with the older librabbitmq C extension, letting Kombu swap between the pure-Python and C-accelerated clients without changing calling code. Rather than offering a higher-level convenience API, it surfaces RabbitMQ-specific protocol extensions (publisher confirms, consumer-cancel notifications, exchange-to-exchange bindings) as first-class features precisely because higher-level libraries like Kombu and Celery build their own abstractions on top of it. Its innovation is architectural discipline and longevity rather than novel technique — it has quietly underpinned the Python task-queue ecosystem for over a decade with a stable, narrow surface area.