# pamqp.specification

The `pamqp.specification` module is auto-generated, created by the `tools/codegen.py` application. It contains all of the information about the protocol that is required for a client library to communicate with RabbitMQ or another AMQP 0-9-1 broker.

The classes inside `pamqp.specification` allow for the automatic marshaling and unmarshaling of AMQP method frames and Basic.Properties. In addition the command classes contain information that designates if they are synchronous commands and if so, what the expected responses are. Each commands arguments are detailed in the class and are listed in the attributes property.

`pamqp.specification` also implements AMQP exceptions as Python exceptions so that client libraries can raise these exceptions as is appropriate without having to implement their own extensions for AMQP protocol related issues.

specification.py

Auto-generated AMQP Support Module

WARNING: DO NOT EDIT. To Generate run tools/codegen.py

exception `pamqp.specification.``AMQPAccessRefused`

  The client attempted to work with a server entity to which it has no access due to security settings.

exception `pamqp.specification.``AMQPChannelError`

  The client attempted to work with a channel that had not been correctly opened. This most likely indicates a fault in the client layer.

exception `pamqp.specification.``AMQPCommandInvalid`

  The client sent an invalid sequence of frames, attempting to perform an operation that was considered invalid by the server. This usually implies a programming error in the client.

exception `pamqp.specification.``AMQPConnectionForced`

  An operator intervened to close the connection for some reason. The client may retry at some later date.

exception `pamqp.specification.``AMQPContentTooLarge`

  The client attempted to transfer content larger than the server could accept at the present time. The client may retry at a later time.

exception `pamqp.specification.``AMQPFrameError`

  The sender sent a malformed frame that the recipient could not decode. This strongly implies a programming error in the sending peer.

exception `pamqp.specification.``AMQPInternalError`

  The server could not complete the method because of an internal error. The server may require intervention by an operator in order to resume normal operations.

exception `pamqp.specification.``AMQPInvalidPath`

  The client tried to work with an unknown virtual host.

exception `pamqp.specification.``AMQPNoConsumers`

  When the exchange cannot deliver to a consumer when the immediate flag is set. As a result of pending data on the queue or the absence of any consumers of the queue.

exception `pamqp.specification.``AMQPNoRoute`

  Undocumented AMQP Soft Error

exception `pamqp.specification.``AMQPNotAllowed`

  The client tried to work with some entity in a manner that is prohibited by the server, due to security settings or by some other criteria.

exception `pamqp.specification.``AMQPNotFound`

  The client attempted to work with a server entity that does not exist.

exception `pamqp.specification.``AMQPNotImplemented`

  The client tried to use functionality that is not implemented in the server.

exception `pamqp.specification.``AMQPPreconditionFailed`

  The client requested a method that was not allowed because some precondition failed.

exception `pamqp.specification.``AMQPResourceError`

  The server could not complete the method because it lacked sufficient resources. This may be due to the client creating too many of some type of entity.

exception `pamqp.specification.``AMQPResourceLocked`

  The client attempted to work with a server entity to which it has no access because another client is working with it.

exception `pamqp.specification.``AMQPSyntaxError`

  The sender sent a frame that contained illegal values for one or more fields. This strongly implies a programming error in the sending peer.

exception `pamqp.specification.``AMQPUnexpectedFrame`

  The peer sent a frame that was not expected, usually in the context of a content header and body. This strongly indicates a fault in the peer’s content processing.

