channel

The Channel class provides a wrapper for interacting with RabbitMQ implementing the methods and behaviors for an AMQP Channel.

Channel

class pika.channel.Channel(connection, channel_number, on_open_callback=None)[source]

A Channel is the primary communication method for interacting with RabbitMQ. It is recommended that you do not directly invoke the creation of a channel object in your application code but rather construct the a channel by calling the active connection’s channel() method.

CLOSED = 0
OPENING = 1
OPEN = 2
CLOSING = 3
add_callback(callback, replies, one_shot=True)[source]

Pass in a callback handler and a list replies from the RabbitMQ broker which you’d like the callback notified of. Callbacks should allow for the frame parameter to be passed in.

Parameters:
  • callback (method) – The method to call
  • replies (list) – The replies to get a callback for
  • one_shot (bool) – Only handle the first type callback
add_on_cancel_callback(callback)[source]

Pass a callback function that will be called when the basic_cancel is sent by the server. The callback function should receive a frame parameter.

Parameters:callback (method) – The method to call on callback
add_on_close_callback(callback)[source]

Pass a callback function that will be called when the channel is closed. The callback function should receive a frame parameter.

Parameters:callback (method) – The method to call on callback
add_on_flow_callback(callback)[source]

Pass a callback function that will be called when Channel.Flow is called by the remote server. Note that newer versions of RabbitMQ will not issue this but instead use TCP backpressure

Parameters:callback (method) – The method to call on callback
add_on_return_callback(callback)[source]

Pass a callback function that will be called when basic_publish as sent a message that has been rejected and returned by the server. The callback handler should receive a method, header and body frame. The base signature for the callback should be the same as the method signature one creates for a basic_consume callback.

Parameters:callback (method) – The method to call on callback
basic_ack(delivery_tag=0, multiple=False)[source]

Acknowledge one or more messages. When sent by the client, this method acknowledges one or more messages delivered via the Deliver or Get-Ok methods. When sent by server, this method acknowledges one or more messages published with the Publish method on a channel in confirm mode. The acknowledgement can be for a single message or a set of messages up to and including a specific message.

Parameters:
  • delivery-tag (int) – The server-assigned delivery tag
  • multiple (bool) – If set to True, the delivery tag is treated as “up to and including”, so that multiple messages can be acknowledged with a single method. If set to False, the delivery tag refers to a single message. If the multiple field is 1, and the delivery tag is zero, this indicates acknowledgement of all outstanding messages.
basic_cancel(callback=None, consumer_tag='', nowait=False)[source]

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. It may also be sent from the server to the client in the event of the consumer being unexpectedly cancelled (i.e. cancelled for any reason other than the server receiving the corresponding basic.cancel from the client). This allows clients to be notified of the loss of consumers due to events such as queue deletion.

Parameters:
  • callback (method) – Method to call for a Basic.CancelOk response
  • consumer_tag (str) – Identifier for the consumer
  • nowait (bool) – Do not expect a Basic.CancelOk response
Raises:

ValueError

basic_consume(consumer_callback, queue='', no_ack=False, exclusive=False, consumer_tag=None)[source]

Sends the AMQP command Basic.Consume to the broker and binds messages for the consumer_tag to the consumer callback. If you do not pass in a consumer_tag, one will be automatically generated for you. Returns the consumer tag.

For more information on basic_consume, see: http://www.rabbitmq.com/amqp-0-9-1-reference.html#basic.consume

Parameters:
  • consumer_callback (method) – The method to callback when consuming
  • queue (str|unicode) – The queue to consume from
  • no_ack (bool) – Tell the broker to not expect a response
  • exclusive (bool) – Don’t allow other consumers on the queue
  • consumer_tag (str|unicode) – Specify your own consumer tag
Return type:

str

basic_get(callback=None, queue='', no_ack=False)[source]

Get a single message from the AMQP broker. The callback method signature should have 3 parameters: The method frame, header frame and the body, like the consumer callback for Basic.Consume. If you want to be notified of Basic.GetEmpty, use the Channel.add_callback method adding your Basic.GetEmpty callback which should expect only one parameter, frame. For more information on basic_get and its parameters, see:

http://www.rabbitmq.com/amqp-0-9-1-reference.html#basic.get

Parameters:
  • callback (method) – The method to callback with a message
  • queue (str|unicode) – The queue to get a message from
  • no_ack (bool) – Tell the broker to not expect a reply
basic_nack(delivery_tag=None, multiple=False, requeue=True)[source]

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

Parameters:
  • delivery-tag (int) – The server-assigned delivery tag
  • multiple (bool) – If set to True, the delivery tag is treated as “up to and including”, so that multiple messages can be acknowledged with a single method. If set to False, the delivery tag refers to a single message. If the multiple field is 1, and the delivery tag is zero, this indicates acknowledgement of all outstanding messages.
  • requeue (bool) – If requeue is true, the server will attempt to requeue the message. If requeue is false or the requeue attempt fails the messages are discarded or dead-lettered.
