pika 0.13.1 documentation

on_connected

Introduction to Pika¶
Pika is a pure-Python implementation of the AMQP 0-9-1 protocol that tries to stay fairly independent of the underlying network support library.
If you have not developed with Pika or RabbitMQ before, the Introduction to Pika documentation is a good place to get started.

Installing Pika¶
Pika is available for download via PyPI and may be installed using easy_install or pip:
pip install pika

or:
easy_install pika

To install from source, run “python setup.py install” in the root source directory.

Using Pika¶

Introduction to Pika¶

IO and Event Looping¶
As AMQP is a two-way RPC protocol where the client can send requests to the server and the server can send requests to a client, Pika implements or extends IO loops in each of its asynchronous connection adapters. These IO loops are blocking methods which loop and listen for events. Each asynchronous adapter follows the same standard for invoking the IO loop. The IO loop is created when the connection adapter is created. To start an IO loop for any given adapter, call the connection.ioloop.start() method.
If you are using an external IO loop such as Tornado’s IOLoop you invoke it normally and then add the Pika Tornado adapter to it.
Example:
import pika

def on_open(connection):
    # Invoked when the connection is open
    pass

# Create our connection object, passing in the on_open method
connection = pika.SelectConnection(on_open_callback=on_open)

try:
    # Loop so we can communicate with RabbitMQ
    connection.ioloop.start()
except KeyboardInterrupt:
    # Gracefully close the connection
    connection.close()
    # Loop until we're fully closed, will stop on its own
    connection.ioloop.start()

Continuation-Passing Style¶
Interfacing with Pika asynchronously is done by passing in callback methods you would like to have invoked when a certain event completes. For example, if you are going to declare a queue, you pass in a method that will be called when the RabbitMQ server returns a Queue.DeclareOk response.
In our example below we use the following five easy steps:

We start by creating our connection object, then starting our event loop.
When we are connected, the on_connected method is called. In that method we create a channel.
When the channel is created, the on_channel_open method is called. In that method we declare a queue.
When the queue is declared successfully, on_queue_declared is called. In that method we call channel.basic_consume telling it to call the handle_delivery for each message RabbitMQ delivers to us.
When RabbitMQ has a message to send us, it calls the handle_delivery method passing the AMQP Method frame, Header frame, and Body.

Note
Step #1 is on line #28 and Step #2 is on line #6. This is so that Python knows about the functions we’ll call in Steps #2 through #5.

Example:
import pika

# Create a global channel variable to hold our channel object in
channel = None

# Step #2
def on_connected(connection):
    """Called when we are fully connected to RabbitMQ"""
    # Open a channel
    connection.channel(on_channel_open)

# Step #3
def on_channel_open(new_channel):
    """Called when our channel has opened"""
    global channel
    channel = new_channel
    channel.queue_declare(queue="test", durable=True, exclusive=False, auto_delete=False, callback=on_queue_declared)

# Step #4
def on_queue_declared(frame):
    """Called when RabbitMQ has told us our Queue has been declared, frame is the response from RabbitMQ"""
    channel.basic_consume(handle_delivery, queue='test')

# Step #5
def handle_delivery(channel, method, header, body):
    """Called when we receive a message from RabbitMQ"""
    print(body)

# Step #1: Connect to RabbitMQ using the default parameters
parameters = pika.ConnectionParameters()
connection = pika.SelectConnection(parameters, on_connected)

try:
    # Loop so we can communicate with RabbitMQ
    connection.ioloop.start()
except KeyboardInterrupt:
    # Gracefully close the connection
    connection.close()
    # Loop until we're fully closed, will stop on its own
    connection.ioloop.start()

Credentials¶
The pika.credentials module provides the mechanism by which you pass the username and password to the ConnectionParameters class when it is created.
Example:
import pika
credentials = pika.PlainCredentials('username', 'password')
parameters = pika.ConnectionParameters(credentials=credentials)

Connection Parameters¶
There are two types of connection parameter classes in Pika to allow you to pass the connection information into a connection adapter, ConnectionParameters and URLParameters. Both classes share the same default connection values.

TCP Backpressure¶
As of RabbitMQ 2.0, client side Channel.Flow has been removed [1]. Instead, the RabbitMQ broker uses TCP Backpressure to slow your client if it is delivering messages too fast. If you pass in backpressure_detection into your connection parameters, Pika attempts to help you handle this situation by providing a mechanism by which you may be notified if Pika has noticed too many frames have yet to be delivered. By registering a callback function with the add_backpressure_callback method of any connection adapter, your function will be called when Pika sees that a backlog of 10 times the average frame size you have been sending has been exceeded. You may tweak the notification multiplier value by calling the set_backpressure_multiplier method passing any integer value.
Example:
import pika

parameters = pika.URLParameters('amqp://guest:guest@rabbit-server1:5672/%2F?backpressure_detection=t')

Footnotes

[1] “more effective flow control mechanism that does not require cooperation from clients and reacts quickly to prevent the broker from exhausting memory - see http://www.rabbitmq.com/extensions.html#memsup” from http://lists.rabbitmq.com/pipermail/rabbitmq-announce/attachments/20100825/2c672695/attachment.txt

Core Class and Module Documentation¶
For the end user, Pika is organized into a small set of objects for all communication with RabbitMQ.

A connection adapter is used to connect to RabbitMQ and manages the connection.
Connection parameters are used to instruct the Connection object how to connect to RabbitMQ.
Authentication Credentials are used to encapsulate all authentication information for the ConnectionParameters class.
A Channel object is used to communicate with RabbitMQ via the AMQP RPC methods.
Exceptions are raised at various points when using Pika when something goes wrong.

Connection Adapters¶
Pika uses connection adapters to provide a flexible method for adapting pika’s
core communication to different IOLoop implementations. In addition to asynchronous adapters, there is the BlockingConnection adapter that provides a more idiomatic procedural approach to using Pika.

Adapters¶

BlockingConnection¶
The blocking connection adapter module implements blocking semantics on top
of Pika’s core AMQP driver. While most of the asynchronous expectations are
removed when using the blocking connection adapter, it attempts to remain true
to the asynchronous RPC nature of the AMQP protocol, supporting server sent
RPC commands.
The user facing classes in the module consist of the
BlockingConnection
and the BlockingChannel
classes.
Be sure to check out examples in Usage Examples.

class pika.adapters.blocking_connection.BlockingConnection(parameters=None, _impl_class=None)[source]¶
The BlockingConnection creates a layer on top of Pika’s asynchronous core
providing methods that will block until their expected response has
returned. Due to the asynchronous nature of the Basic.Deliver and
Basic.Return calls from RabbitMQ to your application, you can still
implement continuation-passing style asynchronous methods if you’d like to
receive messages from RabbitMQ using
basic_consume or if you want to be
notified of a delivery failure when using
basic_publish.
For more information about communicating with the blocking_connection
adapter, be sure to check out the
BlockingChannel class which implements the
Channel based communication for the
blocking_connection adapter.
To prevent recursion/reentrancy, the blocking connection and channel
implementations queue asynchronously-delivered events received
in nested context (e.g., while waiting for BlockingConnection.channel or
BlockingChannel.queue_declare to complete), dispatching them synchronously
once nesting returns to the desired context. This concerns all callbacks,
such as those registered via BlockingConnection.add_timeout,
BlockingConnection.add_on_connection_blocked_callback,
BlockingConnection.add_on_connection_unblocked_callback,
BlockingChannel.basic_consume, etc.
Blocked Connection deadlock avoidance: when RabbitMQ becomes low on
resources, it emits Connection.Blocked (AMQP extension) to the client
connection when client makes a resource-consuming request on that connection
or its channel (e.g., Basic.Publish); subsequently, RabbitMQ suspsends
processing requests from that connection until the affected resources are
restored. See http://www.rabbitmq.com/connection-blocked.html. This
may impact BlockingConnection and BlockingChannel operations in a
way that users might not be expecting. For example, if the user dispatches
BlockingChannel.basic_publish in non-publisher-confirmation mode while
RabbitMQ is in this low-resource state followed by a synchronous request
(e.g., BlockingConnection.channel, BlockingChannel.consume,
BlockingChannel.basic_consume, etc.), the synchronous request will block
indefinitely (until Connection.Unblocked) waiting for RabbitMQ to reply. If
the blocked state persists for a long time, the blocking operation will
appear to hang. In this state, BlockingConnection instance and its
channels will not dispatch user callbacks. SOLUTION: To break this potential
deadlock, applications may configure the blocked_connection_timeout
connection parameter when instantiating BlockingConnection. Upon blocked
connection timeout, this adapter will raise ConnectionClosed exception with
first exception arg of
pika.connection.InternalCloseReasons.BLOCKED_CONNECTION_TIMEOUT. See
pika.connection.ConnectionParameters documentation to learn more about
blocked_connection_timeout configuration.

