PyPubSub

Common errors

• ImportError: No module named 'pubsub'

  cause The PyPubSub library might not be installed, or the import statement is incorrect. The module containing the 'pub' object is named 'pubsub', not 'pypubsub'.
  fix First, ensure the library is installed with `pip install pypubsub`. Then, correct your import statement to `from pubsub import pub`.

• AttributeError: module 'pubsub.pub' has no attribute 'setupArg1'

  cause This error occurs in PyPubSub v4.x when attempting to use the `setupArg1` function, which was part of the deprecated 'arg1' messaging protocol in v3.x and earlier.
  fix Remove the call to `pub.setupArg1()`. Update your listener functions to accept named arguments directly, or use `**kwargs` if you need to capture all published arguments without specific naming.

• TypeError: listener() got an unexpected keyword argument 'extra_key'

  cause A listener function is called with keyword arguments it does not explicitly define, and it does not have a `**kwargs` parameter to catch arbitrary arguments. This is common if migrating from `arg1` protocol or misconfiguring listener signatures.
  fix Modify your listener function signature to include `**kwargs` if it should accept arbitrary arguments, or ensure all arguments passed via `pub.sendMessage()` are explicitly defined in the listener function signature. For example: `def listener(arg1, arg2, extra_key=None):` or `def listener(arg1, arg2, **kwargs):`

Warnings

• breaking PyPubSub v4.0.0 and later drops support for Python 2.x. Users on Python 2.7 must use PyPubSub v3.x or migrate to Python 3.
  Fix: Upgrade your Python environment to 3.7+ and then upgrade PyPubSub to v4.x. If Python 2.7 is strictly required, use `pypubsub==3.4.2`.
• breaking The 'arg1' messaging protocol, which required calling `pub.setupArg1()`, was abandoned in v4.0.0. Listeners must now accept named arguments directly matching those passed to `sendMessage`, or use `**kwargs`.
  Fix: Remove any calls to `pub.setupArg1()`. Update listener function signatures to accept named arguments corresponding to the published message's keywords, or use `**kwargs` for flexibility.
• gotcha Specific older releases (e.g., v3.3.0, v4.0.0, v4.0.3) had known issues when installing from GitHub source distributions directly. Always prioritize installing from PyPI.
  Fix: Always install PyPubSub using `pip install pypubsub` to ensure you get the correctly packaged version from PyPI. Avoid direct installation from GitHub `.zip` or `.tar.gz` archives unless specifically instructed or for development.
• gotcha Version 3.4.2 was specifically released for Python 2.7. There's an explicit warning not to use it for Python 3+. Installing this version on Python 3 will lead to compatibility issues.
  Fix: For Python 3 environments, ensure you install PyPubSub v4.0.0 or later. Use `pip install 'pypubsub>=4.0.0'` or simply `pip install pypubsub` to get the latest compatible version.

Install

• pip install pypubsub Install stable version

Imports

• pub
  wrong:

  from pypubsub import pub

  correct:

  from pubsub import pub

  The main messaging object 'pub' is imported from the 'pubsub' module within the 'pypubsub' package.

Quickstart

This quickstart demonstrates how to subscribe functions to a topic and publish messages. Listeners can accept positional and keyword arguments, matching the arguments passed to `sendMessage`. The `pub` object manages all subscriptions and publications.

from pubsub import pub

def listener_a(arg1, arg2='default'):
    print(f"Listener A received: {arg1=}, {arg2=}")

def listener_b(arg1, **kwargs):
    print(f"Listener B received: {arg1=}, kwargs: {kwargs}")

# Subscribe listeners to a topic
pub.subscribe(listener_a, 'my_topic')
pub.subscribe(listener_b, 'my_topic')

# Publish a message to the topic
pub.sendMessage('my_topic', arg1='hello', arg2='world')
pub.sendMessage('my_topic', arg1='another_message', extra_key=123)

# Unsubscribe a listener
pub.unsubscribe(listener_a, 'my_topic')
pub.sendMessage('my_topic', arg1='after_unsubscribe')