wxPython 4.3.2__cp315-cp315-win_arm64.whl

wx/lib/pubsub/core/publisherbase.py

@@ -0,0 +1,189 @@
+"""
+:copyright: Copyright since 2006 by Oliver Schoenborn, all rights reserved.
+:license: BSD, see LICENSE_BSD_Simple.txt for details.
+"""
+
+from .topicmgr import (
+    TopicManager, 
+    TreeConfig
+)
+
+
+class PublisherBase:
+    """
+    Represent the class that send messages to listeners of given
+    topics and that knows how to subscribe/unsubscribe listeners
+    from topics.
+    """
+    
+    def __init__(self, treeConfig = None):
+        """If treeConfig is None, a default one is created from an
+        instance of TreeConfig."""
+        self.__treeConfig = treeConfig or TreeConfig()
+        self.__topicMgr = TopicManager(self.__treeConfig)
+
+    def getTopicMgr(self):
+        """Get the topic manager created for this publisher."""
+        return self.__topicMgr
+
+    def getListenerExcHandler(self):
+        """Get the listener exception handler that was registered
+        via setListenerExcHandler(), or None of none registered."""
+        return self.__treeConfig.listenerExcHandler
+
+    def setListenerExcHandler(self, handler):
+        """Set the function to call when a listener raises an exception
+        during a sendMessage(). The handler must adhere to the 
+        IListenerExcHandler API. """
+        self.__treeConfig.listenerExcHandler = handler
+
+    def addNotificationHandler(self, handler):
+        """Add a handler for tracing pubsub activity. The handler should be
+        a class that adheres to the API of INotificationHandler. """
+        self.__treeConfig.notificationMgr.addHandler(handler)
+
+    def clearNotificationHandlers(self):
+        """Remove all notification handlers that were added via
+        self.addNotificationHandler(). """
+        self.__treeConfig.notificationMgr.clearHandlers()
+
+    def setNotificationFlags(self, **kwargs):
+        """Set the notification flags on or off for each type of
+        pubsub activity. The kwargs keys can be any of the following:
+        
+        - subscribe:    if True, get notified whenever a listener subscribes to a topic;
+        - unsubscribe:  if True, get notified whenever a listener unsubscribes from a topic;
+        - deadListener: if True, get notified whenever a subscribed listener has been garbage-collected;
+        - sendMessage:  if True, get notified whenever sendMessage() is called;
+        - newTopic:     if True, get notified whenever a new topic is created;
+        - delTopic:     if True, get notified whenever a topic is "deleted" from topic tree;
+        - all:          set all of the above to the given value (True or False).
+
+        The kwargs that are None are left at their current value. Those that are 
+        False will cause corresponding notification to be silenced. The 'all'
+        is set first, then the others. E.g.
+
+            mgr.setFlagStates(all=True, delTopic=False)
+
+        will toggle all notifications on, but will turn off the 'delTopic'
+        notification.
+        """
+        self.__treeConfig.notificationMgr.setFlagStates(**kwargs)
+
+    def getNotificationFlags(self):
+        """Return a dictionary with the notification flag states."""
+        return self.__treeConfig.notificationMgr.getFlagStates()
+
+    def setTopicUnspecifiedFatal(self, newVal=True, checkExisting=True):
+        """Changes the creation policy for topics.
+
+        By default, pubsub will accept topic names for topics that 
+        don't have a message data specification (MDS). This default behavior 
+        makes pubsub easier to use initially, but allows topic
+        names with typos to go uncaught in common operations such as
+        sendMessage() and subscribe(). In a large application, this 
+        can lead to nasty bugs. Pubsub's default behavior is equivalent
+        to setTopicUnspecifiedFatal(false).
+        
+        When called with newVal=True, any future pubsub operation that
+        requires a topic (such as subscribe and sendMessage) will require 
+        an MDS; if none is available, pubsub will raise a TopicDefnError
+        exception. 
+        
+        If checkExisting is not given or True, all existing
+        topics are validated. A TopicDefnError exception is
+        raised if one is found to be incomplete (has hasMDS() false).
+
+        Returns previous value of newVal.
+
+        Note that this method can be used in several ways:
+
+        1. Only use it in your application when something is not working
+           as expected: just add a call at the beginning of your app when
+           you have a problem with topic messages not being received
+           (for instance), and remove it when you have fixed the problem.
+
+        2. Use it from the beginning of your app and never use newVal=False:
+           add a call at the beginning of your app and you leave it in
+           (forever), and use Topic Definition Providers to provide the
+           listener specifications. These are easy to use via the
+           pub.addTopicDefnProvider().
+
+        3. Use it as in #1 during app development, and once stable, use
+           #2. This is easiest to do in combination with
+           pub.exportTopicTreeSpec().
+         """
+        oldVal = self.__treeConfig.raiseOnTopicUnspecified
+        self.__treeConfig.raiseOnTopicUnspecified = newVal
+
+        if newVal and checkExisting:
+            self.__topicMgr.checkAllTopicsHaveMDS()
+
+        return oldVal
+
+    def sendMessage(self, topicName, *args, **kwargs):
+        """Send a message for topic name with given data (args and kwargs).
+        This will be overridden by derived classes that implement
+        message-sending for different messaging protocols; not all 
+        parameters may be accepted."""
+        raise NotImplementedError
+
+    def subscribe(self, listener, topicName):
+        """Subscribe listener to named topic. Raises ListenerMismatchError
+        if listener isn't compatible with the topic's MDS. Returns
+        (pubsub.core.Listener, success), where success is False if listener 
+        was already subscribed. The pub.core.Listener wraps the callable 
+        subscribed and provides introspection-based info about 
+        the callable.
+
+        Note that if 'subscribe' notification is on, the handler's
+        'notifySubscribe' method is called after subscription."""
+        topicObj = self.__topicMgr.getOrCreateTopic(topicName)
+        subscribedListener, success = topicObj.subscribe(listener)
+        return subscribedListener, success
+
+    def unsubscribe(self, listener, topicName):
+        """Unsubscribe from given topic. Returns the pubsub.core.Listener
+        instance that was used to wrap listener at subscription
+        time. Raises an TopicNameError if topicName doesn't exist.
+
+        Note that if 'unsubscribe' notification is on, the handler's
+        notifyUnsubscribe() method will be called after unsubscribing. """
+        topicObj = self.__topicMgr.getTopic(topicName)
+        unsubdLisnr = topicObj.unsubscribe(listener)
+
+        return unsubdLisnr
+
+    def unsubAll(self, topicName = None,
+        listenerFilter = None, topicFilter = None):
+        """By default (no args given), unsubscribe all listeners from all
+        topics. A listenerFilter can be given so that only the listeners
+        that satisfy listenerFilter(listener) == True will be unsubscribed
+        (with listener being a pub.Listener wrapper instance for each listener
+        subscribed). A topicFilter can also be given so that only topics
+        that satisfy topicFilter(topic name) == True will be affected.
+        If only one topic should have listeners unsubscribed, then a topic
+        name 'topicName' can be given *instead* instead of a topic filter.
+
+        Returns the list of all listeners (instances of pub.Listener) that
+        were unsubscribed from the topic tree).
+
+        Note: this method will generate one 'unsubcribe' notification message
+        (see pub.setNotificationFlags()) for each listener unsubscribed."""
+        unsubdListeners = []
+
+        if topicName is None:
+            # unsubscribe all listeners from all topics
+            topicsMap = self.__topicMgr._topicsMap
+            for topicName, topicObj in topicsMap.items():
+                if topicFilter is None or topicFilter(topicName):
+                    tmp = topicObj.unsubscribeAllListeners(listenerFilter)
+                    unsubdListeners.extend(tmp)
+
+        else:
+            topicObj = self.__topicMgr.getTopic(topicName)
+            unsubdListeners = topicObj.unsubscribeAllListeners(listenerFilter)
+
+        return unsubdListeners
+
+

