API Documentation

Warning

This documentation is in the process of being updated. You may find it more useful to refer to the source code doc strings and the examples in the examples folder of the source distribution.

API Versions

There are two supported APIs available in pubsub: the “argspec” API, and a legacy API named “version 1” or v1 for short.

Legacy API

The legacy API was developed as part of wxPython, where pubsub originated. This API is available in pubsub to support wxPython applications based on this API. This distinguishing characteristic of this API is that all data to be sent in a message must fit in one parameter and pubsub does not verify whether the data expected by a listener is present in the message. Note that this API is deprecated!! Only use it if you have no choice.

This API is documented only in Legacy (v1) API.

Argspec API

The Argument Specification (“argspec” for short) API was developed for use in larger applications, where the legacy API was found to provide inadequate support for message validation, debugging and topic documentation, all important considerations in larger projects. The distinguishing characteristics of the argspec API is that the message data can be composite and is controlled by pubsub (via implicit or explicit specification)

The above means that an application written in the legacy API will require a small amount of tweaking, mostly because of the different message sending and receiving syntax.

Note

Except where specifically indicated, the API documentation on this site pertains to the argspec API. A separate section, Legacy (v1) API, documents the v1 API of pubsub.

Installation Types

When installing pubsub as a standalone package in your Python “site packages”, the API available by default will be the Argspec API. In this case, the legacy API can be used only by importing pubsub.setupv1 module before the first ‘from pubsub import pub’ statement. This only needs to be done once for an application.

When using the pubsub package that is installed as part of wxPython (‘from wx.lib.pubsub import ...’), the API provided is the legacy API.

Transition legacy to Argspec API

If you wish to transition an appication from using the legacy v1 API to using the Argspec API, take a look at the Migrations page.

Argspec API Documentation

The User Manual consists of the following sections.

• Examples
  • Hello World
  • More Examples
• Pubsub Package
  • Essential Functionality
  • Extra Functionality
  • Modules and sub-packages
• Chaotic Mess
  • Listener
  • Topic
  • Topic Message Data
  • Message Data Specification (MDS)
  • Sending vs Broadcasting
  • Types of errors
  • Architecture and Design Guidelines
  • Example Development Process
  • Topic Tree Specification
  • Topic Definition Providers
  • Notification
  • Exception Handling
  • Multi-threading
  • Multi-processing
  • Utilities
  • Miscellaneous

Status

Pubsub’s public API is provided via its ‘pub’ and ‘utils’ modules. The following part of this API is unlikely to change:

Messaging, basic:

• pub.sendMessage
• pub.subscribe
• pub.ALL_TOPICS
• pub.AUTO_TOPIC

Topic specification:

• pub.addTopicDefnProvider
• pub.clearTopicDefnProviders
• pub.setTopicUnspecifiedFatal

Notification handling:

• utils.useNotifyByWriteFile
• utils.printTreeDocs
• pub.addNotificationHandler
• pub.clearNotificationHandlers

Listener Exception handling:

• pub.getListenerExcHandler
• pub.setListenerExcHandler
• pub.ExcHandlerError

Exceptions:

• pub.ListenerInadequate
• pub.ListenerNotValidatable
• pub.ListenerSpecIncomplete
• pub.ListenerSpecInvalid
• pub.SenderMissingReqdArgs
• pub.SenderUnknownOptArgs
• pub.UndefinedSubtopic
• pub.UndefinedTopic

Messaging, advanced:

• pub.getAssociatedTopics
• pub.getDefaultPublisher
• pub.getDefaultTopicMgr
• pub.getListenerID
• pub.getTopic
• pub.isSubscribed
• pub.isValid
• pub.Listener
• pub.Publisher
• pub.Topic
• pub.topics
• pub.topicsMap
• pub.unsubAll
• pub.unsubscribe
• pub.validate

Versioning:

• pub.SVN_VERSION
• pub.VERSION_STR
• pub.PUBSUB_VERSION

The following, related to Topic Specification, are likely to evolve:

• pub.TOPIC_TREE_FROM_CLASS
• pub.TOPIC_TREE_FROM_MODULE
• pub.TOPIC_TREE_FROM_STRING
• pub.exportTopicTree
• pub.importTopicTree
• pub.ITopicDefnProvider
• pub.ITopicTreeTraverser
• pub.registerTopicDefnProviderType
• pub.TopicDefnProvider

Legacy API Documentation

See Legacy (v1) API.