.. comment: Pubsub documentation master file, created by
            sphinx-quickstart on Mon Jun 30 10:00:16 2008.
.. comment: generated with "gendocs.bat"

Pubsub Home page
================

.. note:: Latest API released is v3.1.2 from November 2011

The Python Pubsub package provides a publish - subscribe API that allows 
data to be sent between different parts of your application. In many cases, 
using publish - subscribe in your application will dramatically simplify 
its design and improve testability. Robin Dunn, the creator of wxPython, 
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 has the following capability: 

- It allows parts of an application to send messages to other parts of it,
  such that the programmer need not know
  
  - *if* the messages will be handled: 
  
    - perhaps the message will be ignored completely, 
    - or handled by a many different parts of the application;
    
  - *how* the messages will be handled: 

    - what will be done with the message and its contents;
    - if a return value will be received;

- It allows parts of an application to be notified of changes to data 
  in such a way that the programmer need not know the source of the data

A *listener* is "a part of the application that wants to receive messages". 
A listener subscribes to one or more topics. A *sender* is any part of the
application that asks Pubsub to send a message of a given topic. The sender
provides data, if any. Pubsub will send the message, including any data, 
to all listeners of the message's topic. 

Schematically:

.. image:: apidocs/pubsub_concept.png
   :alt: Sketch showing how pubsub fits into a Python application
   :align: center
   :width: 450px


Contributing
-------------

Please consider contributing to this project! More details in the
:ref:`label_contributing` section. 


.. Comment: Site Table of Contents

.. toctree::
   :maxdepth: 3
   :hidden:

   Home Page <self>
   about
   installation
   apidocs/index
   recipes/index