======== 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