carrot.messaging — Carrot v0.4.1 documentation

### Navigation

- index
- modules |
- next |
- previous |
- Carrot v0.4.1 documentation »
- API Reference »

# 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 – see `connection`. queue – see `queue`. exchange – see `exchange`. routing_key – see `routing_key`. durable – see `durable`. auto_delete – see `auto_delete`. exclusive – see `exclusive`. exchange_type – see `exchange_type`. decoder – see `decoder`. backend_cls – see `backend_cls`. auto_ack – see `auto_ack`. no_ack – see `no_ack`.

  `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: | message_data – The deserialized message data. message – The `carrot.backends.base.BaseMessage` instance.
    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:

    > - message_data

    >   > The deserialized message data

    > - message

    >   > The `carrot.backends.base.BaseMessage` instance.

  `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 – see `connection`. exchange – see `exchange`. routing_key – see `routing_key`. encoder – see `encoder`. backend_cls – see `backend_cls`.

  `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`.

### Navigation

- index
- modules |
- next |
- previous |
- Carrot v0.4.1 documentation »
- API Reference »