wxPython-zombie 3.1.5.8__cp313-cp313-win_amd64.whl

wx/lib/pubsub/core/kwargs/topicargspecimpl.py

@@ -0,0 +1,217 @@
+"""
+
+:copyright: Copyright since 2006 by Oliver Schoenborn, all rights reserved.
+:license: BSD, see LICENSE_BSD_Simple.txt for details.
+
+"""
+
+import weakref
+
+from .topicutils import (stringize, WeakNone)
+from .validatedefnargs import verifySubset
+from .. import py2and3
+
+### Exceptions raised during check() from sendMessage()
+
+class SenderMissingReqdMsgDataError(RuntimeError):
+    """
+    Raised when a sendMessage() is missing arguments tagged as
+    'required' by pubsub topic of message.
+    """
+
+    def __init__(self, topicName, argNames, missing):
+        argsStr = ','.join(argNames)
+        missStr = ','.join(missing)
+        msg = "Some required args missing in call to sendMessage('%s', %s): %s" \
+            % (stringize(topicName), argsStr, missStr)
+        RuntimeError.__init__(self, msg)
+
+
+class SenderUnknownMsgDataError(RuntimeError):
+    """
+    Raised when a sendMessage() has arguments not listed among the topic's
+    message data specification (MDS).
+    """
+
+    def __init__(self, topicName, argNames, extra):
+        argsStr = ','.join(argNames)
+        extraStr = ','.join(extra)
+        msg = "Some optional args unknown in call to sendMessage('%s', %s): %s" \
+            % (topicName, argsStr, extraStr)
+        RuntimeError.__init__(self, msg)
+
+
+class ArgsInfo:
+    """
+    Encode the Message Data Specification (MDS) for a given
+    topic. ArgsInfos form a tree identical to that of Topics in that
+    ArgInfos have a reference to their parent and children ArgInfos,
+    created for the parent and children topics.
+
+    The only difference
+    between an ArgsInfo and an ArgSpecGiven is that the latter is
+    what "user thinks is ok" whereas former has been validated:
+    the specification for this topic is a strict superset of the
+    specification of its parent, and a strict subset of the
+    specification of each of its children. Also, the instance
+    can be used to check validity and filter arguments.
+
+    The MDS can be created "empty", ie "incomplete", meaning it cannot
+    yet be used to validate listener subscriptions to topics.
+    """
+
+    SPEC_MISSING        = 10 # no args given
+    SPEC_COMPLETE       = 12 # all args, but not confirmed via user spec
+
+
+    def __init__(self, topicNameTuple, specGiven, parentArgsInfo):
+        self.topicNameTuple = topicNameTuple
+        self.allOptional = () # topic message optional arg names
+        self.allDocs     = {} # doc for each arg
+        self.allRequired = () # topic message required arg names
+        self.argsSpecType = self.SPEC_MISSING
+        self.parentAI = WeakNone()
+        if parentArgsInfo is not None:
+            self.parentAI = weakref.ref(parentArgsInfo)
+            parentArgsInfo.__addChildAI(self)
+        self.childrenAI = []
+
+        if specGiven.isComplete():
+            self.__setAllArgs(specGiven)
+
+    def isComplete(self):
+        return self.argsSpecType == self.SPEC_COMPLETE
+
+    def getArgs(self):
+        return self.allOptional + self.allRequired
+
+    def numArgs(self):
+        return len(self.allOptional) + len(self.allRequired)
+
+    def getReqdArgs(self):
+        return self.allRequired
+
+    def getOptArgs(self):
+        return self.allOptional
+
+    def getArgsDocs(self):
+        return self.allDocs.copy()
+
+    def setArgsDocs(self, docs):
+        """docs is a mapping from arg names to their documentation"""
+        if not self.isComplete():
+            raise
+        for arg, doc in py2and3.iteritems(docs):
+            self.allDocs[arg] = doc
+
+    def check(self, msgKwargs):
+        """Check that the message arguments given satisfy the topic message
+        data specification (MDS). Raises SenderMissingReqdMsgDataError if some required
+        args are missing or not known, and raises SenderUnknownMsgDataError if some
+        optional args are unknown. """
+        all = set(msgKwargs)
+        # check that it has all required args
+        needReqd = set(self.allRequired)
+        hasReqd = (needReqd <= all)
+        if not hasReqd:
+            raise SenderMissingReqdMsgDataError(
+                self.topicNameTuple, py2and3.keys(msgKwargs), needReqd - all)
+
+        # check that all other args are among the optional spec
+        optional = all - needReqd
+        ok = (optional <= set(self.allOptional))
+        if not ok:
+            raise SenderUnknownMsgDataError( self.topicNameTuple,
+                py2and3.keys(msgKwargs), optional - set(self.allOptional) )
+
+    def filterArgs(self, msgKwargs):
+        """Returns a dict which contains only those items of msgKwargs
+        which are defined for topic. E.g. if msgKwargs is {a:1, b:'b'}
+        and topic arg spec is ('a',) then return {a:1}. The returned dict
+        is valid only if check(msgKwargs) was called (or
+        check(superset of msgKwargs) was called)."""
+        assert self.isComplete()
+        if len(msgKwargs) == self.numArgs():
+            return msgKwargs
+
+        # only keep the keys from msgKwargs that are also in topic's kwargs
+        # method 1: SLOWEST
+        #newKwargs = dict( (k,msgKwargs[k]) for k in self.__msgArgs.allOptional if k in msgKwargs )
+        #newKwargs.update( (k,msgKwargs[k]) for k in self.__msgArgs.allRequired )
+
+        # method 2: FAST:
+        #argNames = self.__msgArgs.getArgs()
+        #newKwargs = dict( (key, val) for (key, val) in msgKwargs.iteritems() if key in argNames )
+
+        # method 3: FASTEST:
+        argNames = set(self.getArgs()).intersection(msgKwargs)
+        newKwargs = dict( (k,msgKwargs[k]) for k in argNames )
+
+        return newKwargs
+
+    def hasSameArgs(self, *argNames):
+        """Returns true if self has all the message arguments given, no
+        more and no less. Order does not matter. So if getArgs()
+        returns ('arg1', 'arg2') then self.hasSameArgs('arg2', 'arg1')
+        will return true. """
+        return set(argNames) == set( self.getArgs() )
+
+    def hasParent(self, argsInfo):
+        """return True if self has argsInfo object as parent"""
+        return self.parentAI() is argsInfo
+
+    def getCompleteAI(self):
+        """Get the closest arg spec, starting from self and moving to parent,
+        that is complete. So if self.isComplete() is True, then returns self,
+        otherwise returns parent (if parent.isComplete()), etc. """
+        AI = self
+        while AI is not None:
+            if AI.isComplete():
+                return AI
+            AI = AI.parentAI() # dereference weakref
+        return None
+
+    def updateAllArgsFinal(self, topicDefn):
+        """This can only be called once, if the construction was done
+        with ArgSpecGiven.SPEC_GIVEN_NONE"""
+        assert not self.isComplete()
+        assert topicDefn.isComplete()
+        self.__setAllArgs(topicDefn)
+
+    def __addChildAI(self, childAI):
+        assert childAI not in self.childrenAI
+        self.childrenAI.append(childAI)
+
+    def __notifyParentCompleted(self):
+        """Parent should call this when parent ArgsInfo has been completed"""
+        assert self.parentAI().isComplete()
+        if self.isComplete():
+            # verify that our spec is compatible with parent's
+            self.__validateArgsToParent()
+            return
+
+    def __validateArgsToParent(self):
+        # validate relative to parent arg spec
+        closestParentAI = self.parentAI().getCompleteAI()
+        if closestParentAI is not None:
+            # verify that parent args is a subset of spec given:
+            topicName = stringize(self.topicNameTuple)
+            verifySubset(self.getArgs(), closestParentAI.getArgs(), topicName)
+            verifySubset(self.allRequired, closestParentAI.getReqdArgs(),
+                         topicName, ' required args')
+
+    def __setAllArgs(self, specGiven):
+        assert specGiven.isComplete()
+        self.allOptional = tuple( specGiven.getOptional() )
+        self.allRequired = specGiven.reqdArgs
+        self.allDocs     = specGiven.argsDocs.copy() # doc for each arg
+        self.argsSpecType= self.SPEC_COMPLETE
+
+        if self.parentAI() is not None:
+            self.__validateArgsToParent()
+
+        # notify our children
+        for childAI in self.childrenAI:
+            childAI.__notifyParentCompleted()
+
+

