Setup Modules

There are two setup modules for pubsub; only one can be imported in an application.

pubsub.setupkwargs

Setup pubsub for the kwargs message protocol. In a default installation this is the default protocol so this module is only needed if setupkargs utility functions are used, or in a custom installation where kwargs is not the default messaging protocol (such as in some versions of wxPython).

This module must be imported before the first from pubsub import pub statement in the application. Once :mod:pub has been imported, the messaging protocol cannot be changed (i.e., importing it after the first from pubsub import pub statement has undefined behavior).

The kwargs protocol is defined as follows:

• the sender provides message data via keyword (i.e. named) arguments. The keywords must be the same for all messages of the same topic.
• the listener must be callable as listener(*req_data, **opt_data): the parameter names must be the same for all listeners of a topic, and must be the same as the message data items.

Example:

from pubsub import pub

def listener1(msg):
    assert msg == 'hi'

def listener(r1, o1=None):
    assert r1 == 123
    assert o1 is None

pub.subscribe(listener1, 'someTopic_1')
pub.subscribe(listener2, 'someTopic_2')

pub.sendMessage('someTopic_1', msg='hi')
pub.sendMessage('someTopic_2', r1=123) # ok: o1 optional

pubsub.setupkwargs.transitionFromArg1(commonName)

Utility function to assist migrating an application from using the arg1 messaging protocol to using the kwargs protocol. Call this after having run and debugged your application with setuparg1.enforceArgName(commonName). See the migration docs for more detais.

pubsub.setuparg1

Setup pubsub for the arg1 message protocol. In a default pubsub installation the default protocol is kargs.

This module must be imported before the first from pubsub import pub statement in the application. Once :mod:pub has been imported, the messaging protocol must not be changed (i.e., importing it after the first from pubsub import pub statement has undefined behavior).

from .. import setuparg1
from .. import pub

The arg1 protocol is identical to the legacy messaging protocol from first version of pubsub (when it was still part of wxPython) and is deprecated. This module is therefore deprecated.

The arg1 protocol is defined as follows:

• the sender only provides one data, or nothing. This one data can be any object: a string, a tuple, a dictionary, etc.
• the listener must be callable as listener(message): the message.data is the data given by the sender. The message contains other information such as topic.

An important consequence of the freedom of this protocol is that the same listener can subscribe to any topic; it is the listener’s responsibility to determine what data is packaged in message.data and use properly.

Example:

from pubsub import setuparg1
from pubsub import pub

def listener1(msg):
    assert msg.data == 'hi'

def listener2(msg):
    assert msg.data['r1'] == 123

pub.subscribe(listener1, 'someTopic')
pub.subscribe(listener2, 'someTopic') # same topic ok despite differing message data

pub.sendMessage('someTopic', 'hi')

data = {'r1':123, ...} # replace ... with whatever you want
pub.sendMessage('someTopic', data)

pubsub.setuparg1.enforceArgName(commonName)

This will configure pubsub to require that all listeners use the same argument name (commonName) as first parameter. This is a ueful first step in migrating an application that has been using arg1 protocol to the more powerful kwargs protocol.