basic_publish(exchange, routing_key, body, properties=None, mandatory=False, immediate=False)[source]

Publish to the channel with the given exchange, routing key and body. For more information on basic_publish and what the parameters do, see:

http://www.rabbitmq.com/amqp-0-9-1-reference.html#basic.publish

Parameters:
  • exchange (str) – The exchange name
  • routing_key (str) – The routing key
  • body (str) – The message body
  • properties (pika.spec.Properties) – Basic.properties
  • mandatory (bool) – The mandatory flag
  • immediate (bool) – The immediate flag
basic_qos(callback=None, prefetch_size=0, prefetch_count=0, all_channels=False)[source]

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 client can request that messages be sent in advance so that when the client finishes processing a message, the following message is already held locally, rather than needing to be sent down the channel. Prefetching gives a performance improvement.

Parameters:
  • callback (method) – The method to callback for Basic.QosOk response
  • prefetch_size (int) – This field specifies the prefetch window size. The server will send a message in advance if it is equal to or smaller in size than the available prefetch size (and also falls into other prefetch limits). May be set to zero, meaning “no specific limit”, although other prefetch limits may still apply. The prefetch-size is ignored if the no-ack option is set.
  • prefetch_count (int) – Specifies a prefetch window in terms of whole messages. This field may be used in combination with the prefetch-size field; a message will only be sent in advance if both prefetch windows (and those at the channel and connection level) allow it. The prefetch-count is ignored if the no-ack option is set.
  • all_channels (bool) – Should the QoS apply to all channels
basic_reject(delivery_tag=None, requeue=True)[source]

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.

Parameters:
  • delivery-tag (int) – The server-assigned delivery tag
  • requeue (bool) – If requeue is true, the server will attempt to requeue the message. If requeue is false or the requeue attempt fails the messages are discarded or dead-lettered.
basic_recover(callback=None, requeue=False)[source]

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.

Parameters:
  • callback (method) – Method to call when receiving Basic.RecoverOk
  • requeue (bool) – If False, the message will be redelivered to the original recipient. If True, the server will attempt to requeue the message, potentially then delivering it to an alternative subscriber.
close(reply_code=0, reply_text='Normal Shutdown')[source]

Will invoke a clean shutdown of the channel with the AMQP Broker.

Parameters:
  • reply_code (int) – The reply code to close the channel with
  • reply_text (str) – The reply text to close the channel with
confirm_delivery(callback=None, nowait=False)[source]

Turn on Confirm mode in the channel. Pass in a callback to be notified by the Broker when a message has been confirmed as received or rejected (Basic.Ack, Basic.Nack) from the broker to the publisher.

For more information see:
http://www.rabbitmq.com/extensions.html#confirms
Parameters:
  • callback (method) – The callback for delivery confirmations
  • nowait (bool) – Do not send a reply frame (Confirm.SelectOk)
consumer_tags

Property method that returns a list of currently active consumers

Return type:list
exchange_bind(callback=None, destination=None, source=None, routing_key='', nowait=False, arguments=None)[source]

Bind an exchange to another exchange.

Parameters:
  • callback (method) – The method to call on Exchange.BindOk
  • destination (str|unicode) – The destination exchange to bind
  • source (str|unicode) – The source exchange to bind to
  • routing_key (str|unicode) – The routing key to bind on
  • nowait (bool) – Do not wait for an Exchange.BindOk
  • arguments (dict) – Custom key/value pair arguments for the binding
exchange_declare(callback=None, exchange=None, exchange_type='direct', passive=False, durable=False, auto_delete=False, internal=False, nowait=False, arguments=None)[source]

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.

If passive set, the server will reply with Declare-Ok if the exchange already exists with the same name, and raise an error if not and if the exchange does not already exist, the server MUST raise a channel exception with reply code 404 (not found).

Parameters:
  • callback (method) – Call this method on Exchange.DeclareOk
  • exchange (str|unicode) – The exchange name consists of a non-empty sequence of these characters: letters, digits, hyphen, underscore, period, or colon.
  • exchange_type (str) – The exchange type to use
  • passive (bool) – Perform a declare or just check to see if it exists
  • durable (bool) – Survive a reboot of RabbitMQ
  • auto_delete (bool) – Remove when no more queues are bound to it
  • internal (bool) – Can only be published to by other exchanges
  • nowait (bool) – Do not expect an Exchange.DeclareOk response
  • arguments (dict) – Custom key/value pair arguments for the exchange
exchange_delete(callback=None, exchange=None, if_unused=False, nowait=False)[source]