wx/lib/pubsub/core/kwargs/topicmgrimpl.py

@@ -0,0 +1,13 @@
+"""
+
+:copyright: Copyright since 2006 by Oliver Schoenborn, all rights reserved.
+:license: BSD, see LICENSE_BSD_Simple.txt for details.
+
+"""
+
+def getRootTopicSpec():
+    """If using kwargs protocol, then root topic takes no args."""
+    argsDocs = {}
+    reqdArgs = ()
+    return argsDocs, reqdArgs
+

wx/lib/pubsub/core/listener.py

@@ -0,0 +1,40 @@
+"""
+Top-level functionality related to message listeners. 
+"""
+
+"""
+:copyright: Copyright since 2006 by Oliver Schoenborn, all rights reserved.
+:license: BSD, see LICENSE_BSD_Simple.txt for details.
+"""
+
+from .callables import (
+    getID, 
+    getArgs, 
+    getRawFunction,
+    ListenerMismatchError, 
+    CallArgsInfo
+)
+
+from .listenerimpl import (
+    Listener, 
+    ListenerValidator
+)
+
+class IListenerExcHandler:
+    """
+    Interface class base class for any handler given to pub.setListenerExcHandler()
+    Such handler is called whenever a listener raises an exception during a 
+    pub.sendMessage(). Example::
+
+        from pubsub import pub
+        
+        class MyHandler(pub.IListenerExcHandler):
+            def __call__(self, listenerID, topicObj):
+                ... do something with listenerID ...
+                
+        pub.setListenerExcHandler(MyHandler())
+    """
+    def __call__(self, listenerID, topicObj):
+        raise NotImplementedError('%s must override __call__()' % self.__class__)
+
+

