Pubsub Package
===============

.. automodule:: pubsub

The following two sections list tasks supported by pubsub, such as 
publishing or receiving messages, and link directly to parts of the 
documentation related to those tasks. 

Alternately, the section 
`Modules and sub-packages`_ shows a Reference Table-of-Contents
view of the pages describing the modules and associated concepts/principles. 


Essential Functionality
------------------------

Tasks that are essential when using pubsub are: 

* :ref:`publishing-messages`
* :ref:`receiving-messages`
* Trapping exceptions

They are in the :mod:`pub` module.


Extra Functionality
--------------------

Many other tasks can be involved in using pubsub to its full potential: 

* Tracking pubsub activity in an application via notification, for 
  feedback to user or while debugging
* Recovering from exceptions raised by listeners, for robustness
* Documenting topics, for maintainability
* Specifying topic message data (topic MDS), for robustness and 
  maintainability
* Preventing the creation of topics by mistake (typo)
* Automatically getting the topic name of the message in a listener
* Listen for messages from all topics
* Printing the application's topic tree
* Getting the ID of a listener
* Find which topics a listener is subscribed 
* Determine if a listener is subscribed to a topic
* Stop receiving messages
* Doing something with or to every topic in the topic tree
* Getting version info


Modules and sub-packages
--------------------------

Supported tasks are distributed among several modules modules and packages:

.. toctree::

    The pub module <module_pub>
    The utils package <module_utils>
    Various setup* modules <modules_setup>