Pubsub's Pub Module
=====================

An application that wishes to make use of pubsub's main functionality 
should import pubsub's :mod:`pub` module::

    from pubsub import pub

The pub module supports:

* `publishing <Publishing Messages>`_  and `receiving <Receiving Messages>`_
  messages of a given topic
* tracking pubsub activity in an application
* dealing with "badly behaved" listeners (ie that leak exceptions)
* specifying or just documenting the topic tree of an application

.. note:: the signature of functions of :mod:`pub` module, as seen in this 
    manual, typically have ``self`` as first function parameter. Omit 
    this parameter in your calls, as it is provided for you by Python (so it 
    will not be described in the text). For instance for ``pub.subscribe`` 
    the signature is ``subscribe(self, listener, topicName)``, but it must be 
    called as though it were ``subscribe(listener, topicName)``. 


.. _publishing-messages: 

Publishing Messages
-----------------------

"Publishing" and "Sending a message to the rest of your application" are 
the same thing in this documentation. 

To publish a message, it is sufficient to use the :func:`pub.sendMessage` 
function:

.. autofunction:: pub.sendMessage(topicName, **kwargs)

For example, to send a message of topic 'topicA' with two data items, 
arg1 and arg2::

    pub.sendMessage('topicA', arg1=123, arg2='abc')
    
For the task of publishing messages, here are some important concepts: 

* :ref:`Topics <anchor-message-topics>` are akin to classes in OOP, or to 
  channels in radio broadcasting; similar to classes, they can be organized 
  into a :ref:`hierarchy <anchor-topic-hierarchy>`, known as the "topic tree" 
  of the application.
* :ref:`Topic names <anchor-topic-names>` are strings or tuples of strings.
* :ref:`MDS <anchor-topic-mds-basics>`: Each topic defines what message data 
  is allowed or required for messages of that topic. This is the 
  *Message Data Specification*, or **MDS**. Subtopics :ref:`inherit the 
  MDS <anchor-topic-mds-hierarchy>` of their parent topic.

More details can be found on the following pages:

.. toctree::

    topics
    

.. _receiving-messages:

Receiving Messages
----------------------

In general, listener-related concepts are explained in the section:

.. toctree::

    listeners