wxPython-zombie 3.1.5.8__cp313-cp313-win_amd64.whl

wx/lib/pubsub/utils/__init__.py

@@ -0,0 +1,27 @@
+"""
+Provides utility functions and classes that are not required for using 
+pubsub but are likely to be very useful. 
+"""
+
+"""
+:copyright: Copyright since 2006 by Oliver Schoenborn, all rights reserved.
+:license: BSD, see LICENSE_BSD_Simple.txt for details.
+"""
+
+from .topictreeprinter import printTreeDocs
+
+from .notification import (
+    useNotifyByPubsubMessage, 
+    useNotifyByWriteFile, 
+    IgnoreNotificationsMixin,
+)
+
+from .exchandling import ExcPublisher
+
+__all__ = [
+    'printTreeDocs', 
+    'useNotifyByPubsubMessage', 
+    'useNotifyByWriteFile', 
+    'IgnoreNotificationsMixin',
+    'ExcPublisher'
+    ]

wx/lib/pubsub/utils/exchandling.py

@@ -0,0 +1,100 @@
+"""
+Some utility classes for exception handling of exceptions raised
+within listeners:
+
+- TracebackInfo: convenient way of getting stack trace of latest
+  exception raised. The handler can create the instance to retrieve
+  the stack trace and then log it, present it to user, etc.
+- ExcPublisher: example handler that publishes a message containing
+  traceback info
+
+:copyright: Copyright since 2006 by Oliver Schoenborn, all rights reserved.
+:license: BSD, see LICENSE_BSD_Simple.txt for details.
+
+"""
+
+
+import sys, traceback
+
+from ..core.listener import IListenerExcHandler
+
+
+class TracebackInfo:
+    """
+    Represent the traceback information for when an exception is
+    raised -- but not caught -- in a listener. The complete
+    traceback cannot be stored since this leads to circular
+    references (see docs for sys.exc_info()) which keeps
+    listeners alive even after the application is no longer
+    referring to them.
+
+    Instances of this object are given to listeners of the
+    'uncaughtExcInListener' topic as the excTraceback kwarg.
+    The instance calls sys.exc_info() to get the traceback
+    info but keeps only the following info:
+
+     * self.ExcClass: the class of exception that was raised and not caught
+     * self.excArg: the argument given to exception when raised
+     * self.traceback: list of quadruples as returned by traceback.extract_tb()
+
+    Normally you just need to call one of the two getFormatted() methods.
+    """
+    def __init__(self):
+        tmpInfo = sys.exc_info()
+        self.ExcClass = tmpInfo[0]
+        self.excArg   = tmpInfo[1]
+        # for the traceback, skip the first 3 entries, since they relate to
+        # implementation details for pubsub.
+        self.traceback = traceback.extract_tb(tmpInfo[2])[3:]
+        # help avoid circular refs
+        del tmpInfo
+
+    def getFormattedList(self):
+        """Get a list of strings as returned by the traceback module's
+        format_list() and format_exception_only() functions."""
+        tmp = traceback.format_list(self.traceback)
+        tmp.extend( traceback.format_exception_only(self.ExcClass, self.excArg) )
+        return tmp
+
+    def getFormattedString(self):
+        """Get a string similar to the stack trace that gets printed
+        to stdout by Python interpreter when an exception is not caught."""
+        return ''.join(self.getFormattedList())
+
+    def __str__(self):
+        return self.getFormattedString()
+
+
+class ExcPublisher(IListenerExcHandler):
+    """
+    Example exception handler that simply publishes the exception traceback
+    as a message of topic name given by topicUncaughtExc.
+    """
+
+    # name of the topic
+    topicUncaughtExc = 'uncaughtExcInListener'
+
+    def __init__(self, topicMgr=None):
+        """If topic manager is specified, will automatically call init().
+        Otherwise, caller must call init() after pubsub imported. See
+        pub.setListenerExcHandler()."""
+        if topicMgr is not None:
+            self.init(topicMgr)
+
+    def init(self, topicMgr):
+        """Must be called only after pubsub has been imported since this
+        handler creates a pubsub topic."""
+        obj = topicMgr.getOrCreateTopic(self.topicUncaughtExc)
+        obj.setDescription('generated when a listener raises an exception')
+        obj.setMsgArgSpec( dict(
+            listenerStr  = 'string representation of listener',
+            excTraceback = 'instance of TracebackInfo containing exception info'))
+        self.__topicObj = obj
+
+    def __call__(self, listenerID, topicObj):
+        """Handle the exception raised by given listener. Send the
+        Traceback to all subscribers of topic self.topicUncaughtExc. """
+        tbInfo = TracebackInfo()
+        self.__topicObj.publish(listenerStr=listenerID, excTraceback=tbInfo)
+
+