add_callback_threadsafe(callback)[source]¶
Requests a call to the given function as soon as possible in the
context of this connection’s thread.
NOTE: This is the only thread-safe method in BlockingConnection. All
other manipulations of BlockingConnection must be performed from the
connection’s thread.
For example, a thread may request a call to the
BlockingChannel.basic_ack method of a BlockingConnection that is
running in a different thread via
```
connection.add_callback_threadsafe(

functools.partial(channel.basic_ack, delivery_tag=…))
```

NOTE: if you know that the requester is running on the same thread as
the connection it is more efficient to use the
BlockingConnection.add_timeout() method with a deadline of 0.

Parameters: callback (method) – The callback method; must be callable

add_on_connection_blocked_callback(callback_method)[source]¶
Add a callback to be notified when RabbitMQ has sent a
Connection.Blocked frame indicating that RabbitMQ is low on
resources. Publishers can use this to voluntarily suspend publishing,
instead of relying on back pressure throttling. The callback
will be passed the Connection.Blocked method frame.
See also ConnectionParameters.blocked_connection_timeout.

Parameters: callback_method (method) – Callback to call on Connection.Blocked,
having the signature callback_method(pika.frame.Method), where the
method frame’s method member is of type
pika.spec.Connection.Blocked

add_on_connection_unblocked_callback(callback_method)[source]¶
Add a callback to be notified when RabbitMQ has sent a
Connection.Unblocked frame letting publishers know it’s ok
to start publishing again. The callback will be passed the
Connection.Unblocked method frame.

Parameters: callback_method (method) – Callback to call on
Connection.Unblocked, having the signature
callback_method(pika.frame.Method), where the method frame’s
method member is of type pika.spec.Connection.Unblocked

add_timeout(deadline, callback_method)[source]¶
Create a single-shot timer to fire after deadline seconds. Do not
confuse with Tornado’s timeout where you pass in the time you want to
have your callback called. Only pass in the seconds until it’s to be
called.
NOTE: the timer callbacks are dispatched only in the scope of
specially-designated methods: see
BlockingConnection.process_data_events and
BlockingChannel.start_consuming.

Parameters: 
deadline (float) – The number of seconds to wait to call callback
callback_method (callable) – The callback method with the signature
callback_method()

Returns: opaque timer id

basic_nack¶
Specifies if the server supports basic.nack on the active connection.

Return type: bool

basic_nack_supported¶
Specifies if the server supports basic.nack on the active connection.

Return type: bool

channel(channel_number=None)[source]¶
Create a new channel with the next available channel number or pass
in a channel number to use. Must be non-zero if you would like to
specify but it is recommended that you let Pika manage the channel
numbers.

Return type: pika.adapters.blocking_connection.BlockingChannel

close(reply_code=200, reply_text='Normal shutdown')[source]¶
Disconnect from RabbitMQ. If there are any open channels, it will
attempt to close them prior to fully disconnecting. Channels which
have active consumers will attempt to send a Basic.Cancel to RabbitMQ
to cleanly stop the delivery of messages prior to closing the channel.

Parameters: 
reply_code (int) – The code number for the close
reply_text (str) – The text reason for the close

consumer_cancel_notify¶
Specifies if the server supports consumer cancel notification on the
active connection.

Return type: bool

consumer_cancel_notify_supported¶
Specifies if the server supports consumer cancel notification on the
active connection.

Return type: bool

exchange_exchange_bindings¶
Specifies if the active connection supports exchange to exchange
bindings.

Return type: bool

exchange_exchange_bindings_supported¶
Specifies if the active connection supports exchange to exchange
bindings.

Return type: bool

is_closed¶
Returns a boolean reporting the current connection state.

is_closing¶
Returns True if connection is in the process of closing due to
client-initiated close request, but closing is not yet complete.

is_open¶
Returns a boolean reporting the current connection state.

process_data_events(time_limit=0)[source]¶
Will make sure that data events are processed. Dispatches timer and
channel callbacks if not called from the scope of BlockingConnection or
BlockingChannel callback. Your app can block on this method.

Parameters: time_limit (float) – suggested upper bound on processing time in
seconds. The actual blocking time depends on the granularity of the
underlying ioloop. Zero means return as soon as possible. None means
there is no limit on processing time and the function will block
until I/O produces actionable events. Defaults to 0 for backward
compatibility. This parameter is NEW in pika 0.10.0.

publisher_confirms¶
Specifies if the active connection can use publisher confirmations.

Return type: bool

publisher_confirms_supported¶
Specifies if the active connection can use publisher confirmations.

Return type: bool

remove_timeout(timeout_id)[source]¶
Remove a timer if it’s still in the timeout stack

Parameters: timeout_id – The opaque timer id to remove

sleep(duration)[source]¶
A safer way to sleep than calling time.sleep() directly that would
keep the adapter from ignoring frames sent from the broker. The
connection will “sleep” or block the number of seconds specified in
duration in small intervals.

Parameters: duration (float) – The time to sleep in seconds

class pika.adapters.blocking_connection.BlockingChannel(channel_impl, connection)[source]¶
The BlockingChannel implements blocking semantics for most things that
one would use callback-passing-style for with the
Channel class. In addition,
the BlockingChannel class implements a generator that allows
you to consume messages
without using callbacks.
Example of creating a BlockingChannel:
import pika

# Create our connection object
connection = pika.BlockingConnection()

# The returned object will be a synchronous channel
channel = connection.channel()

add_on_cancel_callback(callback)[source]¶
Pass a callback function that will be called when Basic.Cancel
is sent by the broker. The callback function should receive a method
frame parameter.

Parameters: callback (callable) – a callable for handling broker’s Basic.Cancel
notification with the call signature: callback(method_frame)
where method_frame is of type pika.frame.Method with method of
type spec.Basic.Cancel

add_on_return_callback(callback)[source]¶
Pass a callback function that will be called when a published
message is rejected and returned by the server via Basic.Return.

