Table Of Contents

Previous topic


Next topic

Utils module

This Page

Pub Module

This is the main entry-point to pubsub’s core functionality. The pub module supports:

  • messaging: publishing and receiving messages of a given topic
  • tracing: tracing pubsub activity in an application
  • trapping exceptions: dealing with “badly behaved” listeners (ie that leak exceptions)
  • specificatio of topic tree: defining (or just documenting) the topic tree of an application; message data specification (MDS)

The recommended usage is

from pubsub import pub

// use pub functions:

Note that this module creates a “default” instance of pubsub.core.Publisher and binds several local functions to some of its methods and those of the pubsub.core.TopicManager instance that it contains. However, an application may create as many independent instances of Publisher as required (for instance, one in each thread; with a custom queue to mediate message transfer between threads). = 3

major API version

The pubsub API version. The only valid value currently is the integer 3. Previously, versions 1 and 2 API could also be activated in pubsub before importing pub, in which case pub.VERSION_API had the corresponding value.

Sending Messages

Sending messages is achieved via the following function:, **kwargs)

Send a message.

  • topicName – name of message topic (dotted or tuple format)
  • kwargs – message data (must satisfy the topic’s MDS)

The following exception may be raised when sending a message, if the message data does not comply with the Message Data Specification for the topic:

exception, argNames, missing)

Bases: exceptions.RuntimeError

Raised when a sendMessage() is missing arguments tagged as ‘required’ by pubsub topic of message.

exception, argNames, extra)

Bases: exceptions.RuntimeError

Raised when a sendMessage() has arguments not listed among the topic’s message data specification (MDS).

Advanced use:

The following would typically only be useful in special circumstances, such as if pubsub’s default Publisher must be accessed, on or more separate instances of Publisher is required, and so forth.

Get the Publisher instance created by default when this module is imported. See the module doc for details about this instance.
class pubsub.core.Publisher(treeConfig=None)

Publisher used for kwargs protocol, ie when sending message data via keyword arguments.

See pubsub.core.Publisher for details.

Receiving Messages

The following functions are available for controlling what callable objects (functions, methods, or class instances with a __call__ method) will get called when messages are generated:, topicName)

Subscribe listener to named topic. Raises ListenerMismatchError if listener isn’t compatible with the topic’s MDS. Returns (pubsub.core.Listener, success), where success is False if listener was already subscribed. The pub.core.Listener wraps the callable subscribed and provides introspection-based info about the callable.

Note that if ‘subscribe’ notification is on, the handler’s ‘notifySubscribe’ method is called after subscription., topicName)

Unsubscribe from given topic. Returns the pubsub.core.Listener instance that was used to wrap listener at subscription time. Raises an TopicNameError if topicName doesn’t exist.

Note that if ‘unsubscribe’ notification is on, the handler’s notifyUnsubscribe() method will be called after unsubscribing., listenerFilter=None, topicFilter=None)

By default (no args given), unsubscribe all listeners from all topics. A listenerFilter can be given so that only the listeners that satisfy listenerFilter(listener) == True will be unsubscribed (with listener being a pub.Listener wrapper instance for each listener subscribed). A topicFilter can also be given so that only topics that satisfy topicFilter(topic name) == True will be affected. If only one topic should have listeners unsubscribed, then a topic name ‘topicName’ can be given instead instead of a topic filter.

Returns the list of all listeners (instances of pub.Listener) that were unsubscribed from the topic tree).

Note: this method will generate one ‘unsubcribe’ notification message (see pub.setNotificationFlags()) for each listener unsubscribed., topicName)

Returns true if listener has subscribed to topicName, false otherwise. WARNING: a false return is not a guarantee that listener won’t get messages of topicName: it could receive messages of a subtopic of topicName.

The following exceptions are relevant:

exception, listener, *args)

Bases: exceptions.ValueError

Raised when an attempt is made to subscribe a listener to a topic, but listener does not satisfy the topic’s message data specification (MDS). This specification is inferred from the first listener subscribed to a topic, or from an imported topic tree specification (see pub.addTopicDefnProvider()).

exception, args)

Bases: exceptions.RuntimeError

Raised when an attempt is made to define a topic’s Message Data Specification (MDS) to something that is not valid.

The keyword names for invalid data go in the ‘args’ list, and the msg should state the problem and contain “%s” for the args, such as MessageDataSpecError(‘duplicate args %s’, (‘arg1’, ‘arg2’)).

Use this as default parameter in a listener’s signature: the listener will be given the Topic object of the message.

The following additional functions may be useful during debugging:, topicName)

Return true only if listener can subscribe to messages of given topic., topicName)

Checks if listener can subscribe to topicName. If not, raises ListenerMismatchError, otherwise just returns.


Bases: exceptions.RuntimeError

Raised when an operation requires a topic have an MDS, but it doesn’t. See also pub.setTopicUnspecifiedFatal().

Advanced use:

The following are not typically required but can be useful in certain circumstances, especially during debugging:

class pubsub.core.Listener(callable_, argsInfo, onDead=None)