Delete the exchange.

Parameters:
  • callback (method) – The method to call on Exchange.DeleteOk
  • exchange (str|unicode) – The exchange name
  • if_unused (bool) – only delete if the exchange is unused
  • nowait (bool) – Do not wait for an Exchange.DeleteOk
exchange_unbind(callback=None, destination=None, source=None, routing_key='', nowait=False, arguments=None)[source]

Unbind an exchange from another exchange.

Parameters:
  • callback (method) – The method to call on Exchange.UnbindOk
  • destination (str|unicode) – The destination exchange to unbind
  • source (str|unicode) – The source exchange to unbind from
  • routing_key (str|unicode) – The routing key to unbind
  • nowait (bool) – Do not wait for an Exchange.UnbindOk
  • arguments (dict) – Custom key/value pair arguments for the binding
flow(callback, active)[source]

Turn Channel flow control off and on. Pass a callback to be notified of the response from the server. active is a bool. Callback should expect a bool in response indicating channel flow state. For more information, please reference:

http://www.rabbitmq.com/amqp-0-9-1-reference.html#channel.flow

Parameters:
  • callback (method) – The callback method
  • active (bool) – Turn flow on or off
is_closed

Returns True if the channel is closed.

Return type:bool
is_closing

Returns True if the channel is closing.

Return type:bool
is_open

Returns True if the channel is open.

Return type:bool
open()[source]

Open the channel

queue_bind(callback, queue, exchange, routing_key, nowait=False, arguments=None)[source]

Bind the queue to the specified exchange

Parameters:
  • callback (method) – The method to call on Queue.BindOk
  • queue (str|unicode) – The queue to bind to the exchange
  • exchange (str|unicode) – The source exchange to bind to
  • routing_key (str|unicode) – The routing key to bind on
  • nowait (bool) – Do not wait for a Queue.BindOk
  • arguments (dict) – Custom key/value pair arguments for the binding
queue_declare(callback, queue, passive=False, durable=False, exclusive=False, auto_delete=False, nowait=False, arguments=None)[source]

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.

Parameters:
  • callback (method) – The method to call on Queue.DeclareOk
  • queue (str|unicode) – The queue name
  • passive (bool) – Only check to see if the queue exists
  • durable (bool) – Survive reboots of the broker
  • exclusive (bool) – Only allow access by the current connection
  • auto_delete (bool) – Delete after consumer cancels or disconnects
  • nowait (bool) – Do not wait for a Queue.DeclareOk
  • arguments (dict) – Custom key/value arguments for the queue
queue_delete(callback=None, queue='', if_unused=False, if_empty=False, nowait=False)[source]

Delete a queue from the broker.

Parameters:
  • callback (method) – The method to call on Queue.DeleteOk
  • queue (str|unicode) – The queue to delete
  • if_unused (bool) – only delete if it’s unused
  • if_empty (bool) – only delete if the queue is empty
  • nowait (bool) – Do not wait for a Queue.DeleteOk
queue_purge(callback=None, queue='', nowait=False)[source]

Purge all of the messages from the specified queue

Parameters:
  • callback (method) – The method to call on Queue.PurgeOk
  • str|unicode – The queue to purge
  • nowait (bool) – Do not expect a Queue.PurgeOk response
queue_unbind(callback=None, queue='', exchange=None, routing_key='', arguments=None)[source]

Unbind a queue from an exchange.

Parameters:
  • callback (method) – The method to call on Queue.UnbindOk
  • queue (str|unicode) – The queue to unbind from the exchange
  • exchange (str|unicode) – The source exchange to bind from
  • routing_key (str|unicode) – The routing key to unbind
  • arguments (dict) – Custom key/value pair arguments for the binding
tx_commit(callback=None)[source]

Commit a transaction

Parameters:callback (method) – The callback for delivery confirmations
tx_rollback(callback=None)[source]

Rollback a transaction.

Parameters:callback (method) – The callback for delivery confirmations
tx_select(callback=None)[source]

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.

Parameters:callback (method) – The callback for delivery confirmations
_add_callbacks()[source]

Callbacks that add the required behavior for a channel when connecting and connected to a server.

_add_pending_msg(consumer_tag, method_frame, header_frame, body)[source]

Add the received message to the pending message stack.

Parameters:
  • consumer_tag (str) – The consumer tag for the message
  • method_frame (pika.frame.Method) – The received method frame
  • header_frame (pika.frame.Header) – The received header frame
  • body (str|unicode) – The message body
_cleanup()[source]

Remove any callbacks for the channel.

_get_pending_msg(consumer_tag)[source]

Get a pending message for the consumer tag from the stack.

Parameters:consumer_tag (str) – The consumer tag to get a message from
Return type:tuple(pika.frame.Header, pika.frame.Method, str|unicode)
_handle_content_frame(frame_value)[source]

