======== stomp.py

.. image:: https://badge.fury.io/py/stomp.py.svg :target: https://badge.fury.io/py/stomp.py :alt: PyPI version

"stomp.py" is a Python client library for accessing messaging servers (such as ActiveMQ_, Artemis_ or RabbitMQ_) using the STOMP_ protocol (STOMP v1.0, STOMP v1.1 and STOMP v1.2). It can also be run as a standalone, command-line client for testing. NOTE: Stomp.py has officially ended support for Python2.x. See python3statement.org for more information.

.. contents:: \ :depth: 1

Quick Start

You can connect to a message broker running on the local machine, and send a message using the following example.

.. code-block:: python

import stomp

conn = stomp.Connection() conn.connect('admin', 'password', wait=True) conn.send(body=' '.join(sys.argv[1:]), destination='/queue/test') conn.disconnect()

Documentation and Resources

• Main documentation_
• API documentation_ (see stomp.github.io_ for details on the STOMP protocol itself)
• A basic example of using stomp.py with a message listener can be found in the quick start_ section of the main documentation
• Description of the command-line interface_
• Travis_ for continuous integration builds
• Current test coverage report_
• PyPi stomp.py page_

The current version of stomp.py supports:

• Python 3.x (Python2 support ended as of Jan 2020)
• STOMP version 1.0, 1.1 and 1.2

There is also legacy 3.1.7 version using the old 3-series code (see 3.1.7 on PyPi_ and 3.1.7 on GitHub_). This is no longer supported, but (at least as of 2018) there were still a couple of reports of this version still being used in the wild.

Note: stomp.py now follows semantic versioning_:

• MAJOR version for incompatible API changes,
• MINOR version for functionality added in a backwards compatible manner, and
• PATCH version for backwards compatible bug fixes.

Testing

stomp.py has been perfunctorily tested on:

• Pivotal RabbitMQ_ (test_rabbitmq.py <https://github.com/jasonrbriggs/stomp.py/blob/dev/tests/test_rabbitmq.py>_)
• Apache ActiveMQ_ (test_activemq.py <https://github.com/jasonrbriggs/stomp.py/blob/dev/tests/test_activemq.py>_)
• Apache ActiveMQ Artemis_ (test_artemis.py <https://github.com/jasonrbriggs/stomp.py/blob/dev/tests/test_artemis.py>_)
• stompserver_ (test_stompserver.py <https://github.com/jasonrbriggs/stomp.py/blob/dev/tests/test_stompserver.py>_)

For testing locally, you'll need to install docker (or podman_). Once installed:

#. Install dependencies: poetry install #. Create the docker (or podman) image: make docker-image (or make podman-image) #. Run the container: make run-docker (or make run-podman) #. Run stomp.py unit tests: make test #. Cleanup the container afterwards if you don't need it any more: make remove-docker (or make remove-podman)

If you want to connect to the test services locally (other than from the included tests), you'll want to add test domain names to your hosts file like so: | 172.17.0.2 my.example.com | 172.17.0.2 my.example.org | 172.17.0.2 my.example.net

If you're using podman_ and you want to access services via their private IP addresses, you'll want to run your commands with::

podman unshare --rootless-netns

so that has access to the private container network. Service ports are also exposed to the host and can be accessed directly.

.. _STOMP: http://stomp.github.io .. _STOMP v1.0: http://stomp.github.io/stomp-specification-1.0.html .. _STOMP v1.1: http://stomp.github.io/stomp-specification-1.1.html .. _STOMP v1.2: http://stomp.github.io/stomp-specification-1.2.html .. _python3statement.org: http://python3statement.org/

.. _Main documentation: http://jasonrbriggs.github.io/stomp.py/index.html .. _stomp.github.io: http://stomp.github.io/ .. _quick start: http://jasonrbriggs.github.io/stomp.py/quickstart.html .. _command-line interface: http://jasonrbriggs.github.io/stomp.py/commandline.html .. _PyPi stomp.py page: https://pypi.org/project/stomp.py/ .. _API documentation: http://jasonrbriggs.github.io/stomp.py/api.html .. _test coverage report: http://jasonrbriggs.github.io/stomp.py/htmlcov/ .. _Travis: https://travis-ci.org/jasonrbriggs/stomp.py

.. _3.1.7 on PyPi: https://pypi.org/project/stomp.py/3.1.7/ .. _3.1.7 on GitHub: https://github.com/jasonrbriggs/stomp.py/tree/stomppy-3series

.. _ActiveMQ: http://activemq.apache.org/ .. _Artemis: https://activemq.apache.org/components/artemis/ .. _RabbitMQ: http://www.rabbitmq.com .. _stompserver: http://stompserver.rubyforge.org

.. _semantic versioning: https://semver.org/

.. _podman: https://podman.io/