carrot.messaging

The introduction to carrot that was here previously has been moved to the introduction page.

Sending/Receiving Messages.

class carrot.messaging.Consumer(connection, queue=None, exchange=None, routing_key=None, **kwargs)

Message consumer.

Parameters:
connection
A carrot.connection.AMQPConnection instance.
queue
Name of the queue.
exchange
Name of the exchange the queue binds to.
routing_key

The routing key (if any). The interpretation of the routing key depends on the value of the exchange_type attribute:

  • direct exchange

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

  • fanout exchange

    Always matches, even if the binding does not have a 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".

durable
Durable exchanges remain active when a server restarts. Non-durable exchanges (transient exchanges) are purged when a server restarts. Default is True.
auto_delete
If set, the exchange is deleted when all queues have finished using it. Default is False.
exclusive
Exclusive queues may only be consumed from by the current connection. When exclusive is on, this also implies auto_delete. Default is False.
exchange_type

AMQP defines four default exchange types (routing algorithms) that covers most of the common messaging use cases. An AMQP broker can also define additional exchange types, so see your message brokers manual for more information about available exchange types.

  • Direct

    Direct match between the routing key in the message, and the routing criteria used when a queue is bound to this exchange.

  • Topic

    Wildcard match between the routing key and the routing pattern specified in the binding. The routing key is treated as zero or more words delimited by "." and supports special wildcard characters. "*" matches a single word and "#" matches zero or more words.

  • Fanout

    Queues are bound to this exchange with no arguments. Hence any message sent to this exchange will be forwarded to all queues bound to this exchange.

  • Headers

    Queues are bound to this exchange with a table of arguments containing headers and values (optional). A special argument named “x-match” determines the matching algorithm, where "all" implies an AND (all pairs must match) and "any" implies OR (at least one pair must match).

    NOTE: carrot has poor support for header exchanges at

    this point.

This description of AMQP exchange types was shamelessly stolen from the blog post AMQP in 10 minutes: Part 4 by Rajith Attapattu. Recommended reading.

decoder
A function able to deserialize the message body.
backend_cls
The messaging backend class used. Defaults to the pyamqplib backend.
callbacks
List of registered callbacks to trigger when a message is received by wait(), process_next() or iterqueue().
warn_if_exists
Emit a warning if the queue has already been declared. If a queue already exists, and you try to redeclare the queue with new settings, the new settings will be silently ignored, so this can be useful if you’ve recently changed the routing_key attribute or other settings.
auto_ack
Acknowledgement is handled automatically once messages are received. This means that the carrot.backends.base.BaseMessage.ack() and carrot.backends.base.BaseMessage.reject() methods on the message object are no longer valid. By default auto_ack is set to False, and the receiver is required to manually handle acknowledgment.
no_ack
Disable acknowledgement on the server-side. This is different from auto_ack in that acknowledgement is turned off altogether. This functionality increases performance but at the cost of reliability. Messages can get lost if a client dies before it can deliver them to the application.
Raises amqplib.client_0_8.channel.AMQPChannelException:
 if the queue is exclusive and the queue already exists and is owned by another connection.

Example Usage

>>> consumer = Consumer(connection=DjangoAMQPConnection(),
...               queue="foo", exchange="foo", routing_key="foo")
>>> def process_message(message_data, message):
...     print("Got message %s: %s" % (
...             message.delivery_tag, message_data))
>>> consumer.register_callback(process_message)
>>> consumer.wait() # Go into receive loop
backend_cls
alias of Backend
close()
Close the channel to the queue.
discard_all(filterfunc=None)

Discard all waiting messages.

Parameter:filterfunc – A filter function to only discard the messages this filter returns.
Returns:the number of messages discarded.

WARNING: All incoming messages will be ignored and not processed.

Example using filter:

>>> def waiting_feeds_only(message):
...     try:
...         message_data = message.decode()
...     except: # Should probably be more specific.
...         pass
...
...     if message_data.get("type") == "feed":
...         return True
...     else:
...         return False
fetch(no_ack=None, auto_ack=None, enable_callbacks=False)

Receive the next message waiting on the queue.

Returns:

A carrot.backends.base.BaseMessage instance, or None if there’s no messages to be received.

Parameters:
  • enable_callbacks – Enable callbacks. The message will be processed with all registered callbacks. Default is disabled.
  • auto_ack – Override the default auto_ack setting.
  • no_ack – Override the default no_ack setting.
