wxPython-zombie 3.1.5.8__cp313-cp313-win_amd64.whl

wx/lib/pubsub/core/topicobj.py

@@ -0,0 +1,472 @@
+"""
+Provide the Topic class.
+
+:copyright: Copyright since 2006 by Oliver Schoenborn, all rights reserved.
+:license: BSD, see LICENSE_BSD_Simple.txt for details.
+"""
+
+
+from weakref import ref as weakref
+
+from .listener import (
+    Listener, 
+    ListenerValidator,
+)
+
+from .topicutils import (
+    ALL_TOPICS, 
+    stringize, 
+    tupleize, 
+    validateName, 
+    smartDedent,
+)
+
+from .topicexc import (
+    TopicDefnError, 
+    TopicNameError, 
+    ExcHandlerError,
+)
+
+from .publishermixin import PublisherMixin
+
+from .topicargspec import (
+    ArgsInfo, 
+    ArgSpecGiven, 
+    topicArgsFromCallable, 
+    SenderMissingReqdMsgDataError, 
+    SenderUnknownMsgDataError, 
+    MessageDataSpecError,
+)
+
+from .. import py2and3
+
+
+class Topic(PublisherMixin):
+    """
+    Represent topics in pubsub. Contains information about a topic, 
+    including topic's message data specification (MDS), the list of 
+    subscribed listeners, docstring for the topic. It allows Python-like 
+    access to subtopics (e.g. A.B is subtopic B of topic A).
+    """
+
+    def __init__(self, treeConfig, nameTuple, description,
+        msgArgsInfo, parent=None):
+        """Create a topic. Should only be called by TopicManager via its
+        getOrCreateTopic() method (which gets called in several places 
+        in pubsub, such as sendMessage, subscribe, and newTopic).
+        
+        :param treeConfig: topic tree configuration settings
+        :param nameTuple: topic name, in tuple format (no dots)
+        :param description: "docstring" for topic
+        :param ArgsInfo msgArgsInfo: object that defines MDS for topic
+        :param parent: parent of topic
+        
+        :raises ValueError: invalid topic name
+        """
+        if parent is None:
+            if nameTuple != (ALL_TOPICS,):
+                msg = 'Only one topic, named %s, can be root of topic tree'
+                raise ValueError(msg % 'pub.ALL_TOPICS')
+        else:
+            validateName(nameTuple)
+        self.__tupleName = nameTuple
+
+        self.__handlingUncaughtListenerExc = False
+        self._treeConfig = treeConfig
+        PublisherMixin.__init__(self)
+
+        self.__validator = None
+        # Registered listeners were originally kept in a Python list; however 
+        # a few methods require lookup of the Listener for the given callable, 
+        # which is an O(n) operation. A set() could have been more suitable but
+        # there is no way of retrieving an element from a set without iterating 
+        # over the set, again an O(n) operation. A dict() is ok too. Because 
+        # Listener.__eq__(callable) returns true if the Listener instance wraps
+        # the given callable, and because Listener.__hash__ produces the hash 
+        # value of the wrapped callable, calling dict[callable] on a 
+        # dict(Listener -> Listener) mapping will be O(1) in most cases: 
+        # the dict will take the callables hash, find the list of Listeners that 
+        # have that hash, and then iterate over that inner list to find the 
+        # Listener instance which satisfies Listener == callable, and will return
+        # the Listener. 
+        self.__listeners = dict()
+
+        # specification:
+        self.__description  = None
+        self.setDescription(description)
+        self.__msgArgs = msgArgsInfo
+        if msgArgsInfo.isComplete():
+            self.__finalize()
+        else:
+            assert not self._treeConfig.raiseOnTopicUnspecified
+
+        # now that we know the args are fine, we can link to parent
+        self.__parentTopic = None
+        self.__subTopics = {}
+        if parent is None:
+            assert self.hasMDS()
+        else:
+            self.__parentTopic = weakref(parent)
+            assert self.__msgArgs.parentAI() is parent._getListenerSpec()
+            parent.__adoptSubtopic( self )
+
+    def setDescription(self, desc):
+        """Set the 'docstring' of topic"""
+        self.__description = desc
+
+    def getDescription(self):
+        """Return the 'docstring' of topic"""
+        if self.__description is None:
+            return None
+        return smartDedent(self.__description)
+
+    def setMsgArgSpec(self, argsDocs, required=()):
+        """Specify the message data for topic messages.
+        :param argsDocs: a dictionary of keyword names (message data name) and data 'docstring'; cannot be None
+        :param required: a list of those keyword names, appearing in argsDocs, 
+        which are required (all others are assumed optional)
+            
+        Can only be called if this info has not been already set at construction 
+        or in a previous call. 
+        :raise RuntimeError: if MDS already set at construction or previous call."""
+        assert self.__parentTopic is not None # for root of tree, this method never called!
+        if argsDocs is None:
+            raise ValueError('Cannot set listener spec to None')
+
+        if self.__msgArgs is None or not self.__msgArgs.isComplete():
+            try:
+                specGiven = ArgSpecGiven(argsDocs, required)
+                self.__msgArgs = ArgsInfo(self.__tupleName, specGiven,
+                    self.__parentTopic()._getListenerSpec())
+            except MessageDataSpecError:
+                # discard the lower part of the stack trace
+                exc = py2and3.getexcobj()
+                raise exc
+            self.__finalize()
+
+        else:
+            raise RuntimeError('Not allowed to call this: msg spec already set!')
+
+    def getArgs(self):
+        """Returns a pair (reqdArgs, optArgs) where reqdArgs is tuple
+        of names of required message arguments, optArgs is tuple
+        of names for optional arguments. If topic args not specified
+        yet, returns (None, None)."""
+        sendable = self.__msgArgs.isComplete()
+        assert sendable == self.hasMDS()
+        if sendable:
+            return (self.__msgArgs.allRequired ,
+                    self.__msgArgs.allOptional)
+        return None, None
+
+    def getArgDescriptions(self):
+        """Get a map of keyword names to docstrings: documents each MDS element. """
+        return self.__msgArgs.getArgsDocs()
+
+    def setArgDescriptions(self, **docs):
+        """Set the docstring for each MDS datum."""
+        self.__msgArgs.setArgsDocs(docs)
+
+    def hasMDS(self):
+        """Return true if this topic has a message data specification (MDS)."""
+        return self.__validator is not None
+
+    def filterMsgArgs(self, msgKwargs, check=False):
+        """Get the MDS docstrings for each of the spedified kwargs."""
+        filteredArgs = self.__msgArgs.filterArgs(msgKwargs)
+        # if no check of args yet, do it now:
+        if check:
+            self.__msgArgs.check(filteredArgs)
+        return filteredArgs
+
+    def isAll(self):
+        """Returns true if this topic is the 'all topics' topic. All root
+        topics behave as though they are child of that topic. """
+        return self.__tupleName == (ALL_TOPICS,)
+
+    def isRoot(self):
+        """Returns true if this is a "root" topic, false otherwise. A
+        root topic is a topic whose name contains no dots and which
+        has pub.ALL_TOPICS as parent."""
+        parent = self.getParent()
+        if parent:
+            return parent.isAll()
+        assert self.isAll()
+        return False
+
+    def getName(self):
+        """Return dotted form of full topic name"""
+        return stringize(self.__tupleName)
+
+    def getNameTuple(self):
+        """Return tuple form of full topic name"""
+        return self.__tupleName
+
+    def getNodeName(self):
+        """Return the last part of the topic name (has no dots)"""
+        name = self.__tupleName[-1]
+        return name
+
+    def getParent(self):
+        """Get Topic object that is parent of self (i.e. self is a subtopic
+        of parent). Return none if self is the "all topics" topic."""
+        if self.__parentTopic is None:
+            return None
+        return self.__parentTopic()
+
+    def hasSubtopic(self, name=None):
+        """Return true only if name is a subtopic of self. If name not
+        specified, return true only if self has at least one subtopic."""
+        if name is None:
+            return len(self.__subTopics) > 0
+
+        return name in self.__subTopics
+
+    def getSubtopic(self, relName):
+        """Get the specified subtopic object. The relName can be a valid
+        subtopic name, a dotted-name string, or a tuple. """
+        if not relName:
+            raise ValueError("getSubtopic() arg can't be empty")
+        topicTuple = tupleize(relName)
+        assert topicTuple
+
+        topicObj = self
+        for topicName in topicTuple:
+            child = topicObj.__subTopics.get(topicName)
+            if child is None:
+                msg = 'Topic "%s" doesn\'t have "%s" as subtopic' % (topicObj.getName(), topicName)
+                raise TopicNameError(relName, msg)
+            topicObj = child
+
+        return topicObj
+
+    def getSubtopics(self):
+        """Get a list of Topic instances that are subtopics of self."""
+        return py2and3.values(self.__subTopics)
+
+    def getNumListeners(self):
+        """Return number of listeners currently subscribed to topic. This is
+        different from number of listeners that will get notified since more
+        general topics up the topic tree may have listeners."""
+        return len(self.__listeners)
+
+    def hasListener(self, listener):
+        """Return true if listener is subscribed to this topic."""
+        return listener in self.__listeners
+
+    def hasListeners(self):
+        """Return true if there are any listeners subscribed to
+        this topic, false otherwise."""
+        return bool(self.__listeners)
+
+    def getListeners(self):
+        """Get a copy of list of listeners subscribed to this topic. Safe to iterate over while listeners
+        get un/subscribed from this topics (such as while sending a message)."""
+        return py2and3.keys(self.__listeners)
+
+    def getListenersIter(self):
+        """Get an iterator over listeners subscribed to this topic. Do not use if listeners can be
+        un/subscribed while iterating. """
+        return py2and3.iterkeys(self.__listeners)
+
+    def validate(self, listener):
+        """Checks whether listener could be subscribed to this topic:
+        if yes, just returns; if not, raises ListenerMismatchError.
+        Note that method raises TopicDefnError if self not
+        hasMDS()."""
+        if not self.hasMDS():
+            raise TopicDefnError(self.__tupleName)
+        return self.__validator.validate(listener)
+
+    def isValid(self, listener):
+        """Return True only if listener could be subscribed to this topic,
+        otherwise returns False. Note that method raises TopicDefnError
+        if self not hasMDS()."""
+        if not self.hasMDS():
+            raise TopicDefnError(self.__tupleName)
+        return self.__validator.isValid(listener)
+
+    def subscribe(self, listener):
+        """Subscribe listener to this topic. Returns a pair
+        (pub.Listener, success). The success is true only if listener
+        was not already subscribed and is now subscribed. """
+        if listener in self.__listeners:
+            assert self.hasMDS()
+            subdLisnr, newSub = self.__listeners[listener], False
+
+        else:
+            if self.__validator is None:
+                args, reqd = topicArgsFromCallable(listener)
+                self.setMsgArgSpec(args, reqd)
+            argsInfo = self.__validator.validate(listener)
+            weakListener = Listener(
+                listener, argsInfo, onDead=self.__onDeadListener)
+            self.__listeners[weakListener] = weakListener
+            subdLisnr, newSub = weakListener, True
+
+        # notify of subscription
+        self._treeConfig.notificationMgr.notifySubscribe(subdLisnr, self, newSub)
+
+        return subdLisnr, newSub
+
+    def unsubscribe(self, listener):
+        """Unsubscribe the specified listener from this topic. Returns
+        the pub.Listener object associated with the listener that was
+        unsubscribed, or None if the specified listener was not
+        subscribed to this topic.  Note that this method calls
+        ``notifyUnsubscribe(listener, self)`` on all registered notification
+        handlers (see pub.addNotificationHandler)."""
+        unsubdLisnr = self.__listeners.pop(listener, None)
+        if unsubdLisnr is None: 
+            return None
+
+        unsubdLisnr._unlinkFromTopic_()
+        assert listener == unsubdLisnr.getCallable()
+
+        # notify of unsubscription
+        self._treeConfig.notificationMgr.notifyUnsubscribe(unsubdLisnr, self)
+
+        return unsubdLisnr
+
+    def unsubscribeAllListeners(self, filter=None):
+        """Clears list of subscribed listeners. If filter is given, it must
+        be a function that takes a listener and returns true if the listener
+        should be unsubscribed. Returns the list of Listener for listeners 
+        that were unsubscribed."""
+        unsubd = []
+        if filter is None:
+            for listener in self.__listeners:
+                listener._unlinkFromTopic_()
+            unsubd = py2and3.keys(self.__listeners)
+            self.__listeners = {}
+        else:
+            unsubd = []
+            for listener in py2and3.keys(self.__listeners):
+                if filter(listener):
+                    unsubd.append(listener)
+                    listener._unlinkFromTopic_()
+                    del self.__listeners[listener]
+
+        # send notification regarding all listeners actually unsubscribed
+        notificationMgr = self._treeConfig.notificationMgr
+        for unsubdLisnr in unsubd:
+            notificationMgr.notifyUnsubscribe(unsubdLisnr, self)
+
+        return unsubd
+
+    #############################################################
+    #
+    # Impementation
+    #
+    #############################################################
+
+    def _getListenerSpec(self):
+        """Only to be called by pubsub package"""
+        return self.__msgArgs
+
+    def _publish(self, data):
+        """This sends message to listeners of parent topics as well.
+        If an exception is raised in a listener, the publish is
+        aborted, except if there is a handler (see
+        pub.setListenerExcHandler)."""
+        self._treeConfig.notificationMgr.notifySend('pre', self)
+
+        # send to ourself
+        iterState = self._mix_prePublish(data)
+        self.__sendMessage(data, self, iterState)
+
+        # send up the chain
+        topicObj = self.getParent()
+        while topicObj is not None:
+            if topicObj.hasListeners():
+                iterState = self._mix_prePublish(data, topicObj, iterState)
+                self.__sendMessage(data, topicObj, iterState)
+
+            # done for this topic, continue up branch to parent towards root
+            topicObj = topicObj.getParent()
+
+        self._treeConfig.notificationMgr.notifySend('post', self)
+
+    def __sendMessage(self, data, topicObj, iterState):
+        # now send message data to each listener for current topic;
+        # use list of listeners rather than iterator, so that if listeners added/removed during
+        # send loop, no runtime exception:
+        for listener in topicObj.getListeners():
+            try:
+                self._treeConfig.notificationMgr.notifySend('in', topicObj, pubListener=listener)
+                self._mix_callListener(listener, data, iterState)
+
+            except Exception:
+                # if exception handling is on, handle, otherwise re-raise
+                handler = self._treeConfig.listenerExcHandler
+                if handler is None or self.__handlingUncaughtListenerExc:
+                    raise
+
+                # try handling the exception so we can continue the send:
+                try:
+                    self.__handlingUncaughtListenerExc = True
+                    handler( listener.name(), topicObj )
+                    self.__handlingUncaughtListenerExc = False
+                except Exception:
+                    exc = py2and3.getexcobj()
+                    #print 'exception raised', exc
+                    self.__handlingUncaughtListenerExc = False
+                    raise ExcHandlerError(listener.name(), topicObj, exc)
+
+    def __finalize(self):
+        """Finalize the topic specification, which currently means
+        creating the listener validator for this topic. This allows 
+        calls to subscribe() to validate that listener adheres to 
+        topic's message data specification (MDS)."""
+        assert self.__msgArgs.isComplete()
+        assert not self.hasMDS()
+
+        # must make sure can adopt a validator
+        required = self.__msgArgs.allRequired
+        optional = self.__msgArgs.allOptional
+        self.__validator = ListenerValidator(required, list(optional) )
+        assert not self.__listeners
+
+    def _undefineSelf_(self, topicsMap):
+        """Called by topic manager when deleting a topic."""
+        if self.__parentTopic is not None:
+            self.__parentTopic().__abandonSubtopic(self.__tupleName[-1])
+        self.__undefineBranch(topicsMap)
+
+    def __undefineBranch(self, topicsMap):
+        """Unsubscribe all our listeners, remove all subtopics from self,
+        then detach from parent. Parent is not notified, because method
+        assumes it has been called by parent"""
+        #print 'Remove %s listeners (%s)' % (self.getName(), self.getNumListeners())
+        self.unsubscribeAllListeners()
+        self.__parentTopic = None
+
+        for subName, subObj in py2and3.iteritems(self.__subTopics):
+            assert isinstance(subObj, Topic)
+            #print 'Unlinking %s from parent' % subObj.getName()
+            subObj.__undefineBranch(topicsMap)
+
+        self.__subTopics = {}
+        del topicsMap[self.getName()]
+
+    def __adoptSubtopic(self, topicObj):
+        """Add topicObj as child topic."""
+        assert topicObj.__parentTopic() is self
+        attrName = topicObj.getNodeName()
+        self.__subTopics[attrName] = topicObj
+
+    def __abandonSubtopic(self, name):
+        """The given subtopic becomes orphan (no parent)."""
+        topicObj = self.__subTopics.pop(name)
+        assert topicObj.__parentTopic() is self
+
+    def __onDeadListener(self, weakListener):
+        """One of our subscribed listeners has died, so remove it and notify"""
+        pubListener = self.__listeners.pop(weakListener)
+        # notify:
+        self._treeConfig.notificationMgr.notifyDeadListener(pubListener, self)
+
+    def __str__(self):
+        return "%s(%s)" % (self.getName(), self.getNumListeners())
+
+

