Pubsub Package

The publish-subscribe package is called pubsub. It provides the following modules:

• pub: pubsub’s main module. It provides, first and foremost, functions for sending messages and subscribing listeners. It provides functions and classes for tracking pubsub usage, handling exceptions in listeners, specificying topics, and various others.
• utils: subpackage of utility functions and classes, it provides basic pubsub usage trackers, exception handlers, topic tree printer, and more. These can also serve as examples of how to create your own trackers/handlers/etc.

A few other modules inside pubsub are specific to configuring the pubsub API and must be used only ONCE in an application:

• setupkwargs: module to setup pubsub to use “kwargs” messaging protocol of the Argspec API. This API and protocol are the default so it is not usually necessary to use setupkwargs.
• setupv1: (deprecated) module to force pubsub to use the legacy “version 1” (aka v1) API. Should only be useful to wxPython users for legacy code.
• setuparg1: module to setup pubsub to use “arg1” messaging protocol of the Argspec API. This supports the same messaging semantics as legacy API but with the Argspec API, useful when transitioning an application from legacy to Argspec API.

The following two sections list tasks supported by pubsub, such as publishing or receiving messages, and link directly to parts of the documentation related to those tasks.

Alternately, the section Modules and sub-packages shows a Reference Table-of-Contents view of the pages describing the modules and associated concepts/principles.

Essential Functionality

Tasks that are essential when using pubsub are:

• Publishing Messages
• Receiving Messages
• Trapping exceptions

They are in the pub module.

Extra Functionality

Many other tasks can be involved in using pubsub to its full potential:

• Tracking pubsub activity in an application via notification, for feedback to user or while debugging
• Recovering from exceptions raised by listeners, for robustness
• Documenting topics, for maintainability
• Specifying topic message data (topic MDS), for robustness and maintainability
• Preventing the creation of topics by mistake (typo)
• Automatically getting the topic name of the message in a listener
• Listen for messages from all topics
• Printing the application’s topic tree
• Getting the ID of a listener
• Find which topics a listener is subscribed
• Determine if a listener is subscribed to a topic
• Stop receiving messages
• Doing something with or to every topic in the topic tree
• Getting version info

Modules and sub-packages

Supported tasks are distributed among several modules modules and packages:

• The pub module
  • Publishing Messages
    • About Topics
      • Message Topics
      • Topic Names
      • Topic MDS: Basics
        • Gradual Lockdown of MDS
      • Topic Hierarchy
      • Topic MDS: Hierarchy
      • Topic Definition Tree and Providers
      • Topics (OLD)
  • Receiving Messages
    • Listeners
      • Receiving Messages
      • Listener lifetime
      • Listener exceptions
      • Automatic parameters
• The utils package
• Various setup* modules
  • Kwargs Messaging Protocol
  • Arg1 Messaging Protocol