iterconsume(limit=None)

Iterator processing new messages as they arrive. Every new message will be passed to the callbacks, and the iterator returns True. The iterator is infinite unless the limit argument is specified or someone closes the consumer.

iterconsume() uses transient requests for messages on the server, while iterequeue() uses synchronous access. In most cases you want iterconsume(), but if your environment does not support this behaviour you can resort to using iterqueue() instead.

Also, iterconsume() does not return the message at each step, something which iterqueue() does.

Parameter:limit – Maximum number of messages to process.
Raises StopIteration:
 if limit is set and the message limit has been reached.
iterqueue(limit=None, infinite=False)

Infinite iterator yielding pending messages, by using synchronous direct access to the queue (basic_get).

iterqueue() is used where synchronous functionality is more important than performance. If you can, use iterconsume() instead.

Parameters:
  • limit – If set, the iterator stops when it has processed this number of messages in total.
  • infinite – Don’t raise StopIteration if there is no messages waiting, but return None instead. If infinite you obviously shouldn’t consume the whole iterator at once without using a limit.
Raises StopIteration:
 

If there is no messages waiting, and the iterator is not infinite.

process_next()

DEPRECATED Use fetch() like this instead:

>>> message = self.fetch(enable_callbacks=True)
receive(message_data, message)

This method is called when a new message is received by running wait(), process_next() or iterqueue().

When a message is received, it passes the message on to the callbacks listed in the callbacks attribute. You can register callbacks using register_callback().

Parameters:
Raises NotImplementedError:
 

If no callbacks has been registered.

register_callback(callback)

Register a callback function to be triggered by receive().

The callback function must take two arguments:

wait(limit=None)

Go into consume mode.

Mostly for testing purposes and simple programs, you probably want iterconsume() or iterqueue() instead.

This runs an infinite loop, processing all incoming messages using receive() to apply the message to all registered callbacks.

class carrot.messaging.Messaging(connection, **kwargs)

A combined message publisher and consumer.

close()
Close any open channels.
consumer_cls
alias of Consumer
decoder
The decoder used.
encoder
The encoder used.
fetch(**kwargs)
See Consumer.fetch()
publisher_cls
alias of Publisher
receive(message_data, message)
See Consumer.receive()
register_callback(callback)
See Consumer.register_callback()
send(message_data, delivery_mode=None)
See Publisher.send()
class carrot.messaging.Publisher(connection, exchange=None, routing_key=None, **kwargs)

Message publisher.

Parameters:
connection
The AMQP connection. A carrot.connection.AMQPConnection instance.
exchange
Name of the exchange we send messages to.
routing_key
The default routing key for messages sent using this publisher. See Consumer.routing_key for more information. You can override the routing key by passing an explicit routing_key argument to send().
delivery_mode

The default delivery mode used for messages. The value is an integer. The following delivery modes are supported by (at least) RabbitMQ:

  • 1

    The message is non-persistent. Which means it is stored in memory only, and is lost if the server dies or restarts.

  • 2

    The message is persistent. Which means the message is stored both in-memory, and on disk, and therefore preserved if the server dies or restarts.

The default value is 2 (persistent).

encoder
The function responsible for encoding the message data passed to send(). Note that any consumer of the messages sent must have a decoder supporting the serialization scheme.
backend_cls
The messaging backend class used. Defaults to the pyamqplib backend.
backend_cls
alias of Backend
close()
Close connection to queue.
create_message(message_data, delivery_mode=None, priority=None)
With any data, serialize it and encapsulate it in a AMQP message with the proper headers set.
send(message_data, routing_key=None, delivery_mode=None, mandatory=False, immediate=False, priority=0)

Send a message.

Parameters:
  • message_data – The message data to send. Can be a list, dictionary or a string.
  • routing_key – A custom routing key for the message. If not set, the default routing key set in the routing_key attribute is used.
  • mandatory – If set, the message has mandatory routing. By default the message is silently dropped by the server if it can’t be routed to a queue. However - If the message is mandatory, an exception will be raised instead.
  • immediate – Request immediate delivery. If the message cannot be routed to a queue consumer immediately, an exception will be raised. This is instead of the default behaviour, where the server will accept and queue the message, but with no guarantee that the message will ever be consumed.
  • delivery_mode – Override the default delivery_mode.
  • priority – The message priority, 0 to 9.

Previous topic

carrot.connection

Next topic

carrot.backends

This Page