diff options
| -rw-r--r-- | Makefile | 106 | ||||
| -rw-r--r-- | README.rst | 93 | ||||
| -rw-r--r-- | docs/includes/installation.txt | 27 | ||||
| -rw-r--r-- | docs/includes/introduction.txt | 285 | ||||
| -rw-r--r-- | docs/includes/resources.txt | 30 | ||||
| -rw-r--r-- | docs/introduction.rst | 10 | ||||
| -rw-r--r-- | docs/templates/readme.txt | 23 |
7 files changed, 499 insertions, 75 deletions
@@ -1,70 +1,116 @@ +PROJ=kombu PYTHON=python -SPHINX_DIR="docs/" +GIT=git +TOX=tox +NOSETESTS=nosetests +ICONV=iconv +FLAKE8=flake8 +FLAKEPLUS=flakeplus + +SPHINX_DIR=docs/ SPHINX_BUILDDIR="${SPHINX_DIR}/_build" -README="README.rst" +README=README.rst README_SRC="docs/templates/readme.txt" -CONTRIBUTING_SRC="docs/contributing.rst" SPHINX2RST="sphinx2rst" - SPHINX_HTMLDIR = "${SPHINX_BUILDDIR}/html" - -html: +DOCUMENTATION=Documentation +FLAKEPLUSTARGET=2.7 + +all: help + +help: + @echo "docs - Build documentation." + @echo "test-all - Run tests for all supported python versions." + @echo "distcheck ---------- - Check distribution for problems." + @echo " test - Run unittests using current python." + @echo " lint ------------ - Check codebase for problems." + @echo " apicheck - Check API reference coverage." + @echo " configcheck - Check configuration reference coverage." + @echo " readmecheck - Check README encoding." + @echo " flakes -------- - Check code for syntax and style errors." + @echo " flakecheck - Run flake8 on the source code." + @echo " flakepluscheck - Run flakeplus on the source code." + @echo "readme - Regenerate README.rst file." + @echo "clean-dist --------- - Clean all distribution build artifacts." + @echo " clean-git-force - Remove all uncomitted files." + @echo " clean ------------ - Non-destructive clean" + @echo " clean-pyc - Remove .pyc/__pycache__ files" + @echo " clean-docs - Remove documentation build artifacts." + @echo " clean-build - Remove setup artifacts." + +clean: clean-docs clean-pyc clean-build + +clean-dist: clean clean-git-force + +Documentation: (cd "$(SPHINX_DIR)"; $(MAKE) html) - mv "$(SPHINX_HTMLDIR)" Documentation + mv "$(SPHINX_HTMLDIR)" $(DOCUMENTATION) -docsclean: +docs: Documentation + +clean-docs: -rm -rf "$(SPHINX_BUILDDIR)" -htmlclean: - (cd "$(SPHINX_DIR)"; $(MAKE) clean) +lint: flakecheck apicheck configcheck readmecheck apicheck: (cd "$(SPHINX_DIR)"; $(MAKE) apicheck) +configcheck: + (cd "$(SPHINX_DIR)"; $(MAKE) configcheck) + flakecheck: - flake8 kombu + $(FLAKE8) "$(PROJ)" flakediag: -$(MAKE) flakecheck flakepluscheck: - flakeplus --2.7 kombu + $(FLAKEPLUS) --$(FLAKEPLUSTARGET) "$(PROJ)" flakeplusdiag: -$(MAKE) flakepluscheck flakes: flakediag flakeplusdiag -readmeclean: +clean-readme: -rm -f $(README) readmecheck: - iconv -f ascii -t ascii $(README) >/dev/null + $(ICONV) -f ascii -t ascii $(README) >/dev/null $(README): $(SPHINX2RST) $(README_SRC) --ascii > $@ -readme: readmeclean $(README) readmecheck - -test: - nosetests -xv kombu.tests - -cov: - nosetests -xv kombu.tests --with-coverage --cover-html --cover-branch +readme: clean-readme $(README) readmecheck -removepyc: +clean-pyc: -find . -type f -a \( -name "*.pyc" -o -name "*$$py.class" \) | xargs rm -find . -type d -name "__pycache__" | xargs rm -r -gitclean: - git clean -xdn +removepyc: clean-pyc -gitcleanforce: - git clean -xdf +clean-build: + rm -rf build/ dist/ .eggs/ *.egg-info/ .tox/ .coverage cover/ + +clean-git: + $(GIT) clean -xdn + +clean-git-force: + $(GIT) clean -xdf + +test-all: clean-pyc + $(TOX) + +test: + $(PYTHON) setup.py test + +cov: + $(NOSETESTS) -xv --with-coverage --cover-html --cover-branch -tox: removepyc - tox +build: + $(PYTHON) setup.py sdist bdist_wheel -distcheck: flakecheck apicheck readmecheck test gitclean +distcheck: lint test clean -dist: readme docsclean gitcleanforce removepyc +dist: readme clean-dist build @@ -1,12 +1,17 @@ -.. _kombu-index: - ======================================== kombu - Messaging library for Python ======================================== -|build-status| |coverage-status| +|build-status| |coverage| |bitdeli| :Version: 4.0.0a1 +:Web: http://kombu.me/ +:Download: http://pypi.python.org/pypi/kombu/ +:Source: https://github.com/celery/kombu/ +:Keywords: messaging, amqp, rabbitmq, redis, mongodb, python, queue + +About +===== `Kombu` is a messaging library for Python. @@ -29,8 +34,7 @@ Features * High performance AMQP transport written in C - when using `librabbitmq`_ This is automatically enabled if librabbitmq is installed: - - .. code-block:: console + :: $ pip install librabbitmq @@ -80,7 +84,6 @@ and the `Wikipedia article about AMQP`_. .. _`Pyro`: http://pythonhosting.org/Pyro .. _`SoftLayer MQ`: http://www.softlayer.com/services/additional/message-queue - .. _transport-comparison: Transport Comparison @@ -135,8 +138,7 @@ Kombu is using Sphinx, and the latest documentation can be found here: Quick overview -------------- - -.. code-block:: python +:: from kombu import Connection, Exchange, Queue @@ -180,8 +182,7 @@ Quick overview Or handle channels manually: - -.. code-block:: python +:: with connection.channel() as channel: producer = Producer(channel, ...) @@ -190,8 +191,7 @@ Or handle channels manually: All objects can be used outside of with statements too, just remember to close the objects after use: - -.. code-block:: python +:: from kombu import Connection, Consumer, Producer @@ -214,8 +214,7 @@ to a channel. Binding exchanges and queues to a connection will make it use that connections default channel. - -.. code-block:: pycon +:: >>> exchange = Exchange('tasks', 'direct') @@ -228,33 +227,6 @@ that connections default channel. raise NotBoundError: Can't call delete on Exchange not bound to a channel. -Installation -============ - -You can install `Kombu` either via the Python Package Index (PyPI) -or from source. - -To install using `pip`,: - -.. code-block:: console - - $ pip install kombu - -To install using `easy_install`,: - -.. code-block:: console - - $ easy_install kombu - -If you have downloaded a source tarball you can install it -by doing the following,: - -.. code-block:: console - - $ python setup.py build - # python setup.py install # as root - - Terminology =========== @@ -312,6 +284,32 @@ There are some concepts you should be familiar with before starting: routing keys `"usd.stock"` and `"eur.stock.db"` but not `"stock.nasdaq"`. + +Installation +============ + +You can install `Kombu` either via the Python Package Index (PyPI) +or from source. + +To install using `pip`,: +:: + + $ pip install kombu + +To install using `easy_install`,: +:: + + $ easy_install kombu + +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 + + + Getting Help ============ @@ -342,9 +340,16 @@ License This software is licensed under the `New BSD License`. See the `LICENSE` file in the top distribution directory for the full license text. -.. image:: https://d2weczhvl823v0.cloudfront.net/celery/kombu/trend.png + +.. |build-status| image:: https://secure.travis-ci.org/celery/kombu.png?branch=master + :alt: Build status + :target: https://travis-ci.org/celery/kombu + +.. |coverage| image:: https://codecov.io/github/celery/kombu/coverage.svg?branch=master + :target: https://codecov.io/github/celery/kombu?branch=master + +.. |bitdeli| image:: https://d2weczhvl823v0.cloudfront.net/celery/kombu/trend.png :alt: Bitdeli badge :target: https://bitdeli.com/free +-- -.. |build-status| image:: https://travis-ci.org/celery/kombu.svg?branch=master - :target: https://travis-ci.org/celery/kombu diff --git a/docs/includes/installation.txt b/docs/includes/installation.txt new file mode 100644 index 00000000..b3cc474a --- /dev/null +++ b/docs/includes/installation.txt @@ -0,0 +1,27 @@ +Installation +============ + +You can install `Kombu` either via the Python Package Index (PyPI) +or from source. + +To install using `pip`,: + +.. code-block:: console + + $ pip install kombu + +To install using `easy_install`,: + +.. code-block:: console + + $ easy_install kombu + +If you have downloaded a source tarball you can install it +by doing the following,: + +.. code-block:: console + + $ python setup.py build + # python setup.py install # as root + + diff --git a/docs/includes/introduction.txt b/docs/includes/introduction.txt new file mode 100644 index 00000000..3f39cb73 --- /dev/null +++ b/docs/includes/introduction.txt @@ -0,0 +1,285 @@ +:Version: 4.0.0a1 +:Web: http://kombu.me/ +:Download: http://pypi.python.org/pypi/kombu/ +:Source: https://github.com/celery/kombu/ +:Keywords: messaging, amqp, rabbitmq, redis, mongodb, python, queue + +About +===== + +`Kombu` is a messaging library for Python. + +The aim of `Kombu` is to make messaging in Python as easy as possible by +providing an idiomatic high-level interface for the AMQ protocol, and also +provide proven and tested solutions to common messaging problems. + +`AMQP`_ is the Advanced Message Queuing Protocol, an open standard protocol +for message orientation, queuing, routing, reliability and security, +for which the `RabbitMQ`_ messaging server is the most popular implementation. + +Features +======== + +* Allows application authors to support several message server + solutions by using pluggable transports. + + * AMQP transport using the `py-amqp`_, `librabbitmq`_, or `qpid-python`_ libraries. + + * High performance AMQP transport written in C - when using `librabbitmq`_ + + This is automatically enabled if librabbitmq is installed: + + .. code-block:: console + + $ pip install librabbitmq + + * Virtual transports makes it really easy to add support for non-AMQP + transports. There is already built-in support for `Redis`_, + `Beanstalk`_, `Amazon SQS`_, `CouchDB`_, `MongoDB`_, `ZeroMQ`_, + `ZooKeeper`_, `SoftLayer MQ`_ and `Pyro`_. + + * You can also use the SQLAlchemy and Django ORM transports to + use a database as the broker. + + * In-memory transport for unit testing. + +* Supports automatic encoding, serialization and compression of message + payloads. + +* Consistent exception handling across transports. + +* The ability to ensure that an operation is performed by gracefully + 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. + +* Projects already using `carrot`_ can easily be ported by using + a compatibility layer. + +For an introduction to AMQP you should read the article `Rabbits and warrens`_, +and the `Wikipedia article about AMQP`_. + +.. _`RabbitMQ`: http://www.rabbitmq.com/ +.. _`AMQP`: http://amqp.org +.. _`py-amqp`: http://pypi.python.org/pypi/amqp/ +.. _`qpid-python`: http://pypi.python.org/pypi/qpid-python/ +.. _`Redis`: http://code.google.com/p/redis/ +.. _`Amazon SQS`: http://aws.amazon.com/sqs/ +.. _`MongoDB`: http://www.mongodb.org/ +.. _`CouchDB`: http://couchdb.apache.org/ +.. _`ZeroMQ`: http://zeromq.org/ +.. _`Zookeeper`: https://zookeeper.apache.org/ +.. _`Beanstalk`: http://kr.github.com/beanstalkd/ +.. _`Rabbits and warrens`: http://blogs.digitar.com/jjww/2009/01/rabbits-and-warrens/ +.. _`amqplib`: http://barryp.org/software/py-amqplib/ +.. _`Wikipedia article about AMQP`: http://en.wikipedia.org/wiki/AMQP +.. _`carrot`: http://pypi.python.org/pypi/carrot/ +.. _`librabbitmq`: http://pypi.python.org/pypi/librabbitmq +.. _`Pyro`: http://pythonhosting.org/Pyro +.. _`SoftLayer MQ`: http://www.softlayer.com/services/additional/message-queue + +.. _transport-comparison: + +Transport Comparison +==================== + ++---------------+----------+------------+------------+---------------+--------------+-----------------------+ +| **Client** | **Type** | **Direct** | **Topic** | **Fanout** | **Priority** | **TTL** | ++---------------+----------+------------+------------+---------------+--------------+-----------------------+ +| *amqp* | Native | Yes | Yes | Yes | Yes [#f3]_ | Yes [#f4]_ | ++---------------+----------+------------+------------+---------------+--------------+-----------------------+ +| *qpid* | Native | Yes | Yes | Yes | No | No | ++---------------+----------+------------+------------+---------------+--------------+-----------------------+ +| *redis* | Virtual | Yes | Yes | Yes (PUB/SUB) | Yes | No | ++---------------+----------+------------+------------+---------------+--------------+-----------------------+ +| *mongodb* | Virtual | Yes | Yes | Yes | Yes | Yes | ++---------------+----------+------------+------------+---------------+--------------+-----------------------+ +| *beanstalk* | Virtual | Yes | Yes [#f1]_ | No | Yes | No | ++---------------+----------+------------+------------+---------------+--------------+-----------------------+ +| *SQS* | Virtual | Yes | Yes [#f1]_ | Yes [#f2]_ | No | No | ++---------------+----------+------------+------------+---------------+--------------+-----------------------+ +| *couchdb* | Virtual | Yes | Yes [#f1]_ | No | No | No | ++---------------+----------+------------+------------+---------------+--------------+-----------------------+ +| *zookeeper* | Virtual | Yes | Yes [#f1]_ | No | Yes | No | ++---------------+----------+------------+------------+---------------+--------------+-----------------------+ +| *in-memory* | Virtual | Yes | Yes [#f1]_ | No | No | No | ++---------------+----------+------------+------------+---------------+--------------+-----------------------+ +| *django* | Virtual | Yes | Yes [#f1]_ | No | No | No | ++---------------+----------+------------+------------+---------------+--------------+-----------------------+ +| *sqlalchemy* | Virtual | Yes | Yes [#f1]_ | No | No | No | ++---------------+----------+------------+------------+---------------+--------------+-----------------------+ +| *SLMQ* | Virtual | Yes | Yes [#f1]_ | No | No | No | ++---------------+----------+------------+------------+---------------+--------------+-----------------------+ + + +.. [#f1] Declarations only kept in memory, so exchanges/queues + must be declared by all clients that needs them. + +.. [#f2] Fanout supported via storing routing tables in SimpleDB. + Disabled by default, but can be enabled by using the + ``supports_fanout`` transport option. + +.. [#f3] AMQP Message priority support depends on broker implementation. + +.. [#f4] AMQP Message/Queue TTL support depends on broker implementation. + +Documentation +------------- + +Kombu is using Sphinx, and the latest documentation can be found here: + + http://kombu.readthedocs.org/ + +Quick overview +-------------- + +.. code-block:: python + + from kombu import Connection, Exchange, Queue + + media_exchange = Exchange('media', 'direct', durable=True) + video_queue = Queue('video', exchange=media_exchange, routing_key='video') + + def process_media(body, message): + print body + message.ack() + + # connections + with Connection('amqp://guest:guest@localhost//') as conn: + + # produce + producer = conn.Producer(serializer='json') + producer.publish({'name': '/tmp/lolcat1.avi', 'size': 1301013}, + exchange=media_exchange, routing_key='video', + declare=[video_queue]) + + # the declare above, makes sure the video queue is declared + # so that the messages can be delivered. + # It's a best practice in Kombu to have both publishers and + # consumers declare the queue. You can also declare the + # queue manually using: + # video_queue(conn).declare() + + # consume + with conn.Consumer(video_queue, callbacks=[process_media]) as consumer: + # Process messages and handle events on all channels + while True: + conn.drain_events() + + # Consume from several queues on the same channel: + video_queue = Queue('video', exchange=media_exchange, key='video') + image_queue = Queue('image', exchange=media_exchange, key='image') + + with connection.Consumer([video_queue, image_queue], + callbacks=[process_media]) as consumer: + while True: + connection.drain_events() + + +Or handle channels manually: + +.. code-block:: python + + with connection.channel() as channel: + producer = Producer(channel, ...) + consumer = Producer(channel) + + +All objects can be used outside of with statements too, +just remember to close the objects after use: + +.. code-block:: python + + from kombu import Connection, Consumer, Producer + + connection = Connection() + # ... + connection.release() + + consumer = Consumer(channel_or_connection, ...) + consumer.register_callback(my_callback) + consumer.consume() + # .... + consumer.cancel() + + +`Exchange` and `Queue` are simply declarations that can be pickled +and used in configuration files etc. + +They also support operations, but to do so they need to be bound +to a channel. + +Binding exchanges and queues to a connection will make it use +that connections default channel. + +.. code-block:: pycon + + >>> exchange = Exchange('tasks', 'direct') + + >>> connection = Connection() + >>> bound_exchange = exchange(connection) + >>> bound_exchange.delete() + + # the original exchange is not affected, and stays unbound. + >>> exchange.delete() + raise NotBoundError: Can't call delete on Exchange not bound to + a channel. + +Terminology +=========== + +There are some concepts you should be familiar with before starting: + + * Producers + + Producers 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"`. + diff --git a/docs/includes/resources.txt b/docs/includes/resources.txt new file mode 100644 index 00000000..c2a277f9 --- /dev/null +++ b/docs/includes/resources.txt @@ -0,0 +1,30 @@ +Getting Help +============ + +Mailing list +------------ + +Join the `carrot-users`_ mailing list. + +.. _`carrot-users`: http://groups.google.com/group/carrot-users/ + +Bug tracker +=========== + +If you have any suggestions, bug reports or annoyances please report them +to our issue tracker at http://github.com/celery/kombu/issues/ + +Contributing +============ + +Development of `Kombu` happens at Github: http://github.com/celery/kombu + +You are highly encouraged to participate in the development. If you don't +like Github (for some reason) you're welcome to send regular patches. + +License +======= + +This software is licensed under the `New BSD License`. See the `LICENSE` +file in the top distribution directory for the full license text. + diff --git a/docs/introduction.rst b/docs/introduction.rst index 72a33558..29eadf7b 100644 --- a/docs/introduction.rst +++ b/docs/introduction.rst @@ -1 +1,9 @@ -.. include:: ../README.rst +======================================== + Getting Started +======================================== + +.. include:: includes/introduction.txt + +.. include:: includes/installation.txt + +.. include:: includes/resources.txt diff --git a/docs/templates/readme.txt b/docs/templates/readme.txt new file mode 100644 index 00000000..28efe0cb --- /dev/null +++ b/docs/templates/readme.txt @@ -0,0 +1,23 @@ +======================================== + kombu - Messaging library for Python +======================================== + +|build-status| |coverage| |bitdeli| + +.. include:: ../includes/introduction.txt + +.. include:: ../includes/installation.txt + +.. include:: ../includes/resources.txt + +.. |build-status| image:: https://secure.travis-ci.org/celery/kombu.png?branch=master + :alt: Build status + :target: https://travis-ci.org/celery/kombu + +.. |coverage| image:: https://codecov.io/github/celery/kombu/coverage.svg?branch=master + :target: https://codecov.io/github/celery/kombu?branch=master + +.. |bitdeli| image:: https://d2weczhvl823v0.cloudfront.net/celery/kombu/trend.png + :alt: Bitdeli badge + :target: https://bitdeli.com/free +-- |