README.rst

carrot - AMQP Messaging Framework for Python

NOTE This release contains backward-incompatible changes.
Please read the Changelog for more information.

Introduction

carrot is an AMQP messaging queue framework. AMQP is the Advanced Message
Queuing Protocol, an open standard protocol for message orientation, queuing,
routing, reliability and security.

The aim of carrot is to make messaging in Python as easy as possible by
providing a high-level interface for producing and consuming messages. At the
same time it is a goal to re-use what is already available as much as possible.

Before you start playing with carrot, you should probably read up on
AMQP, and you could start with the excellent article about using RabbitMQ
under Python, Rabbits and warrens. For more detailed information, you can
refer to the Wikipedia article about AMQP.

Documentation

Carrot is using Sphinx, and the latest documentation is available at GitHub:

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
by doing the following,:

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

Terminology

There are some concepts you should be familiar with before starting:

Publishers

Publishers sends messages to an exchange.

Exchanges

Messages are sent to exchanges. Exchanges are named and can be
configured to use one of several routing algorithms. The exchange
routes the messages to consumers by matching the routing key in the
message with the routing key the consumer provides when binding to
the exchange.

Consumers

Consumers declares a queue, binds it to a exchange and receives
messages from it.

Queues

Queues receive messages sent to exchanges. The queues are declared
by consumers.

Routing keys

Every message has a routing key. The interpretation of the routing
key depends on the exchange type. There are four default exchange
types defined by the AMQP standard, and vendors can define custom
types (so see your vendors manual for details).

These are the default exchange types defined by AMQP/0.8:

Direct exchange

Matches if the routing key property of the message and
the routing_key attribute of the consumer are identical.

Fan-out exchange

Always matches, even if the binding does not have a routing
key.

Topic exchange

Matches the routing key property of the message by a primitive
pattern matching scheme. The message routing key then consists
of words separated by dots (".", like domain names), and
two special characters are available; star ("*") and hash
("#"). The star matches any word, and the hash matches
zero or more words. For example "*.stock.#" matches the
routing keys "usd.stock" and "eur.stock.db" but not
"stock.nasdaq".

Examples

Creating a connection

You can set up a connection by creating an instance of
carrot.messaging.BrokerConnection, with the appropriate options for
your broker:

Receiving messages using a Consumer

First we open up a Python shell and start a message consumer.

This consumer declares a queue named "feed", receiving messages with
the routing key "importer" from the "feed" exchange.

The example then uses the consumers wait() method to go into consume
mode, where it continuously polls the queue for new messages, and when a
message is received it passes the message to all registered callbacks.

Look in the first Python shell again (where consumer.wait() is running),
where the following text has been printed to the screen:

Got feed import message for: http://cnn.com/rss/edition.rss

Serialization of Data

By default every message is encoded using JSON, so sending
Python data structures like dictionaries and lists works.
YAML, msgpack and Python's built-in pickle module is also supported,
and if needed you can register any custom serialization scheme you
want to use.

Each option has its advantages and disadvantages.

json -- JSON is supported in many programming languages, is now

a standard part of Python (since 2.6), and is fairly fast to
decode using the modern Python libraries such as cjson or
``simplejson.

The primary disadvantage to JSON is that it limits you to
the following data types: strings, unicode, floats, boolean,
dictionaries, and lists. Decimals and dates are notably missing.

Also, binary data will be transferred using base64 encoding, which
will cause the transferred data to be around 34% larger than an
encoding which supports native binary types.

However, if your data fits inside the above constraints and
you need cross-language support, the default setting of JSON
is probably your best choice.

pickle -- If you have no desire to support any language other than

Python, then using the pickle encoding will gain you
the support of all built-in Python data types (except class instances),
smaller messages when sending binary files, and a slight speedup
over JSON processing.

The message object returned by the Consumer class will have a
content_type and content_encoding attribute.

Receiving messages without a callback

You can also poll the queue manually, by using the fetch method.
This method returns a Message object, from where you can get the
message body, de-serialize the body to get the data, acknowledge, reject or
re-queue the message.