Package: rabbitmq-client
RabbitMQ client helpers based on pikaThis project provides helper classes for using RabbitMQ in Python. It is
based onpika, which is an awesome no-dependency client library for
RabbitMQ. Similarly, this project strives for zero dependencies (except for
dev dependencies).By using this project, users should be able to get started with RabbitMQ in
Python instantly, by simply instantiating and starting aRMQConsumerorRMQProducerclass.ConsumerRMQConsumerextends theRMQConnectionbase class with only one extra
method:consume. Consume can be passed parameters for declaring queues and
exchanges, as well as binding them together, and consume parameters, all of
which have corresponding kwargs in the pika library. The idea is not to
re-invent the wheel, but simply the process of declaring a queue -> declaring an
exchange -> binding the exchange and queue together -> consuming from the queue.Here is an example:fromrabbitmq_clientimportRMQConsumer,ConsumeParams,QueueParamsdefon_message(msg,ack=None):...consumer=RMQConsumer()consumer.start()consumer.consume(ConsumeParams(on_message),queue_params=QueueParams("queue_name"))The flow of declaring, binding, and consuming is quite
straightforward. The above example will declare a queue with the name
"queue_name" and consume from it.NOTE!Although the above may look synchronous, it is not. Start is
asynchronous
and any consume started while the consumer is not fully started will simply be
delayed until it is. When a consume has been successfully started, the bound
callback will receive aConsumeOKobject containing the resulting
consumer tag.Acknowledging received messagesBy default, received messages need to be acknowledged when received. By calling
theackkwarg function a message is acknowledged and won't be sent again.
If a message isn't acknowledged using this function, it will be re-sent by
RabbitMQ on consuming from a queue again.fromrabbitmq_clientimportRMQConsumer,ConsumeParams,QueueParamsfromsome_other_moduleimporthandle_msgdefon_message(msg,ack=None):error=handle_msg(msg)ifnoterror:ack()consumer=RMQConsumer()consumer.start()consumer.consume(ConsumeParams(on_message),queue_params=QueueParams("queue_name"))To enable automatic acknowledgement of messages, pass theauto_ackparameter
to theConsumeParams, set toTrue. Ifauto_ackisTrue, theackkwarg is unset.ProducerRMQProducerextends theRMQConnectionbase class with two additional
methods:publishandactivate_confirm_mode. Publish is used, as it
sounds, to publish messages towards queues and/or exchanges. The confirm
mode activation method enabled confirm mode so that users can verify that
messages have been delivered successfully.fromrabbitmq_clientimportRMQProducer,ExchangeParamsdefon_confirm(confirmation):...producer=RMQProducer()producer.start()producer.activate_confirm_mode(on_confirm)# Or don't, depends on your needsproducer.publish(b"body",exchange_params=ExchangeParams("exchange_name"),routing_key="some.routing.key")activate_confirm_modeisn't synchronous either, but you don't have to
worry about that. Callingpublishafteractivate_confirm_modewill lead
to the publish not happening until confirm mode has been activated
successfully. The callback passed toactivate_confirm_modewill also
receive aConfirmModeOKonce confirm mode is on. Any publish between
callingactivate_confirm_modeand the producer receiving a
confirm_select_ok from RabbitMQ will be buffered and not issues until
confirm mode is on. When confirm mode is on,publishalso returns a key that
clients can use to correlate successful delivered with calls to publish.
Once apublishcall with key X is confirmed, the callback passed toactivate_confirm_modewill be called with X.Abstract connection helperThe abstractRMQConnectionclass can be subclassed to get a head start in
using thepikaSelectConnectionandChannelobjects as it wraps them
and provides an easy-to-use interface as well as event hooks on important
happenings.RMQConnection lifecycle hooksSubclassingRMQConnectionrequires the implementer to override three methods:on_ready,on_close, andon_error.on_readyis called whenRMQConnectionhas established a connection and
opened a channel.on_closeis called when either the connection, or the channel closes for
any reason. This means the implementer may receive two calls for one failed
connection, one for the channel and one for the connection itself. This
makes it important thaton_closeis made idempotent.on_erroris called when a recent action failed, such as an exchange
declaration failure. These hooks are meant to enable the implementer to react
to the connection state and restore an operating state. TheRMQConnectionabstract base class is used by therabbitmq_clientproject to implement itsRMQConsumerandRMQProducerclasses.RMQConnection interface methodsIn addition to the hooks that need to be implemented by implementing classes,RMQConnectionprovides three public methods that can be used to interact
with the connection object:start,restart, andstop.startinitiates the connection, establishing apika.SelectConnectionand
if that's successful, opening apika.Channelfor the opened connection. Once
a channel has been opened,RMQConnectionwill issue a call toon_ready.
Subsequent calls tostarthave no effect if the connection has already been
started.restartcloses the open connection and ensures that it is started again once
is has been fully closed.restartis only meant to be used on successfully
established connections, it will have no effect on closed connections.restartis meant to be used as a means to changepika.ConnectionParameterson the fly.stoppermanently closes an open connection and will have no effect on a
closed connection. A connection for whichstophas been called cannot be
re-used.on_closeis called once the connection is completely stopped.Aside from the connection-related methods, theRMQConnectionalso exposes
interations with thepika.Channel, named similarily. See here for what is
exposed:Pika docs.Automatic reconnectionRMQConnectionwill re-establish lost connections, but not lost channels.
Reconnections will not be done for any reason though, among the reasons for
reconnecting are:pika.exceptions.ConnectionClosedByBrokerpika.exceptions.StreamLostErrorThese two exceptions cover the cases where the broker has been shut down, either
expectedly or unexpectedly, or when the connection is lost for some other
reason.Again, if the channel is lost, but the connection remains intact,RMQConnectionwill not recover the channel.Reconnection attempts will be made with an increasing delay between attempts.
The first attempt is instantaneous, the second is delayed by 1 second, the
third by 2 seconds, etc. After the 9th attempt, the following reconnects
will be made at 30 second intervals.Loggingrabbitmq_clientfollows Python logging standards and is by default disabled.
To enable logging, attach a handler torabbitmq_client:importlogginglogging.getLogger("rabbitmq_client").addHandler(logging.StreamHandler())By default, alogging.NullHandler()is attached to this logger.