doc = """

 8888888b.           888888b.   888                   888
 888   Y88b          888  '88b  888                   888
 888    888          888  .88P  888                   888
 888   d88P 888  888 8888888K.  888  8888b.  .d8888b  888888 .d88b.  888d888
 8888888P'  888  888 888  'Y88b 888     '88b 88K      888   d8P  Y8b 888P'
 888        888  888 888    888 888 .d888888 'Y8888b. 888   88888888 888
 888        Y88b 888 888   d88P 888 888  888      X88 Y88b. Y8b.     888
 888         'Y88888 8888888P'  888 'Y888888  88888P'  'Y888 'Y8888  888
                 888
            Y8b d88P
             'Y88P'

=======================================================
THE ABSTRACT
             
pyBlaster
    The Python way ("The first steps" :-)) to use www.XMLBLASTER.org
    
    A Python module that provides the complete XMLBLASTER interface for XMLRPC 
    This means for asynchronous updates (callbacks), too!
    
    Fredrik Lundh has provided the excellent XMLRPC library for Python.
       http://www.pythonware.com/products/xmlrpc/



Have fun and thanks to the XMLBLASTER-team!
        http://www.xmlblaster.org

        
Peter Arwanitis
spex66 @ gmx . net
(=PA=)

=======================================================
THE DETAILS

Core file
    pyBlaster.py

        My 1st Step:
            class XmlBlasterClient
                Implementation of the complete(?) XMLRPC client interface
                With just a little beautifying of the method-signatures

        My 2nd Step:        
            class XmlBlasterCallbackClient
                Specialisation of XmlBlasterClient with additional 
                threaded XMLRPC server implementation
        

Based on (if you have an uptodate installation, delete the provided files)
    xmlrpclib.py / SimpleXMLRPCServer.py ( Version 1.0.1 )
    
Additional core files
    BaseService.py             class to comfortable handle threads
                               found in the Narval project from LOGILAB
                               http://www.logilab.org
    ThreadedXMLRPCServer.py    mixin class SimpleXMLRPCServer & BaseService
                               to build an threaded XMLRPCServer
                               
                               
                               # since 080503
                               ResponsiveThreadedXMLRPCServer thanks to
                               Robin Munn, I've figured out a XMLRPCServer
                               cooperative with threading, look at the
                               comments in new ResponsiveThreadingTCPServer.py
                               
                               # since 080503
                               startCallbackServer-> port is now optional
                                            it can be allocated automatic
                               
Optional files
    ShellService.py            mixin class BaseService & InteractiveConsole
                               to serve an interactive Python prompt (shell) 
                               for debugging and testing 


=======================================================
THE INSTALLATION

Put the pyBlaster directory (its an python package) into your 
python/Lib/site-packages (or use it direct from the directory)


=======================================================
THE USAGE 

Read the XMLBLASTER documentation / requirements, especially for the
"quality of service QoS" options.

In your python project:

# import
from pyBlaster import pyBlaster

# build an instance
xb = pyBlaster.XmlBlasterCallbackClient()

# start server / use client
# its up to you, thats all!

=======================================================
THE TEST

Developed under Python 2.2.2 with the XMLRPC update from pythonware

Success stories from Jython and other CPython version are appreciated!

Test (batteries included):
    start pyBlaster.py in a shell and have a look at the help text
    start pyBlaster.py in more than one shell and experiment interactive
          with publish / subcribe / get <-- this is the python way :)
    
=======================================================
THE LICENCE
__license__ = 'pyBlaster is under LGPL, see See http://www.xmlBlaster.org/license.html'


(=PA=)        
"""
