[wxWidgets.git] / wxPython / wx / lib / pubsub.py


#---------------------------------------------------------------------------
"""
This module provides a publish-subscribe component that allows
listeners to subcribe to messages of a given topic. Contrary to the
original wxPython.lib.pubsub module (which it is based on), it uses 
weak referencing to the subscribers so the lifetime of subscribers 
is not affected by Publisher. Also, callable objects can be used in 
addition to functions and bound methods. See Publisher class docs for 
more details. 

Thanks to Robb Shecter and Robin Dunn for having provided 
the basis for this module (which now shares most of the concepts but
very little design or implementation with the original 
wxPython.lib.pubsub).

The publisher is a singleton instance of the PublisherClass class. You 
access the instance via the Publisher object available from the module::

    from wx.lib.pubsub import Publisher
    Publisher().subscribe(...)
    Publisher().sendMessage(...)
    ...

:Author:      Oliver Schoenborn
:Since:       Apr 2004
:Version:     $Id$
:Copyright:   \(c) 2004 Oliver Schoenborn
:License:     wxWidgets
"""

_implNotes = """
Implementation notes
--------------------

In class Publisher, I represent the topics-listener set as a tree
where each node is a topic, and contains a list of listeners of that
topic, and a dictionary of subtopics of that topic. When the Publisher
is told to send a message for a given topic, it traverses the tree
down to the topic for which a message is being generated, all
listeners on the way get sent the message.

Publisher currently uses a weak listener topic tree to store the
topics for each listener, and if a listener dies before being
unsubscribed, the tree is notified, and the tree eliminates the
listener from itself.

Ideally, _TopicTreeNode would be a generic _TreeNode with named
subnodes, and _TopicTreeRoot would be a generic _Tree with named
nodes, and Publisher would store listeners in each node and a topic
tuple would be converted to a path in the tree.  This would lead to a
much cleaner separation of concerns. But time is over, time to move on.
"""
#---------------------------------------------------------------------------

# for function and method parameter counting:
from types   import InstanceType
from inspect import getargspec, ismethod, isfunction
# for weakly bound methods:
from new     import instancemethod as InstanceMethod
from weakref import ref as WeakRef

# -----------------------------------------------------------------------------

def _isbound(method):
    """Return true if method is a bound method, false otherwise"""
    assert ismethod(method)
    return method.im_self is not None


def _paramMinCountFunc(function):
    """Given a function, return pair (min,d) where min is minimum # of
    args required, and d is number of default arguments."""
    assert isfunction(function)
    (args, va, kwa, dflt) = getargspec(function)
    lenDef = len(dflt or ())
    lenArgs = len(args or ())
    lenVA = int(va is not None)
    return (lenArgs - lenDef + lenVA, lenDef)


def _paramMinCount(callableObject):
    """
    Given a callable object (function, method or callable instance),
    return pair (min,d) where min is minimum # of args required, and d
    is number of default arguments. The 'self' parameter, in the case
    of methods, is not counted.
    """
    if type(callableObject) is InstanceType:
        min, d = _paramMinCountFunc(callableObject.__call__.im_func)
        return min-1, d
    elif ismethod(callableObject):
        min, d = _paramMinCountFunc(callableObject.im_func)
        return min-1, d
    elif isfunction(callableObject):
        return _paramMinCountFunc(callableObject)
    else:
        raise 'Cannot determine type of callable: '+repr(callableObject)


def _tupleize(items):
    """Convert items to tuple if not already one, 
    so items must be a list, tuple or non-sequence"""
    if isinstance(items, list):
        raise TypeError, 'Not allowed to tuple-ize a list'
    elif isinstance(items, (str, unicode)) and items.find('.') != -1:
        items = tuple(items.split('.'))
    elif not isinstance(items, tuple):
        items = (items,)
    return items


def _getCallableName(callable):
    """Get name for a callable, ie function, bound 
    method or callable instance"""
    if ismethod(callable):
        return '%s.%s ' % (callable.im_self, callable.im_func.func_name)
    elif isfunction(callable):
        return '%s ' % callable.__name__
    else:
        return '%s ' % callable
    
    
def _removeItem(item, fromList):
    """Attempt to remove item from fromList, return true 
    if successful, false otherwise."""
    try: 
        fromList.remove(item)
        return True
    except ValueError:
        return False
        
        
# -----------------------------------------------------------------------------