wx/lib/pubsub/utils/misc.py

@@ -0,0 +1,100 @@
+"""
+Provides useful functions and classes. Most useful are probably
+printTreeDocs and printTreeSpec.
+
+:copyright: Copyright since 2006 by Oliver Schoenborn, all rights reserved.
+:license: BSD, see LICENSE_BSD_Simple.txt for details.
+"""
+
+import sys
+from .. import py2and3
+
+__all__ = ('printImported', 'StructMsg', 'Callback', 'Enum' )
+
+
+def printImported():
+    """Output a list of pubsub modules imported so far"""
+    ll = sorted([mod for mod in sys.modules if mod.find('pubsub') >= 0])
+
+    py2and3.print_('\n'.join(ll))
+
+
+class StructMsg:
+    """
+    This *can* be used to package message data. Each of the keyword
+    args given at construction will be stored as a member of the 'data'
+    member of instance. E.g. "m=Message2(a=1, b='b')" would succeed
+    "assert m.data.a==1" and "assert m.data.b=='b'". However, use of
+    Message2 makes your messaging code less documented and harder to
+    debug.
+    """
+
+    def __init__(self, **kwargs):
+        class Data: pass
+        self.data = Data()
+        self.data.__dict__.update(kwargs)
+
+
+class Callback:
+    """This can be used to wrap functions that are referenced by class
+    data if the data should be called as a function. E.g. given
+    >>> def func(): pass
+    >>> class A:
+    ....def __init__(self): self.a = func
+    then doing
+    >>> boo=A(); boo.a()
+    will fail since Python will try to call a() as a method of boo,
+    whereas a() is a free function. But if you have instead
+    "self.a = Callback(func)", then "boo.a()" works as expected.
+    """
+    def __init__(self, callable_):
+        self.__callable = callable_
+    def __call__(self, *args, **kwargs):
+        return self.__callable(*args, **kwargs)
+
+
+class Enum:
+    """Used only internally. Represent one value out of an enumeration
+    set.  It is meant to be used as::
+
+        class YourAllowedValues:
+            enum1 = Enum()
+            # or:
+            enum2 = Enum(value)
+            # or:
+            enum3 = Enum(value, 'descriptionLine1')
+            # or:
+            enum3 = Enum(None, 'descriptionLine1', 'descriptionLine2', ...)
+
+        val = YourAllowedValues.enum1
+        ...
+        if val is YourAllowedValues.enum1:
+            ...
+    """
+    nextValue = 0
+    values = set()
+
+    def __init__(self, value=None, *desc):
+        """Use value if given, otherwise use next integer."""
+        self.desc = '\n'.join(desc)
+        if value is None:
+            assert Enum.nextValue not in Enum.values
+            self.value = Enum.nextValue
+            Enum.values.add(self.value)
+
+            Enum.nextValue += 1
+            # check that we haven't run out of integers!
+            if Enum.nextValue == 0:
+                raise RuntimeError('Ran out of enumeration values?')
+
+        else:
+            try:
+                value + Enum.nextValue
+                raise ValueError('Not allowed to assign integer to enumerations')
+            except TypeError:
+                pass
+            self.value = value
+            if self.value not in Enum.values:
+                Enum.values.add(self.value)
+
+

wx/lib/pubsub/utils/notification.py

