Welcome to PyPubSub’s Home Page!

Note

The latest API is v3.3.0, released February 2014

Note

This site was updated for v3.3.0. The home page for the previous release v3.2.0 is at this v3.2 URL. The home page for the release before that, v3.1.2, is at this v3.1 URL.

The Pubsub package provides a publish - subscribe Python API that facilitates event-based programming. Using the publish - subscribe pattern in your application can dramatically simplify its design and improve testability. Robin Dunn, the creator of wxPython where the pubsub package was born, summerizes Pubsub nicely:

Basically you just have some part(s) of your program subscribe to a particular topic and have some other part(s) of your program publish messages with that topic. All the plumbing is taken care of by pubsub. – Robin Dunn, Jun 2007

The Publish - Subscribe pattern, as implemented by pubsub, provides the following contract between sender and receiver:

1. Message Sending: A message can be sent (aka broadcast) from any code that can import pubsub’s pub module
2. Message Topic: a. Every message has a “type”: it corresponds to its “topic”, a string name b. Topics form a hierarchy. A parent topic is more generic than a child topic.
3. Message Handling: All message handlers must register with pubsub in order to receive messages of a given topic
4. Message Delivery:
   1. Messages sent will be delivered to all registered handlders (aka listeners, also receivers) for a given topic
   2. Sequence of delivery is unknown: can change at any time; no logic should depend on it
   3. Messages are delivered synchronously: a handler must return or throw an exception before the message is delivered to the next handler
   4. A message sent will be delivered immediately and control will be returned to the sender only once message has been delivered to all handlers
   5. There is no relationship between order of registration vs order of delivery
   6. Additionally occurs to all listeners of more generic, ie parent topics, up to the root topic which is a “catch all” topic
5. Message Constness: message contents will be left unchanged by any handlers
6. Message Direction: a message is one-way from sender to receiver; it cannot be used by the handler to transmit data back to the sender
7. Message Source: Pubsub does not provide any information to the handlers regarding the origin (aka source, or provenance) of a message

In this documentation, a sender is any part of the application that asks Pubsub to send a message of a given topic with a given payload (data, or content). The handler, aka receiver, is a callable object (function etc) referred to as a listener.

Here is a schematic representation of the role of pubsub during message sending and delivery:

Contents:

• About
  • License
  • Authors
  • Acknowledgements
  • Pubsub Users
  • History
• Install
  • System Requirements
  • How-to
  • Support
  • Release Notes
  • Changelog
• Use
  • Basic Usage
  • Advanced Usage
  • How Tos
  • Reference
• Contribute
  • Roadmap
  • Contributing
  • System Requirements
  • Scripts Available
  • Packaging

Indices and tables

• Index
• Module Index
• Search Page