class _WeakMethod:
    """Represent a weak bound method, i.e. a method doesn't keep alive the 
    object that it is bound to. It uses WeakRef which, used on its own, 
    produces weak methods that are dead on creation, not very useful. 
    Typically, you will use the getRef() function instead of using
    this class directly. """
    
    def __init__(self, method, notifyDead = None):
        """The method must be bound. notifyDead will be called when 
        object that method is bound to dies. """
        assert ismethod(method)
        if method.im_self is None:
            raise ValueError, "We need a bound method!"
        if notifyDead is None:
            self.objRef = WeakRef(method.im_self)
        else:
            self.objRef = WeakRef(method.im_self, notifyDead)
        self.fun = method.im_func
        self.cls = method.im_class
        
    def __call__(self):
        """Returns a new.instancemethod if object for method still alive. 
        Otherwise return None. Note that instancemethod causes a 
        strong reference to object to be created, so shouldn't save 
        the return value of this call. Note also that this __call__
        is required only for compatibility with WeakRef.ref(), otherwise
        there would be more efficient ways of providing this functionality."""
        if self.objRef() is None:
            return None
        else:
            return InstanceMethod(self.fun, self.objRef(), self.cls)
        
    def __eq__(self, method2):
        """Two WeakMethod objects compare equal if they refer to the same method
        of the same instance. Thanks to Josiah Carlson for patch and clarifications
        on how dict uses eq/cmp and hashing. """
        if not isinstance(method2, _WeakMethod):
            return False 
        return      self.fun      is method2.fun \
                and self.objRef() is method2.objRef() \
                and self.objRef() is not None
    
    def __hash__(self):
        """Hash is an optimization for dict searches, it need not 
        return different numbers for every different object. Some objects
        are not hashable (eg objects of classes derived from dict) so no
        hash(objRef()) in there, and hash(self.cls) would only be useful
        in the rare case where instance method was rebound. """
        return hash(self.fun)
    
    def __repr__(self):
        dead = ''
        if self.objRef() is None: 
            dead = '; DEAD'
        obj = '<%s at %s%s>' % (self.__class__, id(self), dead)
        return obj
        
    def refs(self, weakRef):
        """Return true if we are storing same object referred to by weakRef."""
        return self.objRef == weakRef


def _getWeakRef(obj, notifyDead=None):
    """Get a weak reference to obj. If obj is a bound method, a _WeakMethod
    object, that behaves like a WeakRef, is returned, if it is
    anything else a WeakRef is returned. If obj is an unbound method,
    a ValueError will be raised."""
    if ismethod(obj):
        createRef = _WeakMethod
    else:
        createRef = WeakRef
        
    if notifyDead is None:
        return createRef(obj)
    else:
        return createRef(obj, notifyDead)
    
    
# -----------------------------------------------------------------------------

def getStrAllTopics():
    """Function to call if, for whatever reason, you need to know 
    explicitely what is the string to use to indicate 'all topics'."""
    return ''


# alias, easier to see where used
ALL_TOPICS = getStrAllTopics()

# -----------------------------------------------------------------------------


class _NodeCallback:
    """Encapsulate a weak reference to a method of a TopicTreeNode
    in such a way that the method can be called, if the node is 
    still alive, but the callback does not *keep* the node alive.
    Also, define two methods, preNotify() and noNotify(), which can 
    be redefined to something else, very useful for testing. 
    """
    
    def __init__(self, obj):
        self.objRef = _getWeakRef(obj)
        
    def __call__(self, weakCB):
        notify = self.objRef()
        if notify is not None: 
            self.preNotify(weakCB)
            notify(weakCB)
        else: 
            self.noNotify()
            
    def preNotify(self, dead):
        """'Gets called just before our callback (self.objRef) is called"""
        pass
        
    def noNotify(self):
        """Gets called if the TopicTreeNode for this callback is dead"""
        pass


class _TopicTreeNode:
    """A node in the topic tree. This contains a list of callables
    that are interested in the topic that this node is associated
    with, and contains a dictionary of subtopics, whose associated
    values are other _TopicTreeNodes. The topic of a node is not stored
    in the node, so that the tree can be implemented as a dictionary
    rather than a list, for ease of use (and, likely, performance).
    
    Note that it uses _NodeCallback to encapsulate a callback for 
    when a registered listener dies, possible thanks to WeakRef.
    Whenever this callback is called, the onDeadListener() function, 
    passed in at construction time, is called (unless it is None).
    """
    
    def __init__(self, topicPath, onDeadListenerWeakCB):
        self.__subtopics = {}
        self.__callables = []
        self.__topicPath = topicPath
        self.__onDeadListenerWeakCB = onDeadListenerWeakCB
        
    def getPathname(self): 
        """The complete node path to us, ie., the topic tuple that would lead to us"""
        return self.__topicPath
    
    def createSubtopic(self, subtopic, topicPath):
        """Create a child node for subtopic"""
        return self.__subtopics.setdefault(subtopic,
                    _TopicTreeNode(topicPath, self.__onDeadListenerWeakCB))
    
    def hasSubtopic(self, subtopic):
        """Return true only if topic string is one of subtopics of this node"""
        return self.__subtopics.has_key(subtopic)
    
    def getNode(self, subtopic):
        """Return ref to node associated with subtopic"""
        return self.__subtopics[subtopic]
    
    def addCallable(self, callable):
        """Add a callable to list of callables for this topic node"""
        try:
            id = self.__callables.index(_getWeakRef(callable))
            return self.__callables[id]
        except ValueError:
            wrCall = _getWeakRef(callable, _NodeCallback(self.__notifyDead))
            self.__callables.append(wrCall)
            return wrCall
            
    def getCallables(self):
        """Get callables associated with this topic node"""
        return [cb() for cb in self.__callables if cb() is not None]
    
    def hasCallable(self, callable):
        """Return true if callable in this node"""
        try: 
            self.__callables.index(_getWeakRef(callable))
            return True
        except ValueError:
            return False
    
    def sendMessage(self, message):
        """Send a message to our callables"""
        deliveryCount = 0
        for cb in self.__callables:
            listener = cb()
            if listener is not None:
                listener(message)
                deliveryCount += 1
        return deliveryCount
    
    def removeCallable(self, callable):
        """Remove weak callable from our node (and return True). 
        Does nothing if not here (and returns False)."""
        try: 
            self.__callables.remove(_getWeakRef(callable))
            return True
        except ValueError:
            return False
        
    def clearCallables(self):
        """Abandon list of callables to caller. We no longer have 
        any callables after this method is called."""
        tmpList = [cb for cb in self.__callables if cb() is not None]
        self.__callables = []
        return tmpList
        
    def __notifyDead(self, dead):
        """Gets called when a listener dies, thanks to WeakRef"""
        #print 'TreeNODE', `self`, 'received death certificate for ', dead
        self.__cleanupDead()
        if self.__onDeadListenerWeakCB is not None:
            cb = self.__onDeadListenerWeakCB()
            if cb is not None: 
                cb(dead)
        
    def __cleanupDead(self):
        """Remove all dead objects from list of callables"""
        self.__callables = [cb for cb in self.__callables if cb() is not None]
        
    def __str__(self):
        """Print us in a not-so-friendly, but readable way, good for debugging."""
        strVal = []
        for callable in self.getCallables():
            strVal.append(_getCallableName(callable))
        for topic, node in self.__subtopics.iteritems():
            strVal.append(' (%s: %s)' %(topic, node))
        return ''.join(strVal)
      
      