class `pamqp.specification.``Basic`

  Work with basic content

  The Basic class provides methods that support an industry-standard messaging model.

  class `Ack`(delivery_tag=0, multiple=False)

    Acknowledge one or more messages

    This method acknowledges one or more messages delivered via the Deliver or Get-Ok methods. The client can ask to confirm a single message or a set of messages up to and including a specific message.

  class `Cancel`(consumer_tag='', nowait=False)

    End a queue consumer

    This method cancels a consumer. This does not affect already delivered messages, but it does mean the server will not send any more messages for that consumer. The client may receive an arbitrary number of messages in between sending the cancel method and receiving the cancel- ok reply.

  class `CancelOk`(consumer_tag='')

    Confirm a cancelled consumer

    This method confirms that the cancellation was completed.

  class `Consume`(ticket=0, queue='', consumer_tag='', no_local=False, no_ack=False, exclusive=False, nowait=False, arguments=None)

    Start a queue consumer

    This method asks the server to start a “consumer”, which is a transient request for messages from a specific queue. Consumers last as long as the channel they were declared on, or until the client cancels them.

  class `ConsumeOk`(consumer_tag='')

    Confirm a new consumer

    The server provides the client with a consumer tag, which is used by the client for methods called on the consumer at a later stage.

  class `Deliver`(consumer_tag='', delivery_tag=None, redelivered=False, exchange='', routing_key='')

    Notify the client of a consumer message

    This method delivers a message to the client, via a consumer. In the asynchronous message delivery model, the client starts a consumer using the Consume method, then the server responds with Deliver methods as and when messages arrive for that consumer.

  class `Get`(ticket=0, queue='', no_ack=False)

    Direct access to a queue

    This method provides a direct access to the messages in a queue using a synchronous dialogue that is designed for specific types of application where synchronous functionality is more important than performance.

  class `GetEmpty`(cluster_id='')

    Indicate no messages available

    This method tells the client that the queue has no messages available for the client.

  class `GetOk`(delivery_tag=None, redelivered=False, exchange='', routing_key='', message_count=0)

    Provide client with a message

    This method delivers a message to the client following a get method. A message delivered by ‘get-ok’ must be acknowledged unless the no-ack option was set in the get method.

  class `Nack`(delivery_tag=0, multiple=False, requeue=True)
  class `Properties`(content_type='', content_encoding='', headers=None, delivery_mode=None, priority=None, correlation_id='', reply_to='', expiration='', message_id='', timestamp=None, message_type='', user_id='', app_id='', cluster_id='')

    Content Properties

  class `Publish`(ticket=0, exchange='', routing_key='', mandatory=False, immediate=False)

    Publish a message

    This method publishes a message to a specific exchange. The message will be routed to queues as defined by the exchange configuration and distributed to any active consumers when the transaction, if any, is committed.

  class `Qos`(prefetch_size=0, prefetch_count=0, global_=False)

    Specify quality of service

    This method requests a specific quality of service. The QoS can be specified for the current channel or for all channels on the connection. The particular properties and semantics of a qos method always depend on the content class semantics. Though the qos method could in principle apply to both peers, it is currently meaningful only for the server.

  class `QosOk`

    Confirm the requested qos

    This method tells the client that the requested QoS levels could be handled by the server. The requested QoS applies to all active consumers until a new QoS is defined.

  class `Recover`(requeue=False)

    Redeliver unacknowledged messages

    This method asks the server to redeliver all unacknowledged messages on a specified channel. Zero or more messages may be redelivered. This method replaces the asynchronous Recover.

  class `RecoverAsync`(requeue=False)

    Redeliver unacknowledged messages

    This method asks the server to redeliver all unacknowledged messages on a specified channel. Zero or more messages may be redelivered. This method is deprecated in favour of the synchronous Recover/Recover-Ok.

  class `RecoverOk`

    Confirm recovery

    This method acknowledges a Basic.Recover method.

  class `Reject`(delivery_tag=None, requeue=True)

    Reject an incoming message

    This method allows a client to reject a message. It can be used to interrupt and cancel large incoming messages, or return untreatable messages to their original queue.

  class `Return`(reply_code=0, reply_text='', exchange='', routing_key='')

    Return a failed message

    This method returns an undeliverable message that was published with the “immediate” flag set, or an unroutable message published with the “mandatory” flag set. The reply code and text provide information about the reason that the message was undeliverable.

class `pamqp.specification.``Channel`

  Work with channels

  The channel class provides methods for a client to establish a channel to a server and for both peers to operate the channel thereafter.

  class `Close`(reply_code=0, reply_text='', class_id=0, method_id=0)

    Request a channel close

    This method indicates that the sender wants to close the channel. This may be due to internal conditions (e.g. a forced shut-down) or due to an error handling a specific method, i.e. an exception. When a close is due to an exception, the sender provides the class and method id of the method which caused the exception.

  class `CloseOk`

    Confirm a channel close

    This method confirms a Channel.Close method and tells the recipient that it is safe to release resources for the channel.

  class `Flow`(active=None)

    Enable/disable flow from peer

    This method asks the peer to pause or restart the flow of content data sent by a consumer. This is a simple flow-control mechanism that a peer can use to avoid overflowing its queues or otherwise finding itself receiving more messages than it can process. Note that this method is not intended for window control. It does not affect contents returned by Basic.Get-Ok methods.

  class `FlowOk`(active=None)

    Confirm a flow method

    Confirms to the peer that a flow command was received and processed.

  class `Open`(out_of_band='')

    Open a channel for use

    This method opens a channel to the server.

  class `OpenOk`(channel_id='')

    Signal that the channel is ready

    This method signals to the client that the channel is ready for use.

