diff options
| -rw-r--r-- | FAQ | 7 | ||||
| -rw-r--r-- | README.rst | 6 | ||||
| -rw-r--r-- | docs/userguide/connections.rst | 14 | ||||
| -rw-r--r-- | docs/userguide/consumers.rst | 21 | ||||
| -rw-r--r-- | docs/userguide/index.rst | 2 | ||||
| -rw-r--r-- | docs/userguide/producers.rst | 27 | ||||
| -rw-r--r-- | docs/userguide/serialization.rst | 15 | ||||
| -rw-r--r-- | kombu/abstract.py | 4 | ||||
| -rw-r--r-- | kombu/common.py | 2 | ||||
| -rw-r--r-- | kombu/connection.py | 14 | ||||
| -rw-r--r-- | kombu/entity.py | 2 | ||||
| -rw-r--r-- | kombu/exceptions.py | 2 | ||||
| -rw-r--r-- | kombu/messaging.py | 9 | ||||
| -rw-r--r-- | kombu/pidbox.py | 2 | ||||
| -rw-r--r-- | kombu/serialization.py | 8 | ||||
| -rw-r--r-- | kombu/utils/__init__.py | 4 |
16 files changed, 94 insertions, 45 deletions
@@ -7,11 +7,8 @@ Questions Q: Message.reject doesn't work? -------------------------------------- -**Answer**: RabbitMQ (as of v1.5.5) has not implemented reject yet. -There was a brief discussion about it on their mailing list, and the reason -why it's not implemented yet is revealed: - -http://lists.rabbitmq.com/pipermail/rabbitmq-discuss/2009-January/003183.html +**Answer**: Earlier versions of RabbitMQ did not implement ``basic.reject``, +so make sure your version is recent enough to support it. Q: Message.requeue doesn't work? -------------------------------------- @@ -42,7 +42,7 @@ Features * Consistent exception handling across transports. * The ability to ensure that an operation is performed by gracefully - handling connection and channel errrors. + handling connection and channel errors. * Several annoyances with `amqplib`_ has been fixed, like supporting timeouts and the ability to wait for events on more than one channel. @@ -148,7 +148,7 @@ Quick overview connection.drain_events() -Or handle channels menually:: +Or handle channels manually:: with connection.channel() as channel: producer = Producer(channel, ...) @@ -177,7 +177,7 @@ just remember to close the objects after use:: `Exchange` and `Queue` are simply declarations that can be pickled -and used in configuaration files etc. +and used in configuration files etc. They also support operations, but to do so they need to be bound to a channel: diff --git a/docs/userguide/connections.rst b/docs/userguide/connections.rst index daf3fc07..fa9de610 100644 --- a/docs/userguide/connections.rst +++ b/docs/userguide/connections.rst @@ -25,7 +25,7 @@ method:: >>> connection.connect() -You can also check wether the connection is connected:: +You can also check whether the connection is connected:: >>> connection.connected() True @@ -37,7 +37,7 @@ Connections must always be closed after use:: But best practice is to release the connection instead, this will release the resource if the connection is associated with a connection pool, or close the connection if not, -and makes it easier to transist to connection pools later:: +and makes it easier to do the transition to connection pools later:: >>> connection.release() @@ -83,7 +83,7 @@ The query part of the URL can also be used to set options, e.g.:: See :ref:`connection-options` for a list of supported options. A connection without options will use the default connection settings, -which is using the localhost host, default port, username `guest`, +which is using the localhost host, default port, user name `guest`, password `guest` and virtual host "/". A connection without arguments is the same as:: @@ -103,8 +103,8 @@ Keyword arguments The :class:`BrokerConnection` class supports additional keyword arguments, these are: -:hostname: Default hostname if not provided in the URL. -:userid: Default username if not provided in the URL. +:hostname: Default host name if not provided in the URL. +:userid: Default user name if not provided in the URL. :password: Default password if not provided in the URL. :virtual_host: Default virtual host if not provided in the URL. :port: Default port if not provided in the URL. @@ -113,7 +113,7 @@ keyword arguments, these are: ``kombu.transport.pyamqplib.Transport``), or one of the aliases: ``amqplib``, ``pika``, ``redis``, ``memory``, and so on. -:ssl: Use ssl to connect to the server. Default is ``False``. +:ssl: Use SSL to connect to the server. Default is ``False``. Only supported by the amqp transport. :insist: Insist on connecting to a server. In a configuration with multiple load-sharing servers, the insist @@ -121,7 +121,7 @@ keyword arguments, these are: to the specified server. Default is ``False``. Only supported by the amqp and pika transports, and not by AMQP 0-9-1. :connect_timeout: Timeout in seconds for connecting to the - server. May not be suported by the specified transport. + server. May not be supported by the specified transport. :transport_options: A dict of additional connection arguments to pass to alternate kombu channel implementations. Consult the transport documentation for available options. diff --git a/docs/userguide/consumers.rst b/docs/userguide/consumers.rst new file mode 100644 index 00000000..9fc53103 --- /dev/null +++ b/docs/userguide/consumers.rst @@ -0,0 +1,21 @@ +.. currentmodule:: kombu.messaging +.. _guide-consumers: + +=========== + Consumers +=========== + +.. _consumer-basics: + +Basics +====== + + +Reference +========= + +.. module:: kombu.messaging + +.. autoclass:: Consumer + :noindex: + :members: diff --git a/docs/userguide/index.rst b/docs/userguide/index.rst index 0f427251..7a6d4a05 100644 --- a/docs/userguide/index.rst +++ b/docs/userguide/index.rst @@ -9,6 +9,8 @@ :maxdepth: 2 connections + producers + consumers examples simple pools diff --git a/docs/userguide/producers.rst b/docs/userguide/producers.rst new file mode 100644 index 00000000..c6e80625 --- /dev/null +++ b/docs/userguide/producers.rst @@ -0,0 +1,27 @@ +.. currentmodule:: kombu.messaging +.. _guide-producers: + +=========== + Producers +=========== + +.. _producer-basics: + +Basics +====== + + +Serialization +============= + +See :ref:`guide-serialization`. + + +Reference +========= + +.. module:: kombu.messaging + +.. autoclass:: Producer + :noindex: + :members: diff --git a/docs/userguide/serialization.rst b/docs/userguide/serialization.rst index 4f24f166..b70ea549 100644 --- a/docs/userguide/serialization.rst +++ b/docs/userguide/serialization.rst @@ -27,10 +27,10 @@ Each option has its advantages and disadvantages. `simplejson`. The primary disadvantage to `JSON` is that it limits you to - the following data types: strings, unicode, floats, boolean, + 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 + 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. @@ -79,16 +79,17 @@ Sending raw data without Serialization ====================================== In some cases, you don't need your message data to be serialized. If you -pass in a plain string or unicode object as your message, then carrot will +pass in a plain string or Unicode object as your message, then carrot will not waste cycles serializing/deserializing the data. You can optionally specify a `content_type` and `content_encoding` for the raw data:: - >>> producer.send(open('~/my_picture.jpg','rb').read(), - content_type="image/jpeg", - content_encoding="binary", - routing_key=rkey) + >>> with open("~/my_picture.jpg", "rb") as fh: + ... producer.publish(fh.read(), + content_type="image/jpeg", + content_encoding="binary", + routing_key=rkey) The `Message` object returned by the `Consumer` class will have a `content_type` and `content_encoding` attribute. diff --git a/kombu/abstract.py b/kombu/abstract.py index e613ad32..6afb9b23 100644 --- a/kombu/abstract.py +++ b/kombu/abstract.py @@ -14,7 +14,7 @@ from kombu.exceptions import NotBoundError class Object(object): - """Common baseclass supporting automatic kwargs->attributes handling, + """Common base class supporting automatic kwargs->attributes handling, and cloning.""" attrs = () @@ -63,7 +63,7 @@ class MaybeChannelBound(Object): return self def revive(self, channel): - """Revive channel afer connection re-established. + """Revive channel after the connection has been re-established. Used by :meth:`~kombu.connection.BrokerConnection.ensure`. diff --git a/kombu/common.py b/kombu/common.py index d2b2ba08..b3295b1b 100644 --- a/kombu/common.py +++ b/kombu/common.py @@ -31,7 +31,7 @@ class Broadcast(entity.Queue): """Convenience class used to define broadcast queues. Every queue instance will have a unique name, - and both the queue and exchange is configued with auto deletion. + and both the queue and exchange is configured with auto deletion. :keyword name: This is used as the name of the exchange. :keyword queue: By default a unique id is used for the queue diff --git a/kombu/connection.py b/kombu/connection.py index bb7cfaab..5719e536 100644 --- a/kombu/connection.py +++ b/kombu/connection.py @@ -63,16 +63,16 @@ class BrokerConnection(object): :param URL: Connection URL. - :keyword hostname: Default Hostname/address if not provided in the URL. - :keyword userid: Default username if not provided in the URL. + :keyword hostname: Default host name/address if not provided in the URL. + :keyword userid: Default user name if not provided in the URL. :keyword password: Default password if not provided in the URL. :keyword virtual_host: Default virtual host if not provided in the URL. :keyword port: Default port if not provided in the URL. - :keyword ssl: Use ssl to connect to the server. Default is ``False``. + :keyword ssl: Use SSL to connect to the server. Default is ``False``. May not be supported by the specified transport. :keyword transport: Default transport if not specified in the URL. :keyword connect_timeout: Timeout in seconds for connecting to the - server. May not be suported by the specified transport. + server. May not be supported by the specified transport. :keyword transport_options: A dict of additional connection arguments to pass to alternate kombu channel implementations. Consult the transport documentation for available options. @@ -167,7 +167,7 @@ class BrokerConnection(object): """Wait for a single event from the server. :keyword timeout: Timeout in seconds before we give up. - Raises :exc:`socket.timeout` if the timeout is execeded. + Raises :exc:`socket.timeout` if the timeout is exceeded. Usually used from an event loop. @@ -234,7 +234,7 @@ class BrokerConnection(object): def ensure(self, obj, fun, errback=None, max_retries=None, interval_start=1, interval_step=1, interval_max=1, on_revive=None): """Ensure operation completes, regardless of any channel/connection - errors occuring. + errors occurring. Will retry by establishing the connection, and reapplying the function. @@ -569,7 +569,7 @@ class BrokerConnection(object): @property def host(self): - """The host as a hostname/port pair separated by colon.""" + """The host as a host name/port pair separated by colon.""" return ":".join([self.hostname, str(self.port)]) @property diff --git a/kombu/entity.py b/kombu/entity.py index a60cf81e..08a12b9e 100644 --- a/kombu/entity.py +++ b/kombu/entity.py @@ -479,7 +479,7 @@ class Queue(MaybeChannelBound): if the queue has consumers. :keyword if_empty: If set, the server will only delete the queue - if it is empty. If if's not empty a channel error will be raised. + if it is empty. If it is not empty a channel error will be raised. :keyword nowait: Do not wait for a reply. diff --git a/kombu/exceptions.py b/kombu/exceptions.py index bac4ac86..8cfa7b17 100644 --- a/kombu/exceptions.py +++ b/kombu/exceptions.py @@ -36,7 +36,7 @@ class ConnectionLimitExceeded(LimitExceeded): class ChannelLimitExceeded(LimitExceeded): - """Maximum number of simultaenous channels exceeded.""" + """Maximum number of simultaneous channels exceeded.""" pass diff --git a/kombu/messaging.py b/kombu/messaging.py index 3f10be26..0d81e7a5 100644 --- a/kombu/messaging.py +++ b/kombu/messaging.py @@ -16,6 +16,7 @@ from kombu.serialization import encode from kombu.syn import blocking as _SYN from kombu.utils import maybe_list + Exchange = entity.Exchange Queue = entity.Queue @@ -109,9 +110,9 @@ class Producer(object): :keyword mandatory: Currently not supported. :keyword immediate: Currently not supported. :keyword priority: Message priority. A number between 0 and 9. - :keyword content_type: Content type. Default is autodetect. - :keyword content_encoding: Content encoding. Default is autodetect. - :keyword serializer: Serializer to use. Default is autodetect. + :keyword content_type: Content type. Default is auto-detect. + :keyword content_encoding: Content encoding. Default is auto-detect. + :keyword serializer: Serializer to use. Default is auto-detect. :keyword headers: Mapping of arbitrary headers to pass along with the message body. :keyword exchange: Override the exchange. Note that this exchange @@ -223,7 +224,7 @@ class Consumer(object): #: #: The signature of the callback must take two arguments: `(message, #: exc)`, which is the message that can't be decoded and the exception - #: that occured while trying to decode it. + #: that occurred while trying to decode it. on_decode_error = None _next_tag = count(1).next # global diff --git a/kombu/pidbox.py b/kombu/pidbox.py index ad624e82..bd4f06f4 100644 --- a/kombu/pidbox.py +++ b/kombu/pidbox.py @@ -212,7 +212,7 @@ class Mailbox(object): raise ValueError("destination must be a list/tuple not %s" % ( type(destination))) - # Set reply limit to number of destinations (if specificed) + # Set reply limit to number of destinations (if specified) if limit is None and destination: limit = destination and len(destination) or None diff --git a/kombu/serialization.py b/kombu/serialization.py index f9a2f86f..378cf5d7 100644 --- a/kombu/serialization.py +++ b/kombu/serialization.py @@ -111,14 +111,14 @@ class SerializerRegistry(object): "No encoder installed for %s" % serializer) # If a raw string was sent, assume binary encoding - # (it's likely either ASCII or a raw binary file, but 'binary' - # charset will encompass both, even if not ideal. + # (it's likely either ASCII or a raw binary file, and a character + # set of 'binary' will encompass both, even if not ideal. if not serializer and isinstance(data, bytes_type): # In Python 3+, this would be "bytes"; allow binary data to be # sent as a message without getting encoder errors return "application/data", "binary", data - # For unicode objects, force it into a string + # For Unicode objects, force it into a string if not serializer and isinstance(data, unicode): payload = data.encode("utf-8") return "text/plain", "utf-8", payload @@ -138,7 +138,7 @@ class SerializerRegistry(object): content_type = content_type or 'application/data' content_encoding = (content_encoding or 'utf-8').lower() - # Don't decode 8-bit strings or unicode objects + # Don't decode 8-bit strings or Unicode objects if content_encoding not in ('binary', 'ascii-8bit') and \ not isinstance(data, unicode): data = _decode(data, content_encoding) diff --git a/kombu/utils/__init__.py b/kombu/utils/__init__.py index 939bc5ec..c8db389c 100644 --- a/kombu/utils/__init__.py +++ b/kombu/utils/__init__.py @@ -51,7 +51,7 @@ def uuid4(): def uuid(): """Generate a unique id, having - hopefully - a very small chance of - collission. + collision. For now this is provided by :func:`uuid.uuid4`. """ @@ -65,7 +65,7 @@ if sys.version_info >= (3, 0): return kwargs else: def kwdict(kwargs): # noqa - """Make sure keyword arguments are not in unicode. + """Make sure keyword arguments are not in Unicode. This should be fixed in newer Python versions, see: http://bugs.python.org/issue4978. |