class _TopicTreeRoot(_TopicTreeNode):
    """
    The root of the tree knows how to access other node of the 
    tree and is the gateway of the tree user to the tree nodes. 
    It can create topics, and and remove callbacks, etc. 
    
    For efficiency, it stores a dictionary of listener-topics, 
    so that unsubscribing a listener just requires finding the 
    topics associated to a listener, and finding the corresponding
    nodes of the tree. Without it, unsubscribing would require 
    that we search the whole tree for all nodes that contain 
    given listener. Since Publisher is a singleton, it will 
    contain all topics in the system so it is likely to be a large
    tree. However, it is possible that in some runs, unsubscribe()
    is called very little by the user, in which case most unsubscriptions
    are automatic, ie caused by the listeners dying. In this case, 
    a flag is set to indicate that the dictionary should be cleaned up
    at the next opportunity. This is not necessary, it is just an 
    optimization.
    """
    
    def __init__(self):
        self.__callbackDict  = {}
        self.__callbackDictCleanup = 0
        # all child nodes will call our __rootNotifyDead method
        # when one of their registered listeners dies 
        _TopicTreeNode.__init__(self, (ALL_TOPICS,), 
                                _getWeakRef(self.__rootNotifyDead))
        
    def addTopic(self, topic, listener):
        """Add topic to tree if doesnt exist, and add listener to topic node"""
        assert isinstance(topic, tuple)
        topicNode = self.__getTreeNode(topic, make=True)
        weakCB = topicNode.addCallable(listener)
        assert topicNode.hasCallable(listener)

        theList = self.__callbackDict.setdefault(weakCB, [])
        assert self.__callbackDict.has_key(weakCB)
        # add it only if we don't already have it
        try:
            weakTopicNode = WeakRef(topicNode)
            theList.index(weakTopicNode)
        except ValueError:
            theList.append(weakTopicNode)
        assert self.__callbackDict[weakCB].index(weakTopicNode) >= 0
        
    def getTopics(self, listener):
        """Return the list of topics for given listener"""
        weakNodes = self.__callbackDict.get(_getWeakRef(listener), [])
        return [weakNode().getPathname() for weakNode in weakNodes 
                if weakNode() is not None]

    def isSubscribed(self, listener, topic=None):
        """Return true if listener is registered for topic specified. 
        If no topic specified, return true if subscribed to something.
        Use topic=getStrAllTopics() to determine if a listener will receive 
        messages for all topics."""
        weakCB = _getWeakRef(listener)
        if topic is None: 
            return self.__callbackDict.has_key(weakCB)
        else:
            topicPath = _tupleize(topic)
            for weakNode in self.__callbackDict[weakCB]:
                if topicPath == weakNode().getPathname():
                    return True
            return False
            
    def unsubscribe(self, listener, topicList):
        """Remove listener from given list of topics. If topicList
        doesn't have any topics for which listener has subscribed,
        nothing happens."""
        weakCB = _getWeakRef(listener)
        if not self.__callbackDict.has_key(weakCB):
            return
        
        cbNodes = self.__callbackDict[weakCB] 
        if topicList is None:
            for weakNode in cbNodes:
                weakNode().removeCallable(listener)
            del self.__callbackDict[weakCB] 
            return

        for weakNode in cbNodes:
            node = weakNode()
            if node is not None and node.getPathname() in topicList:
                success = node.removeCallable(listener)
                assert success == True
                cbNodes.remove(weakNode)
                assert not self.isSubscribed(listener, node.getPathname())

    def unsubAll(self, topicList, onNoSuchTopic):
        """Unsubscribe all listeners registered for any topic in 
        topicList. If a topic in the list does not exist, and 
        onNoSuchTopic is not None, a call
        to onNoSuchTopic(topic) is done for that topic."""
        for topic in topicList:
            node = self.__getTreeNode(topic)
            if node is not None:
                weakCallables = node.clearCallables()
                for callable in weakCallables:
                    weakNodes = self.__callbackDict[callable]
                    success = _removeItem(WeakRef(node), weakNodes)
                    assert success == True
                    if weakNodes == []:
                        del self.__callbackDict[callable]
            elif onNoSuchTopic is not None: 
                onNoSuchTopic(topic)
            
    def sendMessage(self, topic, message, onTopicNeverCreated):
        """Send a message for given topic to all registered listeners. If 
        topic doesn't exist, call onTopicNeverCreated(topic)."""
        # send to the all-toipcs listeners
        deliveryCount = _TopicTreeNode.sendMessage(self, message)
        # send to those who listen to given topic or any of its supertopics
        node = self
        for topicItem in topic:
            assert topicItem != ''
            if node.hasSubtopic(topicItem):
                node = node.getNode(topicItem)
                deliveryCount += node.sendMessage(message)
            else: # topic never created, don't bother continuing
                if onTopicNeverCreated is not None:
                    onTopicNeverCreated(topic)
                break
        return deliveryCount

    def numListeners(self):
        """Return a pair (live, dead) with count of live and dead listeners in tree"""
        dead, live = 0, 0
        for cb in self.__callbackDict:
            if cb() is None: 
                dead += 1
            else:
                live += 1
        return live, dead
    
    # clean up the callback dictionary after how many dead listeners
    callbackDeadLimit = 10

    def __rootNotifyDead(self, dead):
        #print 'TreeROOT received death certificate for ', dead
        self.__callbackDictCleanup += 1
        if self.__callbackDictCleanup > _TopicTreeRoot.callbackDeadLimit:
            self.__callbackDictCleanup = 0
            oldDict = self.__callbackDict
            self.__callbackDict = {}
            for weakCB, weakNodes in oldDict.iteritems():
                if weakCB() is not None:
                    self.__callbackDict[weakCB] = weakNodes
        
    def __getTreeNode(self, topic, make=False):
        """Return the tree node for 'topic' from the topic tree. If it 
        doesnt exist and make=True, create it first."""
        # if the all-topics, give root; 
        if topic == (ALL_TOPICS,):
            return self
            
        # not root, so traverse tree
        node = self
        path = ()
        for topicItem in topic:
            path += (topicItem,)
            if topicItem == ALL_TOPICS:
                raise ValueError, 'Topic tuple must not contain ""'
            if make: 
                node = node.createSubtopic(topicItem, path)
            elif node.hasSubtopic(topicItem):
                node = node.getNode(topicItem)
            else:
                return None
        # done
        return node
        
    def printCallbacks(self):
        strVal = ['Callbacks:\n']
        for listener, weakTopicNodes in self.__callbackDict.iteritems():
            topics = [topic() for topic in weakTopicNodes if topic() is not None]
            strVal.append('  %s: %s\n' % (_getCallableName(listener()), topics))
        return ''.join(strVal)
        
    def __str__(self):
        return 'all: %s' % _TopicTreeNode.__str__(self)
    
    
