pamqp: AMQP 0-9-1 Low-Level Library

Warnings

• breaking Version 4.0.0 and later require Python 3.11 or newer. Previous versions supported Python 3.7+.
  Fix: Upgrade Python environment to 3.11+ or pin pamqp to <4.0.0 if unable to upgrade Python.
• breaking In v4.0.0, explicit `__annotations__` class variables were removed from command and base classes. If your code directly introspects `MyCommand.__annotations__`, it may need updating as Python now manages this automatically.
  Fix: Rely on standard `inspect.get_annotations()` or `MyCommand.__annotations__` directly which Python manages, instead of expecting an explicitly declared class variable.
• breaking Major module reorganization occurred in version 3.x. AMQP command classes (e.g., `Basic.Publish`), exceptions, and constants were moved from `pamqp.specification` to dedicated modules like `pamqp.commands.*`, `pamqp.exceptions`, and `pamqp.constants`.
  Fix: Update all import paths. For example, `from pamqp.specification import Basic` becomes `from pamqp.commands.basic import Basic` (or specific command like `Publish`). Refer to the `pamqp.commands` structure.
• breaking The `Basic.QoS` command's `global_` argument was renamed to `globally` in version 3.0.0a5.
  Fix: Update usage from `Basic.QoS(global_=True)` to `Basic.QoS(globally=True)`.
• gotcha pamqp is a low-level AMQP 0-9-1 protocol serialization library. It does not handle network I/O, connection management, threading, or application logic. Users must implement these aspects themselves to build a functional AMQP client or server.
  Fix: Be prepared to write code for socket communication, frame buffering, and state machines if using pamqp directly. For higher-level abstractions, consider libraries like `pika` or `aio-pika` which use pamqp internally or implement similar logic.
• gotcha In `pamqp` versions < 3.0.1, the `Basic.Reject(requeue=False)` command parameter was erroneously coerced to `True`, meaning messages were always requeued. While fixed in 3.0.1 and later (including 4.0.0), this highlights the importance of verifying critical parameter behavior.
  Fix: Upgrade to pamqp 3.0.1+ to ensure `Basic.Reject(requeue=False)` functions correctly. Thoroughly test critical flags for expected behavior.

Install

• pip install pamqp Install stable version

Imports

• Frame

  from pamqp.frame import Frame

• Publish

  from pamqp.commands.basic import Publish

  AMQP command classes moved from pamqp.specification to pamqp.commands submodules in v3.x.
• ContentHeader

  from pamqp.header import ContentHeader

• ContentBody

  from pamqp.body import ContentBody

• AMQPConnectionError

  from pamqp.exceptions import AMQPConnectionError

  Exceptions moved from pamqp.specification to pamqp.exceptions in v3.x.

Quickstart

This quickstart demonstrates how to create AMQP command, header, and body objects, and then marshal them into raw AMQP frames using `pamqp.frame.Frame.marshal`. It also shows a simple unmarshal operation for a single frame. Note that `pamqp` only handles serialization; managing network I/O and sequencing of frames into complete messages is left to the user.

import pamqp.frame
import pamqp.commands.basic
import pamqp.header
import pamqp.body

# Example: Prepare a Basic.Publish command and marshal it into frames
channel_id = 1
exchange = 'my_exchange'
routing_key = 'my_key'
payload = b'Hello, pamqp!'

# 1. Create the Basic.Publish command object
publish_cmd = pamqp.commands.basic.Publish(
    exchange=exchange,
    routing_key=routing_key,
    mandatory=False,
    immediate=False
)

# 2. Create ContentHeader for the message properties
header = pamqp.header.ContentHeader(
    class_id=publish_cmd.name_id, # class_id comes from the command
    body_size=len(payload),
    properties={} # Basic properties for this example
)

# 3. Create ContentBody for the actual message payload
body = pamqp.body.ContentBody(value=payload)

# 4. Marshal the command into an AMQP frame
command_frame_bytes = pamqp.frame.Frame.marshal(publish_cmd, channel_id)

# 5. Marshal the content header into an AMQP frame
header_frame_bytes = pamqp.frame.Frame.marshal(header, channel_id)

# 6. Marshal the content body into an AMQP frame
body_frame_bytes = pamqp.frame.Frame.marshal(body, channel_id)

print(f"Marshalled command frame: {command_frame_bytes.hex()}")
print(f"Marshalled header frame: {header_frame_bytes.hex()}")
print(f"Marshalled body frame: {body_frame_bytes.hex()}")

# To demonstrate unmarshalling a single frame (e.g., a command frame)
unmarshalled_cmd_frame = pamqp.frame.Frame.unmarshal(command_frame_bytes)
print(f"\nUnmarshalled frame type: {unmarshalled_cmd_frame.frame_type_id}")
print(f"Unmarshalled channel ID: {unmarshalled_cmd_frame.channel_id}")
print(f"Unmarshalled command: {unmarshalled_cmd_frame.value.__class__.__name__}")