pub

Provides “version 1” of pubsub’s publish-subscribe API.

Sending a message is as simple as calling a function with a topic name and (optionally) some data that will be sent to the listeners.

Any callable object can be a message listener, if it can be called with one parameter. Example use:

from pubsub import Publisher
def aCallable(msg):
    print 'data received', msg.data
Publisher.subscribe(aCallable, 'some_topic')
Publisher.sendMessage('some_topic', data=123)
// should see 'data received 123'

Note: in this documentation, pubsub version 1 is assumed to be part of wxPython’s lib package. There isn’t a reason for using version 1 other than for legacy wxPython applications. Even then, consider upgrading your wxPython application to the latest API, as explained on the pubsub website.

The three important concepts for pubsub are:

• listener: a function, bound method or callable object that can be called with one parameter (not counting ‘self’ in the case of methods). For instance, these listeners are ok:

  class Foo:
      def __call__(self, a, b=1): pass # can be called with only one arg
      def meth(self,  a):         pass # takes only one arg
      def meth2(self, a=2, b=''): pass # can be called with one arg
  
  def func(a, b=''): pass
  
  Foo foo
  
  import pubsub as Publisher
  Publisher.subscribe(foo)           # functor
  Publisher.subscribe(foo.meth)      # bound method
  Publisher.subscribe(foo.meth2)     # bound method
  Publisher.subscribe(func)          # function

  The three types of callables all have signature that allows a call with only one argument. When called, the argument will be a reference to a pub.Message object, containing both the data and topic name of the message. In every example above, the ‘a.data’ will contain the message data, ‘a.topic’ will contain the topic name.

• topic: a single word, a tuple of words, or a string containing a set of words separated by dots, for example: ‘sports.baseball’. A tuple or a dotted notation string denotes a hierarchy of topics from most general to least. For example, a listener of this topic:

  'sports.baseball'
  

  would receive messages for these topics:

  'sports.baseball               # because same
  'sports.baseball.highscores'   # because more specific

  but not these:

  'sports'      # because more general
  'news'        # because different topic
  

• message: this is an instance of pub.Message, with self.topic referring to the topic name for which the message was sent, and self.data referring to the data given to sendMessage().

Note that an important feature of pubsub is that as soon as a listener is no longer in use in your application (except for being subscribed to pubsub topics), pubsub will automatically unsubscribe it. See PublisherClass docs for more details.

Author:Oliver Schoenborn Copyright:Copyright since 2006 by Oliver Schoenborn, all rights reserved. License:BSD, see LICENSE.txt for details.

Inheritance Diagram

Inheritance diagram for module pub

Functions Summary

getStrAllTopics	Function to call if, for whatever reason, you need to know
setupForTesting	This is used only by testing modules. Use at your own risk ;)

Classes Summary

_NodeCallback	Encapsulate a weak reference to a method of a _TopicTreeNode
_SingletonKey	Used to “prevent” instantiating a _PublisherClass
_TopicTreeNode	A node in the topic tree. This contains a list of callables
_TopicTreeRoot	The root of the tree knows how to access other node of the
PublisherClass	Class to manage publishing, subscribing and message sending.

Functions

---

getStrAllTopics()

Function to call if, for whatever reason, you need to know explicitely what is the string to use to indicate ‘all topics’.

---

setupForTesting()

This is used only by testing modules. Use at your own risk ;)