# -----------------------------------------------------------------------------

class _SingletonKey: pass

class PublisherClass:
    """
    The publish/subscribe manager.  It keeps track of which listeners
    are interested in which topics (see subscribe()), and sends a
    Message for a given topic to listeners that have subscribed to
    that topic, with optional user data (see sendMessage()).
    
    The three important concepts for Publisher are:
        
    - listener: a function, bound method or
      callable object that can be called with one parameter
      (not counting 'self' in the case of methods). The parameter
      will be a reference to a Message object. E.g., these listeners
      are ok::
          
          class Foo:
              def __call__(self, a, b=1): pass # can be called with only one arg
              def meth(self,  a):         pass # takes only one arg
              def meth2(self, a=2, b=''): pass # can be called with one arg
        
          def func(a, b=''): pass
          
          Foo foo
          Publisher().subscribe(foo)           # functor
          Publisher().subscribe(foo.meth)      # bound method
          Publisher().subscribe(foo.meth2)     # bound method
          Publisher().subscribe(func)          # function
          
      The three types of callables all have arguments that allow a call 
      with only one argument. In every case, the parameter 'a' will contain
      the message. 

    - topic: a single word, a tuple of words, or a string containing a
      set of words separated by dots, for example: 'sports.baseball'.
      A tuple or a dotted notation string denotes a hierarchy of
      topics from most general to least. For example, a listener of
      this topic::

          ('sports','baseball')

      would receive messages for these topics::

          ('sports', 'baseball')                 # because same
          ('sports', 'baseball', 'highscores')   # because more specific

      but not these::

           'sports'      # because more general
          ('sports',)    # because more general
          () or ('')     # because only for those listening to 'all' topics
          ('news')       # because different topic
          
    - message: this is an instance of Message, containing the topic for 
      which the message was sent, and any data the sender specified. 
      
    :note: This class is visible to importers of pubsub only as a 
    Singleton. I.e., every time you execute 'Publisher()', it's 
    actually the same instance of PublisherClass that is returned. So to 
    use, just do 'Publisher().method()'.
    """
    
    __ALL_TOPICS_TPL = (ALL_TOPICS, )
    
    def __init__(self, singletonKey):
        """Construct a Publisher. This can only be done by the pubsub 
        module. You just use pubsub.Publisher()."""
        if not isinstance(singletonKey, _SingletonKey):
            raise invalid_argument("Use Publisher() to get access to singleton")
        self.__messageCount  = 0
        self.__deliveryCount = 0
        self.__topicTree     = _TopicTreeRoot()

    #
    # Public API
    #

    def getDeliveryCount(self):
        """How many listeners have received a message since beginning of run"""
        return self.__deliveryCount
    
    def getMessageCount(self):
        """How many times sendMessage() was called since beginning of run"""
        return self.__messageCount
    
    def subscribe(self, listener, topic = ALL_TOPICS):
        """
        Subscribe listener for given topic. If topic is not specified,
        listener will be subscribed for all topics (that listener will 
        receive a Message for any topic for which a message is generated). 
        
        This method may be called multiple times for one listener,
        registering it with many topics.  It can also be invoked many
        times for a particular topic, each time with a different
        listener.  See the class doc for requirements on listener and
        topic.

        :note: The listener is held by Publisher() only by *weak* reference.
        This means you must ensure you have at least one strong reference
        to listener, otherwise it will be DOA ("dead on arrival"). This is 
        particularly easy to forget when wrapping a listener method in a 
        proxy object (e.g. to bind some of its parameters), e.g. 
        
        :code:
            class Foo: 
                def listener(self, event): pass
            class Wrapper:
                def __init__(self, fun): self.fun = fun
                def __call__(self, *args): self.fun(*args)
            foo = Foo()
            Publisher().subscribe( Wrapper(foo.listener) ) # whoops: DOA!
            wrapper = Wrapper(foo.listener)
            Publisher().subscribe(wrapper) # good!
        
        :note: Calling 
        this method for the same listener, with two topics in the same 
        branch of the topic hierarchy, will cause the listener to be
        notified twice when a message for the deepest topic is sent. E.g.
        subscribe(listener, 't1') and then subscribe(listener, ('t1','t2'))
        means that when calling sendMessage('t1'), listener gets one message,
        but when calling sendMessage(('t1','t2')), listener gets message 
        twice. 
        """
        self.validate(listener)

        if topic is None: 
            raise TypeError, 'Topic must be either a word, tuple of '\
                             'words, or getStrAllTopics()'
            
        self.__topicTree.addTopic(_tupleize(topic), listener)

    def isSubscribed(self, listener, topic=None):
        """Return true if listener has subscribed to topic specified. 
        If no topic specified, return true if subscribed to something.
        Use topic=getStrAllTopics() to determine if a listener will receive 
        messages for all topics."""
        return self.__topicTree.isSubscribed(listener, topic)
            
    def validate(self, listener):
        """Similar to isValid(), but raises a TypeError exception if not valid"""
        # check callable
        if not callable(listener):
            raise TypeError, 'Listener '+`listener`+' must be a '\
                             'function, bound method or instance.'
        # ok, callable, but if method, is it bound:
        elif ismethod(listener) and not _isbound(listener):
            raise TypeError, 'Listener '+`listener`+\
                             ' is a method but it is unbound!'
                             
        # check that it takes the right number of parameters
        min, d = _paramMinCount(listener)
        if min > 1:
            raise TypeError, 'Listener '+`listener`+" can't"\
                             ' require more than one parameter!'
        if min <= 0 and d == 0:
            raise TypeError, 'Listener '+`listener`+' lacking arguments!'
                             
        assert (min == 0 and d>0) or (min == 1)

    def isValid(self, listener):
        """Return true only if listener will be able to subscribe to 
        Publisher."""
        try: 
            self.validate(listener)
            return True
        except TypeError:
            return False

    def unsubAll(self, topics=None, onNoSuchTopic=None):
        """Unsubscribe all listeners subscribed for topics. Topics can 
        be a single topic (string or tuple) or a list of topics (ie 
        list containing strings and/or tuples). If topics is not 
        specified, all listeners for all topics will be unsubscribed, 
        ie. the Publisher singleton will have no topics and no listeners
        left. If onNoSuchTopic is given, it will be called as 
        onNoSuchTopic(topic) for each topic that is unknown.
        """
        if topics is None: 
            del self.__topicTree
            self.__topicTree = _TopicTreeRoot()
            return
        
        # make sure every topics are in tuple form
        if isinstance(topics, list):
            topicList = [_tupleize(x) for x in topics]
        else:
            topicList = [_tupleize(topics)]
            
        # unsub every listener of topics
        self.__topicTree.unsubAll(topicList, onNoSuchTopic)
            
    def unsubscribe(self, listener, topics=None):
        """Unsubscribe listener. If topics not specified, listener is
        completely unsubscribed. Otherwise, it is unsubscribed only 
        for the topic (the usual tuple) or list of topics (ie a list
        of tuples) specified. Nothing happens if listener is not actually
        subscribed to any of the topics.
        
        Note that if listener subscribed for two topics (a,b) and (a,c), 
        then unsubscribing for topic (a) will do nothing. You must 
        use getAssociatedTopics(listener) and give unsubscribe() the returned 
        list (or a subset thereof).
        """
        self.validate(listener)
        topicList = None
        if topics is not None:
            if isinstance(topics, list):
                topicList = [_tupleize(x) for x in topics]
            else:
                topicList = [_tupleize(topics)]
            
        self.__topicTree.unsubscribe(listener, topicList)
        
    def getAssociatedTopics(self, listener):
        """Return a list of topics the given listener is registered with. 
        Returns [] if listener never subscribed.
        
        :attention: when using the return of this method to compare to 
        expected list of topics, remember that topics that are not in the
        form of a tuple appear as a one-tuple in the return. E.g. if you 
        have subscribed a listener to 'topic1' and ('topic2','subtopic2'), 
        this method returns::
            
            associatedTopics = [('topic1',), ('topic2','subtopic2')]
        """
        return self.__topicTree.getTopics(listener)
    
    def sendMessage(self, topic=ALL_TOPICS, data=None, onTopicNeverCreated=None):
        """Send a message for given topic, with optional data, to
        subscribed listeners. If topic is not specified, only the
        listeners that are interested in all topics will receive message. 
        The onTopicNeverCreated is an optional callback of your choice that 
        will be called if the topic given was never created (i.e. it, or 
        one of its subtopics, was never subscribed to by any listener). 
        It will be called as onTopicNeverCreated(topic)."""
        aTopic  = _tupleize(topic)
        message = Message(aTopic, data)
        self.__messageCount += 1
        
        # send to those who listen to all topics
        self.__deliveryCount += \
            self.__topicTree.sendMessage(aTopic, message, onTopicNeverCreated)
        
    #
    # Private methods
    #

    def __call__(self):
        """Allows for singleton"""
        return self
    
    def __str__(self):
        return str(self.__topicTree)