wx/lib/pubsub/core/topictreetraverser.py

@@ -0,0 +1,143 @@
+"""
+
+:copyright: Copyright since 2006 by Oliver Schoenborn, all rights reserved.
+:license: BSD, see LICENSE_BSD_Simple.txt for details.
+
+"""
+
+class TopicTreeTraverser:
+    """
+    Supports taking action on every topic in the topic tree. The traverse() method 
+    traverses a topic tree and calls visitor._onTopic() for each topic in the tree 
+    that satisfies visitor._accept(). Additionally it calls visitor._startChildren() 
+    whenever it starts traversing the subtopics of a topic, and 
+    visitor._endChildren() when it is done with the subtopics. Finally, it calls 
+    visitor._doneTraversal() when traversal has been completed. The visitor must 
+    therefore adhere to the ITopicTreeVisitor interface.
+    """
+    DEPTH   = 'Depth first through topic tree'
+    BREADTH = 'Breadth first through topic tree'
+    MAP     = 'Sequential through topic manager\'s topics map'
+
+    def __init__(self, visitor = None):
+        """The visitor, if given, must adhere to API of
+        ITopicTreeVisitor. The visitor can be changed or
+        set via setVisitor(visitor) before calling traverse()."""
+        self.__handler = visitor
+
+    def setVisitor(self, visitor):
+        """The visitor must adhere to API of ITopicTreeVisitor. """
+        self.__handler = visitor
+
+    def traverse(self, topicObj, how=DEPTH, onlyFiltered=True):
+        """Start traversing tree at topicObj. Note that topicObj is a
+        Topic object, not a topic name. The how defines if tree should
+        be traversed breadth or depth first. If onlyFiltered is
+        False, then all nodes are accepted (_accept(node) not called).
+
+        This method can be called multiple times.
+        """
+        if how == self.MAP:
+            raise NotImplementedError('not yet available')
+
+        self.__handler._startTraversal()
+
+        if how == self.BREADTH:
+            self.__traverseBreadth(topicObj, onlyFiltered)
+        else: 
+            assert how == self.DEPTH
+            self.__traverseDepth(topicObj, onlyFiltered)
+
+        self.__handler._doneTraversal()
+
+    def __traverseBreadth(self, topicObj, onlyFiltered):
+        visitor = self.__handler
+
+        def extendQueue(subtopics):
+            topics.append(visitor._startChildren)
+            topics.extend(subtopics)
+            topics.append(visitor._endChildren)
+
+        topics = [topicObj]
+        while topics:
+            topicObj = topics.pop(0)
+
+            if topicObj in (visitor._startChildren, visitor._endChildren):
+                topicObj()
+                continue
+
+            if onlyFiltered:
+                if visitor._accept(topicObj):
+                    extendQueue( topicObj.getSubtopics() )
+                    visitor._onTopic(topicObj)
+            else:
+                extendQueue( topicObj.getSubtopics() )
+                visitor._onTopic(topicObj)
+
+    def __traverseDepth(self, topicObj, onlyFiltered):
+        visitor = self.__handler
+
+        def extendStack(topicTreeStack, subtopics):
+            topicTreeStack.insert(0, visitor._endChildren) # marker functor
+            # put subtopics in list in alphabetical order
+            subtopicsTmp = subtopics
+            subtopicsTmp.sort(reverse=True, key=topicObj.__class__.getName)
+            for sub in subtopicsTmp:
+                topicTreeStack.insert(0, sub) # this puts them in reverse order
+            topicTreeStack.insert(0, visitor._startChildren) # marker functor
+
+        topics = [topicObj]
+        while topics:
+            topicObj = topics.pop(0)
+
+            if topicObj in (visitor._startChildren, visitor._endChildren):
+                topicObj()
+                continue
+
+            if onlyFiltered:
+                if visitor._accept(topicObj):
+                    extendStack( topics, topicObj.getSubtopics() )
+                    visitor._onTopic(topicObj)
+            else:
+                extendStack( topics, topicObj.getSubtopics() )
+                visitor._onTopic(topicObj)
+
+
+class ITopicTreeVisitor:
+    """
+    Derive from ITopicTreeVisitor and override one or more of the
+    self._*() methods. Give an instance to an instance of 
+    TopicTreeTraverser.
+    """
+
+    def _accept(self, topicObj):
+        """Override this to filter nodes of topic tree. Must return
+        True (accept node) of False (reject node). Note that rejected
+        nodes cause traversal to move to next branch (no children
+        traversed)."""
+        return True
+
+    def _startTraversal(self):
+        """Override this to define what to do when traversal() starts."""
+        pass
+
+    def _onTopic(self, topicObj):
+        """Override this to define what to do for each node."""
+        pass
+
+    def _startChildren(self):
+        """Override this to take special action whenever a
+        new level of the topic hierarchy is started (e.g., indent
+        some output). """
+        pass
+
+    def _endChildren(self):
+        """Override this to take special action whenever a
+        level of the topic hierarchy is completed (e.g., dedent
+        some output). """
+        pass
+
+    def _doneTraversal(self):
+        """Override this to take special action when traversal done."""
+        pass
+