.. _label-usage:

API Documentation
====================

.. warning::

   This documentation is in the process of being updated. You may find 
   it more useful to refer to the
   source code doc strings and the examples in the :file:`examples`
   folder of the source distribution.


.. _api-versions:

API Versions
-------------

There are two supported APIs available in pubsub: the "argspec" API, 
and a legacy API named "version 1" or v1 for short. 

Legacy API
^^^^^^^^^^^^

The legacy API was developed as part of wxPython, where pubsub 
:ref:`originated <label-history>`. This API is available in pubsub 
to support wxPython applications based on this API. This distinguishing 
characteristic of this API is that all data to be sent in a message 
must fit in one parameter and pubsub does not verify whether the data
expected by a listener is present in the message.  **Note that this 
API is deprecated!!** Only use it if you have no choice. 

This API is documented only in :ref:`label-api-v1-docs`. 

Argspec API
^^^^^^^^^^^^^

The *Argument Specification* ("argspec" for short) API was developed 
for use in larger applications, where the 
legacy API was found to provide inadequate support
for message validation, debugging and topic documentation, all important
considerations in larger projects. The distinguishing characteristics of 
the argspec API is that the message data can be composite and is 
controlled by pubsub (via implicit or explicit specification)

The above means that an application written in the legacy API will require
a small amount of tweaking, mostly because of the different message sending
and receiving syntax. 

.. note::
    Except where specifically indicated, the API documentation on this site
    pertains to the argspec API. A separate section, 
    :ref:`label-api-v1-docs`, documents the v1 API of pubsub.

Installation Types
^^^^^^^^^^^^^^^^^^^

When installing pubsub as a standalone package in your 
Python "site packages", the API available by default will be the Argspec
API. In this case, the legacy API can be used only by importing 
pubsub.setupv1 module before the first 'from pubsub import pub' 
statement. This only needs to be done once for an application. 

When using the pubsub package that is installed as part of wxPython 
('from wx.lib.pubsub import ...'), the API provided is the legacy API. 

Transition legacy to Argspec API
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If you wish to transition an appication from using the legacy v1 API to
using the Argspec API, take a look at the :ref:`label-migrations` page.


.. _label-api-v3-docs:

Argspec API Documentation
-------------------------------

The User Manual consists of the following sections.

.. toctree::
   :maxdepth: 2

   examples
   basic_use
   more_advanced_use

Status 
^^^^^^^

Pubsub's public API is provided via its 'pub' and 'utils' modules. 
The following part of this API is unlikely to change:

Messaging, basic: 

- pub.sendMessage
- pub.subscribe
- pub.ALL_TOPICS
- pub.AUTO_TOPIC

Topic specification: 

- pub.addTopicDefnProvider
- pub.clearTopicDefnProviders
- pub.setTopicUnspecifiedFatal

Notification handling: 

- utils.useNotifyByWriteFile
- utils.printTreeDocs
- pub.addNotificationHandler
- pub.clearNotificationHandlers

Listener Exception handling: 

- pub.getListenerExcHandler
- pub.setListenerExcHandler
- pub.ExcHandlerError

Exceptions: 

- pub.ListenerInadequate
- pub.ListenerNotValidatable
- pub.ListenerSpecIncomplete
- pub.ListenerSpecInvalid
- pub.SenderMissingReqdArgs
- pub.SenderUnknownOptArgs
- pub.UndefinedSubtopic
- pub.UndefinedTopic

Messaging, advanced: 

- pub.getAssociatedTopics
- pub.getDefaultPublisher
- pub.getDefaultTopicMgr
- pub.getListenerID
- pub.getTopic
- pub.isSubscribed
- pub.isValid
- pub.Listener
- pub.Publisher
- pub.Topic
- pub.topics
- pub.topicsMap
- pub.unsubAll
- pub.unsubscribe
- pub.validate

Versioning: 

- pub.SVN_VERSION
- pub.VERSION_STR
- pub.PUBSUB_VERSION

The following, related to Topic Specification, are likely to evolve:

- pub.TOPIC_TREE_FROM_CLASS
- pub.TOPIC_TREE_FROM_MODULE
- pub.TOPIC_TREE_FROM_STRING
- pub.exportTopicTree
- pub.importTopicTree
- pub.ITopicDefnProvider
- pub.ITopicTreeTraverser
- pub.registerTopicDefnProviderType
- pub.TopicDefnProvider


Legacy API Documentation
-------------------------------

See :ref:`label-api-v1-docs`.

.. toctree::
   :hidden:
   :maxdepth: 2

   docs4v1