Wraps a callable so it can be stored by weak reference and introspected to verify that it adheres to a topic’s MDS.

A Listener instance has the same hash value as the callable that it wraps.

Callables that have ‘argName=pub.AUTO_TOPIC’ as a kwarg will be given the Topic object for the message sent by sendMessage(). Such a Listener will have wantsTopicObjOnCall() True.

Callables that have a ‘**kargs’ argument will receive all message data, not just that for the topic they are subscribed to. Such a listener will have wantsAllMessageData() True.

See pubsub.core.Listener for details.


Get name and module name for a callable, ie function, bound method or callable instance, by inspecting the callable. E.g. getID( returns (‘’, ‘a.b’) if was defined in module a.b.


In most cases, topics are used by name in dotted string format. The following may be useful for basic pubsub use:

exception, msg)

Bases: exceptions.ValueError

Raised when the topic name is not properly formatted or no corresponding Topic object found.

Advanced use:

Some advanced uses of pubsub, especially (but not only) for debugging a pubsub-based application, could require access to the associated Topic instance, topic tree manager, special topic-related constants, or other helper functions and classes.


Supports taking action on every topic in the topic tree. The traverse() method traverses a topic tree and calls visitor._onTopic() for each topic in the tree that satisfies visitor._accept(). Additionally it calls visitor._startChildren() whenever it starts traversing the subtopics of a topic, and visitor._endChildren() when it is done with the subtopics. Finally, it calls visitor._doneTraversal() when traversal has been completed. The visitor must therefore adhere to the ITopicTreeVisitor interface.

Name of topic that is root of topic tree. Subscribe a listener to this topic to get all pubsub messages. Use **kwargs to receive all message data, regardless of topic.

The topic object that is parent of all root topics. The name of this topic is pub.ALL_TOPICS.

The dictionary that maps topic names to Topic objects.

Advanced use:

The following are not typically required but can be useful in certain circumstances, such as during debugging:

Get the TopicManager instance created by default when this module is imported. This function is a shortcut for pub.getDefaultPublisher().getTopicMgr().

class pubsub.core.TopicManager(treeConfig=None)

Manages the registry of all topics and creation/deletion of topics.

Note that any method that accepts a topic name can accept it in the ‘dotted’ format such as 'a.b.c.' or in tuple format such as ('a', 'b', 'c'). Any such method will raise a ValueError if name not valid (empty, invalid characters, etc).

See pubsub.core.TopicManager for details.

class pubsub.core.Topic(treeConfig, nameTuple, description, msgArgsInfo, parent=None)

Represent topics in pubsub. Contains information about a topic, including topic’s message data specification (MDS), the list of subscribed listeners, docstring for the topic. It allows Python-like access to subtopics (e.g. A.B is subtopic B of topic A).

See pubsub.core.Topic for details.

Listener Exception Handling

Listeners that leak exceptions are typically burried deep into the stacktrace, and can cause an application to abort. The following may simplify the task of providing useful error messages from misbehaved listeners, without interrupting the application or even the pubsub send-message:

Get the listener exception handler that was registered via setListenerExcHandler(), or None of none registered.

Set the function to call when a listener raises an exception during a sendMessage(). The handler must adhere to the IListenerExcHandler API.


Interface class base class for any handler given to pub.setListenerExcHandler() Such handler is called whenever a listener raises an exception during a pub.sendMessage(). Example:

from pubsub import pub

class MyHandler(pub.IListenerExcHandler):
    def __call__(self, listenerID, topicObj):
        ... do something with listenerID ...
exception, topicObj, origExc=None)

Bases: exceptions.RuntimeError

Raised when a listener exception handler (see pub.setListenerExcHandler()) raises an exception. The original exception is contained.

See pubsub.utils.exchandling for ready-made exception handlers which may fit your requirements.

Pubsub Tracing (aka Notification)

While debugging an application it may be useful to trap some of pubsub’s activity:


Defines the interface expected by pubsub for pubsub activity notifications. Any instance that supports the same methods, or derives from this class, will work as a notification handler for pubsub events (see pub.addNotificationHandler).

Add a handler for tracing pubsub activity. The handler should be a class that adheres to the API of INotificationHandler.

Remove all notification handlers that were added via self.addNotificationHandler().**kwargs)

Set the notification flags on or off for each type of pubsub activity. The kwargs keys can be any of the following:

  • subscribe: if True, get notified whenever a listener subscribes to a topic;
  • unsubscribe: if True, get notified whenever a listener unsubscribes from a topic;
  • deadListener: if True, get notified whenever a subscribed listener has been garbage-collected;
  • sendMessage: if True, get notified whenever sendMessage() is called;
  • newTopic: if True, get notified whenever a new topic is created;
  • delTopic: if True, get notified whenever a topic is “deleted” from topic tree;
  • all: set all of the above to the given value (True or False).

The kwargs that are None are left at their current value. Those that are False will cause corresponding notification to be silenced. The ‘all’ is set first, then the others. E.g.

mgr.setFlagStates(all=True, delTopic=False)

will toggle all notifications on, but will turn off the ‘delTopic’ notification.

