wxPython 4.3.2__cp315-cp315-win_amd64.whl

wx/lib/pubsub/utils/topictreeprinter.py

@@ -0,0 +1,195 @@
+"""
+Output various aspects of topic tree to string or file.
+
+:copyright: Copyright since 2006 by Oliver Schoenborn, all rights reserved.
+:license: BSD, see LICENSE_BSD_Simple.txt for details.
+"""
+
+from textwrap import TextWrapper
+
+from ..core.topictreetraverser import (ITopicTreeVisitor, TopicTreeTraverser)
+
+
+class TopicTreePrinter(ITopicTreeVisitor):
+    """
+    Example topic tree visitor that prints a prettified representation
+    of topic tree by doing a depth-first traversal of topic tree and
+    print information at each (topic) node of tree. Extra info to be
+    printed is specified via the 'extra' kwarg. Its value must be a
+    list of characters, the order determines output order:
+    - D: print description of topic
+    - a: print kwarg names only
+    - A: print topic kwargs and their description
+    - L: print listeners currently subscribed to topic
+
+    E.g. TopicTreePrinter(extra='LaDA') would print, for each topic,
+    the list of subscribed listeners, the topic's list of kwargs, the
+    topic description, and the description for each kwarg,
+
+        >>> Topic "delTopic"
+           >> Listeners:
+              > listener1_2880 (from yourModule)
+              > listener2_3450 (from yourModule)
+           >> Names of Message arguments:
+              > arg1
+              > arg2
+           >> Description: whenever a topic is deleted
+           >> Descriptions of Message arguments:
+              > arg1: (required) its description
+              > arg2: some other description
+
+    """
+
+    allowedExtras = frozenset('DAaL') # must NOT change
+    ALL_TOPICS_NAME = 'ALL_TOPICS'    # output for name of 'all topics' topic
+
+    def __init__(self, extra=None, width=70, indentStep=4,
+        bulletTopic='\\--', bulletTopicItem='|==', bulletTopicArg='-', fileObj=None):
+        """Topic tree printer will print listeners for each topic only
+        if printListeners is True. The width will be used to limit
+        the width of text output, while indentStep is the number of
+        spaces added each time the text is indented further. The
+        three bullet parameters define the strings used for each
+        item (topic, topic items, and kwargs). """
+        self.__contentMeth = dict(
+            D = self.__printTopicDescription,
+            A = self.__printTopicArgsAll,
+            a = self.__printTopicArgNames,
+            L = self.__printTopicListeners)
+        assert self.allowedExtras == set(self.__contentMeth)
+        import sys
+        self.__destination = fileObj or sys.stdout
+        self.__output = []
+
+        self.__content = extra or ''
+        unknownSel = set(self.__content) - self.allowedExtras
+        if unknownSel:
+            msg = 'These extra chars not known: %s' % ','.join(unknownSel)
+            raise ValueError(msg)
+
+        self.__width   = width
+        self.__wrapper = TextWrapper(width)
+        self.__indent  = 0
+        self.__indentStep = indentStep
+        self.__topicsBullet     = bulletTopic
+        self.__topicItemsBullet = bulletTopicItem
+        self.__topicArgsBullet  = bulletTopicArg
+
+    def getOutput(self):
+        return '\n'.join( self.__output )
+
+    def _doneTraversal(self):
+        if self.__destination is not None:
+            self.__destination.write(self.getOutput())
+
+    def _onTopic(self, topicObj):
+        """This gets called for each topic. Print as per specified content."""
+
+        # topic name
+        self.__wrapper.width = self.__width
+        indent = self.__indent
+        if topicObj.isAll():
+            topicName = self.ALL_TOPICS_NAME
+        else:
+            topicName = topicObj.getNodeName()
+        head = '%s Topic "%s"' % (self.__topicsBullet, topicName)
+        self.__output.append( self.__formatDefn(indent, head) )
+        indent += self.__indentStep
+
+        # each extra content (assume constructor verified that chars are valid)
+        for item in self.__content:
+            function = self.__contentMeth[item]
+            function(indent, topicObj)
+
+    def _startChildren(self):
+        """Increase the indent"""
+        self.__indent += self.__indentStep
+
+    def _endChildren(self):
+        """Decrease the indent"""
+        self.__indent -= self.__indentStep
+
+    def __formatDefn(self, indent, item, defn='', sep=': '):
+        """Print a definition: a block of text at a certain indent,
+        has item name, and an optional definition separated from
+        item by sep. """
+        if defn:
+            prefix = '%s%s%s' % (' '*indent, item, sep)
+            self.__wrapper.initial_indent = prefix
+            self.__wrapper.subsequent_indent = ' '*(indent+self.__indentStep)
+            return self.__wrapper.fill(defn)
+        else:
+            return '%s%s' % (' '*indent, item)
+
+    def __printTopicDescription(self, indent, topicObj):
+        # topic description
+        defn = '%s Description' % self.__topicItemsBullet
+        self.__output.append(
+            self.__formatDefn(indent, defn, topicObj.getDescription()) )
+
+    def __printTopicArgsAll(self, indent, topicObj, desc=True):
+        # topic kwargs
+        args = topicObj.getArgDescriptions()
+        if args:
+            #required, optional, complete = topicObj.getArgs()
+            headName = 'Names of Message arguments:'
+            if desc:
+                headName = 'Descriptions of message arguments:'
+            head = '%s %s' % (self.__topicItemsBullet, headName)
+            self.__output.append( self.__formatDefn(indent, head) )
+            tmpIndent = indent + self.__indentStep
+            required = topicObj.getArgs()[0]
+            for key, arg in args.items(): # iter in 3, list in 2 ok
+                if not desc:
+                    arg = ''
+                elif key in required:
+                    arg = '(required) %s' % arg
+                msg = '%s %s' % (self.__topicArgsBullet,key)
+                self.__output.append( self.__formatDefn(tmpIndent, msg, arg) )
+
+    def __printTopicArgNames(self, indent, topicObj):
+        self.__printTopicArgsAll(indent, topicObj, False)
+
+    def __printTopicListeners(self, indent, topicObj):
+        if topicObj.hasListeners():
+            item = '%s Listeners:' % self.__topicItemsBullet
+            self.__output.append( self.__formatDefn(indent, item) )
+            tmpIndent = indent + self.__indentStep
+            for listener in topicObj.getListenersIter():
+                item = '%s %s (from %s)' % (self.__topicArgsBullet, listener.name(), listener.module())
+                self.__output.append( self.__formatDefn(tmpIndent, item) )
+
+
+def printTreeDocs(rootTopic=None, topicMgr=None, **kwargs):
+    """Print out the topic tree to a file (or file-like object like a
+    StringIO), starting at rootTopic. If root topic should be root of
+    whole tree, get it from pub.getDefaultTopicTreeRoot().
+    The treeVisitor is an instance of pub.TopicTreeTraverser.
+
+    Printing the tree docs would normally involve this::
+
+        from pubsub import pub
+        from pubsub.utils.topictreeprinter import TopicTreePrinter
+        traverser = pub.TopicTreeTraverser( TopicTreePrinter(**kwargs) )
+        traverser.traverse( pub.getDefaultTopicTreeRoot() )
+
+    With printTreeDocs, it looks like this::
+
+        from pubsub import pub
+        from pubsub.utils import printTreeDocs
+        printTreeDocs()
+
+    The kwargs are the same as for TopicTreePrinter constructor:
+    extra(None), width(70), indentStep(4), bulletTopic, bulletTopicItem,
+    bulletTopicArg, fileObj(stdout). If fileObj not given, stdout is used."""
+    if rootTopic is None:
+        if topicMgr is None:
+            from .. import pub
+            topicMgr = pub.getDefaultTopicMgr()
+        rootTopic = topicMgr.getRootAllTopics()
+
+    printer = TopicTreePrinter(**kwargs)
+    traverser = TopicTreeTraverser(printer)
+    traverser.traverse(rootTopic)
+
+

