Package: pika
Pika is a RabbitMQ (AMQP 0-9-1) client library for Python.IntroductionPika is a pure-Python implementation of the AMQP 0-9-1 protocol including
RabbitMQ’s extensions.Supports Python 3.7+ (1.1.0was the last version to support 2.7)Since threads aren’t appropriate to every situation, it doesn’t require
threads. Pika core takes care not to forbid them, either. The same goes for
greenlets, callbacks, continuations, and generators. An instance of Pika’s
built-in connection adapters isn’t thread-safe, however.People may be using direct sockets, plain oldselect(), or any of the
wide variety of ways of getting network events to and from a Python
application. Pika tries to stay compatible with all of these, and to make
adapting it to a new environment as simple as possible.DocumentationPika’s documentation can be found athttps://pika.readthedocs.io.ExampleHere is the most simple example of use, sending a message with thepika.BlockingConnectionadapter:importpikaconnection=pika.BlockingConnection()channel=connection.channel()channel.basic_publish(exchange='test',routing_key='test',body=b'Test message.')connection.close()And an example of writing a blocking consumer:importpikaconnection=pika.BlockingConnection()channel=connection.channel()formethod_frame,properties,bodyinchannel.consume('test'):# Display the message parts and acknowledge the messageprint(method_frame,properties,body)channel.basic_ack(method_frame.delivery_tag)# Escape out of the loop after 10 messagesifmethod_frame.delivery_tag==10:break# Cancel the consumer and return any pending messagesrequeued_messages=channel.cancel()print('Requeued%imessages'%requeued_messages)connection.close()Pika provides the following adapterspika.adapters.asyncio_connection.AsyncioConnection- asynchronous adapter
for Python 3AsyncIO’s
I/O loop.pika.BlockingConnection- synchronous adapter on top of library for
simple usage.pika.SelectConnection- asynchronous adapter without third-party
dependencies.pika.adapters.gevent_connection.GeventConnection- asynchronous adapter
for use withGevent’s I/O loop.pika.adapters.tornado_connection.TornadoConnection- asynchronous adapter
for use withTornado’s I/O loop.pika.adapters.twisted_connection.TwistedProtocolConnection- asynchronous
adapter for use withTwisted’s I/O loop.Multiple connection parametersYou can also pass multiplepika.ConnectionParametersinstances for
fault-tolerance as in the code snippet below (host names are just examples, of
course). To enable retries, setconnection_attemptsandretry_delayas
needed in the lastpika.ConnectionParameterselement of the sequence.
Retries occur after connection attempts using all of the given connection
parameters fail.importpikaparameters=(pika.ConnectionParameters(host='rabbitmq.zone1.yourdomain.com'),pika.ConnectionParameters(host='rabbitmq.zone2.yourdomain.com',connection_attempts=5,retry_delay=1))connection=pika.BlockingConnection(parameters)With non-blocking adapters, such aspika.SelectConnectionandpika.adapters.asyncio_connection.AsyncioConnection, you can request a
connection using multiple connection parameter instances via the connection
adapter’screate_connection()class method.Requesting message acknowledgements from another threadThe single-threaded usage constraint of an individual Pika connection adapter
instance may result in a dropped AMQP/stream connection due to AMQP heartbeat
timeout in consumers that take a long time to process an incoming message. A
common solution is to delegate processing of the incoming messages to another
thread, while the connection adapter’s thread continues to service its I/O
loop’s message pump, permitting AMQP heartbeats and other I/O to be serviced in
a timely fashion.Messages processed in another thread may not be acknowledged directly from that
thread, since all accesses to the connection adapter instance must be from a
single thread, which is the thread running the adapter’s I/O loop. This is
accomplished by requesting a callback to be executed in the adapter’s
I/O loop thread. For example, the callback function’s implementation might look
like this:defack_message(channel,delivery_tag):"""Note that `channel` must be the same Pika channel instance via which
    the message being acknowledged was retrieved (AMQP protocol constraint).
    """ifchannel.is_open:channel.basic_ack(delivery_tag)else:# Channel is already closed, so we can't acknowledge this message;# log and/or do something that makes sense for your app in this case.passThe code running in the other thread may request theack_message()function