Return a dictionary with the notification flag states.

See pubsub.utils for some ready-made notification handlers which may fit your requirements.

Topic Specification

Topic definition, documentation, and MDS:


Bases: exceptions.RuntimeError

Raised when an operation requires a topic have an MDS, but it doesn’t. See also pub.setTopicUnspecifiedFatal()., rootTopic=None, bak='bak', moduleDoc=None)

Using TopicTreeSpecPrinter, exports the topic tree rooted at rootTopic to a Python module (.py) file. This module will define module-level classes representing root topics, nested classes for subtopics etc. Returns a string representing the contents of the file. Parameters:

  • If moduleName is given, the topic tree is written to in os.getcwd(). By default, it is first backed up, it it already exists, using bak as the filename extension. If bak is None, existing module file gets overwritten.
  • If rootTopic is specified, the export only traverses tree from corresponding topic. Otherwise, complete tree, using pub.getDefaultTopicTreeRoot() as starting point.
  • The moduleDoc is the doc string for the module ie topic tree., checkExisting=True)

Changes the creation policy for topics.

By default, pubsub will accept topic names for topics that don’t have a message data specification (MDS). This default behavior makes pubsub easier to use initially, but allows topic names with typos to go uncaught in common operations such as sendMessage() and subscribe(). In a large application, this can lead to nasty bugs. Pubsub’s default behavior is equivalent to setTopicUnspecifiedFatal(false).

When called with newVal=True, any future pubsub operation that requires a topic (such as subscribe and sendMessage) will require an MDS; if none is available, pubsub will raise a TopicDefnError exception.

If checkExisting is not given or True, all existing topics are validated. A TopicDefnError exception is raised if one is found to be incomplete (has hasMDS() false).

Returns previous value of newVal.

Note that this method can be used in several ways:

  1. Only use it in your application when something is not working as expected: just add a call at the beginning of your app when you have a problem with topic messages not being received (for instance), and remove it when you have fixed the problem.
  2. Use it from the beginning of your app and never use newVal=False: add a call at the beginning of your app and you leave it in (forever), and use Topic Definition Providers to provide the listener specifications. These are easy to use via the pub.addTopicDefnProvider().
  3. Use it as in #1 during app development, and once stable, use #2. This is easiest to do in combination with pub.exportTopicTreeSpec()., format=None)

Register a topic definition provider. After this method is called, whenever a topic must be created, the first definition provider that has a definition for the required topic is used to instantiate the topic.

If providerOrSource is an instance of ITopicDefnProvider, register it as a provider of topic definitions. Otherwise, register a new instance of TopicDefnProvider(providerOrSource, format). In that case, if format is not given, it defaults to TOPIC_TREE_FROM_MODULE. Either way, returns the instance of ITopicDefnProvider registered.

Get how many topic definitions providers are registered.

Remove all registered topic definition providers

Loop over all topics of given provider and “instantiate” each topic, thus forcing a parse of the topics documentation, message data specification (MDS), comparison with parent MDS, and MDS documentation. Without this function call, an error among any of those characteristics will manifest only if the a listener is registered on it.


Bases: exceptions.ValueError

Raised when a topic definition provider doesn’t recognize the format of source input it was given. = 'module'

str(object=’‘) -> string

Return a nice string representation of the object. If the argument is a string, the return value is the same object.

Provide to pub.addTopicDefnProvider() as value for format parameter when the source is a module which has been imported. The module can contain any number of classes, the names of which correspond to root topics. = 'class'

str(object=’‘) -> string

Return a nice string representation of the object. If the argument is a string, the return value is the same object.

Provide to pub.addTopicDefnProvider() as value for format parameter when the source is a class. The class contains, as nested classes, the root topics (and those contain nested classes for subtopics, etc). = 'string'

str(object=’‘) -> string

Return a nice string representation of the object. If the argument is a string, the return value is the same object.

Provide to pub.addTopicDefnProvider() as value for format parameter when the source is a string. The string contains Python code that defines one class for each root topic (and those contain nested classes for subtopics, etc).


The following are useful to extend the capabilities of pubsub to support more topic definition providers or serialization formats for the builtin provider:

class pubsub.core.ITopicDefnProvider

All topic definition providers added via pub.addTopicDefnProvider() must have this interface. Derived classes must override the getDefn(), getTreeDoc() and topicNames() methods.

class pubsub.core.ITopicDefnDeserializer

Interface class for all topic definition de-serializers that can be accepted by TopicDefnProvider. A deserializer creates a topic tree from something such as file, module, or string.

class pubsub.core.TopicDefnProvider(source, format, **providerKwargs)

Bases: pubsub.core.topicdefnprovider.ITopicDefnProvider

Default implementation of the ITopicDefnProvider API. This implementation accepts several formats for the topic tree source data and delegates to a registered ITopicDefnDeserializer that converts source data into topic definitions.

This provider is instantiated automatically by pub.addTopicDefnProvider(source, format) when source is not an ITopicDefnProvider.

Additional de-serializers can be registered via registerTypeForImport().