Parameters: callback (callable) – The method to call on callback with the
signature callback(channel, method, properties, body), where
channel: pika.Channel
method: pika.spec.Basic.Return
properties: pika.spec.BasicProperties
body: str, unicode, or bytes (python 3.x)

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(consumer_tag)[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.
NOTE: When cancelling a no_ack=False consumer, this implementation
automatically Nacks and suppresses any incoming messages that have not
yet been dispatched to the consumer’s callback. However, when cancelling
a no_ack=True consumer, this method will return any pending messages
that arrived before broker confirmed the cancellation.

Parameters: consumer_tag (str) – Identifier for the consumer; the result of
passing a consumer_tag that was created on another channel is
undefined (bad things will happen)

Returns: (NEW IN pika 0.10.0) empty sequence for a no_ack=False
consumer; for a no_ack=True consumer, returns a (possibly empty)
sequence of pending messages that arrived before broker confirmed
the cancellation (this is done instead of via consumer’s callback in
order to prevent reentrancy/recursion. Each message is four-tuple:
(channel, method, properties, body)
channel: BlockingChannel
method: spec.Basic.Deliver
properties: spec.BasicProperties
body: str or unicode

basic_consume(consumer_callback, queue, no_ack=False, exclusive=False, consumer_tag=None, arguments=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.
NOTE: the consumer callbacks are dispatched only in the scope of
specially-designated methods: see
BlockingConnection.process_data_events and
BlockingChannel.start_consuming.
For more information about Basic.Consume, see:
http://www.rabbitmq.com/amqp-0-9-1-reference.html#basic.consume

Parameters: 
consumer_callback (callable) – The function for dispatching messages
to user, having the signature:
consumer_callback(channel, method, properties, body)

channel: BlockingChannel
method: spec.Basic.Deliver
properties: spec.BasicProperties
body: str or unicode

queue (str or unicode) – The queue to consume from
no_ack (bool) – Tell the broker to not expect a response (i.e.,
no ack/nack)
exclusive (bool) – Don’t allow other consumers on the queue
consumer_tag (str or unicode) – You may specify your own consumer tag; if left
empty, a consumer tag will be generated automatically
arguments (dict) – Custom key/value pair arguments for the consumer

Returns: consumer tag

Return type: str

Raises: pika.exceptions.DuplicateConsumerTag – if consumer with given
consumer_tag is already present.

basic_get(queue=None, no_ack=False)[source]¶
Get a single message from the AMQP broker. Returns a sequence with
the method frame, message properties, and body.

Parameters: 
queue (str or unicode) – Name of queue to get a message from
no_ack (bool) – Tell the broker to not expect a reply

Returns: a three-tuple; (None, None, None) if the queue was empty;
otherwise (method, properties, body); NOTE: body may be None

Return type: (None, None, None)|(spec.Basic.GetOk,
spec.BasicProperties,
str or unicode or None)

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.
Returns a boolean value indicating the success of the operation.
This is the legacy BlockingChannel method for publishing. See also
BlockingChannel.publish that provides more information about failures.
For more information on basic_publish and what the parameters do, see:

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

NOTE: mandatory and immediate may be enabled even without delivery
confirmation, but in the absence of delivery confirmation the
synchronous implementation has no way to know how long to wait for
the Basic.Return or lack thereof.

Parameters: 
exchange (str or unicode) – The exchange to publish to
routing_key (str or unicode) – The routing key to bind on
body (str or unicode) – The message body; empty string if no body
properties (pika.spec.BasicProperties) – message properties
mandatory (bool) – The mandatory flag
immediate (bool) – The immediate flag

Returns: True if delivery confirmation is not enabled (NEW in pika
0.10.0); otherwise returns False if the message could not be
delivered (Basic.nack and/or Basic.Return) and True if the message
was delivered (Basic.ack and no Basic.Return)

basic_qos(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: 
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 in the consumer.
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 in the consumer.
all_channels (bool) – Should the QoS apply to all channels

basic_recover(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: 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.

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.

cancel()[source]¶
Cancel the queue consumer created by BlockingChannel.consume,
rejecting all pending ackable messages.
NOTE: If you’re looking to cancel a consumer issued with
BlockingChannel.basic_consume then you should call
BlockingChannel.basic_cancel.

Return int: The number of messages requeued by Basic.Nack.
NEW in 0.10.0: returns 0

channel_number¶
Channel number

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()[source]¶
Turn on RabbitMQ-proprietary Confirm mode in the channel.

For more information see:
http://www.rabbitmq.com/extensions.html#confirms

connection¶
The channel’s BlockingConnection instance

consume(queue, no_ack=False, exclusive=False, arguments=None, inactivity_timeout=None)[source]¶
Blocking consumption of a queue instead of via a callback. This
method is a generator that yields each message as a tuple of method,
properties, and body. The active generator iterator terminates when the
consumer is cancelled by client via BlockingChannel.cancel() or by
broker.
Example:

for method, properties, body in channel.consume(‘queue’):
print body
channel.basic_ack(method.delivery_tag)

You should call BlockingChannel.cancel() when you escape out of the
generator loop.
If you don’t cancel this consumer, then next call on the same channel
to consume() with the exact same (queue, no_ack, exclusive) parameters
will resume the existing consumer generator; however, calling with
different parameters will result in an exception.

Parameters: 
queue (str or unicode) – The queue name to consume
no_ack (bool) – Tell the broker to not expect a ack/nack response
exclusive (bool) – Don’t allow other consumers on the queue
arguments (dict) – Custom key/value pair arguments for the consumer
inactivity_timeout (float) – if a number is given (in
seconds), will cause the method to yield (None, None, None) after the
given period of inactivity; this permits for pseudo-regular maintenance
activities to be carried out by the user while waiting for messages
to arrive. If None is given (default), then the method blocks until
the next event arrives. NOTE that timing granularity is limited by
the timer resolution of the underlying implementation.
NEW in pika 0.10.0.

Yields: tuple(spec.Basic.Deliver, spec.BasicProperties, str or unicode)

Raises: ValueError – if consumer-creation parameters don’t match those
of the existing queue consumer generator, if any.
NEW in pika 0.10.0

exchange_bind(destination=None, source=None, routing_key='', arguments=None)[source]¶
Bind an exchange to another exchange.

Parameters: 
destination (str or unicode) – The destination exchange to bind
source (str or unicode) – The source exchange to bind to
routing_key (str or unicode) – The routing key to bind on
arguments (dict) – Custom key/value pair arguments for the binding

Returns: Method frame from the Exchange.Bind-ok response

Return type: pika.frame.Method having method attribute of type
spec.Exchange.BindOk

exchange_declare(exchange=None, exchange_type='direct', passive=False, durable=False, auto_delete=False, internal=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: 
exchange (str or 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
arguments (dict) – Custom key/value pair arguments for the exchange

Returns: Method frame from the Exchange.Declare-ok response

Return type: pika.frame.Method having method attribute of type
spec.Exchange.DeclareOk

exchange_delete(exchange=None, if_unused=False)[source]¶
Delete the exchange.

Parameters: 
exchange (str or unicode) – The exchange name
if_unused (bool) – only delete if the exchange is unused

Returns: Method frame from the Exchange.Delete-ok response

Return type: pika.frame.Method having method attribute of type
spec.Exchange.DeleteOk

exchange_unbind(destination=None, source=None, routing_key='', arguments=None)[source]¶
Unbind an exchange from another exchange.

Parameters: 
destination (str or unicode) – The destination exchange to unbind
source (str or unicode) – The source exchange to unbind from
routing_key (str or unicode) – The routing key to unbind
arguments (dict) – Custom key/value pair arguments for the binding

Returns: Method frame from the Exchange.Unbind-ok response

Return type: pika.frame.Method having method attribute of type
spec.Exchange.UnbindOk

flow(active)[source]¶
Turn Channel flow control off and on.
NOTE: RabbitMQ doesn’t support active=False; per
https://www.rabbitmq.com/specification.html: “active=false is not
supported by the server. Limiting prefetch with basic.qos provides much
better control”
For more information, please reference:
http://www.rabbitmq.com/amqp-0-9-1-reference.html#channel.flow

Parameters: active (bool) – Turn flow on (True) or off (False)

Returns: True if broker will start or continue sending; False if not

Return type: bool

get_waiting_message_count()[source]¶
Returns the number of messages that may be retrieved from the current
queue consumer generator via BlockingChannel.consume without blocking.
NEW in pika 0.10.0

Return type: int

is_closed¶
Returns True if the channel is closed.

Return type: bool

is_closing¶
Returns True if client-initiated closing of the channel is in
progress.

Return type: bool

is_open¶
Returns True if the channel is open.

Return type: bool

publish(exchange, routing_key, body, properties=None, mandatory=False, immediate=False)[source]¶
Publish to the channel with the given exchange, routing key, and
body. Unlike the legacy BlockingChannel.basic_publish, this method
provides more information about failures via exceptions.
For more information on basic_publish and what the parameters do, see:

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

NOTE: mandatory and immediate may be enabled even without delivery
confirmation, but in the absence of delivery confirmation the
synchronous implementation has no way to know how long to wait for
the Basic.Return.

Parameters: 
exchange (str or unicode) – The exchange to publish to
routing_key (str or unicode) – The routing key to bind on
body (str or unicode) – The message body; empty string if no body
properties (pika.spec.BasicProperties) – message properties
mandatory (bool) – The mandatory flag
immediate (bool) – The immediate flag

Raises: 
UnroutableError – raised when a message published in
publisher-acknowledgments mode (see
BlockingChannel.confirm_delivery) is returned via Basic.Return
followed by Basic.Ack.
NackError – raised when a message published in
publisher-acknowledgements mode is Nack’ed by the broker. See
BlockingChannel.confirm_delivery.

queue_bind(queue, exchange, routing_key=None, arguments=None)[source]¶
Bind the queue to the specified exchange

Parameters: 
queue (str or unicode) – The queue to bind to the exchange
exchange (str or unicode) – The source exchange to bind to
routing_key (str or unicode) – The routing key to bind on
arguments (dict) – Custom key/value pair arguments for the binding

Returns: Method frame from the Queue.Bind-ok response

Return type: pika.frame.Method having method attribute of type
spec.Queue.BindOk

queue_declare(queue='', passive=False, durable=False, exclusive=False, auto_delete=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.
Leave the queue name empty for a auto-named queue in RabbitMQ

Parameters: 
queue (str or unicode; if empty string, the broker will create a
unique queue name;) – The queue name
passive (bool) – Only check to see if the queue exists and raise
ChannelClosed if it doesn’t;
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
arguments (dict) – Custom key/value arguments for the queue

Returns: Method frame from the Queue.Declare-ok response

Return type: pika.frame.Method having method attribute of type
spec.Queue.DeclareOk

queue_delete(queue='', if_unused=False, if_empty=False)[source]¶
Delete a queue from the broker.

Parameters: 
queue (str or unicode) – The queue to delete
if_unused (bool) – only delete if it’s unused
if_empty (bool) – only delete if the queue is empty

Returns: Method frame from the Queue.Delete-ok response

Return type: pika.frame.Method having method attribute of type
spec.Queue.DeleteOk

queue_purge(queue='')[source]¶
Purge all of the messages from the specified queue

Parameters: queue (str or unicode) – The queue to purge

Returns: Method frame from the Queue.Purge-ok response

Return type: pika.frame.Method having method attribute of type
spec.Queue.PurgeOk

queue_unbind(queue='', exchange=None, routing_key=None, arguments=None)[source]¶
Unbind a queue from an exchange.

Parameters: 
queue (str or unicode) – The queue to unbind from the exchange
exchange (str or unicode) – The source exchange to bind from
routing_key (str or unicode) – The routing key to unbind
arguments (dict) – Custom key/value pair arguments for the binding

Returns: Method frame from the Queue.Unbind-ok response

Return type: pika.frame.Method having method attribute of type
spec.Queue.UnbindOk

start_consuming()[source]¶
Processes I/O events and dispatches timers and basic_consume
callbacks until all consumers are cancelled.
NOTE: this blocking function may not be called from the scope of a
pika callback, because dispatching basic_consume callbacks from this
context would constitute recursion.

Raises: pika.exceptions.RecursionError – if called from the scope of a
BlockingConnection or BlockingChannel callback

stop_consuming(consumer_tag=None)[source]¶
Cancels all consumers, signalling the start_consuming loop to
exit.
NOTE: pending non-ackable messages will be lost; pending ackable
messages will be rejected.

tx_commit()[source]¶
Commit a transaction.

Returns: Method frame from the Tx.Commit-ok response

Return type: pika.frame.Method having method attribute of type
spec.Tx.CommitOk

tx_rollback()[source]¶
Rollback a transaction.

Returns: Method frame from the Tx.Commit-ok response

Return type: pika.frame.Method having method attribute of type
spec.Tx.CommitOk

tx_select()[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.

Returns: Method frame from the Tx.Select-ok response

Return type: pika.frame.Method having method attribute of type
spec.Tx.SelectOk

Select Connection Adapter¶
A connection adapter that tries to use the best polling method for the
platform pika is running on.

class pika.adapters.select_connection.SelectConnection(parameters=None, on_open_callback=None, on_open_error_callback=None, on_close_callback=None, stop_ioloop_on_close=True, custom_ioloop=None)[source]¶
An asynchronous connection adapter that attempts to use the fastest
event loop adapter for the given platform.

add_backpressure_callback(callback_method)¶
Call method “callback” when pika believes backpressure is being
applied.

Parameters: callback_method (method) – The method to call

add_callback_threadsafe(callback)¶
Requests a call to the given function as soon as possible in the
context of this connection’s IOLoop thread.

NOTE: This is the only thread-safe method offered by the connection. All
other manipulations of the connection must be performed from the
connection’s thread.

For example, a thread may request a call to the
channel.basic_ack method of a connection that is running in a
different thread via
```
connection.add_callback_threadsafe(

functools.partial(channel.basic_ack, delivery_tag=…))
```

Parameters: callback (method) – The callback method; must be callable.

add_on_close_callback(callback_method)¶
Add a callback notification when the connection has closed. The
callback will be passed the connection, the reply_code (int) and the
reply_text (str), if sent by the remote server.

Parameters: callback_method (method) – Callback to call on close

add_on_connection_blocked_callback(callback_method)¶
Add a callback to be notified when RabbitMQ has sent a
Connection.Blocked frame indicating that RabbitMQ is low on
resources. Publishers can use this to voluntarily suspend publishing,
instead of relying on back pressure throttling. The callback
will be passed the Connection.Blocked method frame.
See also ConnectionParameters.blocked_connection_timeout.

Parameters: callback_method (method) – Callback to call on Connection.Blocked,
having the signature callback_method(pika.frame.Method), where the
method frame’s method member is of type
pika.spec.Connection.Blocked

add_on_connection_unblocked_callback(callback_method)¶
Add a callback to be notified when RabbitMQ has sent a
Connection.Unblocked frame letting publishers know it’s ok
to start publishing again. The callback will be passed the
Connection.Unblocked method frame.

Parameters: callback_method (method) – Callback to call on
Connection.Unblocked, having the signature
callback_method(pika.frame.Method), where the method frame’s
method member is of type pika.spec.Connection.Unblocked

add_on_open_callback(callback_method)¶
Add a callback notification when the connection has opened.

Parameters: callback_method (method) – Callback to call when open

add_on_open_error_callback(callback_method, remove_default=True)¶
Add a callback notification when the connection can not be opened.
The callback method should accept the connection object that could not
connect, and an optional error message.

Parameters: 
callback_method (method) – Callback to call when can’t connect
remove_default (bool) – Remove default exception raising callback

add_timeout(deadline, callback_method)¶
Add the callback_method to the IOLoop timer to fire after deadline
seconds. Returns a handle to the timeout

Parameters: 
deadline (int) – The number of seconds to wait to call callback
callback_method (method) – The callback method

Return type: str

basic_nack¶
Specifies if the server supports basic.nack on the active connection.

Return type: bool

channel(on_open_callback, channel_number=None)¶
Create a new channel with the next available channel number or pass
in a channel number to use. Must be non-zero if you would like to
specify but it is recommended that you let Pika manage the channel
numbers.

Parameters: 
on_open_callback (method) – The callback when the channel is opened
channel_number (int) – The channel number to use, defaults to the
next available.

Return type: pika.channel.Channel

close(reply_code=200, reply_text='Normal shutdown')¶
Disconnect from RabbitMQ. If there are any open channels, it will
attempt to close them prior to fully disconnecting. Channels which
have active consumers will attempt to send a Basic.Cancel to RabbitMQ
to cleanly stop the delivery of messages prior to closing the channel.

Parameters: 
reply_code (int) – The code number for the close
reply_text (str) – The text reason for the close

connect()¶
Invoke if trying to reconnect to a RabbitMQ server. Constructing the
Connection object should connect on its own.

consumer_cancel_notify¶
Specifies if the server supports consumer cancel notification on the
active connection.

Return type: bool

exchange_exchange_bindings¶
Specifies if the active connection supports exchange to exchange
bindings.

Return type: bool

is_closed¶
Returns a boolean reporting the current connection state.

is_closing¶
Returns True if connection is in the process of closing due to
client-initiated close request, but closing is not yet complete.

is_open¶
Returns a boolean reporting the current connection state.

publisher_confirms¶
Specifies if the active connection can use publisher confirmations.

Return type: bool

remove_timeout(timeout_id)¶
Remove the timeout from the IOLoop by the ID returned from
add_timeout.

Return type: str

set_backpressure_multiplier(value=10)¶
Alter the backpressure multiplier value. We set this to 10 by default.
This value is used to raise warnings and trigger the backpressure
callback.

Parameters: value (int) – The multiplier value to set

Tornado Connection Adapter¶
Be sure to check out the asynchronous examples including the Tornado specific consumer example.

Twisted Connection Adapter¶
Using Pika with a Twisted reactor.
Supports two methods of establishing the connection, using TwistedConnection
or TwistedProtocolConnection. For details about each method, see the docstrings
of the corresponding classes.
The interfaces in this module are Deferred-based when possible. This means that
the connection.channel() method and most of the channel methods return
Deferreds instead of taking a callback argument and that basic_consume()
returns a Twisted DeferredQueue where messages from the server will be
stored. Refer to the docstrings for TwistedConnection.channel() and the
TwistedChannel class for details.

class pika.adapters.twisted_connection.TwistedConnection(parameters=None, on_open_callback=None, on_open_error_callback=None, on_close_callback=None, stop_ioloop_on_close=False)[source]¶
A standard Pika connection adapter. You instantiate the class passing the
connection parameters and the connected callback and when it gets called
you can start using it.
The problem is that connection establishing is done using the blocking
socket module. For instance, if the host you are connecting to is behind a
misconfigured firewall that just drops packets, the whole process will
freeze until the connection timeout passes. To work around that problem,
use TwistedProtocolConnection, but read its docstring first.
Objects of this class get put in the Twisted reactor which will notify them
when the socket connection becomes readable or writable, so apart from
implementing the BaseConnection interface, they also provide Twisted’s
IReadWriteDescriptor interface.

add_backpressure_callback(callback_method)¶
Call method “callback” when pika believes backpressure is being
applied.

Parameters: callback_method (method) – The method to call

add_callback_threadsafe(callback)¶
Requests a call to the given function as soon as possible in the
context of this connection’s IOLoop thread.

NOTE: This is the only thread-safe method offered by the connection. All
other manipulations of the connection must be performed from the
connection’s thread.

For example, a thread may request a call to the
channel.basic_ack method of a connection that is running in a
different thread via
```
connection.add_callback_threadsafe(

functools.partial(channel.basic_ack, delivery_tag=…))
```

Parameters: callback (method) – The callback method; must be callable.

add_on_close_callback(callback_method)¶
Add a callback notification when the connection has closed. The
callback will be passed the connection, the reply_code (int) and the
reply_text (str), if sent by the remote server.

Parameters: callback_method (method) – Callback to call on close

add_on_connection_blocked_callback(callback_method)¶
Add a callback to be notified when RabbitMQ has sent a
Connection.Blocked frame indicating that RabbitMQ is low on
resources. Publishers can use this to voluntarily suspend publishing,
instead of relying on back pressure throttling. The callback
will be passed the Connection.Blocked method frame.
See also ConnectionParameters.blocked_connection_timeout.

Parameters: callback_method (method) – Callback to call on Connection.Blocked,
having the signature callback_method(pika.frame.Method), where the
method frame’s method member is of type
pika.spec.Connection.Blocked

add_on_connection_unblocked_callback(callback_method)¶
Add a callback to be notified when RabbitMQ has sent a
Connection.Unblocked frame letting publishers know it’s ok
to start publishing again. The callback will be passed the
Connection.Unblocked method frame.

Parameters: callback_method (method) – Callback to call on
Connection.Unblocked, having the signature
callback_method(pika.frame.Method), where the method frame’s
method member is of type pika.spec.Connection.Unblocked

add_on_open_callback(callback_method)¶
Add a callback notification when the connection has opened.

Parameters: callback_method (method) – Callback to call when open

add_on_open_error_callback(callback_method, remove_default=True)¶
Add a callback notification when the connection can not be opened.
The callback method should accept the connection object that could not
connect, and an optional error message.

Parameters: 
callback_method (method) – Callback to call when can’t connect
remove_default (bool) – Remove default exception raising callback

add_timeout(deadline, callback_method)¶
Add the callback_method to the IOLoop timer to fire after deadline
seconds. Returns a handle to the timeout

Parameters: 
deadline (int) – The number of seconds to wait to call callback
callback_method (method) – The callback method

Return type: str

basic_nack¶
Specifies if the server supports basic.nack on the active connection.

Return type: bool

channel(channel_number=None)[source]¶
Return a Deferred that fires with an instance of a wrapper around the
Pika Channel class.

close(reply_code=200, reply_text='Normal shutdown')¶
Disconnect from RabbitMQ. If there are any open channels, it will
attempt to close them prior to fully disconnecting. Channels which
have active consumers will attempt to send a Basic.Cancel to RabbitMQ
to cleanly stop the delivery of messages prior to closing the channel.

Parameters: 
reply_code (int) – The code number for the close
reply_text (str) – The text reason for the close

connect()¶
Invoke if trying to reconnect to a RabbitMQ server. Constructing the
Connection object should connect on its own.

consumer_cancel_notify¶
Specifies if the server supports consumer cancel notification on the
active connection.

Return type: bool

exchange_exchange_bindings¶
Specifies if the active connection supports exchange to exchange
bindings.

Return type: bool

is_closed¶
Returns a boolean reporting the current connection state.

is_closing¶
Returns True if connection is in the process of closing due to
client-initiated close request, but closing is not yet complete.

is_open¶
Returns a boolean reporting the current connection state.

publisher_confirms¶
Specifies if the active connection can use publisher confirmations.

Return type: bool

remove_timeout(timeout_id)¶
Remove the timeout from the IOLoop by the ID returned from
add_timeout.

Return type: str

set_backpressure_multiplier(value=10)¶
Alter the backpressure multiplier value. We set this to 10 by default.
This value is used to raise warnings and trigger the backpressure
callback.

Parameters: value (int) – The multiplier value to set

class pika.adapters.twisted_connection.TwistedProtocolConnection(parameters=None, on_close_callback=None)[source]¶
A hybrid between a Pika Connection and a Twisted Protocol. Allows using
Twisted’s non-blocking connectTCP/connectSSL methods for connecting to the
server.
It has one caveat: TwistedProtocolConnection objects have a ready
instance variable that’s a Deferred which fires when the connection is
ready to be used (the initial AMQP handshaking has been done). You have
to wait for this Deferred to fire before requesting a channel.
Since it’s Twisted handling connection establishing it does not accept
connect callbacks, you have to implement that within Twisted. Also remember
that the host, port and ssl values of the connection parameters are ignored
because, yet again, it’s Twisted who manages the connection.

add_backpressure_callback(callback_method)¶
Call method “callback” when pika believes backpressure is being
applied.

Parameters: callback_method (method) – The method to call

add_callback_threadsafe(callback)¶
Requests a call to the given function as soon as possible in the
context of this connection’s IOLoop thread.

NOTE: This is the only thread-safe method offered by the connection. All
other manipulations of the connection must be performed from the
connection’s thread.

For example, a thread may request a call to the
channel.basic_ack method of a connection that is running in a
different thread via
```
connection.add_callback_threadsafe(

functools.partial(channel.basic_ack, delivery_tag=…))
```

Parameters: callback (method) – The callback method; must be callable.

add_on_close_callback(callback_method)¶
Add a callback notification when the connection has closed. The
callback will be passed the connection, the reply_code (int) and the
reply_text (str), if sent by the remote server.

Parameters: callback_method (method) – Callback to call on close

add_on_connection_blocked_callback(callback_method)¶
Add a callback to be notified when RabbitMQ has sent a
Connection.Blocked frame indicating that RabbitMQ is low on
resources. Publishers can use this to voluntarily suspend publishing,
instead of relying on back pressure throttling. The callback
will be passed the Connection.Blocked method frame.
See also ConnectionParameters.blocked_connection_timeout.

Parameters: callback_method (method) – Callback to call on Connection.Blocked,
having the signature callback_method(pika.frame.Method), where the
method frame’s method member is of type
pika.spec.Connection.Blocked

add_on_connection_unblocked_callback(callback_method)¶
Add a callback to be notified when RabbitMQ has sent a
Connection.Unblocked frame letting publishers know it’s ok
to start publishing again. The callback will be passed the
Connection.Unblocked method frame.

Parameters: callback_method (method) – Callback to call on
Connection.Unblocked, having the signature
callback_method(pika.frame.Method), where the method frame’s
method member is of type pika.spec.Connection.Unblocked

add_on_open_callback(callback_method)¶
Add a callback notification when the connection has opened.

Parameters: callback_method (method) – Callback to call when open

add_on_open_error_callback(callback_method, remove_default=True)¶
Add a callback notification when the connection can not be opened.
The callback method should accept the connection object that could not
connect, and an optional error message.

Parameters: 
callback_method (method) – Callback to call when can’t connect
remove_default (bool) – Remove default exception raising callback

add_timeout(deadline, callback_method)¶
Add the callback_method to the IOLoop timer to fire after deadline
seconds. Returns a handle to the timeout

Parameters: 
deadline (int) – The number of seconds to wait to call callback
callback_method (method) – The callback method

Return type: str

basic_nack¶
Specifies if the server supports basic.nack on the active connection.

Return type: bool

channel(channel_number=None)[source]¶
Create a new channel with the next available channel number or pass
in a channel number to use. Must be non-zero if you would like to
specify but it is recommended that you let Pika manage the channel
numbers.
Return a Deferred that fires with an instance of a wrapper around the
Pika Channel class.

Parameters: channel_number (int) – The channel number to use, defaults to the
next available.

close(reply_code=200, reply_text='Normal shutdown')¶
Disconnect from RabbitMQ. If there are any open channels, it will
attempt to close them prior to fully disconnecting. Channels which
have active consumers will attempt to send a Basic.Cancel to RabbitMQ
to cleanly stop the delivery of messages prior to closing the channel.

Parameters: 
reply_code (int) – The code number for the close
reply_text (str) – The text reason for the close

connect()[source]¶
Invoke if trying to reconnect to a RabbitMQ server. Constructing the
Connection object should connect on its own.

consumer_cancel_notify¶
Specifies if the server supports consumer cancel notification on the
active connection.

Return type: bool

exchange_exchange_bindings¶
Specifies if the active connection supports exchange to exchange
bindings.

Return type: bool

is_closed¶
Returns a boolean reporting the current connection state.

is_closing¶
Returns True if connection is in the process of closing due to
client-initiated close request, but closing is not yet complete.

is_open¶
Returns a boolean reporting the current connection state.

publisher_confirms¶
Specifies if the active connection can use publisher confirmations.

Return type: bool

remove_timeout(timeout_id)¶
Remove the timeout from the IOLoop by the ID returned from
add_timeout.

Return type: str

set_backpressure_multiplier(value=10)¶
Alter the backpressure multiplier value. We set this to 10 by default.
This value is used to raise warnings and trigger the backpressure
callback.

Parameters: value (int) – The multiplier value to set

class pika.adapters.twisted_connection.TwistedChannel(channel)[source]¶
A wrapper wround Pika’s Channel.
Channel methods that normally take a callback argument are wrapped to
return a Deferred that fires with whatever would be passed to the callback.
If the channel gets closed, all pending Deferreds are errbacked with a
ChannelClosed exception. The returned Deferreds fire with whatever
arguments the callback to the original method would receive.
The basic_consume method is wrapped in a special way, see its docstring for
details.

basic_consume(*args, **kwargs)[source]¶
Consume from a server queue. Returns a Deferred that fires with a
tuple: (queue_object, consumer_tag). The queue object is an instance of
ClosableDeferredQueue, where data received from the queue will be
stored. Clients should use its get() method to fetch individual
message.

basic_publish(*args, **kwargs)[source]¶
Make sure the channel is not closed and then publish. Return a
Deferred that fires with the result of the channel’s basic_publish.

queue_delete(*args, **kwargs)[source]¶
Wraps the method the same way all the others are wrapped, but removes
the reference to the queue object after it gets deleted on the server.

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)[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.

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 (callable) – The callback 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 (callable) – The callback to call on Basic.Cancel from
broker

add_on_close_callback(callback)[source]¶
Pass a callback function that will be called when the channel is
closed. The callback function will receive the channel, the
reply_code (int) and the reply_text (string) describing why the channel was
closed.
If the channel is closed by broker via Channel.Close, the callback will
receive the reply_code/reply_text provided by the broker.
If channel closing is initiated by user (either directly of indirectly
by closing a connection containing the channel) and closing
concludes gracefully without Channel.Close from the broker and without
loss of connection, the callback will receive 0 as reply_code and empty
string as reply_text.
If channel was closed due to loss of connection, the callback will
receive reply_code and reply_text representing the loss of connection.

Parameters: callback (callable) – The callback, having the signature:
callback(Channel, int reply_code, str reply_text)

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 (callable) – The callback function

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.

Parameters: callback (callable) – The function to call, having the signature
callback(channel, method, properties, body)
where
channel: pika.Channel
method: pika.spec.Basic.Return
properties: pika.spec.BasicProperties
body: str, unicode, or bytes (python 3.x)

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 (integer) – int/long 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 (callable) – Callback to call for a Basic.CancelOk
response; MUST be None when nowait=True. MUST be callable when
nowait=False.
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, arguments=None)[source]¶
Sends the AMQP 0-9-1 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:
Tutorial 2 at http://www.rabbitmq.com/getstarted.html
http://www.rabbitmq.com/confirms.html
http://www.rabbitmq.com/amqp-0-9-1-reference.html#basic.consume

Parameters: 
consumer_callback (callable) – The function to call when consuming
with the signature consumer_callback(channel, method, properties,

body), where
channel: pika.Channel
method: pika.spec.Basic.Deliver
properties: pika.spec.BasicProperties
body: str, unicode, or bytes (python 3.x)

queue (str or unicode) – The queue to consume from
no_ack (bool) – if set to True, automatic acknowledgement mode will be used
(see http://www.rabbitmq.com/confirms.html)
exclusive (bool) – Don’t allow other consumers on the queue
consumer_tag (str or unicode) – Specify your own consumer tag
arguments (dict) – Custom key/value pair arguments for the consumer

Return type: str

basic_get(callback=None, queue='', no_ack=False)[source]¶
Get a single message from the AMQP broker. 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. Due to implementation details, this cannot be called
a second time until the callback is executed.  For more information on
basic_get and its parameters, see:
http://www.rabbitmq.com/amqp-0-9-1-reference.html#basic.get

Parameters: 
callback (callable) – The callback to call with a message that has
the signature callback(channel, method, properties, body), where:
channel: pika.Channel
method: pika.spec.Basic.GetOk
properties: pika.spec.BasicProperties
body: str, unicode, or bytes (python 3.x)
queue (str or 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 (integer) – int/long 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 or unicode) – The exchange to publish to
routing_key (str or unicode) – The routing key to bind on
body (str or unicode) – The message body
properties (pika.spec.BasicProperties) – 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 (callable) – The callback to call 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, 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 (integer) – int/long 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.

Raises: TypeError

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 (callable) – Callback 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]¶
Invoke a graceful shutdown of the channel with the AMQP Broker.
If channel is OPENING, transition to CLOSING and suppress the incoming
Channel.OpenOk, if any.

Parameters: 
reply_code (int) – The reason code to send to broker
reply_text (str) – The reason text to send to broker

Raises: 
ChannelClosed – if channel is already closed
ChannelAlreadyClosing – if channel is already closing

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 (callable) – The callback for delivery confirmations that
has the following signature: callback(pika.frame.Method), where
method_frame contains either method spec.Basic.Ack or
spec.Basic.Nack.
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 (callable) – The callback to call on Exchange.BindOk; MUST
be None when nowait=True
destination (str or unicode) – The destination exchange to bind
source (str or unicode) – The source exchange to bind to
routing_key (str or 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 (callable) – Call this method on Exchange.DeclareOk; MUST
be None when nowait=True
exchange (str or unicode
sequence of these characters: letters,
digits, hyphen, underscore, period, or
colon.) – The exchange name consists of a non-empty
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 (callable) – The function to call on Exchange.DeleteOk;
MUST be None when nowait=True.
exchange (str or 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 (callable) – The callback to call on Exchange.UnbindOk;
MUST be None when nowait=True.
destination (str or unicode) – The destination exchange to unbind
source (str or unicode) – The source exchange to unbind from
routing_key (str or 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 (callable) – The callback to call upon completion
active (bool) – Turn flow on or off

is_closed¶
Returns True if the channel is closed.

Return type: bool

is_closing¶
Returns True if client-initiated closing of the channel is in
progress.

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=None, nowait=False, arguments=None)[source]¶
Bind the queue to the specified exchange

Parameters: 
callback (callable) – The callback to call on Queue.BindOk;
MUST be None when nowait=True.
queue (str or unicode) – The queue to bind to the exchange
exchange (str or unicode) – The source exchange to bind to
routing_key (str or 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.
Leave the queue name empty for a auto-named queue in RabbitMQ

Parameters: 
callback (callable) – callback(pika.frame.Method) for method
Queue.DeclareOk; MUST be None when nowait=True.
queue (str or 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 (callable) – The callback to call on Queue.DeleteOk;
MUST be None when nowait=True.
queue (str or 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 (callable) – The callback to call on Queue.PurgeOk;
MUST be None when nowait=True.
queue (str or unicode) – The queue to purge
nowait (bool) – Do not expect a Queue.PurgeOk response

queue_unbind(callback=None, queue='', exchange=None, routing_key=None, arguments=None)[source]¶
Unbind a queue from an exchange.

Parameters: 
callback (callable) – The callback to call on Queue.UnbindOk
queue (str or unicode) – The queue to unbind from the exchange
exchange (str or unicode) – The source exchange to bind from
routing_key (str or 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 (callable) – The callback for delivery confirmations

tx_rollback(callback=None)[source]¶
Rollback a transaction.

Parameters: callback (callable) – 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 (callable) – The callback for delivery confirmations

Connection¶
The Connection class implements the base behavior
that all connection adapters extend.

class pika.connection.Connection(parameters=None, on_open_callback=None, on_open_error_callback=None, on_close_callback=None)[source]¶
This is the core class that implements communication with RabbitMQ. This
class should not be invoked directly but rather through the use of an
adapter such as SelectConnection or BlockingConnection.

Parameters: 
parameters (pika.connection.Parameters) – Connection parameters
on_open_callback (method) – Called when the connection is opened
on_open_error_callback (method) – Called if the connection cant
be opened
on_close_callback (method) – Called when the connection is closed

add_backpressure_callback(callback_method)[source]¶
Call method “callback” when pika believes backpressure is being
applied.

Parameters: callback_method (method) – The method to call

add_on_close_callback(callback_method)[source]¶
Add a callback notification when the connection has closed. The
callback will be passed the connection, the reply_code (int) and the
reply_text (str), if sent by the remote server.

Parameters: callback_method (method) – Callback to call on close

add_on_connection_blocked_callback(callback_method)[source]¶
Add a callback to be notified when RabbitMQ has sent a
Connection.Blocked frame indicating that RabbitMQ is low on
resources. Publishers can use this to voluntarily suspend publishing,
instead of relying on back pressure throttling. The callback
will be passed the Connection.Blocked method frame.
See also ConnectionParameters.blocked_connection_timeout.

Parameters: callback_method (method) – Callback to call on Connection.Blocked,
having the signature callback_method(pika.frame.Method), where the
method frame’s method member is of type
pika.spec.Connection.Blocked

add_on_connection_unblocked_callback(callback_method)[source]¶
Add a callback to be notified when RabbitMQ has sent a
Connection.Unblocked frame letting publishers know it’s ok
to start publishing again. The callback will be passed the
Connection.Unblocked method frame.

Parameters: callback_method (method) – Callback to call on
Connection.Unblocked, having the signature
callback_method(pika.frame.Method), where the method frame’s
method member is of type pika.spec.Connection.Unblocked

add_on_open_callback(callback_method)[source]¶
Add a callback notification when the connection has opened.

Parameters: callback_method (method) – Callback to call when open

add_on_open_error_callback(callback_method, remove_default=True)[source]¶
Add a callback notification when the connection can not be opened.
The callback method should accept the connection object that could not
connect, and an optional error message.

Parameters: 
callback_method (method) – Callback to call when can’t connect
remove_default (bool) – Remove default exception raising callback

add_timeout(deadline, callback_method)[source]¶
Adapters should override to call the callback after the
specified number of seconds have elapsed, using a timer, or a
thread, or similar.

Parameters: 
deadline (int) – The number of seconds to wait to call callback
callback_method (method) – The callback method

basic_nack¶
Specifies if the server supports basic.nack on the active connection.

Return type: bool

channel(on_open_callback, channel_number=None)[source]¶
Create a new channel with the next available channel number or pass
in a channel number to use. Must be non-zero if you would like to
specify but it is recommended that you let Pika manage the channel
numbers.

Parameters: 
on_open_callback (method) – The callback when the channel is opened
channel_number (int) – The channel number to use, defaults to the
next available.

Return type: pika.channel.Channel

close(reply_code=200, reply_text='Normal shutdown')[source]¶
Disconnect from RabbitMQ. If there are any open channels, it will
attempt to close them prior to fully disconnecting. Channels which
have active consumers will attempt to send a Basic.Cancel to RabbitMQ
to cleanly stop the delivery of messages prior to closing the channel.

Parameters: 
reply_code (int) – The code number for the close
reply_text (str) – The text reason for the close

connect()[source]¶
Invoke if trying to reconnect to a RabbitMQ server. Constructing the
Connection object should connect on its own.

consumer_cancel_notify¶
Specifies if the server supports consumer cancel notification on the
active connection.

Return type: bool

exchange_exchange_bindings¶
Specifies if the active connection supports exchange to exchange
bindings.

Return type: bool

is_closed¶
Returns a boolean reporting the current connection state.

is_closing¶
Returns True if connection is in the process of closing due to
client-initiated close request, but closing is not yet complete.

is_open¶
Returns a boolean reporting the current connection state.

publisher_confirms¶
Specifies if the active connection can use publisher confirmations.

Return type: bool

remove_timeout(timeout_id)[source]¶
Adapters should override: Remove a timeout

Parameters: timeout_id (str) – The timeout id to remove

set_backpressure_multiplier(value=10)[source]¶
Alter the backpressure multiplier value. We set this to 10 by default.
This value is used to raise warnings and trigger the backpressure
callback.

Parameters: value (int) – The multiplier value to set

Authentication Credentials¶
The credentials classes are used to encapsulate all authentication
information for the ConnectionParameters class.
The PlainCredentials class returns the properly
formatted username and password to the Connection.
To authenticate with Pika, create a PlainCredentials
object passing in the username and password and pass it as the credentials
argument value to the ConnectionParameters object.
If you are using URLParameters you do not need a
credentials object, one will automatically be created for you.
If you are looking to implement SSL certificate style authentication, you would
extend the ExternalCredentials class implementing
the required behavior.

PlainCredentials¶

class pika.credentials.PlainCredentials(username, password, erase_on_connect=False)[source]
A credentials object for the default authentication methodology with
RabbitMQ.
If you do not pass in credentials to the ConnectionParameters object, it
will create credentials for ‘guest’ with the password of ‘guest’.
If you pass True to erase_on_connect the credentials will not be stored
in memory after the Connection attempt has been made.

Parameters: 
username (str) – The username to authenticate with
password (str) – The password to authenticate with
erase_on_connect (bool) – erase credentials on connect.

erase_credentials()[source]
Called by Connection when it no longer needs the credentials

response_for(start)[source]
Validate that this type of authentication is supported

Parameters: start (spec.Connection.Start) – Connection.Start method

Return type: tuple(str|None, str|None)

ExternalCredentials¶

class pika.credentials.ExternalCredentials[source]
The ExternalCredentials class allows the connection to use EXTERNAL
authentication, generally with a client SSL certificate.

erase_credentials()[source]
Called by Connection when it no longer needs the credentials

response_for(start)[source]
Validate that this type of authentication is supported

Parameters: start (spec.Connection.Start) – Connection.Start method

Return type: tuple(str or None, str or None)

Exceptions¶
Pika specific exceptions

exception pika.exceptions.AMQPChannelError[source]¶

exception pika.exceptions.AMQPConnectionError[source]¶

exception pika.exceptions.AMQPError[source]¶

exception pika.exceptions.AuthenticationError[source]¶

exception pika.exceptions.BodyTooLongError[source]¶

exception pika.exceptions.ChannelAlreadyClosing[source]¶
Raised when Channel.close is called while channel is already closing

exception pika.exceptions.ChannelClosed[source]¶

exception pika.exceptions.ChannelError[source]¶

exception pika.exceptions.ConnectionClosed[source]¶

exception pika.exceptions.ConsumerCancelled[source]¶

exception pika.exceptions.DuplicateConsumerTag[source]¶

exception pika.exceptions.DuplicateGetOkCallback[source]¶

exception pika.exceptions.IncompatibleProtocolError[source]¶

exception pika.exceptions.InvalidChannelNumber[source]¶

exception pika.exceptions.InvalidFieldTypeException[source]¶

exception pika.exceptions.InvalidFrameError[source]¶

exception pika.exceptions.InvalidMaximumFrameSize[source]¶
DEPRECATED; pika.connection.Parameters.frame_max property setter now
raises the standard ValueError exception when the value is out of bounds.

exception pika.exceptions.InvalidMinimumFrameSize[source]¶
DEPRECATED; pika.connection.Parameters.frame_max property setter now
raises the standard ValueError exception when the value is out of bounds.

exception pika.exceptions.MethodNotImplemented[source]¶

exception pika.exceptions.NackError(messages)[source]¶
This exception is raised when a message published in
publisher-acknowledgements mode is Nack’ed by the broker.
Used by BlockingChannel.

exception pika.exceptions.NoFreeChannels[source]¶

exception pika.exceptions.ProbableAccessDeniedError[source]¶

exception pika.exceptions.ProbableAuthenticationError[source]¶

exception pika.exceptions.ProtocolSyntaxError[source]¶

exception pika.exceptions.ProtocolVersionMismatch[source]¶

exception pika.exceptions.RecursionError[source]¶
The requested operation would result in unsupported recursion or
reentrancy.
Used by BlockingConnection/BlockingChannel

exception pika.exceptions.ShortStringTooLong[source]¶

exception pika.exceptions.UnexpectedFrameError[source]¶

exception pika.exceptions.UnroutableError(messages)[source]¶
Exception containing one or more unroutable messages returned by broker
via Basic.Return.
Used by BlockingChannel.
In publisher-acknowledgements mode, this is raised upon receipt of Basic.Ack
from broker; in the event of Basic.Nack from broker, NackError is raised
instead

exception pika.exceptions.UnspportedAMQPFieldException[source]¶
Deprecated version of UnsupportedAMQPFieldException

exception pika.exceptions.UnsupportedAMQPFieldException[source]¶

Connection Parameters¶
To maintain flexibility in how you specify the connection information required for your applications to properly connect to RabbitMQ, pika implements two classes for encapsulating the information, ConnectionParameters and URLParameters.

ConnectionParameters¶
The classic object for specifying all of the connection parameters required to connect to RabbitMQ, ConnectionParameters provides attributes for tweaking every possible connection option.
Example:
import pika

# Set the connection parameters to connect to rabbit-server1 on port 5672
# on the / virtual host using the username "guest" and password "guest"
credentials = pika.PlainCredentials('guest', 'guest')
parameters = pika.ConnectionParameters('rabbit-server1',
                                       5672,
                                       '/',
                                       credentials)

class pika.connection.ConnectionParameters(host=<class 'pika.connection._DEFAULT'>, port=<class 'pika.connection._DEFAULT'>, virtual_host=<class 'pika.connection._DEFAULT'>, credentials=<class 'pika.connection._DEFAULT'>, channel_max=<class 'pika.connection._DEFAULT'>, frame_max=<class 'pika.connection._DEFAULT'>, heartbeat=<class 'pika.connection._DEFAULT'>, ssl=<class 'pika.connection._DEFAULT'>, ssl_options=<class 'pika.connection._DEFAULT'>, connection_attempts=<class 'pika.connection._DEFAULT'>, retry_delay=<class 'pika.connection._DEFAULT'>, socket_timeout=<class 'pika.connection._DEFAULT'>, locale=<class 'pika.connection._DEFAULT'>, backpressure_detection=<class 'pika.connection._DEFAULT'>, blocked_connection_timeout=<class 'pika.connection._DEFAULT'>, client_properties=<class 'pika.connection._DEFAULT'>, tcp_options=<class 'pika.connection._DEFAULT'>, **kwargs)[source]¶
Connection parameters object that is passed into the connection adapter
upon construction.

backpressure_detection¶

Returns: boolean indicating whether backpressure detection is
enabled. Defaults to DEFAULT_BACKPRESSURE_DETECTION.

blocked_connection_timeout¶

Returns: None or float blocked connection timeout. Defaults to
DEFAULT_BLOCKED_CONNECTION_TIMEOUT.

channel_max¶

Returns: max preferred number of channels. Defaults to
DEFAULT_CHANNEL_MAX.

Return type: int

client_properties¶

Returns: None or dict of client properties used to override the fields
in the default client poperties reported  to RabbitMQ via
Connection.StartOk method. Defaults to
DEFAULT_CLIENT_PROPERTIES.

connection_attempts¶

Returns: number of socket connection attempts. Defaults to
DEFAULT_CONNECTION_ATTEMPTS.

credentials¶

Return type: one of the classes from pika.credentials.VALID_TYPES. Defaults
to DEFAULT_CREDENTIALS.

frame_max¶

Returns: desired maximum AMQP frame size to use. Defaults to
DEFAULT_FRAME_MAX.

heartbeat¶

Returns: AMQP connection heartbeat timeout value for negotiation during
connection tuning or callable which is invoked during connection tuning.
None to accept broker’s value. 0 turns heartbeat off. Defaults to
DEFAULT_HEARTBEAT_TIMEOUT.

Return type: integer, None or callable

host¶

Returns: hostname or ip address of broker. Defaults to DEFAULT_HOST.

Return type: str

locale¶

Returns: locale value to pass to broker; e.g., ‘en_US’. Defaults to
DEFAULT_LOCALE.

Return type: str

retry_delay¶

Returns: interval between socket connection attempts; see also
connection_attempts. Defaults to DEFAULT_RETRY_DELAY.

Return type: float

socket_timeout¶

Returns: socket timeout value. Defaults to DEFAULT_SOCKET_TIMEOUT.

Return type: float

ssl¶

Returns: boolean indicating whether to connect via SSL. Defaults to
DEFAULT_SSL.

ssl_options¶

Returns: None or a dict of options to pass to ssl.wrap_socket.
Defaults to DEFAULT_SSL_OPTIONS.

port¶

Returns: port number of broker’s listening socket. Defaults to
DEFAULT_PORT.

Return type: int

virtual_host¶

Returns: rabbitmq virtual host name. Defaults to
DEFAULT_VIRTUAL_HOST.

tcp_options¶

Returns: None or a dict of options to pass to the underlying socket

URLParameters¶
The URLParameters class allows you to pass in an AMQP URL when creating the object and supports the host, port, virtual host, ssl, username and password in the base URL and other options are passed in via query parameters.
Example:
import pika

# Set the connection parameters to connect to rabbit-server1 on port 5672
# on the / virtual host using the username "guest" and password "guest"
parameters = pika.URLParameters('amqp://guest:guest@rabbit-server1:5672/%2F')

class pika.connection.URLParameters(url)[source]¶
Connect to RabbitMQ via an AMQP URL in the format:
amqp://username:password@host:port/<virtual_host>[?query-string]

Ensure that the virtual host is URI encoded when specified. For example if
you are using the default “/” virtual host, the value should be %2f.
See Parameters for default values.
Valid query string values are:

backpressure_detection:
DEPRECATED in favor of
Connection.Blocked and Connection.Unblocked. See
Connection.add_on_connection_blocked_callback.

channel_max:
Override the default maximum channel count value

client_properties:
dict of client properties used to override the fields in the default
client properties reported to RabbitMQ via Connection.StartOk
method

connection_attempts:
Specify how many times pika should try and reconnect before it gives up

frame_max:
Override the default maximum frame size for communication

heartbeat:
Desired connection heartbeat timeout for negotiation. If not present
the broker’s value is accepted. 0 turns heartbeat off.

locale:
Override the default en_US locale value

ssl:
Toggle SSL, possible values are t, f

ssl_options:
Arguments passed to ssl.wrap_socket()

retry_delay:
The number of seconds to sleep before attempting to connect on
connection failure.

socket_timeout:
Override low level socket timeout value

blocked_connection_timeout:
Set the timeout, in seconds, that the connection may remain blocked
(triggered by Connection.Blocked from broker); if the timeout
expires before connection becomes unblocked, the connection will be
torn down, triggering the connection’s on_close_callback

tcp_options:
Set the tcp options for the underlying socket.

Parameters: url (str) – The AMQP URL to connect to

ssl¶

Returns: boolean indicating whether to connect via SSL. Defaults to
DEFAULT_SSL.

host¶

Returns: hostname or ip address of broker. Defaults to DEFAULT_HOST.

Return type: str

port¶

Returns: port number of broker’s listening socket. Defaults to
DEFAULT_PORT.

Return type: int

credentials¶

Return type: one of the classes from pika.credentials.VALID_TYPES. Defaults
to DEFAULT_CREDENTIALS.

virtual_host¶

Returns: rabbitmq virtual host name. Defaults to
DEFAULT_VIRTUAL_HOST.

backpressure_detection¶

Returns: boolean indicating whether backpressure detection is
enabled. Defaults to DEFAULT_BACKPRESSURE_DETECTION.

blocked_connection_timeout¶

Returns: None or float blocked connection timeout. Defaults to
DEFAULT_BLOCKED_CONNECTION_TIMEOUT.

channel_max¶

Returns: max preferred number of channels. Defaults to
DEFAULT_CHANNEL_MAX.

Return type: int

client_properties¶

Returns: None or dict of client properties used to override the fields
in the default client poperties reported  to RabbitMQ via
Connection.StartOk method. Defaults to
DEFAULT_CLIENT_PROPERTIES.

connection_attempts¶

Returns: number of socket connection attempts. Defaults to
DEFAULT_CONNECTION_ATTEMPTS.

frame_max¶

Returns: desired maximum AMQP frame size to use. Defaults to
DEFAULT_FRAME_MAX.

heartbeat¶

Returns: AMQP connection heartbeat timeout value for negotiation during
connection tuning or callable which is invoked during connection tuning.
None to accept broker’s value. 0 turns heartbeat off. Defaults to
DEFAULT_HEARTBEAT_TIMEOUT.

Return type: integer, None or callable

locale¶

Returns: locale value to pass to broker; e.g., ‘en_US’. Defaults to
DEFAULT_LOCALE.

Return type: str

retry_delay¶

Returns: interval between socket connection attempts; see also
connection_attempts. Defaults to DEFAULT_RETRY_DELAY.

Return type: float

socket_timeout¶

Returns: socket timeout value. Defaults to DEFAULT_SOCKET_TIMEOUT.

Return type: float

ssl_options¶

Returns: None or a dict of options to pass to ssl.wrap_socket.
Defaults to DEFAULT_SSL_OPTIONS.

tcp_options¶

Returns: None or a dict of options to pass to the underlying socket

pika.spec¶

AMQP Specification¶
This module implements the constants and classes that comprise AMQP protocol
level constructs. It should rarely be directly referenced outside of Pika’s
own internal use.

Note
Auto-generated code by codegen.py, do not edit directly. Pull

requests to this file without accompanying utils/codegen.py changes will be
rejected.

class pika.spec.Connection[source]¶

INDEX = 10¶

NAME = 'Connection'¶

class Start(version_major=0, version_minor=9, server_properties=None, mechanisms='PLAIN', locales='en_US')[source]¶

INDEX = 655370¶

NAME = 'Connection.Start'¶

synchronous¶

decode(encoded, offset=0)[source]¶

encode()[source]¶