to be executed in the connection adapter’s I/O loop thread using an
adapter-specific mechanism:pika.BlockingConnectionabstracts its I/O loop from the application and
thus exposespika.BlockingConnection.add_callback_threadsafe(). Refer to
this method’s docstring for additional information. For example:connection.add_callback_threadsafe(functools.partial(ack_message,channel,delivery_tag))When using a non-blocking connection adapter, such aspika.adapters.asyncio_connection.AsyncioConnectionorpika.SelectConnection, you use the underlying asynchronous framework’s
native API for requesting an I/O loop-bound callback from another thread. For
example,pika.SelectConnection’s I/O loop providesadd_callback_threadsafe(),pika.adapters.tornado_connection.TornadoConnection’s I/O loop hasadd_callback(), whilepika.adapters.asyncio_connection.AsyncioConnection’s I/O loop exposescall_soon_threadsafe().This threadsafe callback request mechanism may also be used to delegate
publishing of messages, etc., from a background thread to the connection
adapter’s thread.Connection recoverySome RabbitMQ clients (Bunny, Java, .NET, Objective-C, Swift) provide a way to
automatically recover a connection, its channels and topology (e.g. queues,
bindings and consumers) after a network failure. Others require connection
recovery to be performed by the application code and strive to make it a
straightforward process. Pika falls into the second category.Pika supports multiple connection adapters. They take different approaches to
connection recovery.Forpika.BlockingConnectionadapter exception handling can be used to check
for connection errors. Here is a very basic example:importpikawhileTrue:try:connection=pika.BlockingConnection()channel=connection.channel()channel.basic_consume('test',on_message_callback)channel.start_consuming()# Don't recover if connection was closed by brokerexceptpika.exceptions.ConnectionClosedByBroker:break# Don't recover on channel errorsexceptpika.exceptions.AMQPChannelError:break# Recover on all other connection errorsexceptpika.exceptions.AMQPConnectionError:continueThis example can be found inexamples/consume_recover.py.Generic operation retry libraries such asretrycan be used. Decorators make it
possible to configure some additional recovery behaviours, like delays between
retries and limiting the number of retries:fromretryimportretry@retry(pika.exceptions.AMQPConnectionError,delay=5,jitter=(1,3))defconsume():connection=pika.BlockingConnection()channel=connection.channel()channel.basic_consume('test',on_message_callback)try:channel.start_consuming()# Don't recover connections closed by serverexceptpika.exceptions.ConnectionClosedByBroker:passconsume()This example can be found inexamples/consume_recover_retry.py.For asynchronous adapters, useon_close_callbackto react to connection
failure events. This callback can be used to clean up and recover the
connection.An example of recovery usingon_close_callbackcan be found inexamples/asynchronous_consumer_example.py.ContributingTo contribute to Pika, please make sure that any new features or changes to
existing functionalityinclude test coverage.Pull requests that add or change code without adequate test coverage will be
rejected.Additionally, please format your code usingYapfwithgooglestyle prior to
issuing your pull request.Note: only format those lines that you have changed
in your pull request. If you format an entire file and change code outside of
the scope of your PR, it will likely be rejected.Extending to support additional I/O frameworksNew non-blocking adapters may be implemented in either of the following ways:By subclassingpika.BaseConnection, implementing its abstract method and
passing its constructor an implementation ofpika.adapters.utils.nbio_interface.AbstractIOServices.pika.BaseConnectionimplementspika.connection.Connection’s abstract
methods, including internally-initiated connection logic. For examples, refer
to the implementations ofpika.adapters.asyncio_connection.AsyncioConnection,pika.adapters.gevent_connection.GeventConnectionandpika.adapters.tornado_connection.TornadoConnection.By subclassingpika.connection.Connectionand implementing its abstract
methods. This approach facilitates implementation of custom
connection-establishment and transport mechanisms. For an example, refer to
the implementation ofpika.adapters.twisted_connection.TwistedProtocolConnection.