class AstWalker(NodeVisitor): """ A walker that'll recursively progress through an AST. Given an abstract syntax tree for Python code, walk through all the nodes looking for significant types (for our purposes we only care about module starts, class definitions, function definitions, variable assignments, and function calls, as all the information we want to pass to Doxygen is found within these constructs). If the autobrief option is set, it further attempts to parse docstrings to create appropriate Doxygen tags. """ # We have a number of regular expressions that we use. They don't # vary across instances and so are compiled directly in the class # definition. __indentRE = regexpCompile(r'^(\s*)\S') __newlineRE = regexpCompile(r'^#', MULTILINE) __blanklineRE = regexpCompile(r'^\s*$') __docstrMarkerRE = regexpCompile(r"\s*([uUbB]*[rR]?(['\"]{3}))") __docstrOneLineRE = regexpCompile(r"\s*[uUbB]*[rR]?(['\"]{3})(.+)\1") __implementsRE = regexpCompile(r"^(\s*)(?:zope\.)?(?:interface\.)?" r"(?:module|class|directly)?" r"(?:Provides|Implements)\(\s*(.+)\s*\)", IGNORECASE) __interfaceRE = regexpCompile(r"^\s*class\s+(\S+)\s*\(\s*(?:zope\.)?" r"(?:interface\.)?" r"Interface\s*\)\s*:", IGNORECASE) __attributeRE = regexpCompile(r"^(\s*)(\S+)\s*=\s*(?:zope\.)?" r"(?:interface\.)?" r"Attribute\s*\(['\"]{1,3}(.*)['\"]{1,3}\)", IGNORECASE) __singleLineREs = { ' @author: ': regexpCompile(r"^(\s*Authors?:\s*)(.*)$", IGNORECASE), ' @copyright ': regexpCompile(r"^(\s*Copyright:\s*)(.*)$", IGNORECASE), ' @date ': regexpCompile(r"^(\s*Date:\s*)(.*)$", IGNORECASE), ' @file ': regexpCompile(r"^(\s*File:\s*)(.*)$", IGNORECASE), ' @version: ': regexpCompile(r"^(\s*Version:\s*)(.*)$", IGNORECASE), ' @note ': regexpCompile(r"^(\s*Note:\s*)(.*)$", IGNORECASE), ' @warning ': regexpCompile(r"^(\s*Warning:\s*)(.*)$", IGNORECASE) } __argsStartRE = regexpCompile(r"^(\s*(?:(?:Keyword\s+)?" r"(?:A|Kwa)rg(?:ument)?|Attribute)s?" r"\s*:\s*)$", IGNORECASE) __argsRE = regexpCompile(r"^\s*(?P<name>\w+)\s*(?P<type>\(?\S*\)?)?\s*" r"(?:-|:)+\s+(?P<desc>.+)$") __returnsStartRE = regexpCompile(r"^\s*(?:Return|Yield)s:\s*$", IGNORECASE) __raisesStartRE = regexpCompile(r"^\s*(Raises|Exceptions|See Also):\s*$", IGNORECASE) __listRE = regexpCompile(r"^\s*(([\w\.]+),\s*)+(&|and)?\s*([\w\.]+)$") __singleListItemRE = regexpCompile(r'^\s*([\w\.]+)\s*$') __listItemRE = regexpCompile(r'([\w\.]+),?\s*') __examplesStartRE = regexpCompile(r"^\s*(?:Example|Doctest)s?:\s*$", IGNORECASE) __sectionStartRE = regexpCompile(r"^\s*(([A-Z]\w* ?){1,2}):\s*$") # The error line should match traceback lines, error exception lines, and # (due to a weird behavior of codeop) single word lines. __errorLineRE = regexpCompile(r"^\s*((?:\S+Error|Traceback.*):?\s*(.*)|@?[\w.]+)\s*$", IGNORECASE) def __init__(self, lines, options, inFilename): """Initialize a few class variables in preparation for our walk.""" self.lines = lines self.options = options self.inFilename = inFilename self.docLines = [] @staticmethod def _stripOutAnds(inStr): """Takes a string and returns the same without ands or ampersands.""" assert isinstance(inStr, str) return inStr.replace(' and ', ' ').replace(' & ', ' ') @staticmethod def _endCodeIfNeeded(line, inCodeBlock): """Simple routine to append end code marker if needed.""" assert isinstance(line, str) if inCodeBlock: line = '# @endcode{0}{1}'.format(linesep, line.rstrip()) inCodeBlock = False return line, inCodeBlock @coroutine def _checkIfCode(self, inCodeBlock): """Checks whether or not a given line appears to be Python code.""" while True: line, lines, lineNum = (yield) testLineNum = 1 currentLineNum = 0 testLine = line.strip() lineOfCode = None while lineOfCode is None: match = AstWalker.__errorLineRE.match(testLine) if not testLine or testLine == '...' or match: # These are ambiguous. line, lines, lineNum = (yield) testLine = line.strip() #testLineNum = 1 elif testLine.startswith('>>> '): # This is definitely code. lineOfCode = True else: try: compLine = compile_command(testLine) if compLine and lines[currentLineNum].strip().startswith('#'): lineOfCode = True else: line, lines, lineNum = (yield) line = line.strip() if line.startswith('>>> '): # Definitely code, don't compile further. lineOfCode = True else: testLine += linesep + line testLine = testLine.strip() testLineNum += 1 except (SyntaxError, RuntimeError): # This is definitely not code. lineOfCode = False except Exception: # Other errors are ambiguous. line, lines, lineNum = (yield) testLine = line.strip() #testLineNum = 1 currentLineNum = lineNum - testLineNum if not inCodeBlock and lineOfCode: inCodeBlock = True lines[currentLineNum] = '{0}{1}# @code{1}'.format( lines[currentLineNum], linesep ) elif inCodeBlock and lineOfCode is False: # None is ambiguous, so strict checking # against False is necessary. inCodeBlock = False lines[currentLineNum] = '{0}{1}# @endcode{1}'.format( lines[currentLineNum], linesep ) @coroutine def __alterDocstring(self, tail='', writer=None): """ Runs eternally, processing docstring lines. Parses docstring lines as they get fed in via send, applies appropriate Doxygen tags, and passes them along in batches for writing. """ assert isinstance(tail, str) and isinstance(writer, GeneratorType) lines = [] timeToSend = False inCodeBlock = False inSection = False prefix = '' firstLineNum = -1 sectionHeadingIndent = 0 codeChecker = self._checkIfCode(False) proseChecker = self._checkIfCode(True) while True: lineNum, line = (yield) if firstLineNum < 0: firstLineNum = lineNum # Don't bother doing extra work if it's a sentinel. if line is not None: # Also limit work if we're not parsing the docstring. if self.options.autobrief: for doxyTag, tagRE in AstWalker.__singleLineREs.items(): match = tagRE.search(line) if match: # We've got a simple one-line Doxygen command lines[-1], inCodeBlock = self._endCodeIfNeeded( lines[-1], inCodeBlock) writer.send((firstLineNum, lineNum - 1, lines)) lines = [] firstLineNum = lineNum line = line.replace(match.group(1), doxyTag) timeToSend = True if inSection: # The last line belonged to a section. # Does this one too? (Ignoring empty lines.) match = AstWalker.__blanklineRE.match(line) if not match: indent = len(line.expandtabs(self.options.tablength)) - \ len(line.expandtabs(self.options.tablength).lstrip()) if indent <= sectionHeadingIndent: inSection = False else: if lines[-1] == '#': # If the last line was empty, but we're still in a section # then we need to start a new paragraph. lines[-1] = '# @par' match = AstWalker.__returnsStartRE.match(line) if match: # We've got a "returns" section line = line.replace(match.group(0), ' @return\t').rstrip() prefix = '@return\t' else: match = AstWalker.__argsStartRE.match(line) if match: # We've got an "arguments" section line = line.replace(match.group(0), '').rstrip() if 'attr' in match.group(0).lower(): prefix = '@property\t' else: prefix = '@param\t' lines[-1], inCodeBlock = self._endCodeIfNeeded( lines[-1], inCodeBlock) lines.append('#' + line) continue else: match = AstWalker.__argsRE.match(line) if match and not inCodeBlock: # We've got something that looks like an item / # description pair. if 'property' in prefix: line = '# {0}\t{1[name]}{2}# {1[desc]}'.format( prefix, match.groupdict(), linesep) else: line = ' {0}\t{1[name]}\t{1[desc]}'.format( prefix, match.groupdict()) else: match = AstWalker.__raisesStartRE.match(line) if match: line = line.replace(match.group(0), '').rstrip() if 'see' in match.group(1).lower(): # We've got a "see also" section prefix = '@sa\t' else: # We've got an "exceptions" section prefix = '@exception\t' lines[-1], inCodeBlock = self._endCodeIfNeeded( lines[-1], inCodeBlock) lines.append('#' + line) continue else: match = AstWalker.__listRE.match(line) if match and not inCodeBlock: # We've got a list of something or another itemList = [] for itemMatch in AstWalker.__listItemRE.findall(self._stripOutAnds( match.group(0))): itemList.append('# {0}\t{1}{2}'.format( prefix, itemMatch, linesep)) line = ''.join(itemList)[1:] else: match = AstWalker.__examplesStartRE.match(line) if match and lines[-1].strip() == '#' \ and self.options.autocode: # We've got an "example" section inCodeBlock = True line = line.replace(match.group(0), ' @b Examples{0}# @code'.format(linesep)) else: match = AstWalker.__sectionStartRE.match(line) if match: # We've got an arbitrary section prefix = '' inSection = True # What's the indentation of the section heading? sectionHeadingIndent = len(line.expandtabs(self.options.tablength)) \ - len(line.expandtabs(self.options.tablength).lstrip()) line = line.replace( match.group(0), ' @par {0}'.format(match.group(1)) ) if lines[-1] == '# @par': lines[-1] = '#' lines[-1], inCodeBlock = self._endCodeIfNeeded( lines[-1], inCodeBlock) lines.append('#' + line) continue elif prefix: match = AstWalker.__singleListItemRE.match(line) if match and not inCodeBlock: # Probably a single list item line = ' {0}\t{1}'.format( prefix, match.group(0)) elif self.options.autocode and inCodeBlock: proseChecker.send( ( line, lines, lineNum - firstLineNum ) ) elif self.options.autocode: codeChecker.send( ( line, lines, lineNum - firstLineNum ) ) # If we were passed a tail, append it to the docstring. # Note that this means that we need a docstring for this # item to get documented. if tail and lineNum == len(self.docLines) - 1: line = '{0}{1}# {2}'.format(line.rstrip(), linesep, tail) # Add comment marker for every line. line = '#{0}'.format(line.rstrip()) # Ensure the first line has the Doxygen double comment. if lineNum == 0: line = '#' + line lines.append(line.replace(' ' + linesep, linesep)) else: # If we get our sentinel value, send out what we've got. timeToSend = True if timeToSend: lines[-1], inCodeBlock = self._endCodeIfNeeded(lines[-1], inCodeBlock) writer.send((firstLineNum, lineNum, lines)) lines = [] firstLineNum = -1 timeToSend = False @coroutine def __writeDocstring(self): """ Runs eternally, dumping out docstring line batches as they get fed in. Replaces original batches of docstring lines with modified versions fed in via send. """ while True: firstLineNum, lastLineNum, lines = (yield) newDocstringLen = lastLineNum - firstLineNum + 1 while len(lines) < newDocstringLen: lines.append('') # Substitute the new block of lines for the original block of lines. self.docLines[firstLineNum: lastLineNum + 1] = lines def _processDocstring(self, node, tail='', **kwargs): """ Handles a docstring for functions, classes, and modules. Basically just figures out the bounds of the docstring and sends it off to the parser to do the actual work. """ typeName = type(node).__name__ # Modules don't have lineno defined, but it's always 0 for them. curLineNum = startLineNum = 0 if typeName != 'Module': startLineNum = curLineNum = node.lineno - 1 # Figure out where both our enclosing object and our docstring start. line = '' while curLineNum < len(self.lines): line = self.lines[curLineNum] match = AstWalker.__docstrMarkerRE.match(line) if match: break curLineNum += 1 docstringStart = curLineNum # Figure out where our docstring ends. if not AstWalker.__docstrOneLineRE.match(line): # Skip for the special case of a single-line docstring. curLineNum += 1 while curLineNum < len(self.lines): line = self.lines[curLineNum] if line.find(match.group(2)) >= 0: break curLineNum += 1 endLineNum = curLineNum + 1 # Isolate our enclosing object's declaration. defLines = self.lines[startLineNum: docstringStart] # Isolate our docstring. self.docLines = self.lines[docstringStart: endLineNum] # If we have a docstring, extract information from it. if self.docLines: # Get rid of the docstring delineators. self.docLines[0] = AstWalker.__docstrMarkerRE.sub('', self.docLines[0]) self.docLines[-1] = AstWalker.__docstrMarkerRE.sub('', self.docLines[-1]) # Handle special strings within the docstring. docstringConverter = self.__alterDocstring( tail, self.__writeDocstring()) for lineInfo in enumerate(self.docLines): docstringConverter.send(lineInfo) docstringConverter.send((len(self.docLines) - 1, None)) # Add a Doxygen @brief tag to any single-line description. if self.options.autobrief: safetyCounter = 0 while len(self.docLines) > 0 and self.docLines[0].lstrip('#').strip() == '': del self.docLines[0] self.docLines.append('') safetyCounter += 1 if safetyCounter >= len(self.docLines): # Escape the effectively empty docstring. break if len(self.docLines) == 1 or (len(self.docLines) >= 2 and ( self.docLines[1].strip(whitespace + '#') == '' or self.docLines[1].strip(whitespace + '#').startswith('@'))): self.docLines[0] = "## @brief {0}".format(self.docLines[0].lstrip('#')) if len(self.docLines) > 1 and self.docLines[1] == '# @par': self.docLines[1] = '#' if defLines: match = AstWalker.__indentRE.match(defLines[0]) indentStr = match and match.group(1) or '' self.docLines = [AstWalker.__newlineRE.sub(indentStr + '#', docLine) for docLine in self.docLines] # Taking away a docstring from an interface method definition sometimes # leaves broken code as the docstring may be the only code in it. # Here we manually insert a pass statement to rectify this problem. if typeName != 'Module': if docstringStart < len(self.lines): match = AstWalker.__indentRE.match(self.lines[docstringStart]) indentStr = match and match.group(1) or '' else: indentStr = '' containingNodes = kwargs.get('containingNodes', []) or [] fullPathNamespace = self._getFullPathName(containingNodes) parentType = fullPathNamespace[-2][1] if parentType == 'interface' and typeName == 'FunctionDef' \ or fullPathNamespace[-1][1] == 'interface': defLines[-1] = '{0}{1}{2}pass'.format(defLines[-1], linesep, indentStr) elif self.options.autobrief and typeName == 'ClassDef': # If we're parsing docstrings separate out class attribute # definitions to get better Doxygen output. for firstVarLineNum, firstVarLine in enumerate(self.docLines): if '@property\t' in firstVarLine: break lastVarLineNum = len(self.docLines) if '@property\t' in firstVarLine: while lastVarLineNum > firstVarLineNum: lastVarLineNum -= 1 if '@property\t' in self.docLines[lastVarLineNum]: break lastVarLineNum += 1 if firstVarLineNum < len(self.docLines): indentLineNum = endLineNum indentStr = '' while not indentStr and indentLineNum < len(self.lines): match = AstWalker.__indentRE.match(self.lines[indentLineNum]) indentStr = match and match.group(1) or '' indentLineNum += 1 varLines = ['{0}{1}'.format(linesep, docLine).replace( linesep, linesep + indentStr) for docLine in self.docLines[ firstVarLineNum: lastVarLineNum]] defLines.extend(varLines) self.docLines[firstVarLineNum: lastVarLineNum] = [] # After the property shuffling we will need to relocate # any existing namespace information. namespaceLoc = defLines[-1].find('\n# @namespace') if namespaceLoc >= 0: self.docLines[-1] += defLines[-1][namespaceLoc:] defLines[-1] = defLines[-1][:namespaceLoc] # For classes and functions, apply our changes and reverse the # order of the declaration and docstring, and for modules just # apply our changes. if typeName != 'Module': self.lines[startLineNum: endLineNum] = self.docLines + defLines else: self.lines[startLineNum: endLineNum] = defLines + self.docLines @staticmethod def _checkMemberName(name): """ See if a member name indicates that it should be private. Private variables in Python (starting with a double underscore but not ending in a double underscore) and bed lumps (variables that are not really private but are by common convention treated as protected because they begin with a single underscore) get Doxygen tags labeling them appropriately. """ assert isinstance(name, str) restrictionLevel = None if not name.endswith('__'): if name.startswith('__'): restrictionLevel = 'private' elif name.startswith('_'): restrictionLevel = 'protected' return restrictionLevel def _processMembers(self, node, contextTag): """ Mark up members if they should be private. If the name indicates it should be private or protected, apply the appropriate Doxygen tags. """ restrictionLevel = self._checkMemberName(node.name) if restrictionLevel: workTag = '{0}{1}# @{2}'.format(contextTag, linesep, restrictionLevel) else: workTag = contextTag return workTag def generic_visit(self, node, **kwargs): """ Extract useful information from relevant nodes including docstrings. This is virtually identical to the standard version contained in NodeVisitor. It is only overridden because we're tracking extra information (the hierarchy of containing nodes) not preserved in the original. """ for field, value in iter_fields(node): if isinstance(value, list): for item in value: if isinstance(item, AST): self.visit(item, containingNodes=kwargs['containingNodes']) elif isinstance(value, AST): self.visit(value, containingNodes=kwargs['containingNodes']) def visit(self, node, **kwargs): """ Visit a node and extract useful information from it. This is virtually identical to the standard version contained in NodeVisitor. It is only overridden because we're tracking extra information (the hierarchy of containing nodes) not preserved in the original. """ containingNodes = kwargs.get('containingNodes', []) method = 'visit_' + node.__class__.__name__ visitor = getattr(self, method, self.generic_visit) return visitor(node, containingNodes=containingNodes) def _getFullPathName(self, containingNodes): """ Returns the full node hierarchy rooted at module name. The list representing the full path through containing nodes (starting with the module itself) is returned. """ assert isinstance(containingNodes, list) return [(self.options.fullPathNamespace, 'module')] + containingNodes def visit_Module(self, node, **kwargs): """ Handles the module-level docstring. Process the module-level docstring and create appropriate Doxygen tags if autobrief option is set. """ if self.options.debug: stderr.write("# Module {0}{1}".format(self.options.fullPathNamespace, linesep)) if get_docstring(node): self._processDocstring(node) # Visit any contained nodes (in this case pretty much everything). self.generic_visit(node, containingNodes=kwargs.get('containingNodes', [])) def visit_Assign(self, node, **kwargs): """ Handles assignments within code. Variable assignments in Python are used to represent interface attributes in addition to basic variables. If an assignment appears to be an attribute, it gets labeled as such for Doxygen. If a variable name uses Python mangling or is just a bed lump, it is labeled as private for Doxygen. """ lineNum = node.lineno - 1 # Assignments have one Doxygen-significant special case: # interface attributes. match = AstWalker.__attributeRE.match(self.lines[lineNum]) if match: self.lines[lineNum] = '{0}## @property {1}{2}{0}# {3}{2}' \ '{0}# @hideinitializer{2}{4}{2}'.format( match.group(1), match.group(2), linesep, match.group(3), self.lines[lineNum].rstrip() ) if self.options.debug: stderr.write("# Attribute {0.id}{1}".format(node.targets[0], linesep)) if isinstance(node.targets[0], Name): match = AstWalker.__indentRE.match(self.lines[lineNum]) indentStr = match and match.group(1) or '' restrictionLevel = self._checkMemberName(node.targets[0].id) if restrictionLevel: self.lines[lineNum] = '{0}## @var {1}{2}{0}' \ '# @hideinitializer{2}{0}# @{3}{2}{4}{2}'.format( indentStr, node.targets[0].id, linesep, restrictionLevel, self.lines[lineNum].rstrip() ) # Visit any contained nodes. self.generic_visit(node, containingNodes=kwargs['containingNodes']) def visit_Call(self, node, **kwargs): """ Handles function calls within code. Function calls in Python are used to represent interface implementations in addition to their normal use. If a call appears to mark an implementation, it gets labeled as such for Doxygen. """ lineNum = node.lineno - 1 # Function calls have one Doxygen-significant special case: interface # implementations. match = AstWalker.__implementsRE.match(self.lines[lineNum]) if match: self.lines[lineNum] = '{0}## @implements {1}{2}{0}{3}{2}'.format( match.group(1), match.group(2), linesep, self.lines[lineNum].rstrip()) if self.options.debug: stderr.write("# Implements {0}{1}".format(match.group(1), linesep)) # Visit any contained nodes. self.generic_visit(node, containingNodes=kwargs['containingNodes']) def visit_FunctionDef(self, node, **kwargs): """ Handles function definitions within code. Process a function's docstring, keeping well aware of the function's context and whether or not it's part of an interface definition. """ if self.options.debug: stderr.write("# Function {0.name}{1}".format(node, linesep)) # Push either 'interface' or 'class' onto our containing nodes # hierarchy so we can keep track of context. This will let us tell # if a function is nested within another function or even if a class # is nested within a function. containingNodes = kwargs.get('containingNodes', []) or [] containingNodes.append((node.name, 'function')) if self.options.topLevelNamespace: fullPathNamespace = self._getFullPathName(containingNodes) contextTag = '.'.join(pathTuple[0] for pathTuple in fullPathNamespace) modifiedContextTag = self._processMembers(node, contextTag) tail = '@namespace {0}'.format(modifiedContextTag) else: tail = self._processMembers(node, '') if get_docstring(node): self._processDocstring(node, tail, containingNodes=containingNodes) # Visit any contained nodes. self.generic_visit(node, containingNodes=containingNodes) # Remove the item we pushed onto the containing nodes hierarchy. containingNodes.pop() def visit_ClassDef(self, node, **kwargs): """ Handles class definitions within code. Process the docstring. Note though that in Python Class definitions are used to define interfaces in addition to classes. If a class definition appears to be an interface definition tag it as an interface definition for Doxygen. Otherwise tag it as a class definition for Doxygen. """ lineNum = node.lineno - 1 # Push either 'interface' or 'class' onto our containing nodes # hierarchy so we can keep track of context. This will let us tell # if a function is a method or an interface method definition or if # a class is fully contained within another class. containingNodes = kwargs.get('containingNodes', []) or [] match = AstWalker.__interfaceRE.match(self.lines[lineNum]) if match: if self.options.debug: stderr.write("# Interface {0.name}{1}".format(node, linesep)) containingNodes.append((node.name, 'interface')) else: if self.options.debug: stderr.write("# Class {0.name}{1}".format(node, linesep)) containingNodes.append((node.name, 'class')) if self.options.topLevelNamespace: fullPathNamespace = self._getFullPathName(containingNodes) contextTag = '.'.join(pathTuple[0] for pathTuple in fullPathNamespace) tail = '@namespace {0}'.format(contextTag) else: tail = '' # Class definitions have one Doxygen-significant special case: # interface definitions. if match: contextTag = '{0}{1}# @interface {2}'.format(tail, linesep, match.group(1)) else: contextTag = tail contextTag = self._processMembers(node, contextTag) if get_docstring(node): self._processDocstring(node, contextTag, containingNodes=containingNodes) # Visit any contained nodes. self.generic_visit(node, containingNodes=containingNodes) # Remove the item we pushed onto the containing nodes hierarchy. containingNodes.pop() def parseLines(self): """Form an AST for the code and produce a new version of the source.""" inAst = parse(''.join(self.lines), self.inFilename) # Visit all the nodes in our tree and apply Doxygen tags to the source. self.visit(inAst) def getLines(self): """Return the modified file once processing has been completed.""" return linesep.join(line.rstrip() for line in self.lines)
class RE: _indentRE = regexpCompile(r'^(\s*)\S') _newlineRE = regexpCompile(r'^#', MULTILINE) _blanklineRE = regexpCompile(r'^\s*$') _docstrMarkerRE = regexpCompile(r"\s*([uUbB]*[rR]?(['\"]{3}))") _docstrOneLineRE = regexpCompile(r"\s*[uUbB]*[rR]?(['\"]{3})(.+)\1") _implementsRE = regexpCompile(r"^(\s*)(?:zope\.)?(?:interface\.)?" r"(?:module|class|directly)?" r"(?:Provides|Implements)\(\s*(.+)\s*\)", IGNORECASE) ## zope _classRE = regexpCompile(r"^\s*class\s+(\S+)\s*\((\S+)\):") _interfaceRE = regexpCompile(r"^\s*class\s+(\S+)\s*\(\s*(?:zope\.)?" r"(?:interface\.)?" r"Interface\s*\)\s*:", IGNORECASE) ## zope _attributeRE = regexpCompile(r"^(\s*)(\S+)\s*=\s*(?:zope\.)?" r"(?:interface\.)?" r"Attribute\s*\(['\"]{1,3}(.*)['\"]{1,3}\)", IGNORECASE) ## zope _singleLineREs = { ' @author: ' : regexpCompile(r"^(\s*Authors?:\s*)(.*)$", IGNORECASE), ' @copyright ': regexpCompile(r"^(\s*Copyright:\s*)(.*)$", IGNORECASE), ' @date ' : regexpCompile(r"^(\s*Date:\s*)(.*)$", IGNORECASE), ' @file ' : regexpCompile(r"^(\s*File:\s*)(.*)$", IGNORECASE), ' @version: ' : regexpCompile(r"^(\s*Version:\s*)(.*)$", IGNORECASE), ' @note ' : regexpCompile(r"^(\s*Note:\s*)(.*)$", IGNORECASE), ' @warning ' : regexpCompile(r"^(\s*Warning:\s*)(.*)$", IGNORECASE) } _argsStartRE = regexpCompile(r"^(\s*(?:(?:Keyword\s+)?" r"(?:A|Kwa)rg(?:ument)?|Attribute)s?" r"\s*:\s*)$", IGNORECASE) _argsRE = regexpCompile(r"^\s*(?P<name>\w+)\s*(?P<type>\(?\S*\)?)?\s*" r"(?:-|:)+\s+(?P<desc>.+)$") _returnsStartRE = regexpCompile(r"^\s*(?:Return|Yield)s:\s*$", IGNORECASE) _raisesStartRE = regexpCompile(r"^\s*(Raises|Exceptions|See Also):\s*$", IGNORECASE) _listRE = regexpCompile(r"^\s*(([\w\.]+),\s*)+(&|and)?\s*([\w\.]+)$") _singleListItemRE = regexpCompile(r'^\s*([\w\.]+)\s*$') _listItemRE = regexpCompile(r'([\w\.]+),?\s*') _examplesStartRE = regexpCompile(r"^\s*(?:Example|Doctest)s?:\s*$", IGNORECASE) _sectionStartRE = regexpCompile(r"^\s*(([A-Z]\w* ?){1,2}):\s*$") # The error line should match traceback lines, error exception lines, and # (due to a weird behavior of codeop) single word lines. _errorLineRE = regexpCompile(r"^\s*((?:\S+Error|Traceback.*):?\s*(.*)|@?[\w.]+)\s*$", IGNORECASE)