This is invoked by the connection when frames that are not registered with the CallbackManager have been found. This should only be the case when the frames are related to content delivery.

The frame_dispatcher will be invoked which will return the fully formed message in three parts when all of the body frames have been received.

Parameters:frame_value (pika.amqp_object.Frame) – The frame to deliver
_has_content(method_frame)[source]

Return a bool if it’s a content method as defined by the spec

Parameters:method_frame (pika.amqp_object.Method) – The method frame received
_on_cancel(method_frame)[source]

When the broker cancels a consumer, delete it from our internal dictionary.

Parameters:method_frame (pika.frame.Method) – The method frame received
_on_cancelok(method_frame)[source]
Called in response to a frame from the Broker when the
client sends Basic.Cancel
Parameters:method_frame (pika.frame.Method) – The method frame received
_on_close(method_frame)[source]

Handle the case where our channel has been closed for us

Parameters:method_frame (pika.frame.Method) – The close frame
_on_deliver(method_frame, header_frame, body)[source]

Cope with reentrancy. If a particular consumer is still active when another delivery appears for it, queue the deliveries up until it finally exits.

Parameters:
_on_eventok(method_frame)[source]

Generic events that returned ok that may have internal callbacks. We keep a list of what we’ve yet to implement so that we don’t silently drain events that we don’t support.

Parameters:method_frame (pika.frame.Method) – The method frame received
_on_flow(method_frame_unused)[source]

Called if the server sends a Channel.Flow frame.

Parameters:method_frame_unused (pika.frame.Method) – The Channel.Flow frame
_on_flowok(method_frame)[source]

Called in response to us asking the server to toggle on Channel.Flow

Parameters:method_frame (pika.frame.Method) – The method frame received
_on_getempty(method_frame)[source]

When we receive an empty reply do nothing but log it

Parameters:method_frame (pika.frame.Method) – The method frame received
_on_getok(method_frame, header_frame, body)[source]

Called in reply to a Basic.Get when there is a message.

Parameters:
_on_openok(frame_unused)[source]

Called by our callback handler when we receive a Channel.OpenOk and subsequently calls our _on_openok_callback which was passed into the Channel constructor. The reason we do this is because we want to make sure that the on_open_callback parameter passed into the Channel constructor is not the first callback we make.

Parameters:frame_unused (pika.frame.Method) – Unused Channel.OpenOk frame
_on_return(method_frame, header_frame, body)[source]

Called if the server sends a Basic.Return frame.

Parameters:
_on_selectok(method_frame)[source]

Called when the broker sends a Confirm.SelectOk frame

Parameters:method_frame (pika.frame.Method) – The method frame received
_on_synchronous_complete(method_frame_unused)[source]

This is called when a synchronous command is completed. It will undo the blocking state and send all the frames that stacked up while we were in the blocking state.

Parameters:method_frame_unused (pika.frame.Method) – The method frame received
_rpc(method_frame, callback=None, acceptable_replies=None)[source]

Shortcut wrapper to the Connection’s rpc command using its callback stack, passing in our channel number.

Parameters:
  • method_frame (pika.amqp_object.Method) – The method frame to call
  • callback (method) – The callback for the RPC response
  • acceptable_replies (list) – The replies this RPC call expects
_send_method(method_frame, content=None)[source]

Shortcut wrapper to send a method through our connection, passing in the channel number

Parameters:
  • method_frame (pika.object.Method) – The method frame to send
  • content (tuple) – If set, is a content frame, is tuple of properties and body.
_set_state(connection_state)[source]

Set the channel connection state to the specified state value.

Parameters:connection_state (int) – The connection_state value
_shutdown()[source]

Called when close() is invoked either directly or when all of the consumers have been cancelled.

_validate_channel_and_callback(callback)[source]

ContentFrameDispatcher

class pika.channel.ContentFrameDispatcher[source]

Handle content related frames, building a message and return the message back in three parts upon receipt.

process(frame_value)[source]

Invoked by the Channel object when passed frames that are not setup in the rpc process and that don’t have explicit reply types defined. This includes Basic.Publish, Basic.GetOk and Basic.Return

Parameters:frame_value (Method|Header|Body) – The frame to process
_finish()[source]

Invoked when all of the message has been received

Return type:tuple(pika.frame.Method, pika.frame.Header, str|unicode)
_handle_body_frame(body_frame)[source]

Receive body frames and append them to the stack. When the body size matches, call the finish method.

Parameters:body_frame (Body) – The body frame
Raises:pika.exceptions.BodyTooLongError
Return type:tuple(pika.frame.Method, pika.frame.Header, str|unicode)|None
_reset()[source]

Reset the values for processing frames