# Create the Publisher singleton. We prevent users from (inadvertently)
# instantiating more than one object, by requiring a key that is 
# accessible only to module.  From
# this point forward any calls to Publisher() will invoke the __call__
# of this instance which just returns itself.
#
# The only flaw with this approach is that you can't derive a new
# class from Publisher without jumping through hoops.  If this ever
# becomes an issue then a new Singleton implementaion will need to be
# employed.
_key = _SingletonKey()
Publisher = PublisherClass(_key)


#---------------------------------------------------------------------------

class Message:
    """
    A simple container object for the two components of a message: the 
    topic and the user data. An instance of Message is given to your 
    listener when called by Publisher().sendMessage(topic) (if your
    listener callback was registered for that topic).
    """
    def __init__(self, topic, data):
        self.topic = topic
        self.data  = data

    def __str__(self):
        return '[Topic: '+`self.topic`+',  Data: '+`self.data`+']'


#---------------------------------------------------------------------------


#
# Code for a simple command-line test
#
def test():
    def done(funcName):
        print '----------- Done %s -----------' % funcName
        
    def testParam():
        def testFunc00(): pass
        def testFunc21(a,b,c=1): pass
        def testFuncA(*args): pass
        def testFuncAK(*args,**kwds): pass
        def testFuncK(**kwds): pass
        
        class Foo:
            def testMeth(self,a,b): pass
            def __call__(self, a): pass
        class Foo2:
            def __call__(self, *args): pass
            
        assert _paramMinCount(testFunc00)==(0,0)
        assert _paramMinCount(testFunc21)==(2,1)
        assert _paramMinCount(testFuncA) ==(1,0)
        assert _paramMinCount(testFuncAK)==(1,0)
        assert _paramMinCount(testFuncK) ==(0,0)
        foo = Foo()
        assert _paramMinCount(Foo.testMeth)==(2,0)
        assert _paramMinCount(foo.testMeth)==(2,0)
        assert _paramMinCount(foo)==(1,0)
        assert _paramMinCount(Foo2())==(1,0)
    
        done('testParam')

    testParam()
    #------------------------

    _NodeCallback.notified = 0
    def testPreNotifyNode(self, dead):
        _NodeCallback.notified += 1
        print 'testPreNotifyNODE heard notification of', `dead`
    _NodeCallback.preNotify = testPreNotifyNode
    
    def testTreeNode():

        class WS:
            def __init__(self, s):
                self.s = s
            def __call__(self, msg):
                print 'WS#', self.s, ' received msg ', msg
            def __str__(self):
                return self.s
            
        def testPreNotifyRoot(dead):
            print 'testPreNotifyROOT heard notification of', `dead`
    
        node = _TopicTreeNode((ALL_TOPICS,), WeakRef(testPreNotifyRoot))
        boo, baz, bid = WS('boo'), WS('baz'), WS('bid')
        node.addCallable(boo)
        node.addCallable(baz)
        node.addCallable(boo)
        assert node.getCallables() == [boo,baz]
        assert node.hasCallable(boo)
        
        node.removeCallable(bid) # no-op
        assert node.hasCallable(baz)
        assert node.getCallables() == [boo,baz]
        
        node.removeCallable(boo)
        assert node.getCallables() == [baz]
        assert node.hasCallable(baz)
        assert not node.hasCallable(boo)
        
        node.removeCallable(baz)
        assert node.getCallables() == []
        assert not node.hasCallable(baz)

        node2 = node.createSubtopic('st1', ('st1',))
        node3 = node.createSubtopic('st2', ('st2',))
        cb1, cb2, cb = WS('st1_cb1'), WS('st1_cb2'), WS('st2_cb')
        node2.addCallable(cb1)
        node2.addCallable(cb2)
        node3.addCallable(cb)
        node2.createSubtopic('st3', ('st1','st3'))
        node2.createSubtopic('st4', ('st1','st4'))
       
        print str(node)
        assert str(node) == ' (st1: st1_cb1 st1_cb2  (st4: ) (st3: )) (st2: st2_cb )'
    
        # verify send message, and that a dead listener does not get sent one
        delivered = node2.sendMessage('hello')
        assert delivered == 2
        del cb1
        delivered = node2.sendMessage('hello')
        assert delivered == 1
        assert _NodeCallback.notified == 1
        
        done('testTreeNode')
        
    testTreeNode()
    #------------------------
    
    def testValidate():
        class Foo:
            def __call__(self, a):   pass
            def fun(self, b):        pass
            def fun2(self, b=1):     pass
            def fun3(self, a, b=2):  pass
            def badFun(self):        pass
            def badFun2():           pass
            def badFun3(self, a, b): pass
            
        server = Publisher()
        foo = Foo()
        server.validate(foo)
        server.validate(foo.fun)
        server.validate(foo.fun2)
        server.validate(foo.fun3)
        assert not server.isValid(foo.badFun)
        assert not server.isValid(foo.badFun2)
        assert not server.isValid(foo.badFun3)
    
        done('testValidate')

    testValidate()
    #------------------------
    
    class SimpleListener:
        def __init__(self, number):
            self.number = number
        def __call__(self, message = ''): 
            print 'Callable #%s got the message "%s"' %(self.number, message)
        def notify(self, message):
            print '%s.notify() got the message "%s"' %(self.number, message)
        def __str__(self):
            return "SimpleListener_%s" % self.number

    def testSubscribe():
        publisher = Publisher()
        
        topic1 = 'politics'
        topic2 = ('history','middle age')
        topic3 = ('politics','UN')
        topic4 = ('politics','NATO')
        topic5 = ('politics','NATO','US')
        
        lisnr1 = SimpleListener(1)
        lisnr2 = SimpleListener(2)
        def func(message, a=1): 
            print 'Func received message "%s"' % message
        lisnr3 = func
        lisnr4 = lambda x: 'Lambda received message "%s"' % x

        assert not publisher.isSubscribed(lisnr1)
        assert not publisher.isSubscribed(lisnr2)
        assert not publisher.isSubscribed(lisnr3)
        assert not publisher.isSubscribed(lisnr4)
        
        publisher.subscribe(lisnr1, topic1)
        assert publisher.getAssociatedTopics(lisnr1) == [(topic1,)]
        publisher.subscribe(lisnr1, topic2)
        publisher.subscribe(lisnr1, topic1) # do it again, should be no-op
        assert publisher.getAssociatedTopics(lisnr1) == [(topic1,),topic2]
        publisher.subscribe(lisnr2.notify, topic3)
        assert publisher.getAssociatedTopics(lisnr2.notify) == [topic3]
        assert publisher.getAssociatedTopics(lisnr1) == [(topic1,),topic2]
        publisher.subscribe(lisnr3, topic5)
        assert publisher.getAssociatedTopics(lisnr3) == [topic5]
        assert publisher.getAssociatedTopics(lisnr2.notify) == [topic3]
        assert publisher.getAssociatedTopics(lisnr1) == [(topic1,),topic2]
        publisher.subscribe(lisnr4)
        
        print "Publisher tree: ", publisher
        assert publisher.isSubscribed(lisnr1)
        assert publisher.isSubscribed(lisnr1, topic1)
        assert publisher.isSubscribed(lisnr1, topic2)
        assert publisher.isSubscribed(lisnr2.notify)
        assert publisher.isSubscribed(lisnr3, topic5)
        assert publisher.isSubscribed(lisnr4, ALL_TOPICS)
        expectTopicTree = 'all: <lambda>  (politics: SimpleListener_1  (UN: SimpleListener_2.notify ) (NATO:  (US: func ))) (history:  (middle age: SimpleListener_1 ))'
        print "Publisher tree: ", publisher
        assert str(publisher) == expectTopicTree
        
        publisher.unsubscribe(lisnr1, 'booboo') # should do nothing
        assert publisher.getAssociatedTopics(lisnr1) == [(topic1,),topic2]
        assert publisher.getAssociatedTopics(lisnr2.notify) == [topic3]
        assert publisher.getAssociatedTopics(lisnr3) == [topic5]
        publisher.unsubscribe(lisnr1, topic1)
        assert publisher.getAssociatedTopics(lisnr1) == [topic2]
        assert publisher.getAssociatedTopics(lisnr2.notify) == [topic3]
        assert publisher.getAssociatedTopics(lisnr3) == [topic5]
        publisher.unsubscribe(lisnr1, topic2)
        publisher.unsubscribe(lisnr1, topic2)
        publisher.unsubscribe(lisnr2.notify, topic3)
        publisher.unsubscribe(lisnr3, topic5)
        assert publisher.getAssociatedTopics(lisnr1) == []
        assert publisher.getAssociatedTopics(lisnr2.notify) == []
        assert publisher.getAssociatedTopics(lisnr3) == []
        publisher.unsubscribe(lisnr4)
        
        expectTopicTree = 'all:  (politics:  (UN: ) (NATO:  (US: ))) (history:  (middle age: ))'
        print "Publisher tree: ", publisher
        assert str(publisher) == expectTopicTree
        assert publisher.getDeliveryCount() == 0
        assert publisher.getMessageCount() == 0
        
        publisher.unsubAll()
        assert str(publisher) == 'all: '
        
        done('testSubscribe')
    
    testSubscribe()
    #------------------------
    
    def testUnsubAll():
        publisher = Publisher()
        
        topic1 = 'politics'
        topic2 = ('history','middle age')
        topic3 = ('politics','UN')
        topic4 = ('politics','NATO')
        topic5 = ('politics','NATO','US')
        
        lisnr1 = SimpleListener(1)
        lisnr2 = SimpleListener(2)
        def func(message, a=1): 
            print 'Func received message "%s"' % message
        lisnr3 = func
        lisnr4 = lambda x: 'Lambda received message "%s"' % x

        publisher.subscribe(lisnr1, topic1)
        publisher.subscribe(lisnr1, topic2)
        publisher.subscribe(lisnr2.notify, topic3)
        publisher.subscribe(lisnr3, topic2)
        publisher.subscribe(lisnr3, topic5)
        publisher.subscribe(lisnr4)
        
        expectTopicTree = 'all: <lambda>  (politics: SimpleListener_1  (UN: SimpleListener_2.notify ) (NATO:  (US: func ))) (history:  (middle age: SimpleListener_1 func ))'
        print "Publisher tree: ", publisher
        assert str(publisher) == expectTopicTree
    
        publisher.unsubAll(topic1)
        assert publisher.getAssociatedTopics(lisnr1) == [topic2]
        assert not publisher.isSubscribed(lisnr1, topic1)
        
        publisher.unsubAll(topic2)
        print publisher
        assert publisher.getAssociatedTopics(lisnr1) == []
        assert publisher.getAssociatedTopics(lisnr3) == [topic5]
        assert not publisher.isSubscribed(lisnr1)
        assert publisher.isSubscribed(lisnr3, topic5)
        
        #print "Publisher tree: ", publisher
        expectTopicTree = 'all: <lambda>  (politics:  (UN: SimpleListener_2.notify ) (NATO:  (US: func ))) (history:  (middle age: ))'
        assert str(publisher) == expectTopicTree
        publisher.unsubAll(ALL_TOPICS)
        #print "Publisher tree: ", publisher
        expectTopicTree = 'all:  (politics:  (UN: SimpleListener_2.notify ) (NATO:  (US: func ))) (history:  (middle age: ))'
        assert str(publisher) == expectTopicTree
        
        publisher.unsubAll()
        done('testUnsubAll')
    
    testUnsubAll()
    #------------------------
    
    def testSend():
        publisher = Publisher()
        called = []
        
        class TestListener:
            def __init__(self, num):
                self.number = num
            def __call__(self, b): 
                called.append( 'TL%scb' % self.number )
            def notify(self, b):
                called.append( 'TL%sm' % self.number )
        def funcListener(b):
            called.append('func')
            
        lisnr1 = TestListener(1)
        lisnr2 = TestListener(2)
        lisnr3 = funcListener
        lisnr4 = lambda x: called.append('lambda')

        topic1 = 'politics'
        topic2 = 'history'
        topic3 = ('politics','UN')
        topic4 = ('politics','NATO','US')
        topic5 = ('politics','NATO')
        
        publisher.subscribe(lisnr1, topic1)
        publisher.subscribe(lisnr2, topic2)
        publisher.subscribe(lisnr2.notify, topic2)
        publisher.subscribe(lisnr3, topic4)
        publisher.subscribe(lisnr4)
        
        print publisher
        
        # setup ok, now test send/receipt
        publisher.sendMessage(topic1)
        assert called == ['lambda','TL1cb']
        called = []
        publisher.sendMessage(topic2)
        assert called == ['lambda','TL2cb','TL2m']
        called = []
        publisher.sendMessage(topic3)
        assert called == ['lambda','TL1cb']
        called = []
        publisher.sendMessage(topic4)
        assert called == ['lambda','TL1cb','func']
        called = []
        publisher.sendMessage(topic5)
        assert called == ['lambda','TL1cb']
        assert publisher.getDeliveryCount() == 12
        assert publisher.getMessageCount() == 5
    
        # test weak referencing works:
        _NodeCallback.notified = 0
        del lisnr2
        called = []
        publisher.sendMessage(topic2)
        assert called == ['lambda']
        assert _NodeCallback.notified == 2
        
        done('testSend')
        
    testSend()
    assert _NodeCallback.notified == 5
    
    def testDead():
        # verify if weak references work as expected
        print '------ Starting testDead ----------'
        node = _TopicTreeNode('t1', None)
        lisnr1 = SimpleListener(1)
        lisnr2 = SimpleListener(2)
        lisnr3 = SimpleListener(3)
        lisnr4 = SimpleListener(4)

        node.addCallable(lisnr1)
        node.addCallable(lisnr2)
        node.addCallable(lisnr3)
        node.addCallable(lisnr4)
        
        print 'Deleting listeners first'
        _NodeCallback.notified = 0
        del lisnr1
        del lisnr2
        assert _NodeCallback.notified == 2
        
        print 'Deleting node first'
        _NodeCallback.notified = 0
        del node
        del lisnr3
        del lisnr4
        assert _NodeCallback.notified == 0
        
        lisnr1 = SimpleListener(1)
        lisnr2 = SimpleListener(2)
        lisnr3 = SimpleListener(3)
        lisnr4 = SimpleListener(4)
        
        # try same with root of tree
        node = _TopicTreeRoot()
        node.addTopic(('',), lisnr1)
        node.addTopic(('',), lisnr2)
        node.addTopic(('',), lisnr3)
        node.addTopic(('',), lisnr4)
        # add objects that will die immediately to see if cleanup occurs
        # this must be done visually as it is a low-level detail
        _NodeCallback.notified = 0
        _TopicTreeRoot.callbackDeadLimit = 3
        node.addTopic(('',), SimpleListener(5))
        node.addTopic(('',), SimpleListener(6))
        node.addTopic(('',), SimpleListener(7))
        print node.numListeners()
        assert node.numListeners() == (4, 3)
        node.addTopic(('',), SimpleListener(8))
        assert node.numListeners() == (4, 0)
        assert _NodeCallback.notified == 4
        
        print 'Deleting listeners first'
        _NodeCallback.notified = 0
        del lisnr1
        del lisnr2
        assert _NodeCallback.notified == 2
        print 'Deleting node first'
        _NodeCallback.notified = 0
        del node
        del lisnr3
        del lisnr4
        assert _NodeCallback.notified == 0
        
        done('testDead')
    
    testDead()
    
    print 'Exiting tests'
#---------------------------------------------------------------------------

if __name__ == '__main__':
    test()