class `pamqp.specification.``Connection`

  Work with socket connections

  The connection class provides methods for a client to establish a network connection to a server, and for both peers to operate the connection thereafter.

  class `Blocked`(reason='')

    Signal that connection is blocked

    This method signals to the client that the connection is blocked by RabbitMQ.

  class `Close`(reply_code=0, reply_text='', class_id=0, method_id=0)

    Request a connection close

    This method indicates that the sender wants to close the connection. This may be due to internal conditions (e.g. a forced shut-down) or due to an error handling a specific method, i.e. an exception. When a close is due to an exception, the sender provides the class and method id of the method which caused the exception.

  class `CloseOk`

    Confirm a connection close

    This method confirms a Connection.Close method and tells the recipient that it is safe to release resources for the connection and close the socket.

  class `Open`(virtual_host='/', capabilities='', insist=False)

    Open connection to virtual host

    This method opens a connection to a virtual host, which is a collection of resources, and acts to separate multiple application domains within a server. The server may apply arbitrary limits per virtual host, such as the number of each type of entity that may be used, per connection and/or in total.

  class `OpenOk`(known_hosts='')

    Signal that connection is ready

    This method signals to the client that the connection is ready for use.

  class `Secure`(challenge='')

    Security mechanism challenge

    The SASL protocol works by exchanging challenges and responses until both peers have received sufficient information to authenticate each other. This method challenges the client to provide more information.

  class `SecureOk`(response='')

    Security mechanism response

    This method attempts to authenticate, passing a block of SASL data for the security mechanism at the server side.

  class `Start`(version_major=0, version_minor=9, server_properties=None, mechanisms='PLAIN', locales='en_US')

    Start connection negotiation

    This method starts the connection negotiation process by telling the client the protocol version that the server proposes, along with a list of security mechanisms which the client can use for authentication.

  class `StartOk`(client_properties=None, mechanism='PLAIN', response='', locale='en_US')

    Select security mechanism and locale

    This method selects a SASL security mechanism.

  class `Tune`(channel_max=0, frame_max=0, heartbeat=0)

    Propose connection tuning parameters

    This method proposes a set of connection configuration values to the client. The client can accept and/or adjust these.

  class `TuneOk`(channel_max=0, frame_max=0, heartbeat=0)

    Negotiate connection tuning parameters

    This method sends the client’s connection tuning parameters to the server. Certain fields are negotiated, others provide capability information.

  class `Unblocked`

    Signal that connection is no longer blocked

    This method signals to the client that the connection is no longer blocked by RabbitMQ.

class `pamqp.specification.``Exchange`

  Work with exchanges

  Exchanges match and distribute messages across queues. Exchanges can be configured in the server or declared at runtime.

  class `Bind`(ticket=0, destination='', source='', routing_key='', nowait=False, arguments=None)
  class `BindOk`
  class `Declare`(ticket=0, exchange='', exchange_type='direct', passive=False, durable=False, auto_delete=False, internal=False, nowait=False, arguments=None)

    Verify exchange exists, create if needed

    This method creates an exchange if it does not already exist, and if the exchange exists, verifies that it is of the correct and expected class.

  class `DeclareOk`

    Confirm exchange declaration

    This method confirms a Declare method and confirms the name of the exchange, essential for automatically-named exchanges.

  class `Delete`(ticket=0, exchange='', if_unused=False, nowait=False)

    Delete an exchange

    This method deletes an exchange. When an exchange is deleted all queue bindings on the exchange are cancelled.

  class `DeleteOk`

    Confirm deletion of an exchange

    This method confirms the deletion of an exchange.

  class `Unbind`(ticket=0, destination='', source='', routing_key='', nowait=False, arguments=None)
  class `UnbindOk`

class `pamqp.specification.``Frame`

  Base Class for AMQP Methods which specifies the encoding and decoding behavior.

  `marshal`()

    Dynamically encode the frame by taking the list of attributes and encode them item by item getting the value form the object attribute and the data type from the class attribute.

    Return type: | str

  classmethod `type`(attr)

    Return the data type for an attribute.

    Return type: | str

  `unmarshal`(data)

    Dynamically decode the frame data applying the values to the method object by iterating through the attributes in order and decoding them.

    Parameters: | data (str) – The binary encoded method data

