.. include:: headings.inc

.. module:: lib.pubsub

.. currentmodule:: lib.pubsub

.. highlight:: python



.. _lib.pubsub:

==========================================================================================================================================
|phoenix_title|  **pubsub**
==========================================================================================================================================

The publish-subscribe package is called *pubsub*. It provides the 
following modules:

- ``pub``: pubsub's main module. It provides, first and foremost,   
  functions for sending messages and subscribing listeners. It provides 
  functions and classes for tracking pubsub usage, handling exceptions
  in listeners, specificying topics, and various others. 
- ``utils``: subpackage of utility functions and classes, it provides 
  basic pubsub usage trackers, exception handlers, topic tree printer, 
  and more. These can also serve as examples of how to create your 
  own trackers/handlers/etc. 
  
A few other modules inside pubsub are specific to configuring the pubsub API
and must be used only ONCE in an application:

- ``setupkwargs``: module to setup pubsub to use "kwargs" messaging protocol 
  of the Argspec API. This API and protocol are the default so it is 
  not usually necessary to use setupkwargs. 
- ``setupv1``: (deprecated) module to force pubsub to use the legacy
  "version 1" (aka v1) API. Should only be useful to wxPython users
  for legacy code.
- ``setuparg1``: module to setup pubsub to use "arg1" messaging protocol of 
  the Argspec API. This supports the same messaging semantics as legacy API
  but with the Argspec API, useful when transitioning an application 
  from legacy to Argspec API. 


|package_summary| Packages Summary
==================================

================================================================================ ================================================================================
:mod:`~lib.pubsub.core`                                                          Core package of pubsub, holding the publisher, listener, and topic
:mod:`~lib.pubsub.pubsub1`                                                       This __init__ file is present to help with certain non-standard uses
================================================================================ ================================================================================


|


|module_summary| Modules Summary
================================

================================================================================ ================================================================================
:mod:`~lib.pubsub.pub`                                                           Provides "version 1" of pubsub's publish-subscribe API.
:mod:`~lib.pubsub.pubsubconf`                                                    Configuration of pubsub API to use either the *arg1* or *kwargs*
:mod:`~lib.pubsub.setuparg1`                                                     Import this file before the first 'from pubsub import pub' statement
:mod:`~lib.pubsub.setupkwargs`                                                   Import this file before the first 'from pubsub import pub' statement
:mod:`~lib.pubsub.setupv1`                                                       Import this file before the first 'from pubsub import pub' statement
:mod:`~lib.pubsub.setupv2`                                                       Import this file before the first 'from pubsub import pub' statement
:mod:`~lib.pubsub.sphinx`                                                        Sphinx autodoc requires direct import of pubsub.pubsub1.pub.
:mod:`~lib.pubsub.utils`                                                         There are no utilities supported for legacy v1 of pubsub.
================================================================================ ================================================================================


|


.. toctree::
   :maxdepth: 1
   :hidden:

   lib.pubsub.core
   lib.pubsub.pubsub1
   lib.pubsub.pub
   lib.pubsub.pubsubconf
   lib.pubsub.setuparg1
   lib.pubsub.setupkwargs
   lib.pubsub.setupv1
   lib.pubsub.setupv2
   lib.pubsub.sphinx
   lib.pubsub.utils