@@ -0,0 +1,331 @@
+"""
+Provide an interface class for handling pubsub notification messages, 
+and an example class (though very useful in practice) showing how to 
+use it. 
+
+Notification messages are generated by pubsub
+
+- if a handler has been configured via pub.addNotificationHandler()
+- when pubsub does certain tasks, such as when a listener subscribes to
+  or unsubscribes from a topic
+  
+Derive from this class to handle notification events from 
+various parts of pubsub. E.g. when a listener subscribes, 
+unsubscribes, or dies, a notification handler, if you 
+specified one via pub.addNotificationHandler(), is given the 
+relevant information. 
+
+:copyright: Copyright since 2006 by Oliver Schoenborn, all rights reserved.
+:license: BSD, see LICENSE_BSD_Simple.txt for details.
+"""
+
+from ..core import callables
+from ..core.notificationmgr import INotificationHandler
+
+
+class IgnoreNotificationsMixin(INotificationHandler):
+    """
+    Derive your Notifications handler from this class if your handler
+    just wants to be notified of one or two types of pubsub events.
+    Then just override the desired methods. The rest of the notifications
+    will automatically be ignored.
+    """
+    
+    def notifySubscribe(self, pubListener, topicObj, newSub):
+        pass
+    def notifyUnsubscribe(self, pubListener, topicObj):
+        pass
+    def notifyDeadListener(self, pubListener, topicObj):
+        pass
+    def notifySend(self, stage, topicObj, pubListener=None):
+        pass
+
+    def notifyNewTopic(self, topicObj, description, required, argsDocs):
+        pass
+    def notifyDelTopic(self, topicName):
+        pass
+
+
+class NotifyByWriteFile(INotificationHandler):
+    """
+    Print a message to stdout when a notification is received. 
+    """
+
+    defaultPrefix = 'PUBSUB:'
+    
+    def __init__(self, fileObj = None, prefix = None):
+        """Will write to stdout unless fileObj given. Will use
+        defaultPrefix as prefix for each line output, unless prefix
+        specified. """
+        self.__pre = prefix or self.defaultPrefix
+
+        if fileObj is None:
+            import sys
+            self.__fileObj = sys.stdout
+        else:
+            self.__fileObj = fileObj
+
+    def changeFile(self, fileObj):
+        self.__fileObj = fileObj
+        
+    def notifySubscribe(self, pubListener, topicObj, newSub):
+        if newSub:
+            msg = '%s Subscribed listener "%s" to topic "%s"\n'
+        else:
+            msg = '%s Subscription of "%s" to topic "%s" redundant\n'
+        msg = msg % (self.__pre, pubListener, topicObj.getName())
+        self.__fileObj.write(msg)
+
+    def notifyUnsubscribe(self, pubListener, topicObj):
+        msg = '%s Unsubscribed listener "%s" from topic "%s"\n'
+        msg = msg % (self.__pre, pubListener, topicObj.getName())
+        self.__fileObj.write(msg)
+
+    def notifyDeadListener(self, pubListener, topicObj):
+        msg = '%s Listener "%s" of Topic "%s" has died\n' \
+            % (self.__pre, pubListener, topicObj.getName())
+        # a bug apparently: sometimes on exit, the stream gets closed before
+        # and leads to a TypeError involving NoneType
+        self.__fileObj.write(msg)
+
+    def notifySend(self, stage, topicObj, pubListener=None):
+        if stage == 'in':
+            msg = '%s Sending message of topic "%s" to listener %s\n' % (self.__pre, topicObj.getName(), pubListener)
+        elif stage == 'pre':
+            msg = '%s Start sending message of topic "%s"\n' % (self.__pre, topicObj.getName())
+        else:
+            msg = '%s Done sending message of topic "%s"\n' % (self.__pre, topicObj.getName())
+        self.__fileObj.write(msg)
+    
+    def notifyNewTopic(self, topicObj, description, required, argsDocs):
+        msg = '%s New topic "%s" created\n' % (self.__pre, topicObj.getName())
+        self.__fileObj.write(msg)
+
+    def notifyDelTopic(self, topicName):
+        msg = '%s Topic "%s" destroyed\n' % (self.__pre, topicName)
+        self.__fileObj.write(msg)
+
+
+class NotifyByPubsubMessage(INotificationHandler):
+    """
+    Handle pubsub notification messages by generating
+    messages of a 'pubsub.' subtopic. Also provides
+    an example of how to create a notification handler.  
+    
+    Use it by calling::
+    
+        import pubsub.utils
+        pubsub.utils.useNotifyByPubsubMessage()
+        ...
+        pub.setNotificationFlags(...) # optional
+        
+    E.g. whenever a listener is unsubscribed, a 'pubsub.unsubscribe'
+    message is generated. If you have subscribed a listener of 
+    this topic, your listener will be notified of what listener 
+    unsubscribed from what topic. 
+    """
+    
+    topicRoot = 'pubsub'
+
+    topics = dict(
+        send         = '%s.sendMessage'  % topicRoot,
+        subscribe    = '%s.subscribe'    % topicRoot,
+        unsubscribe  = '%s.unsubscribe'  % topicRoot,
+        newTopic     = '%s.newTopic'     % topicRoot,
+        delTopic     = '%s.delTopic'     % topicRoot,
+        deadListener = '%s.deadListener' % topicRoot)
+    
+    def __init__(self, topicMgr=None):
+        self._pubTopic = None
+        self.__sending = False # used to guard against infinite loop
+        if topicMgr is not None:
+            self.createNotificationTopics(topicMgr)
+        
+    def createNotificationTopics(self, topicMgr):
+        """Create the notification topics. The root of the topics created
+        is self.topicRoot. The topicMgr is (usually) pub.topicMgr."""
+        # see if the special topics have already been defined
+        try:
+            topicMgr.getTopic(self.topicRoot)
+            
+        except ValueError:
+            # no, so create them
+            self._pubTopic = topicMgr.getOrCreateTopic(self.topicRoot)
+            self._pubTopic.setDescription('root of all pubsub-specific topics')
+            
+            _createTopics(self.topics, topicMgr)
+    
+    def notifySubscribe(self, pubListener, topicObj, newSub):
+        if (self._pubTopic is None) or self.__sending:
+            return
+    
+        pubTopic = self._pubTopic.getSubtopic('subscribe')
+        if topicObj is not pubTopic:
+            kwargs = dict(listener=pubListener, topic=topicObj, newSub=newSub)
+            self.__doNotification(pubTopic, kwargs)
+
+    def notifyUnsubscribe(self, pubListener, topicObj):
+        if (self._pubTopic is None) or self.__sending:
+            return
+    
+        pubTopic = self._pubTopic.getSubtopic('unsubscribe')
+        if topicObj is not pubTopic:
+            kwargs = dict(
+                topic       = topicObj, 
+                listenerRaw = pubListener.getCallable(), 
+                listener    = pubListener)
+            self.__doNotification(pubTopic, kwargs)
+    
+    def notifyDeadListener(self, pubListener, topicObj):
+        if (self._pubTopic is None) or self.__sending:
+            return
+
+        pubTopic = self._pubTopic.getSubtopic('deadListener')
+        kwargs = dict(topic=topicObj, listener=pubListener)
+        self.__doNotification(pubTopic, kwargs)
+
+    def notifySend(self, stage, topicObj, pubListener=None):
+        """Stage must be 'pre' or 'post'. Note that any pubsub sendMessage
+        operation resulting from this notification (which sends a message; 
+        listener could handle by sending another message!) will NOT themselves
+        lead to a send notification. """
+        if (self._pubTopic is None) or self.__sending:
+            return
+    
+        sendMsgTopic = self._pubTopic.getSubtopic('sendMessage')
+        if stage == 'pre' and (topicObj is sendMsgTopic):
+                msg = 'Not allowed to send messages of topic %s' % topicObj.getName()
+                raise ValueError(msg)
+
+        self.__doNotification(sendMsgTopic, dict(topic=topicObj, stage=stage))
+    
+    def notifyNewTopic(self, topicObj, desc, required, argsDocs):
+        if (self._pubTopic is None) or self.__sending:
+            return
+    
+        pubTopic = self._pubTopic.getSubtopic('newTopic')
+        kwargs = dict(topic=topicObj, description=desc, required=required, args=argsDocs)
+        self.__doNotification(pubTopic, kwargs)
+    
+    def notifyDelTopic(self, topicName):
+        if (self._pubTopic is None) or self.__sending:
+            return
+    
+        pubTopic = self._pubTopic.getSubtopic('delTopic')
+        self.__doNotification(pubTopic, dict(name=topicName) )
+
+    def __doNotification(self, pubTopic, kwargs):
+        self.__sending = True
+        try:
+            pubTopic.publish( **kwargs )
+        finally:
+            self.__sending = False
+
+
+def _createTopics(topicMap, topicMgr):
+    """
+    Create notification topics. These are used when 
+    some of the notification flags have been set to True (see
+    pub.setNotificationFlags(). The topicMap is a dict where key is 
+    the notification type, and value is the topic name to create.
+    Notification type is a string in ('send', 'subscribe', 
+    'unsubscribe', 'newTopic', 'delTopic', 'deadListener'. 
+    """
+    def newTopic(_name, _desc, _required=None, **argsDocs):
+        topic = topicMgr.getOrCreateTopic(_name)
+        topic.setDescription(_desc)
+        topic.setMsgArgSpec(argsDocs, _required)
+
+    newTopic(
+        _name = topicMap['subscribe'], 
+        _desc = 'whenever a listener is subscribed to a topic',
+        topic = 'topic that listener has subscribed to',
+        listener = 'instance of pub.Listener containing listener', 
+        newSub = 'false if listener was already subscribed, true otherwise')
+        
+    newTopic(
+        _name = topicMap['unsubscribe'], 
+        _desc = 'whenever a listener is unsubscribed from a topic',
+        topic = 'instance of Topic that listener has been unsubscribed from',
+        listener = 'instance of pub.Listener unsubscribed; None if listener not found',
+        listenerRaw = 'listener unsubscribed')
+        
+    newTopic(
+        _name = topicMap['send'], 
+        _desc = 'sent at beginning and end of sendMessage()',
+        topic = 'instance of topic for message being sent',
+        stage = 'stage of send operation: "pre" or "post" or "in"',
+        listener = 'which listener being sent to')
+        
+    newTopic(
+        _name = topicMap['newTopic'],
+        _desc = 'whenever a new topic is defined', 
+        topic       = 'instance of Topic created',
+        description = 'description of topic (use)',
+        args        = 'the argument names/descriptions for arguments that listeners must accept',
+        required    = 'which args are required (all others are optional)')
+        
+    newTopic(
+        _name = topicMap['delTopic'],
+        _desc = 'whenever a topic is deleted',
+        name  = 'full name of the Topic instance that was destroyed')
+        
+    newTopic(
+        _name = topicMap['deadListener'], 
+        _desc = 'whenever a listener dies without having unsubscribed',
+        topic = 'instance of Topic that listener was subscribed to',
+        listener = 'instance of pub.Listener containing dead listener')
+
+
+def useNotifyByPubsubMessage(publisher=None, all=True, **kwargs):
+    """Will cause all of pubsub's notifications of pubsub "actions" (such as
+    new topic created, message sent, listener subscribed, etc) to be sent
+    out as messages. Topic will be 'pubsub' subtopics, such as
+    'pubsub.newTopic', 'pubsub.delTopic', 'pubsub.sendMessage', etc.
+
+    The 'all' and kwargs args are the same as pubsub's setNotificationFlags(), 
+    except that 'all' defaults to True.
+    
+    The publisher is rarely needed:
+
+    * The publisher must be specfied if pubsub is not installed
+      on the system search path (ie from pubsub import ... would fail or
+      import wrong pubsub -- such as if pubsub is within wxPython's
+      wx.lib package). Then pbuModule is the pub module to use::
+
+        from wx.lib.pubsub import pub
+        from wx.lib.pubsub.utils import notification
+        notification.useNotifyByPubsubMessage()
+
+    """
+    if publisher is None:
+        from .. import pub
+        publisher = pub.getDefaultPublisher()
+    topicMgr = publisher.getTopicMgr()
+    notifHandler = NotifyByPubsubMessage( topicMgr )
+    
+    publisher.addNotificationHandler(notifHandler)
+    publisher.setNotificationFlags(all=all, **kwargs)
+
+
+def useNotifyByWriteFile(fileObj=None, prefix=None, 
+    publisher=None, all=True, **kwargs):
+    """Will cause all pubsub notifications of pubsub "actions" (such as
+    new topic created, message sent, listener died etc) to be written to
+    specified file (or stdout if none given). The fileObj need only
+    provide a 'write(string)' method.
+    
+    The first two arguments are the same as those of NotifyByWriteFile
+    constructor. The 'all' and kwargs arguments are those of pubsub's
+    setNotificationFlags(), except that 'all' defaults to True.  See
+    useNotifyByPubsubMessage() for an explanation of pubModule (typically
+    only if pubsub inside wxPython's wx.lib)"""
+    notifHandler = NotifyByWriteFile(fileObj, prefix)
+
+    if publisher is None:
+        from .. import pub
+        publisher = pub.getDefaultPublisher()
+    publisher.addNotificationHandler(notifHandler)
+    publisher.setNotificationFlags(all=all, **kwargs)
+
+