wx/lib/pubsub/core/listenerbase.py

@@ -0,0 +1,185 @@
+"""
+:copyright: Copyright since 2006 by Oliver Schoenborn, all rights reserved.
+:license: BSD, see LICENSE_BSD_Simple.txt for details.
+"""
+
+from . import weakmethod
+
+from .callables import (
+    getID, 
+    getArgs,
+    ListenerMismatchError, 
+    CallArgsInfo, 
+    AUTO_TOPIC as _AUTO_ARG
+)
+
+
+class ListenerBase:
+    """
+    Base class for listeners, ie. callables subscribed to pubsub. 
+    """
+    
+    AUTO_TOPIC = _AUTO_ARG
+    
+    def __init__(self, callable_, argsInfo, onDead=None):
+        """Use callable_ as a listener of topicName. The argsInfo is the
+        return value from a Validator, ie an instance of callables.CallArgsInfo.
+        If given, the onDead will be called with self as parameter, if/when
+        callable_ gets garbage collected (callable_ is held only by weak
+        reference). """
+        # set call policies
+        self.acceptsAllKwargs = argsInfo.acceptsAllKwargs
+        
+        self._autoTopicArgName = argsInfo.autoTopicArgName
+        self._callable = weakmethod.getWeakRef(callable_, self.__notifyOnDead)
+        self.__onDead = onDead
+        
+        # save identity now in case callable dies:
+        name, mod = getID(callable_)   #
+        self.__nameID = name
+        self.__module = mod 
+        self.__id     = str(id(callable_))[-4:] # only last four digits of id
+        self.__hash   = hash(callable_)
+    
+    def __call__(self, args, kwargs, actualTopic, allArgs=None):
+        raise NotImplementedError
+    
+    def name(self):
+        """Return a human readable name for listener, based on the
+        listener's type name and its id (as obtained from id(listener)). If 
+        caller just needs name based on type info, specify instance=False. 
+        Note that the listener's id() was saved at construction time (since 
+        it may get garbage collected at any time) so the return value of 
+        name() is not necessarily unique if the callable has died (because 
+        id's can be re-used after garbage collection)."""
+        return '%s_%s'  % (self.__nameID, self.__id)
+
+    def typeName(self):
+        """Get a type name for the listener. This is a class name or
+        function name, as appropriate. """
+        return self.__nameID
+    
+    def module(self):
+        """Get the module in which the callable was defined."""
+        return self.__module
+
+    def getCallable(self):
+        """Get the listener that was given at initialization. Note that
+        this could be None if it has been garbage collected (e.g. if it was 
+        created as a wrapper of some other callable, and not stored 
+        locally)."""
+        return self._callable()
+
+    def isDead(self):
+        """Return True if this listener died (has been garbage collected)"""
+        return self._callable() is None
+
+    def wantsTopicObjOnCall(self):
+        """True if this listener wants topic object: it has a arg=pub.AUTO_TOPIC"""
+        return self._autoTopicArgName is not None
+
+    def wantsAllMessageData(self):
+        """True if this listener wants all message data: it has a \**kwargs argument"""
+        return self.acceptsAllKwargs
+    
+    def _unlinkFromTopic_(self):
+        """Tell self that it is no longer used by a Topic. This allows
+        to break some cyclical references."""
+        self.__onDead = None
+
+    def _calledWhenDead(self):
+        raise RuntimeError('BUG: Dead Listener called, still subscribed!')
+
+    def __notifyOnDead(self, ref):
+        """This gets called when listener weak ref has died. Propagate
+        info to Topic)."""
+        notifyDeath = self.__onDead
+        self._unlinkFromTopic_()
+        if notifyDeath is not None:
+            notifyDeath(self)
+
+    def __eq__(self, rhs):
+        """Compare for equality to rhs. This returns true if rhs has our id id(rhs) is
+        same as id(self) or id(callable in self). """
+        if id(self) == id(rhs):
+            return True
+
+        try:
+            c1 = self._callable()
+            c2 = rhs._callable()
+
+        except Exception:
+            # then rhs is not a Listener, compare with c1
+            return c1 == rhs
+
+        # both side of == are Listener, but always compare unequal if both dead
+        if c2 is None and c1 is None:
+            return False
+        
+        return c1 == c2
+
+    def __ne__(self, rhs):
+        """Counterpart to __eq__ MUST be defined... equivalent to
+        'not (self == rhs)'."""
+        return not self.__eq__(rhs)
+
+    def __hash__(self):
+        """Hash is an optimization for dict/set searches, it need not
+        return different numbers for every different object. """
+        return self.__hash
+
+    def __str__(self):
+        """String rep is the callable"""
+        return self.__nameID
+
+
+class ValidatorBase:
+    """
+    Validates listeners. It checks whether the listener given to 
+    validate() method complies with required and optional arguments
+    specified for topic. 
+    """
+    
+    def __init__(self, topicArgs, topicKwargs):
+        """topicArgs is a list of argument names that will be required when sending
+        a message to listener. Hence order of items in topicArgs matters. The topicKwargs
+        is a list of argument names that will be optional, ie given as keyword arguments
+        when sending a message to listener. The list is unordered. """
+        self._topicArgs   = set(topicArgs)
+        self._topicKwargs = set(topicKwargs)
+
+
+    def validate(self, listener):
+        """Validate that listener satisfies the requirements of
+        being a topic listener, if topic's kwargs keys are topicKwargKeys
+        (so only the list of keyword arg names for topic are necessary). 
+        Raises ListenerMismatchError if listener not usable for topic. 
+        
+        Otherwise, returns an CallArgsInfo object containing information about
+        the listener's call arguments, such as whether listener wants topic
+        name (signified by a kwarg value = AUTO_TOPIC in listener protocol).
+        E.g. def fn1(msgTopic=Listener.AUTO_TOPIC) would 
+        cause validate(fn1) to return True, whereas any other kwarg name or value 
+        would cause a False to be returned. 
+        """
+        paramsInfo = getArgs( listener )
+        self._validateArgs(listener, paramsInfo)
+        return paramsInfo
+
+
+    def isValid(self, listener):
+        """Return true only if listener can subscribe to messages where
+        topic has kwargs keys topicKwargKeys. Just calls validate() in 
+        a try-except clause."""
+        try:
+            self.validate(listener)
+            return True
+        except ListenerMismatchError:
+            return False
+
+    
+    def _validateArgs(self, listener, paramsInfo):
+        """Provide implementation in derived classes"""
+        raise NotImplementedError
+    
+

