.. include:: headings.inc

.. module:: lib.pubsub.pub

.. currentmodule:: lib.pubsub.pub

.. highlight:: python



.. _lib.pubsub.pub:

==========================================================================================================================================
|phoenix_title|  **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.



|

|class_hierarchy| Inheritance Diagram
=====================================

Inheritance diagram for module **pub**

.. raw:: html

   <p class="graphviz">
   <img src="_static/images/inheritance/lib.pubsub.pub_inheritance.png" alt="Inheritance diagram of pub" usemap="#dummy" class="inheritance"/>
   <map id="dummy" name="dummy"> <area shape="rect" id="node1" href="lib.pubsub.pub._TopicTreeNode.html" title="A node in the topic tree. This contains a list of callables" alt="" coords="7,165,180,195"/> <area shape="rect" id="node5" href="lib.pubsub.pub._TopicTreeRoot.html" title="The root of the tree knows how to access other node of the" alt="" coords="231,165,399,195"/> <area shape="rect" id="node2" href="lib.pubsub.pub.PublisherClass.html" title="Class to manage publishing, subscribing and message sending." alt="" coords="12,111,175,142"/> <area shape="rect" id="node3" href="lib.pubsub.pub._SingletonKey.html" title="Used to 'prevent' instantiating a _PublisherClass" alt="" coords="15,58,172,89"/> <area shape="rect" id="node4" href="lib.pubsub.pub._NodeCallback.html" title="Encapsulate a weak reference to a method of a _TopicTreeNode" alt="" coords="12,5,175,35"/> </map> 
   </p>

|


|function_summary| Functions Summary
====================================

================================================================================ ================================================================================
:func:`~lib.pubsub.pub.getStrAllTopics`                                          Function to call if, for whatever reason, you need to know
:func:`~lib.pubsub.pub.setupForTesting`                                          This is used only by testing modules. Use at your own risk ;)
================================================================================ ================================================================================


|


|class_summary| Classes Summary
===============================

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


|


.. toctree::
   :maxdepth: 1
   :hidden:

   lib.pubsub.pub._NodeCallback
   lib.pubsub.pub._SingletonKey
   lib.pubsub.pub._TopicTreeNode
   lib.pubsub.pub._TopicTreeRoot
   lib.pubsub.pub.PublisherClass





Functions
------------

.. function:: getStrAllTopics()

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


.. function:: setupForTesting()

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