PKG-INFO 17 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404
  1. Metadata-Version: 2.1
  2. Name: kombu
  3. Version: 4.3.0
  4. Summary: Messaging library for Python.
  5. Home-page: https://kombu.readthedocs.io
  6. Author: Ask Solem
  7. Author-email: ask@celeryproject.org
  8. License: BSD
  9. Description: ========================================
  10. kombu - Messaging library for Python
  11. ========================================
  12. |build-status| |coverage| |license| |wheel| |pyversion| |pyimp|
  13. :Version: 4.3.0
  14. :Documentation: https://kombu.readthedocs.io/
  15. :Download: https://pypi.org/project/kombu/
  16. :Source: https://github.com/celery/kombu/
  17. :Keywords: messaging, amqp, rabbitmq, redis, mongodb, python, queue
  18. About
  19. =====
  20. `Kombu` is a messaging library for Python.
  21. The aim of `Kombu` is to make messaging in Python as easy as possible by
  22. providing an idiomatic high-level interface for the AMQ protocol, and also
  23. provide proven and tested solutions to common messaging problems.
  24. `AMQP`_ is the Advanced Message Queuing Protocol, an open standard protocol
  25. for message orientation, queuing, routing, reliability and security,
  26. for which the `RabbitMQ`_ messaging server is the most popular implementation.
  27. Features
  28. ========
  29. * Allows application authors to support several message server
  30. solutions by using pluggable transports.
  31. * AMQP transport using the `py-amqp`_, `librabbitmq`_, or `qpid-python`_ libraries.
  32. * High performance AMQP transport written in C - when using `librabbitmq`_
  33. This is automatically enabled if librabbitmq is installed:
  34. ::
  35. $ pip install librabbitmq
  36. * Virtual transports makes it really easy to add support for non-AMQP
  37. transports. There is already built-in support for `Redis`_,
  38. `Amazon SQS`_, `ZooKeeper`_, `SoftLayer MQ`_ and `Pyro`_.
  39. * In-memory transport for unit testing.
  40. * Supports automatic encoding, serialization and compression of message
  41. payloads.
  42. * Consistent exception handling across transports.
  43. * The ability to ensure that an operation is performed by gracefully
  44. handling connection and channel errors.
  45. * Several annoyances with `amqplib`_ has been fixed, like supporting
  46. timeouts and the ability to wait for events on more than one channel.
  47. * Projects already using `carrot`_ can easily be ported by using
  48. a compatibility layer.
  49. For an introduction to AMQP you should read the article `Rabbits and warrens`_,
  50. and the `Wikipedia article about AMQP`_.
  51. .. _`RabbitMQ`: https://www.rabbitmq.com/
  52. .. _`AMQP`: https://amqp.org
  53. .. _`py-amqp`: https://pypi.org/project/amqp/
  54. .. _`qpid-python`: https://pypi.org/project/qpid-python/
  55. .. _`Redis`: https://redis.io
  56. .. _`Amazon SQS`: https://aws.amazon.com/sqs/
  57. .. _`Zookeeper`: https://zookeeper.apache.org/
  58. .. _`Rabbits and warrens`: http://web.archive.org/web/20160323134044/http://blogs.digitar.com/jjww/2009/01/rabbits-and-warrens/
  59. .. _`amqplib`: https://barryp.org/software/py-amqplib/
  60. .. _`Wikipedia article about AMQP`: https://en.wikipedia.org/wiki/AMQP
  61. .. _`carrot`: https://pypi.org/project/carrot/
  62. .. _`librabbitmq`: https://pypi.org/project/librabbitmq/
  63. .. _`Pyro`: https://pyro4.readthedocs.io/
  64. .. _`SoftLayer MQ`: https://sldn.softlayer.com/reference/messagequeueapi
  65. .. _transport-comparison:
  66. Transport Comparison
  67. ====================
  68. +---------------+----------+------------+------------+---------------+--------------+-----------------------+
  69. | **Client** | **Type** | **Direct** | **Topic** | **Fanout** | **Priority** | **TTL** |
  70. +---------------+----------+------------+------------+---------------+--------------+-----------------------+
  71. | *amqp* | Native | Yes | Yes | Yes | Yes [#f3]_ | Yes [#f4]_ |
  72. +---------------+----------+------------+------------+---------------+--------------+-----------------------+
  73. | *qpid* | Native | Yes | Yes | Yes | No | No |
  74. +---------------+----------+------------+------------+---------------+--------------+-----------------------+
  75. | *redis* | Virtual | Yes | Yes | Yes (PUB/SUB) | Yes | No |
  76. +---------------+----------+------------+------------+---------------+--------------+-----------------------+
  77. | *mongodb* | Virtual | Yes | Yes | Yes | Yes | Yes |
  78. +---------------+----------+------------+------------+---------------+--------------+-----------------------+
  79. | *SQS* | Virtual | Yes | Yes [#f1]_ | Yes [#f2]_ | No | No |
  80. +---------------+----------+------------+------------+---------------+--------------+-----------------------+
  81. | *zookeeper* | Virtual | Yes | Yes [#f1]_ | No | Yes | No |
  82. +---------------+----------+------------+------------+---------------+--------------+-----------------------+
  83. | *in-memory* | Virtual | Yes | Yes [#f1]_ | No | No | No |
  84. +---------------+----------+------------+------------+---------------+--------------+-----------------------+
  85. | *SLMQ* | Virtual | Yes | Yes [#f1]_ | No | No | No |
  86. +---------------+----------+------------+------------+---------------+--------------+-----------------------+
  87. | *Pyro* | Virtual | Yes | Yes [#f1]_ | No | No | No |
  88. +---------------+----------+------------+------------+---------------+--------------+-----------------------+
  89. .. [#f1] Declarations only kept in memory, so exchanges/queues
  90. must be declared by all clients that needs them.
  91. .. [#f2] Fanout supported via storing routing tables in SimpleDB.
  92. Disabled by default, but can be enabled by using the
  93. ``supports_fanout`` transport option.
  94. .. [#f3] AMQP Message priority support depends on broker implementation.
  95. .. [#f4] AMQP Message/Queue TTL support depends on broker implementation.
  96. Documentation
  97. -------------
  98. Kombu is using Sphinx, and the latest documentation can be found here:
  99. https://kombu.readthedocs.io/
  100. Quick overview
  101. --------------
  102. .. code:: python
  103. from kombu import Connection, Exchange, Queue
  104. media_exchange = Exchange('media', 'direct', durable=True)
  105. video_queue = Queue('video', exchange=media_exchange, routing_key='video')
  106. def process_media(body, message):
  107. print body
  108. message.ack()
  109. # connections
  110. with Connection('amqp://guest:guest@localhost//') as conn:
  111. # produce
  112. producer = conn.Producer(serializer='json')
  113. producer.publish({'name': '/tmp/lolcat1.avi', 'size': 1301013},
  114. exchange=media_exchange, routing_key='video',
  115. declare=[video_queue])
  116. # the declare above, makes sure the video queue is declared
  117. # so that the messages can be delivered.
  118. # It's a best practice in Kombu to have both publishers and
  119. # consumers declare the queue. You can also declare the
  120. # queue manually using:
  121. # video_queue(conn).declare()
  122. # consume
  123. with conn.Consumer(video_queue, callbacks=[process_media]) as consumer:
  124. # Process messages and handle events on all channels
  125. while True:
  126. conn.drain_events()
  127. # Consume from several queues on the same channel:
  128. video_queue = Queue('video', exchange=media_exchange, key='video')
  129. image_queue = Queue('image', exchange=media_exchange, key='image')
  130. with connection.Consumer([video_queue, image_queue],
  131. callbacks=[process_media]) as consumer:
  132. while True:
  133. connection.drain_events()
  134. Or handle channels manually:
  135. .. code:: python
  136. with connection.channel() as channel:
  137. producer = Producer(channel, ...)
  138. consumer = Producer(channel)
  139. All objects can be used outside of with statements too,
  140. just remember to close the objects after use:
  141. .. code:: python
  142. from kombu import Connection, Consumer, Producer
  143. connection = Connection()
  144. # ...
  145. connection.release()
  146. consumer = Consumer(channel_or_connection, ...)
  147. consumer.register_callback(my_callback)
  148. consumer.consume()
  149. # ....
  150. consumer.cancel()
  151. `Exchange` and `Queue` are simply declarations that can be pickled
  152. and used in configuration files etc.
  153. They also support operations, but to do so they need to be bound
  154. to a channel.
  155. Binding exchanges and queues to a connection will make it use
  156. that connections default channel.
  157. ::
  158. >>> exchange = Exchange('tasks', 'direct')
  159. >>> connection = Connection()
  160. >>> bound_exchange = exchange(connection)
  161. >>> bound_exchange.delete()
  162. # the original exchange is not affected, and stays unbound.
  163. >>> exchange.delete()
  164. raise NotBoundError: Can't call delete on Exchange not bound to
  165. a channel.
  166. Terminology
  167. ===========
  168. There are some concepts you should be familiar with before starting:
  169. * Producers
  170. Producers sends messages to an exchange.
  171. * Exchanges
  172. Messages are sent to exchanges. Exchanges are named and can be
  173. configured to use one of several routing algorithms. The exchange
  174. routes the messages to consumers by matching the routing key in the
  175. message with the routing key the consumer provides when binding to
  176. the exchange.
  177. * Consumers
  178. Consumers declares a queue, binds it to a exchange and receives
  179. messages from it.
  180. * Queues
  181. Queues receive messages sent to exchanges. The queues are declared
  182. by consumers.
  183. * Routing keys
  184. Every message has a routing key. The interpretation of the routing
  185. key depends on the exchange type. There are four default exchange
  186. types defined by the AMQP standard, and vendors can define custom
  187. types (so see your vendors manual for details).
  188. These are the default exchange types defined by AMQP/0.8:
  189. * Direct exchange
  190. Matches if the routing key property of the message and
  191. the `routing_key` attribute of the consumer are identical.
  192. * Fan-out exchange
  193. Always matches, even if the binding does not have a routing
  194. key.
  195. * Topic exchange
  196. Matches the routing key property of the message by a primitive
  197. pattern matching scheme. The message routing key then consists
  198. of words separated by dots (`"."`, like domain names), and
  199. two special characters are available; star (`"*"`) and hash
  200. (`"#"`). The star matches any word, and the hash matches
  201. zero or more words. For example `"*.stock.#"` matches the
  202. routing keys `"usd.stock"` and `"eur.stock.db"` but not
  203. `"stock.nasdaq"`.
  204. Installation
  205. ============
  206. You can install `Kombu` either via the Python Package Index (PyPI)
  207. or from source.
  208. To install using `pip`,:
  209. ::
  210. $ pip install kombu
  211. To install using `easy_install`,:
  212. ::
  213. $ easy_install kombu
  214. If you have downloaded a source tarball you can install it
  215. by doing the following,:
  216. ::
  217. $ python setup.py build
  218. # python setup.py install # as root
  219. Getting Help
  220. ============
  221. Mailing list
  222. ------------
  223. Join the `celery-users`_ mailing list.
  224. .. _`celery-users`: https://groups.google.com/group/celery-users/
  225. Bug tracker
  226. ===========
  227. If you have any suggestions, bug reports or annoyances please report them
  228. to our issue tracker at https://github.com/celery/kombu/issues/
  229. Contributing
  230. ============
  231. Development of `Kombu` happens at Github: https://github.com/celery/kombu
  232. You are highly encouraged to participate in the development. If you don't
  233. like Github (for some reason) you're welcome to send regular patches.
  234. License
  235. =======
  236. This software is licensed under the `New BSD License`. See the `LICENSE`
  237. file in the top distribution directory for the full license text.
  238. .. |build-status| image:: https://secure.travis-ci.org/celery/kombu.png?branch=master
  239. :alt: Build status
  240. :target: https://travis-ci.org/celery/kombu
  241. .. |coverage| image:: https://codecov.io/github/celery/kombu/coverage.svg?branch=master
  242. :target: https://codecov.io/github/celery/kombu?branch=master
  243. .. |license| image:: https://img.shields.io/pypi/l/kombu.svg
  244. :alt: BSD License
  245. :target: https://opensource.org/licenses/BSD-3-Clause
  246. .. |wheel| image:: https://img.shields.io/pypi/wheel/kombu.svg
  247. :alt: Kombu can be installed via wheel
  248. :target: https://pypi.org/project/kombu/
  249. .. |pyversion| image:: https://img.shields.io/pypi/pyversions/kombu.svg
  250. :alt: Supported Python versions.
  251. :target: https://pypi.org/project/kombu/
  252. .. |pyimp| image:: https://img.shields.io/pypi/implementation/kombu.svg
  253. :alt: Support Python implementations.
  254. :target: https://pypi.org/project/kombu/
  255. --
  256. Keywords: messaging message amqp rabbitmq redis actor producer consumer
  257. Platform: any
  258. Classifier: Development Status :: 5 - Production/Stable
  259. Classifier: License :: OSI Approved :: BSD License
  260. Classifier: Operating System :: OS Independent
  261. Classifier: Programming Language :: Python
  262. Classifier: Programming Language :: Python :: 3
  263. Classifier: Programming Language :: Python :: 3.4
  264. Classifier: Programming Language :: Python :: 3.5
  265. Classifier: Programming Language :: Python :: 3.6
  266. Classifier: Programming Language :: Python :: 3.7
  267. Classifier: Programming Language :: Python :: 2.7
  268. Classifier: Programming Language :: Python :: 2
  269. Classifier: Programming Language :: Python :: Implementation :: CPython
  270. Classifier: Programming Language :: Python :: Implementation :: PyPy
  271. Classifier: Intended Audience :: Developers
  272. Classifier: Topic :: Communications
  273. Classifier: Topic :: System :: Distributed Computing
  274. Classifier: Topic :: System :: Networking
  275. Classifier: Topic :: Software Development :: Libraries :: Python Modules
  276. Requires-Python: >=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*
  277. Provides-Extra: redis
  278. Provides-Extra: yaml
  279. Provides-Extra: azureservicebus
  280. Provides-Extra: azurestoragequeues
  281. Provides-Extra: qpid
  282. Provides-Extra: consul
  283. Provides-Extra: slmq
  284. Provides-Extra: pyro
  285. Provides-Extra: mongodb
  286. Provides-Extra: sqlalchemy
  287. Provides-Extra: zookeeper
  288. Provides-Extra: sqs
  289. Provides-Extra: msgpack
  290. Provides-Extra: librabbitmq