class `pamqp.specification.``PropertiesBase`

  Provide a base object that marshals and unmarshals the Basic.Properties object values.

  classmethod `attributes`()

    Return the list of attributes

    Return type: | list

  `encode_property`(property_name, property_value)

    Encode a single property value

    Parameters:

    - property_name (str) – The property name to encode
    - property_value (any) – The value to encode

  `marshal`()

    Take the Basic.Properties data structure and marshal it into the data structure needed for the ContentHeader.

    Return type: | bytes

  `to_dict`()

    Return the properties as a dict

    Return type: | dict

  classmethod `type`(attr)

    Return the data type for an attribute.

    Return type: | str

  `unmarshal`(flags, data)

    Dynamically decode the frame data applying the values to the method object by iterating through the attributes in order and decoding them.

    Parameters:

    - flags (int) – Flags that indicate if the data has the property
    - data (bytes) – The binary encoded method data

class `pamqp.specification.``Queue`

  Work with queues

  Queues store and forward messages. Queues can be configured in the server or created at runtime. Queues must be attached to at least one exchange in order to receive messages from publishers.

  class `Bind`(ticket=0, queue='', exchange='', routing_key='', nowait=False, arguments=None)

    Bind queue to an exchange

    This method binds a queue to an exchange. Until a queue is bound it will not receive any messages. In a classic messaging model, store-and- forward queues are bound to a direct exchange and subscription queues are bound to a topic exchange.

  class `BindOk`

    Confirm bind successful

    This method confirms that the bind was successful.

  class `Declare`(ticket=0, queue='', passive=False, durable=False, exclusive=False, auto_delete=False, nowait=False, arguments=None)

    Declare queue, create if needed

    This method creates or checks a queue. When creating a new queue the client can specify various properties that control the durability of the queue and its contents, and the level of sharing for the queue.

  class `DeclareOk`(queue='', message_count=0, consumer_count=0)

    Confirms a queue definition

    This method confirms a Declare method and confirms the name of the queue, essential for automatically-named queues.

  class `Delete`(ticket=0, queue='', if_unused=False, if_empty=False, nowait=False)

    Delete a queue

    This method deletes a queue. When a queue is deleted any pending messages are sent to a dead-letter queue if this is defined in the server configuration, and all consumers on the queue are cancelled.

  class `DeleteOk`(message_count=0)

    Confirm deletion of a queue

    This method confirms the deletion of a queue.

  class `Purge`(ticket=0, queue='', nowait=False)

    Purge a queue

    This method removes all messages from a queue which are not awaiting acknowledgment.

  class `PurgeOk`(message_count=0)

    Confirms a queue purge

    This method confirms the purge of a queue.

  class `Unbind`(ticket=0, queue='', exchange='', routing_key='', arguments=None)

    Unbind a queue from an exchange

    This method unbinds a queue from an exchange.

  class `UnbindOk`

    Confirm unbind successful

    This method confirms that the unbind was successful.

class `pamqp.specification.``Tx`

  Work with transactions

  The Tx class allows publish and ack operations to be batched into atomic units of work. The intention is that all publish and ack requests issued within a transaction will complete successfully or none of them will. Servers SHOULD implement atomic transactions at least where all publish or ack requests affect a single queue. Transactions that cover multiple queues may be non-atomic, given that queues can be created and destroyed asynchronously, and such events do not form part of any transaction. Further, the behaviour of transactions with respect to the immediate and mandatory flags on Basic.Publish methods is not defined.

  class `Commit`

    Commit the current transaction

    This method commits all message publications and acknowledgments performed in the current transaction. A new transaction starts immediately after a commit.

  class `CommitOk`

    Confirm a successful commit

    This method confirms to the client that the commit succeeded. Note that if a commit fails, the server raises a channel exception.

  class `Rollback`

    Abandon the current transaction

    This method abandons all message publications and acknowledgments performed in the current transaction. A new transaction starts immediately after a rollback. Note that unacked messages will not be automatically redelivered by rollback; if that is required an explicit recover call should be issued.

  class `RollbackOk`

    Confirm successful rollback

    This method confirms to the client that the rollback succeeded. Note that if an rollback fails, the server raises a channel exception.

  class `Select`

    Select standard transaction mode

    This method sets the channel to use standard transactions. The client must use this method at least once on a channel before using the Commit or Rollback methods.

  class `SelectOk`

    Confirm transaction mode

    This method confirms to the client that the channel was successfully set to use standard transactions.