README.rst 5.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130
  1. =====================================================================
  2. Python AMQP 0.9.1 client library
  3. =====================================================================
  4. |build-status| |coverage| |license| |wheel| |pyversion| |pyimp|
  5. :Version: 2.4.1
  6. :Web: https://amqp.readthedocs.io/
  7. :Download: https://pypi.org/project/amqp/
  8. :Source: http://github.com/celery/py-amqp/
  9. :Keywords: amqp, rabbitmq
  10. About
  11. =====
  12. This is a fork of amqplib_ which was originally written by Barry Pederson.
  13. It is maintained by the Celery_ project, and used by `kombu`_ as a pure python
  14. alternative when `librabbitmq`_ is not available.
  15. This library should be API compatible with `librabbitmq`_.
  16. .. _amqplib: https://pypi.org/project/amqplib/
  17. .. _Celery: http://celeryproject.org/
  18. .. _kombu: https://kombu.readthedocs.io/
  19. .. _librabbitmq: https://pypi.org/project/librabbitmq/
  20. Differences from `amqplib`_
  21. ===========================
  22. - Supports draining events from multiple channels (``Connection.drain_events``)
  23. - Support for timeouts
  24. - Channels are restored after channel error, instead of having to close the
  25. connection.
  26. - Support for heartbeats
  27. - ``Connection.heartbeat_tick(rate=2)`` must called at regular intervals
  28. (half of the heartbeat value if rate is 2).
  29. - Or some other scheme by using ``Connection.send_heartbeat``.
  30. - Supports RabbitMQ extensions:
  31. - Consumer Cancel Notifications
  32. - by default a cancel results in ``ChannelError`` being raised
  33. - but not if a ``on_cancel`` callback is passed to ``basic_consume``.
  34. - Publisher confirms
  35. - ``Channel.confirm_select()`` enables publisher confirms.
  36. - ``Channel.events['basic_ack'].append(my_callback)`` adds a callback
  37. to be called when a message is confirmed. This callback is then
  38. called with the signature ``(delivery_tag, multiple)``.
  39. - Exchange-to-exchange bindings: ``exchange_bind`` / ``exchange_unbind``.
  40. - ``Channel.confirm_select()`` enables publisher confirms.
  41. - ``Channel.events['basic_ack'].append(my_callback)`` adds a callback
  42. to be called when a message is confirmed. This callback is then
  43. called with the signature ``(delivery_tag, multiple)``.
  44. - Authentication Failure Notifications
  45. Instead of just closing the connection abruptly on invalid
  46. credentials, py-amqp will raise an ``AccessRefused`` error
  47. when connected to rabbitmq-server 3.2.0 or greater.
  48. - Support for ``basic_return``
  49. - Uses AMQP 0-9-1 instead of 0-8.
  50. - ``Channel.access_request`` and ``ticket`` arguments to methods
  51. **removed**.
  52. - Supports the ``arguments`` argument to ``basic_consume``.
  53. - ``internal`` argument to ``exchange_declare`` removed.
  54. - ``auto_delete`` argument to ``exchange_declare`` deprecated
  55. - ``insist`` argument to ``Connection`` removed.
  56. - ``Channel.alerts`` has been removed.
  57. - Support for ``Channel.basic_recover_async``.
  58. - ``Channel.basic_recover`` deprecated.
  59. - Exceptions renamed to have idiomatic names:
  60. - ``AMQPException`` -> ``AMQPError``
  61. - ``AMQPConnectionException`` -> ConnectionError``
  62. - ``AMQPChannelException`` -> ChannelError``
  63. - ``Connection.known_hosts`` removed.
  64. - ``Connection`` no longer supports redirects.
  65. - ``exchange`` argument to ``queue_bind`` can now be empty
  66. to use the "default exchange".
  67. - Adds ``Connection.is_alive`` that tries to detect
  68. whether the connection can still be used.
  69. - Adds ``Connection.connection_errors`` and ``.channel_errors``,
  70. a list of recoverable errors.
  71. - Exposes the underlying socket as ``Connection.sock``.
  72. - Adds ``Channel.no_ack_consumers`` to keep track of consumer tags
  73. that set the no_ack flag.
  74. - Slightly better at error recovery
  75. Further
  76. =======
  77. - Differences between AMQP 0.8 and 0.9.1
  78. http://www.rabbitmq.com/amqp-0-8-to-0-9-1.html
  79. - AMQP 0.9.1 Quick Reference
  80. http://www.rabbitmq.com/amqp-0-9-1-quickref.html
  81. - RabbitMQ Extensions
  82. http://www.rabbitmq.com/extensions.html
  83. - For more information about AMQP, visit
  84. http://www.amqp.org
  85. - For other Python client libraries see:
  86. http://www.rabbitmq.com/devtools.html#python-dev
  87. .. |build-status| image:: https://secure.travis-ci.org/celery/py-amqp.png?branch=master
  88. :alt: Build status
  89. :target: https://travis-ci.org/celery/py-amqp
  90. .. |coverage| image:: https://codecov.io/github/celery/py-amqp/coverage.svg?branch=master
  91. :target: https://codecov.io/github/celery/py-amqp?branch=master
  92. .. |license| image:: https://img.shields.io/pypi/l/amqp.svg
  93. :alt: BSD License
  94. :target: https://opensource.org/licenses/BSD-3-Clause
  95. .. |wheel| image:: https://img.shields.io/pypi/wheel/amqp.svg
  96. :alt: Python AMQP can be installed via wheel
  97. :target: https://pypi.org/project/amqp/
  98. .. |pyversion| image:: https://img.shields.io/pypi/pyversions/amqp.svg
  99. :alt: Supported Python versions.
  100. :target: https://pypi.org/project/amqp/
  101. .. |pyimp| image:: https://img.shields.io/pypi/implementation/amqp.svg
  102. :alt: Support Python implementations.
  103. :target: https://pypi.org/project/amqp/