wx/lib/pubsub/core/topicargspec.py

@@ -0,0 +1,77 @@
+"""
+Definitions related to message data specification.
+
+:copyright: Copyright since 2006 by Oliver Schoenborn, all rights reserved.
+:license: BSD, see LICENSE_BSD_Simple.txt for details.
+
+"""
+
+
+from .listener import getArgs as getListenerArgs
+from .validatedefnargs import MessageDataSpecError
+from .topicargspecimpl import (
+    SenderMissingReqdMsgDataError,
+    SenderUnknownMsgDataError,
+    ArgsInfo
+)
+
+
+def topicArgsFromCallable(_callable):
+    """Get the topic message data names and list of those that are required,
+    by introspecting given callable. Returns a pair, (args, required)
+    where args is a dictionary of allowed message data names vs docstring,
+    and required states which ones are required rather than optional."""
+    argsInfo = getListenerArgs(_callable)
+    required = argsInfo.getRequiredArgs()
+    defaultDoc = 'UNDOCUMENTED'
+    args = dict.fromkeys(argsInfo.allParams, defaultDoc)
+    return args, required
+
+
+class ArgSpecGiven:
+    """
+    The message data specification (MDS) for a topic.
+    This consists of each argument name that listener should have in its
+    call protocol, plus which ones are required in any sendMessage(), and a
+    documentation string for each argument. This instance will be transformed
+    into an ArgsInfo object which is basically a superset of that information,
+    needed to ensure that the arguments specifications satisfy
+    pubsub policies for chosen API version.
+    """
+
+    SPEC_GIVEN_NONE     = 1 # specification not given
+    SPEC_GIVEN_ALL      = 3 # all args specified
+
+    def __init__(self, argsDocs=None, reqdArgs=None):
+        self.reqdArgs = tuple(reqdArgs or ())
+
+        if argsDocs is None:
+            self.argsSpecType = ArgSpecGiven.SPEC_GIVEN_NONE
+            self.argsDocs = {}
+        else:
+            self.argsSpecType = ArgSpecGiven.SPEC_GIVEN_ALL
+            self.argsDocs = argsDocs
+
+            # check that all args marked as required are in argsDocs
+            missingArgs = set(self.reqdArgs).difference(self.argsDocs)
+            if missingArgs:
+                msg = 'Params [%s] missing inherited required args [%%s]' % ','.join(argsDocs)
+                raise MessageDataSpecError(msg, missingArgs)
+
+    def setAll(self, allArgsDocs, reqdArgs = None):
+        self.argsDocs     = allArgsDocs
+        self.reqdArgs     = reqdArgs or ()
+        self.argsSpecType = ArgSpecGiven.SPEC_GIVEN_ALL
+
+    def isComplete(self):
+        """Returns True if the definition is usable, false otherwise."""
+        return self.argsSpecType == ArgSpecGiven.SPEC_GIVEN_ALL
+
+    def getOptional(self):
+        return tuple( set( self.argsDocs ).difference( self.reqdArgs ) )
+
+    def __str__(self):
+        return "%s, %s, %s" % \
+            (self.argsDocs, self.reqdArgs, self.argsSpecType)
+
+