.. _label-api-v1-docs:

Legacy (v1) API
=================

This section describes Version 1 of the pubsub API (versions are discussed in
:ref:`api-versions` section). **Note that this 
API is deprecated!!** Only use it if you have no choice. See 
:ref:`label-upgrade_for_wx` for how to upgrade your application to use the
new API. 

The pubsub package must be configured for version 1 API *before* any 
other pubsub module is imported from it, by using the :mod:`pubsub.setupv1` 
module from the top-level script of your application::

    from pubsub import setupv1

This can then be followed by ::

    from pubsub import Publisher

in the same module. *Other modules in your application do not need to 
import setupv1.*


Overview
---------

.. automodule:: pubsub.pubsub1.pub


The :data:`Publisher`
-----------------------

   .. data:: Publisher

      Singleton instance of pub.PublisherClass. Methods of this class are
      described next. 

   .. autoclass:: PublisherClass
        :members:

Example::

    from pubsub import Publisher
    
    def listenerAll(msg):
        print "listenerAll:      topic=", msg.topic
    def listenerSubTopic(msg):
        print "listenerSubTopic: topic=", msg.topic
        
    Publisher.subscribe(listenerAll, Publisher.ALL_TOPICS)
    Publisher.sendMessage('some_topic.sub_topic', data=123)
    # will print 
    # listenerAll:      topic=some_topic.sub_topic
    # listenerSubTopic: topic=some_topic.sub_topic


Other objects in :mod:`pub`
------------------------------

It is unlikely that you will need the :mod:`pub` module directly. The 
:data:`Publisher` described in the previous section is an instance 
of :class:`pub.PublisherClass`. The :mod:`pub` module also contains:
    
   .. autoclass:: Message
        :members:

   .. autofunction:: getStrAllTopics
   
   .. data:: ALL_TOPICS
   
      The string that refers to the root topic of the topic tree hierarchy.
      Listeners of this topic receive all messages. This data is also 
      an attribute of `Publisher`. 

Example::

    from pubsub import pub
    help(pub.Message)
    help(pub.getStrAllTopics)