wx/lib/pubsub/utils/xmltopicdefnprovider.py

@@ -0,0 +1,286 @@
+"""
+Contributed by Joshua R English, adapted by Oliver Schoenborn to be
+consistent with pubsub API.
+
+An extension for pubsub (http://pubsub.sourceforge.net) so topic tree
+specification can be encoded in XML format rather than pubsub's default
+Python nested class format.
+
+To use:
+
+    xml = '''
+        <topicdefntree>
+        <description>Test showing topic hierarchy and inheritance</description>
+        <topic id="parent">
+            <description>Parent with a parameter and subtopics</description>
+            <listenerspec>
+                <arg id="name" optional="true">given name</arg>
+                <arg id="lastname">surname</arg>
+            </listenerspec>
+
+            <topic id="child">
+                <description>This is the first child</description>
+                <listenerspec>
+                    <arg id="nick">A nickname</arg>
+                </listenerspec>
+            </topic>
+        </topic>
+        </topicdefntree>
+    '''
+
+These topic definitions are loaded through an XmlTopicDefnProvider:
+
+    pub.addTopicDefnProvider( XmlTopicDefnProvider(xml) )
+
+The XmlTopicDefnProvider also accepts a filename instead of XML string:
+
+    provider = XmlTopicDefnProvider("path/to/XMLfile.xml", TOPIC_TREE_FROM_FILE)
+    pub.addTopicDefnProvider( provider )
+
+Topics can be exported to an XML file using the exportTopicTreeSpecXml function.
+This will create a text file for the XML and return the string representation
+of the XML tree.
+
+:copyright: Copyright since 2013 by Oliver Schoenborn, all rights reserved.
+:license: BSD, see LICENSE_BSD_Simple.txt for details.
+"""
+
+__author__ = 'Joshua R English'
+__revision__ = 6
+__date__ = '2013-07-27'
+
+
+from ..core.topictreetraverser import ITopicTreeVisitor
+from ..core.topicdefnprovider import (
+    ITopicDefnProvider,
+    ArgSpecGiven,
+    TOPIC_TREE_FROM_STRING,
+    )
+
+try:
+    from elementtree import ElementTree as ET
+except ImportError:
+    try: # for Python 2.4, must use cElementTree:
+        from xml.etree import ElementTree as ET
+    except ImportError:
+        from cElementTree import ElementTree as ET
+
+__all__ = [
+    'XmlTopicDefnProvider',
+    'exportTopicTreeSpecXml',
+    'TOPIC_TREE_FROM_FILE'
+    ]
+
+
+def _get_elem(elem):
+    """Assume an ETree.Element object or a string representation.
+    Return the ETree.Element object"""
+    if not ET.iselement(elem):
+        try:
+            elem = ET.fromstring(elem)
+        except:
+            print("Value Error", elem)
+            raise ValueError("Cannot convert to element")
+    return elem
+
+
+TOPIC_TREE_FROM_FILE = 'file'
+
+
+class XmlTopicDefnProvider(ITopicDefnProvider):
+
+    class XmlParserError(RuntimeError): pass
+
+    class UnrecognizedSourceFormatError(ValueError): pass
+
+    def __init__(self, xml, format=TOPIC_TREE_FROM_STRING):
+        self._topics = {}
+        self._treeDoc = ''
+        if format == TOPIC_TREE_FROM_FILE:
+            with open(xml, mode="r") as fid:
+                self._parse_tree(_get_elem(fid.read()))
+        elif format == TOPIC_TREE_FROM_STRING:
+            self._parse_tree(_get_elem(xml))
+        else:
+            raise UnrecognizedSourceFormatError()
+
+    def _parse_tree(self, tree):
+        doc_node = tree.find('description')
+
+        if doc_node is None:
+            self._treeDoc = "UNDOCUMENTED"
+        else:
+            self._treeDoc = ' '.join(doc_node.text.split())
+
+        for node in tree.findall('topic'):
+            self._parse_topic(node)
+
+    def _parse_topic(self, node, parents=None, specs=None, reqlist=None):
+        parents = parents or []
+        specs = specs or {}
+        reqlist = reqlist or []
+
+        descNode = node.find('description')
+
+        if descNode is None:
+            desc = "UNDOCUMENTED"
+        else:
+            desc = ' '.join(descNode.text.split())
+
+        node_id = node.get('id')
+        if node_id is None:
+            raise XmlParserError("topic element must have an id attribute")
+
+        for this in (node.findall('listenerspec/arg')):
+            this_id = this.get('id')
+            if this_id is None:
+                raise XmlParserError("arg element must have an id attribute")
+
+            this_desc = this.text.strip()
+            this_desc = this_desc or "UNDOCUMENTED"
+            this_desc = ' '.join(this_desc.split())
+
+            specs[this_id] = this_desc
+
+            if this.get('optional', '').lower() not in ['true', 't','yes','y']:
+                reqlist.append(this_id)
+
+        defn = ArgSpecGiven(specs, tuple(reqlist))
+
+        parents.append(node.get('id'))
+
+        self._topics[tuple(parents)] = desc, defn
+
+        for subtopic in node.findall('topic'):
+            self._parse_topic(subtopic, parents[:], specs.copy(), reqlist[:])
+
+
+    def getDefn(self, topicNameTuple):
+        return self._topics.get(topicNameTuple, (None, None))
+
+    def topicNames(self):
+        return iter(self._topics.keys())
+
+    def getTreeDoc(self):
+        return self._treeDoc
+
+
+class XmlVisitor(ITopicTreeVisitor):
+    def __init__(self, elem):
+        self.tree = elem
+        self.known_topics = []
+
+    def _startTraversal(self):
+        self.roots = [self.tree]
+
+    def _onTopic(self, topicObj):
+        if topicObj.isAll():
+            self.last_elem = self.tree
+            return
+        if self.roots:
+            this_elem = ET.SubElement(self.roots[-1], 'topic',
+                {'id':topicObj.getNodeName()})
+        else:
+            this_elem = ET.Element('topic', {'id':topicObj.getNodeName()})
+        req, opt = topicObj.getArgs()
+        req = req or ()
+        opt = opt or ()
+        desc_elem = ET.SubElement(this_elem, 'description')
+        topicDesc = topicObj.getDescription()
+        if topicDesc:
+            desc_elem.text = ' '.join(topicDesc.split())
+        else:
+            desc_elem.text = "UNDOCUMENTED"
+        argDescriptions = topicObj.getArgDescriptions()
+
+        # pubsub way of getting known_args
+        known_args = []
+        parent = topicObj.getParent()
+        while parent:
+            if parent in self.known_topics:
+                p_req, p_opt = parent.getArgs()
+                if p_req:
+                    known_args.extend(p_req)
+                if p_opt:
+                    known_args.extend(p_opt)
+            parent = parent.getParent()
+
+        # there is probably a cleaner way to do this
+        if req or opt:
+            spec = ET.SubElement(this_elem, 'listenerspec')
+            for arg in req:
+                if arg in known_args:
+                    continue
+                arg_elem = ET.SubElement(spec, 'arg', {'id': arg})
+                arg_elem.text = ' '.join(argDescriptions.get(arg, 'UNDOCUMENTED').split())
+            for arg in opt:
+                if arg in known_args:
+                    continue
+                arg_elem = ET.SubElement(spec, 'arg', {'id': arg, 'optional':'True'})
+                arg_elem.text = ' '.join(argDescriptions.get(arg, 'UNDOCUMENTED').split())
+
+        self.last_elem = this_elem
+        self.known_topics.append(topicObj)
+
+    def _startChildren(self):
+        self.roots.append(self.last_elem)
+
+    def _endChildren(self):
+        self.roots.pop()
+
+
+## http://infix.se/2007/02/06/gentlemen-indent-your-xml
+def indent(elem, level=0):
+    i = "\n" + level*"    "
+    if len(elem):
+        if not elem.text or not elem.text.strip():
+            elem.text = i + "  "
+        for e in elem:
+            indent(e, level+1)
+            if not e.tail or not e.tail.strip():
+                e.tail = i + "  "
+        if not e.tail or not e.tail.strip():
+            e.tail = i
+    else:
+        if level and (not elem.tail or not elem.tail.strip()):
+            elem.tail = i
+        else:
+            elem.tail="\n"
+
+
+def exportTopicTreeSpecXml(moduleName=None, rootTopic=None, bak='bak', moduleDoc=None):
+    """
+    If rootTopic is None, then pub.getDefaultTopicTreeRoot() is assumed.
+    """
+
+    if rootTopic is None:
+        from .. import pub
+        rootTopic = pub.getDefaultTopicTreeRoot()
+    elif isinstance(rootTopic, str):
+        from .. import pub
+        rootTopic = pub.getTopic(rootTopic)
+
+    tree = ET.Element('topicdefntree')
+    if moduleDoc:
+        mod_desc = ET.SubElement(tree, 'description')
+        mod_desc.text = ' '.join(moduleDoc.split())
+
+    traverser = pub.TopicTreeTraverser(XmlVisitor(tree))
+    traverser.traverse(rootTopic)
+
+    indent(tree)
+
+    if moduleName:
+
+        filename = '%s.xml' % moduleName
+        if bak:
+            pub._backupIfExists(filename, bak)
+
+        fulltree= ET.ElementTree(tree)
+        fulltree.write(filename, "utf-8", True)
+
+    return ET.tostring(tree)
+
+
+
+