tmc / carrot

Simple RabbitMQ/ZeroMQ (AMQP) messaging queue support for Django.

carrot

Authors:	Ask Solem ([e-mail])
Version:	0.1.0

Simple amqplib wrapper to provide a nicer AMQP interface.

Note This software is not finished. And is likely to change drastically in the near future.

Introduction

carrot is a messaging queue framework built on top of py-amqplib. It encapsulates a simple workflow and attempts to fall back to sane defaults. carrot supports loading settings from the local environment or `Django`_ configuration (there is no hard dependancy on `Django`_). carrot was created through inspiration obtained through the Rabbits and warrens article below.

Installation

You can install carrot either via the Python Package Index (PyPI) or from source.

To install using pip:

    $ pip install carrot

To install using ``easy_install``

    $ easy_install carrot

If you have downloaded a source tarball you can install it
in the following way:

$ python setup.py build
# python setup.py install # as root

Example

This is a carrot implementation of the example publisher and consumer described in the article Rabbits and warrens

>>> from carrot.messaging import Publisher, Consumer

>>> class PostOfficePublisher(Publisher):
...     exchange = "sorting_room"
...     routing_key = "jason"

>>> class PostOfficeConsumer(Consumer):
...     queue = "po_box"
...     exchange = "sorting_room"
...     routing_key = "json"
...
...     def receieve(self, message_data, message):
...         """This is the method that is called whenever we
...         receieve a message in this queue."""
...         print("Received: %s" % message_data)

By default every message is encoded using JSON, if you don't want this you have to set the encoding attribute in the producer and the decoding attribute in the consumer to lambda x: x.

There are lots of other options for producers and consumers for which the only documentation right now is the source code (sorry!)

To start sending and receveing messages with these classes, you first have to configure the AMQP server for your django app. If you have a `RabbitMQ`_ server running on localhost you can add these settings to your settings.py:

    AMQP_SERVER = "localhost"
    AMQP_PORT = 5672
    AMQP_USER = "guest"
    AMQP_PASSWORD = "guest"
    AMQP_VHOST = "/"

First we have to set up the connection instance, and map it to the
publishers and consumers:

    >>> from carrot.connection import AMQPConnection
    >>> po_publisher = PostOfficePublisher(connection=AMQPConnection)
    >>> po_consumer = PostOfficeConsumer(connection=AMQPConnection)


Then, finally, we can send and receive some messages:

    >>> po_publisher.send({"My message": ["foo", "bar", "baz"]})
    >>> po_publisher.close()
    >>> po_consumer.next()
    Received: {"My message": ["foo", "bar", "baz"]} from channel #1