wx/lib/pubsub/core/notificationmgr.py

@@ -0,0 +1,185 @@
+"""
+:copyright: Copyright since 2006 by Oliver Schoenborn, all rights reserved.
+:license: BSD, see LICENSE_BSD_Simple.txt for details.
+"""
+import sys
+
+class NotificationMgr:
+    """
+    Manages notifications for tracing pubsub activity. When pubsub takes a 
+    certain action such as sending a message or creating a topic, and 
+    the notification flag for that activity is True, all registered
+    notification handlers get corresponding method called with information
+    about the activity, such as which listener subscribed to which topic. 
+    See INotificationHandler for which method gets called for each activity.
+    
+    If more than one notification handler has been registered, the order in 
+    which they are notified is unspecified (do not rely on it).
+
+    Note that this manager automatically unregisters all handlers when
+    the Python interpreter exits, to help avoid NoneType exceptions during
+    shutdown. This "shutdown" starts when the last line of app "main" has
+    executed; the Python interpreter then starts cleaning up, garbage 
+    collecting everything, which could lead to various pubsub notifications
+    -- by then they should be of no interest -- such as dead
+    listeners, etc. 
+    """
+
+    def __init__(self, notificationHandler = None):
+        self.__notifyOnSend = False
+        self.__notifyOnSubscribe = False
+        self.__notifyOnUnsubscribe = False
+
+        self.__notifyOnNewTopic = False
+        self.__notifyOnDelTopic = False
+        self.__notifyOnDeadListener = False
+
+        self.__handlers = []
+        if notificationHandler is not None:
+            self.addHandler(notificationHandler)
+
+        self.__atExitRegistered = False
+
+    def addHandler(self, handler):
+        if not self.__atExitRegistered:
+            self.__registerForAppExit()
+        self.__handlers.append(handler)
+
+    def getHandlers(self):
+        return self.__handlers[:]
+
+    def clearHandlers(self):
+        self.__handlers = []
+
+    def notifySubscribe(self, *args, **kwargs):
+        if self.__notifyOnSubscribe and self.__handlers:
+            for handler in self.__handlers:
+                handler.notifySubscribe(*args, **kwargs)
+
+    def notifyUnsubscribe(self, *args, **kwargs):
+        if self.__notifyOnUnsubscribe and self.__handlers:
+            for handler in self.__handlers:
+                handler.notifyUnsubscribe(*args, **kwargs)
+
+    def notifySend(self, *args, **kwargs):
+        if self.__notifyOnSend and self.__handlers:
+            for handler in self.__handlers:
+                handler.notifySend(*args, **kwargs)
+
+    def notifyNewTopic(self, *args, **kwargs):
+        if self.__notifyOnNewTopic and self.__handlers:
+            for handler in self.__handlers:
+                handler.notifyNewTopic(*args, **kwargs)
+
+    def notifyDelTopic(self, *args, **kwargs):
+        if self.__notifyOnDelTopic and self.__handlers:
+            for handler in self.__handlers:
+                handler.notifyDelTopic(*args, **kwargs)
+
+    def notifyDeadListener(self, *args, **kwargs):
+        if self.__notifyOnDeadListener and self.__handlers:
+            for handler in self.__handlers:
+                handler.notifyDeadListener(*args, **kwargs)
+
+    def getFlagStates(self):
+        """Return state of each notification flag, as a dict."""
+        return dict(
+            subscribe    = self.__notifyOnSubscribe,
+            unsubscribe  = self.__notifyOnUnsubscribe,
+            deadListener = self.__notifyOnDeadListener,
+            sendMessage  = self.__notifyOnSend,
+            newTopic     = self.__notifyOnNewTopic,
+            delTopic     = self.__notifyOnDelTopic,
+            )
+    
+    def setFlagStates(self, subscribe=None, unsubscribe=None,
+        deadListener=None, sendMessage=None, newTopic=None,
+        delTopic=None, all=None):
+        """Set the notification flag on/off for various aspects of pubsub.
+        The kwargs that are None are left at their current value. The 'all',
+        if not None, is set first. E.g.
+
+            mgr.setFlagStates(all=True, delTopic=False)
+
+        will toggle all notifications on, but will turn off the 'delTopic'
+        notification.
+        """
+        if all is not None:
+            # ignore all other arg settings, and set all of them to true:
+            numArgs = 7 # how many args in this method
+            self.setFlagStates( all=None, * ((numArgs-1)*[all]) )
+
+        if sendMessage is not None:
+            self.__notifyOnSend = sendMessage
+        if subscribe is not None:
+            self.__notifyOnSubscribe = subscribe
+        if unsubscribe is not None:
+            self.__notifyOnUnsubscribe = unsubscribe
+
+        if newTopic is not None:
+            self.__notifyOnNewTopic = newTopic
+        if delTopic is not None:
+            self.__notifyOnDelTopic = delTopic
+        if deadListener is not None:
+            self.__notifyOnDeadListener = deadListener
+
+
+    def __registerForAppExit(self):
+        import atexit
+        atexit.register(self.clearHandlers)
+        self.__atExitRegistered = True
+
+
+
+class INotificationHandler:
+    """
+    Defines the interface expected by pubsub for pubsub activity 
+    notifications. Any instance that supports the same methods, or 
+    derives from this class, will work as a notification handler
+    for pubsub events (see pub.addNotificationHandler).
+    """
+    
+    def notifySubscribe(self, pubListener, topicObj, newSub):
+        """Called when a listener is subscribed to a topic.
+        :param pubListener: the pubsub.core.Listener that wraps subscribed listener.
+        :param topicObj: the pubsub.core.Topic object subscribed to.
+        :param newSub: false if pubListener was already subscribed. """
+        raise NotImplementedError
+        
+    def notifyUnsubscribe(self, pubListener, topicObj):
+        """Called when a listener is unsubscribed from given topic.
+        :param pubListener: the pubsub.core.Listener that wraps unsubscribed listener.
+        :param topicObj: the pubsub.core.Topic object unsubscribed from."""
+        raise NotImplementedError
+        
+    def notifyDeadListener(self, pubListener, topicObj):
+        """Called when a listener has been garbage collected.
+        :param pubListener: the pubsub.core.Listener that wraps GC'd listener.
+        :param topicObj: the pubsub.core.Topic object it was subscribed to."""
+        raise NotImplementedError
+        
+    def notifySend(self, stage, topicObj, pubListener=None):
+        """Called multiple times during a sendMessage: once before message
+        sending has started (pre), once for each listener about to be sent the 
+        message, and once after all listeners have received the message (post).
+        :param stage: 'pre', 'post', or 'loop'.
+        :param topicObj: the Topic object for the message.
+        :param pubListener: None for pre and post stages; for loop, the listener
+            that is about to be sent the message."""
+        raise NotImplementedError
+    
+    def notifyNewTopic(self, topicObj, description, required, argsDocs):
+        """Called whenever a new topic is added to the topic tree.
+        :param topicObj: the Topic object for the message.
+        :param description: docstring for the topic.
+        :param required: list of message data names (keys in argsDocs) that are required.
+        :param argsDocs: dictionary of all message data names, with the 
+        corresponding docstring. """
+        raise NotImplementedError
+        
+    def notifyDelTopic(self, topicName):
+        """Called whenever a topic is removed from topic tree.
+        :param topicName: name of topic removed."""
+        raise NotImplementedError
+
+