mirror of https://github.com/celery/kombu.git
151 lines
5.2 KiB
ReStructuredText
151 lines
5.2 KiB
ReStructuredText
==================
|
|
Simple Interface
|
|
==================
|
|
|
|
.. contents::
|
|
:local:
|
|
|
|
|
|
:mod:`kombu.simple` is a simple interface to AMQP queueing.
|
|
It is only slightly different from the :class:`~Queue.Queue` class in the
|
|
Python Standard Library, which makes it excellent for users with basic
|
|
messaging needs.
|
|
|
|
Instead of defining exchanges and queues, the simple classes only requires
|
|
two arguments, a connection channel and a name. The name is used as the
|
|
queue, exchange and routing key. If the need arises, you can specify
|
|
a :class:`~kombu.entity.Queue` as the name argument instead.
|
|
|
|
In addition, the :class:`~kombu.connection.BrokerConnection` comes with
|
|
shortcuts to create simple queues using the current connection::
|
|
|
|
>>> queue = connection.SimpleQueue("myqueue")
|
|
>>> # ... do something with queue
|
|
>>> queue.close()
|
|
|
|
|
|
This is equivalent to::
|
|
|
|
>>> from kombu import SimpleQueue, SimpleBuffer
|
|
|
|
>>> channel = connection.channel()
|
|
>>> queue = SimpleBuffer(channel)
|
|
>>> # ... do something with queue
|
|
>>> channel.close()
|
|
>>> queue.close()
|
|
|
|
Connections and transports
|
|
==========================
|
|
|
|
To send and receive messages you need a transport and a connection.
|
|
There are several transports to choose from (amqplib, pika, redis, in-memory),
|
|
and you can even create your own. The default transport is amqplib.
|
|
|
|
Create a connection using the default transport::
|
|
|
|
>>> from kombu import BrokerConnection
|
|
>>> connection = BrokerConnection()
|
|
|
|
The connection will not be established yet, as the connection is established
|
|
when needed. If you want to explicitly establish the connection
|
|
you have to call the :meth:`~kombu.connection.BrokerConnection.connect`
|
|
method::
|
|
|
|
>>> connection.connect()
|
|
|
|
This connection will use the default connection settings, which is using
|
|
the localhost host, default port, username ``guest``,
|
|
password ``guest`` and virtual host "/". A connection without arguments
|
|
is the same as::
|
|
|
|
>>> BrokerConnection(hostname="localhost",
|
|
... userid="guest",
|
|
... password="guest",
|
|
... virtual_host="/",
|
|
... port=6379)
|
|
|
|
The default port is transport specific, for AMQP this is 6379.
|
|
|
|
Other fields may also have different meaning depending on the transport
|
|
used. For example, the Redis transport uses the ``virtual_host`` argument as
|
|
the redis database number.
|
|
|
|
See the :class:`~kombu.connection.BrokerConnection` reference documentation
|
|
for more information and a full list of the arguments supported.
|
|
|
|
Sending and receiving messages
|
|
==============================
|
|
|
|
The simple interface defines two classes; :class:`~kombu.simple.SimpleQueue`,
|
|
and :class:`~kombu.simple.SimpleBuffer`. The former is used for persistent
|
|
messages, and the latter is used for transient, buffer-like queues.
|
|
They both have the same interface, so you can use them interchangeably.
|
|
|
|
Here is an example using the :class:`~kombu.simple.SimpleQueue` class
|
|
to produce and consume logging messages:
|
|
|
|
.. code-block:: python
|
|
|
|
from socket import gethostname
|
|
from time import time
|
|
|
|
from kombu import BrokerConnection
|
|
|
|
|
|
class Logger(object):
|
|
|
|
def __init__(self, connection, queue_name="log_queue",
|
|
serializer="json", compression=None):
|
|
self.queue = connection.SimpleQueue(self.queue_name)
|
|
self.serializer = serializer
|
|
self.compression = compression
|
|
|
|
def log(self, message, level="INFO", context={}):
|
|
self.queue.put({"message": message,
|
|
"level": level,
|
|
"context": context,
|
|
"hostname": socket.gethostname(),
|
|
"timestamp": time()},
|
|
serializer=self.serializer,
|
|
compression=self.compression)
|
|
|
|
def process(self, callback, n=1, timeout=1):
|
|
for i in xrange(n):
|
|
log_message = self.queue.get(block=True, timeout=1)
|
|
entry = log_message.payload # deserialized data.
|
|
callback(entry)
|
|
log_message.ack() # remove message from queue
|
|
|
|
def close(self):
|
|
self.queue.close()
|
|
|
|
|
|
if __name__ == "__main__":
|
|
connection = BrokerConnection(hostname="localhost",
|
|
userid="guest",
|
|
password="guest",
|
|
virtual_host="/")
|
|
logger = Logger(connection)
|
|
|
|
# Send message
|
|
logger.log("Error happened while encoding video",
|
|
level="ERROR",
|
|
context={"filename": "cutekitten.mpg"})
|
|
|
|
# Consume and process message
|
|
|
|
# This is the callback called when a log message is
|
|
# received.
|
|
def dump_entry(entry):
|
|
date = datetime.fromtimestamp(entry["timestamp"])
|
|
print("[%s %s %s] %s %r" % (date,
|
|
entry["hostname"],
|
|
entry["level"],
|
|
entry["message"],
|
|
entry["context"]))
|
|
|
|
# Process a single message using the callback above.
|
|
logger.process(dump_entry, n=1)
|
|
|
|
logger.close()
|