News

• December 2025: pypubsub 4.0.7 released! (update to latest packaging system, testing, docs).
• ... (has it really been this long since I cleaned this up?!)...
• January 2019: pypubsub 4.0.3 released! (for those -- and only those -- who use Python >= 3).
• March 2019: pypubsub 3.4.2 released (for those -- and only those -- who use Python 2.7.x).

Overview

Provides a publish-subscribe API to facilitate event-based or message-based architecture in a single-process application. It is pure Python and works on Python 3.7+ (tested through 3.14). It is centered on the notion of a topic; senders publish messages of a given topic, and listeners subscribe to messages of a given topic, all inside the same process. The package also supports a variety of advanced features that facilitate debugging and maintaining topics and messages in larger desktop- or server-based applications.

Install most recent stable with "pip install pypubsub".

Useful links:

• Project on PyPI: https://pypi.python.org/pypi/PyPubSub
• The documentation for latest stable release is at http://pypubsub.readthedocs.io.
• The documentation for latest code is at http://pypubsub.readthedocs.io/en/latest.

Contributing and testing

Install uv, then run the test matrix with tox (uses tox-uv under the hood):

uv tool install tox --with tox-uv
tox  # or: tox -e py312

Package build verification is available via tox -e pkg (runs python -m build and twine check).

Python 3.7 note: uv does not auto-provide CPython 3.7. tox -e py37 will skip locally if 3.7 isn’t available; it is exercised in GitHub CI.

Local development install

Create a virtual environment and install in editable mode:

uv venv .venv && source .venv/bin/activate
uv pip install -e .

Then you can open a Python shell (python) and import pubsub, or run examples such as:

python examples/advanced/advanced_main.py
python examples/basic_kwargs/console_main.py

To run a small example suite, use the helper script (assumes your venv is active):

bash examples/runall.sh  # uses 'python' from your venv

Versioning and tags

Versions come from git tags via setuptools_scm. To see the last tagged release:

git describe --tags --abbrev=0

To create a new tag, pick your next version (e.g. v4.0.7) and tag the current commit:

git tag v4.0.7
git push origin v4.0.7

There is also a helper script with subcommands for tagging/pushing:

python release.py get-latest            # show latest vX.Y.Z tag (or v0.0.0)
python release.py init-tag v4.0.7       # create a specific tag
python release.py bump-local [patch]    # create a local tag (major/minor/patch; default patch)
python release.py push-tag              # push latest tag (prompts/warns about PyPI release)

Warning: pushing a v* tag triggers the GitHub Actions release workflow, which builds and uploads to PyPI using the configured token.

CI will build and publish from that tag (using the tag version; no manual bump needed).

wxPython on Ubuntu 22+

If you want to run the wx examples, install wxPython and SDL2 runtime in your venv on Ubuntu 22.x+:

pip install --upgrade pip setuptools wheel
pip install --only-binary=:all: -f https://extras.wxpython.org/wxPython4/extras/linux/gtk3/ubuntu-22.04 wxPython==4.2.4
sudo apt-get install libsdl2-2.0-0  # runtime for the wheel

If the wheel is not found for your distro/Python combo, you’ll need GTK3/SDL build deps to compile from source instead.

Docs

Install deps into a local venv and build:

pip install -r docs/requirements.txt
make docs          # builds docs/_build/html
make clean-docs    # removes docs/_build

Helpers:

• make venv sets up a local venv at .venv (uses system python).
• make clean-venv removes that venv.
• make add-wxpy-ubuntu installs wxPython 4.2.4 wheel + SDL2 runtime on Ubuntu (requires sudo). Useful for running wx examples in that venv.
• Release helpers can be run via Makefile wrappers, e.g. make init-tag TAG=v4.0.7 or make bump-local BUMP=patch.

Release helpers can be run via the Makefile wrappers, e.g. make init-tag TAG=v4.0.7 or make bump-local BUMP=patch.