eric: comparison src/eric7/QScintilla/DocstringGenerator/PyDocstringGenerator.py

-:e9e7eca7efee
+:bf71ee032bb4
 """
 import re
 import collections
-from .BaseDocstringGenerator import (
+from .BaseDocstringGenerator import BaseDocstringGenerator, FunctionInfo, getIndentStr
-BaseDocstringGenerator, FunctionInfo, getIndentStr
-)
 class PyDocstringGenerator(BaseDocstringGenerator):
 """
 Class implementing a docstring generator for Python.
 """
 def __init__(self, editor):
 """
 Constructor
 @param editor reference to the editor widget
 @type Editor
 """
 super().__init__(editor)
 self.__quote3 = '"""'
 self.__quote3Alternate = "'''"
 def isFunctionStart(self, text):
 """
 Public method to test, if a text is the start of a function or method
 definition.
 @param text line of text to be tested
 @type str
 @return flag indicating that the given text starts a function or
 method definition
 @rtype bool
 """
 if isinstance(text, str):
 text = text.lstrip()
 if text.startswith(("def", "async def")):
 return True
 return False
 def hasFunctionDefinition(self, cursorPosition):
 """
 Public method to test, if the cursor is right below a function
 definition.
 @param cursorPosition current cursor position (line and column)
 @type tuple of (int, int)
 @return flag indicating cursor is right below a function definition
 @rtype bool
 """
-return (
+return self.__getFunctionDefinitionFromBelow(cursorPosition) is not None
-self.__getFunctionDefinitionFromBelow(cursorPosition) is not None
-)
 def isDocstringIntro(self, cursorPosition):
 """
 Public function to test, if the line up to the cursor position might be
 introducing a docstring.
 @param cursorPosition current cursor position (line and column)
 @type tuple of (int, int)
 @return flag indicating a potential start of a docstring
 @rtype bool
 """
 cline, cindex = cursorPosition
 lineToCursor = self.editor.text(cline)[:cindex]
 return self.__isTripleQuotesStart(lineToCursor)
 def __isTripleQuotesStart(self, text):
 """
 Private method to test, if the given text is the start of a triple
 quoted string.
 @param text text to be inspected
 @type str
 @return flag indicating a triple quote start
 @rtype bool
 """
 docstringTriggers = ('"""', 'r"""', "'''", "r'''")
 if text.lstrip() in docstringTriggers:
 return True
 return False
 def insertDocstring(self, cursorPosition, fromStart=True):
 """
 Public method to insert a docstring for the function at the cursor
 position.
 @param cursorPosition position of the cursor (line and index)
 @type tuple of (int, int)
 @param fromStart flag indicating that the editor text cursor is placed
 on the line starting the function definition
 @type bool
 """
 if fromStart:
 self.__functionStartLine = cursorPosition[0]
-docstring, insertPos, newCursorLine = (
+docstring, insertPos, newCursorLine = self.__generateDocstringFromStart()
-self.__generateDocstringFromStart()
+else:
+docstring, insertPos, newCursorLine = self.__generateDocstringFromBelow(
+cursorPosition
 )
-else:
-docstring, insertPos, newCursorLine = (
-self.__generateDocstringFromBelow(cursorPosition)
-)
 if docstring:
 self.editor.beginUndoAction()
 self.editor.insertAt(docstring, *insertPos)
 if not fromStart:
 # correct triple quote indentation if neccessary
-functionIndent = self.editor.indentation(
+functionIndent = self.editor.indentation(self.__functionStartLine)
-self.__functionStartLine)
 quoteIndent = self.editor.indentation(insertPos[0])
 # step 1: unindent quote line until indentation is zero
 while quoteIndent > 0:
 self.editor.unindent(insertPos[0])
 quoteIndent = self.editor.indentation(insertPos[0])
 # step 2: indent quote line until indentation is one greater
 # than function definition line
 while quoteIndent <= functionIndent:
 self.editor.indent(insertPos[0])
 quoteIndent = self.editor.indentation(insertPos[0])
 self.editor.endUndoAction()
 self.editor.setCursorPosition(
 newCursorLine, len(self.editor.text(newCursorLine)) - 1
 )
 def insertDocstringFromShortcut(self, cursorPosition):
 """
 Public method to insert a docstring for the function at the cursor
 position initiated via a keyboard shortcut.
 @param cursorPosition position of the cursor (line and index)
 @type tuple of (int, int)
 """
 result = self.__getFunctionDefinitionFromBelow(cursorPosition)
 if result is not None:
 self.__functionStartLine = cursorPosition[0]
 else:
 # neither after the function definition nor at the start
 # just do nothing
 return
-docstring, insertPos, newCursorLine = (
+docstring, insertPos, newCursorLine = self.__generateDocstringFromStart()
-self.__generateDocstringFromStart()
-)
 if docstring:
 self.editor.beginUndoAction()
 self.editor.insertAt(docstring, *insertPos)
 self.editor.endUndoAction()
 self.editor.setCursorPosition(
 newCursorLine, len(self.editor.text(newCursorLine)) - 1
 )
 def __getIndentationInsertString(self, text):
 """
 Private method to create the indentation string for the docstring.
 @param text text to based the indentation on
 @type str
 @return indentation string for docstring
 @rtype str
 """
 indent = getIndentStr(text)
 indentWidth = self.editor.indentationWidth()
 if indentWidth == 0:
 indentWidth = self.editor.tabWidth()
 return indent + indentWidth * " "
 #######################################################################
 ## Methods to generate the docstring when the text cursor is on the
 ## line starting the function definition.
 #######################################################################
 def __generateDocstringFromStart(self):
 """
 Private method to generate a docstring based on the cursor being
 placed on the first line of the definition.
 @return tuple containing the docstring and a tuple containing the
 insertion line and index
 @rtype tuple of (str, tuple(int, int))
 """
 result = self.__getFunctionDefinitionFromStart()
 if result:
 functionDefinition, functionDefinitionLength = result
 insertLine = self.__functionStartLine + functionDefinitionLength
 indentation = self.__getIndentationInsertString(functionDefinition)
 sep = self.editor.getLineSeparator()
 bodyStart = insertLine
-docstringList = self.__generateDocstring(
+docstringList = self.__generateDocstring('"', functionDefinition, bodyStart)
-'"', functionDefinition, bodyStart
-)
 if docstringList:
 if self.getDocstringType() == "ericdoc":
 docstringList.insert(0, self.__quote3)
 newCursorLine = insertLine + 1
 else:
 docstringList[0] = self.__quote3 + docstringList[0]
 newCursorLine = insertLine
 docstringList.append(self.__quote3)
 return (
-indentation +
+(
-"{0}{1}".format(sep, indentation).join(docstringList) +
+indentation
-sep
++ "{0}{1}".format(sep, indentation).join(docstringList)
-), (insertLine, 0), newCursorLine
++ sep
+),
+(insertLine, 0),
+newCursorLine,
+)
 return "", (0, 0), 0
 def __getFunctionDefinitionFromStart(self):
 """
 Private method to extract the function definition based on the cursor
 being placed on the first line of the definition.
 @return text containing the function definition
 @rtype str
 """
 startLine = self.__functionStartLine
 endLine = startLine + min(
-self.editor.lines() - startLine,
+self.editor.lines() - startLine, 20  # max. 20 lines of definition allowed
-20          # max. 20 lines of definition allowed
 )
 isFirstLine = True
 functionIndent = ""
 functionTextList = []
 for lineNo in range(startLine, endLine):
 text = self.editor.text(lineNo).rstrip()
 if isFirstLine:
 if not self.isFunctionStart(text):
 return None
 functionIndent = getIndentStr(text)
 isFirstLine = False
 else:
 currentIndent = getIndentStr(text)
-if (
+if currentIndent <= functionIndent or self.isFunctionStart(text):
-currentIndent <= functionIndent or
-self.isFunctionStart(text)
-):
 # no function body exists
 return None
 if text.strip() == "":
 # empty line, illegal/incomplete function definition
 return None
 if text.endswith("\\"):
 text = text[:-1]
 functionTextList.append(text)
 if text.endswith(":"):
 # end of function definition reached
 functionDefinitionLength = len(functionTextList)
 # check, if function is decorated with a supported one
 if startLine > 0:
 decoratorLine = self.editor.text(startLine - 1)
 if (
-"@classmethod" in decoratorLine or
+"@classmethod" in decoratorLine
-"@staticmethod" in decoratorLine or
+or "@staticmethod" in decoratorLine
-"pyqtSlot" in decoratorLine or          # PyQt slot
+or "pyqtSlot" in decoratorLine
-"Slot" in decoratorLine                 # PySide slot
+or "Slot" in decoratorLine  # PyQt slot  # PySide slot
 ):
 functionTextList.insert(0, decoratorLine)
 return "".join(functionTextList), functionDefinitionLength
 return None
 #######################################################################
 ## Methods to generate the docstring when the text cursor is on the
 ## line after the function definition (e.g. after a triple quote).
 #######################################################################
 def __generateDocstringFromBelow(self, cursorPosition):
 """
 Private method to generate a docstring when the gicen position is on
 the line below the end of the definition.
 @param cursorPosition position of the cursor (line and index)
 @type tuple of (int, int)
 @return tuple containing the docstring and a tuple containing the
 insertion line and index
 @rtype tuple of (str, tuple(int, int))
 """
-functionDefinition = self.__getFunctionDefinitionFromBelow(
+functionDefinition = self.__getFunctionDefinitionFromBelow(cursorPosition)
-cursorPosition)
 if functionDefinition:
-lineTextToCursor = (
+lineTextToCursor = self.editor.text(cursorPosition[0])[: cursorPosition[1]]
-self.editor.text(cursorPosition[0])[:cursorPosition[1]]
-)
 insertLine = cursorPosition[0]
 indentation = self.__getIndentationInsertString(functionDefinition)
 sep = self.editor.getLineSeparator()
 bodyStart = insertLine
-docstringList = self.__generateDocstring(
+docstringList = self.__generateDocstring('"', functionDefinition, bodyStart)
-'"', functionDefinition, bodyStart
-)
 if docstringList:
 if self.__isTripleQuotesStart(lineTextToCursor):
 if self.getDocstringType() == "ericdoc":
 docstringList.insert(0, "")
 newCursorLine = cursorPosition[0] + 1
 newCursorLine = cursorPosition[0] + 1
 else:
 docstringList[0] = self.__quote3 + docstringList[0]
 newCursorLine = cursorPosition[0]
 docstringList.append(self.__quote3)
-docstring = (
+docstring = "{0}{1}".format(sep, indentation).join(docstringList)
-"{0}{1}".format(sep, indentation).join(docstringList)
-)
 return docstring, cursorPosition, newCursorLine
 return "", (0, 0), 0
 def __getFunctionDefinitionFromBelow(self, cursorPosition):
 """
 Private method to extract the function definition based on the cursor
 being placed on the first line after the definition.
 @param cursorPosition current cursor position (line and column)
 @type tuple of (int, int)
 @return text containing the function definition
 @rtype str
 """
 startLine = cursorPosition[0] - 1
 endLine = startLine - min(startLine, 20)
 # max. 20 lines of definition allowed
 isFirstLine = True
 functionTextList = []
 for lineNo in range(startLine, endLine, -1):
 text = self.editor.text(lineNo).rstrip()
 if isFirstLine:
 if not text.endswith(":"):
 return None
 isFirstLine = False
 elif text.endswith(":") or text == "":
 return None
 if text.endswith("\\"):
 text = text[:-1]
 functionTextList.insert(0, text)
 if self.isFunctionStart(text):
 # start of function definition reached
 self.__functionStartLine = lineNo
 # check, if function is decorated with a supported one
 if lineNo > 0:
 decoratorLine = self.editor.text(lineNo - 1)
 if (
-"@classmethod" in decoratorLine or
+"@classmethod" in decoratorLine
-"@staticmethod" in decoratorLine or
+or "@staticmethod" in decoratorLine
-"pyqtSlot" in decoratorLine or          # PyQt slot
+or "pyqtSlot" in decoratorLine
-"Slot" in decoratorLine                 # PySide slot
+or "Slot" in decoratorLine  # PyQt slot  # PySide slot
 ):
 functionTextList.insert(0, decoratorLine)
 return "".join(functionTextList)
 return None
 #######################################################################
 ## Methods to generate the docstring contents.
 #######################################################################
 def __getFunctionBody(self, functionIndent, startLine):
 """
 Private method to get the function body.
 @param functionIndent indentation string of the function definition
 @type str
 @param startLine starting line for the extraction process
 @type int
 @return text containing the function body
 @rtype str
 """
 bodyList = []
 for line in range(startLine, self.editor.lines()):
 text = self.editor.text(line)
 textIndent = getIndentStr(text)
 if text.strip() == "":
 pass
 elif len(textIndent) <= len(functionIndent):
 break
 bodyList.append(text)
 return "".join(bodyList)
 def __generateDocstring(self, quote, functionDef, bodyStartLine):
 """
 Private method to generate the list of docstring lines.
 @param quote quote string
 @type str
 @param functionDef text containing the function definition
 @type str
 @param bodyStartLine starting line of the function body
 quote3replace = 3 * "'"
 elif quote == "'":
 quote3replace = 3 * '"'
 functionInfo = PyFunctionInfo()
 functionInfo.parseDefinition(functionDef, quote3, quote3replace)
 if functionInfo.hasInfo:
-functionBody = self.__getFunctionBody(functionInfo.functionIndent,
+functionBody = self.__getFunctionBody(
-bodyStartLine)
+functionInfo.functionIndent, bodyStartLine
+)
 if functionBody:
 functionInfo.parseBody(functionBody)
 docstringType = self.getDocstringType()
 return self._generateDocstringList(functionInfo, docstringType)
 return []
 class PyFunctionInfo(FunctionInfo):
 """
 Class implementing an object to extract and store function information.
 """
 def __init__(self):
 """
 Constructor
 """
 super().__init__()
 def __isCharInPairs(self, posChar, pairs):
 """
 Private method to test, if the given character position is between
 pairs of brackets or quotes.
 @param posChar character position to be tested
 @type int
 @param pairs list containing pairs of positions
 @type list of tuple of (int, int)
 @return flag indicating the position is in between
 @rtype bool
 """
-return any(posLeft < posChar < posRight
+return any(posLeft < posChar < posRight for (posLeft, posRight) in pairs)
-for (posLeft, posRight) in pairs)
 def __findQuotePosition(self, text):
 """
 Private method to find the start and end position of pairs of quotes.
 @param text text to be parsed
 @type str
 @return list of tuple with start and end position of pairs of quotes
 @rtype list of tuple of (int, int)
 @exception IndexError raised when a matching close quote is missing
 """
 pos = []
 foundLeftQuote = False
 for index, character in enumerate(text):
 if foundLeftQuote is False:
 if character in ("'", '"'):
 foundLeftQuote = True
 quote = character
 leftPos = index
 else:
 if character == quote and text[index - 1] != "\\":
 pos.append((leftPos, index))
 foundLeftQuote = False
 if foundLeftQuote:
 raise IndexError("No matching close quote at: {0}".format(leftPos))
 return pos
 def __findBracketPosition(self, text, bracketLeft, bracketRight, posQuote):
 """
 Private method to find the start and end position of pairs of brackets.
 https://stackoverflow.com/questions/29991917/
 indices-of-matching-parentheses-in-python
 @param text text to be parsed
 @type str
 @param bracketLeft character of the left bracket
 @type str
 @param bracketRight character of the right bracket
 @exception IndexError raised when a closing or opening bracket is
 missing
 """
 pos = []
 pstack = []
 for index, character in enumerate(text):
-if (
+if character == bracketLeft and not self.__isCharInPairs(index, posQuote):
-character == bracketLeft and
-not self.__isCharInPairs(index, posQuote)
-):
 pstack.append(index)
-elif (
+elif character == bracketRight and not self.__isCharInPairs(
-character == bracketRight and
+index, posQuote
-not self.__isCharInPairs(index, posQuote)
 ):
 if len(pstack) == 0:
-raise IndexError(
+raise IndexError("No matching closing parens at: {0}".format(index))
-"No matching closing parens at: {0}".format(index))
 pos.append((pstack.pop(), index))
 if len(pstack) > 0:
-raise IndexError(
+raise IndexError("No matching opening parens at: {0}".format(pstack.pop()))
-"No matching opening parens at: {0}".format(pstack.pop()))
 return pos
-def __splitArgumentToNameTypeValue(self, argumentsList,
+def __splitArgumentToNameTypeValue(self, argumentsList, quote, quoteReplace):
-quote, quoteReplace):
 """
 Private method to split some argument text to name, type and value.
 @param argumentsList list of function argument definitions
 @type list of str
 @param quote quote string to be replaced
 @type str
 @param quoteReplace quote string to replace the original
 @type str
 """
 for arg in argumentsList:
 hasType = False
 hasValue = False
 colonPosition = arg.find(":")
 equalPosition = arg.find("=")
 if equalPosition > -1:
 hasValue = True
-if (
+if colonPosition > -1 and (not hasValue or equalPosition > colonPosition):
-colonPosition > -1 and
-(not hasValue or equalPosition > colonPosition)
-):
 # exception for def foo(arg1=":")
 hasType = True
 if hasValue and hasType:
 argName = arg[0:colonPosition].strip()
-argType = arg[colonPosition + 1:equalPosition].strip()
+argType = arg[colonPosition + 1 : equalPosition].strip()
-argValue = arg[equalPosition + 1:].strip()
+argValue = arg[equalPosition + 1 :].strip()
 elif not hasValue and hasType:
 argName = arg[0:colonPosition].strip()
-argType = arg[colonPosition + 1:].strip()
+argType = arg[colonPosition + 1 :].strip()
 argValue = None
 elif hasValue and not hasType:
 argName = arg[0:equalPosition].strip()
 argType = None
-argValue = arg[equalPosition + 1:].strip()
+argValue = arg[equalPosition + 1 :].strip()
 else:
 argName = arg.strip()
 argType = None
 argValue = None
 if argValue and quote:
 # sanitize argValue with respect to quotes
 argValue = argValue.replace(quote, quoteReplace)
 self.argumentsList.append((argName, argType, argValue))
 def __splitArgumentsTextToList(self, argumentsText):
 """
 Private method to split the given arguments text into a list of
 arguments.
 This function uses a comma to separate arguments and ignores a comma in
 brackets and quotes.
 @param argumentsText text containing the list of arguments
 @type str
 @return list of individual argument texts
 @rtype list of str
 """
 argumentsList = []
 indexFindStart = 0
 indexArgStart = 0
 try:
 posQuote = self.__findQuotePosition(argumentsText)
-posRound = self.__findBracketPosition(
+posRound = self.__findBracketPosition(argumentsText, "(", ")", posQuote)
-argumentsText, "(", ")", posQuote)
+posCurly = self.__findBracketPosition(argumentsText, "{", "}", posQuote)
-posCurly = self.__findBracketPosition(
+posSquare = self.__findBracketPosition(argumentsText, "[", "]", posQuote)
-argumentsText, "{", "}", posQuote)
-posSquare = self.__findBracketPosition(
-argumentsText, "[", "]", posQuote)
 except IndexError:
 return None
 while True:
 posComma = argumentsText.find(",", indexFindStart)
 if posComma == -1:
 break
 indexFindStart = posComma + 1
 if (
-self.__isCharInPairs(posComma, posRound) or
+self.__isCharInPairs(posComma, posRound)
-self.__isCharInPairs(posComma, posCurly) or
+or self.__isCharInPairs(posComma, posCurly)
-self.__isCharInPairs(posComma, posSquare) or
+or self.__isCharInPairs(posComma, posSquare)
-self.__isCharInPairs(posComma, posQuote)
+or self.__isCharInPairs(posComma, posQuote)
 ):
 continue
 argumentsList.append(argumentsText[indexArgStart:posComma])
 indexArgStart = posComma + 1
 if indexArgStart < len(argumentsText):
 argumentsList.append(argumentsText[indexArgStart:])
 return argumentsList
 def parseDefinition(self, text, quote, quoteReplace):
 """
 Public method to parse the function definition text.
 @param text text containing the function definition
 @type str
 @param quote quote string to be replaced
 @type str
 @param quoteReplace quote string to replace the original
 @type str
 """
 self.functionIndent = getIndentStr(text)
 textList = text.splitlines()
 if textList[0].lstrip().startswith("@"):
 # first line of function definition is a decorator
 decorator = textList.pop(0).strip()
 if decorator == "@staticmethod":
 self.functionType = "staticmethod"
 elif decorator == "@classmethod":
 self.functionType = "classmethod"
-elif (
+elif re.match(r"@(PyQt[456]\.)?(QtCore\.)?pyqtSlot", decorator) or re.match(
-re.match(r"@(PyQt[456]\.)?(QtCore\.)?pyqtSlot", decorator) or
+r"@(PySide[26]\.)?(QtCore\.)?Slot", decorator
-re.match(r"@(PySide[26]\.)?(QtCore\.)?Slot", decorator)
 ):
 self.functionType = "qtslot"
 text = "".join(textList).strip()
 if text.startswith("async def "):
 self.isAsync = True
 returnType = re.search(r"->[ ]*([a-zA-Z0-9_,()\[\] ]*):$", text)
 if returnType:
 self.returnTypeAnnotated = returnType.group(1)
 textEnd = text.rfind(returnType.group(0))
 else:
 self.returnTypeAnnotated = None
 textEnd = len(text)
 positionArgumentsStart = text.find("(") + 1
-positionArgumentsEnd = text.rfind(")", positionArgumentsStart,
+positionArgumentsEnd = text.rfind(")", positionArgumentsStart, textEnd)
-textEnd)
 self.argumentsText = text[positionArgumentsStart:positionArgumentsEnd]
 argumentsList = self.__splitArgumentsTextToList(self.argumentsText)
 if argumentsList is not None:
 self.hasInfo = True
-self.__splitArgumentToNameTypeValue(
+self.__splitArgumentToNameTypeValue(argumentsList, quote, quoteReplace)
-argumentsList, quote, quoteReplace)
 functionName = (
-text[:positionArgumentsStart - 1]
+text[: positionArgumentsStart - 1]
 .replace("async def ", "")
 .replace("def ", "")
 )
 if functionName == "__init__":
 self.functionType = "constructor"
 self.visibility = "private"
 elif functionName.startswith("_"):
 self.visibility = "protected"
 else:
 self.visibility = "public"
 def parseBody(self, text):
 """
 Public method to parse the function body text.
 @param text function body text
 @type str
 """
 raiseRe = re.findall(r"[ \t]raise ([a-zA-Z0-9_]*)", text)
 if len(raiseRe) > 0:
 self.raiseList = [x.strip() for x in raiseRe]
 # remove duplicates from list while keeping it in the order
-self.raiseList = list(collections.OrderedDict.fromkeys(
+self.raiseList = list(collections.OrderedDict.fromkeys(self.raiseList))
-self.raiseList))
 yieldRe = re.search(r"[ \t]yield ", text)
 if yieldRe:
 self.hasYield = True
 returnTmpLine = ""
 for line in lineList:
 line = line.strip()
-if (
+if returnFound is False and re.match(returnPattern, line):
-returnFound is False and
-re.match(returnPattern, line)
-):
 returnFound = True
 if returnFound:
 returnTmpLine += line
 # check the integrity of line
 if returnTmpLine.endswith("\\"):
 returnTmpLine = returnTmpLine[:-1]
 continue
-self.__findBracketPosition(
+self.__findBracketPosition(returnTmpLine, "(", ")", quotePos)
-returnTmpLine, "(", ")", quotePos)
+self.__findBracketPosition(returnTmpLine, "{", "}", quotePos)
-self.__findBracketPosition(
+self.__findBracketPosition(returnTmpLine, "[", "]", quotePos)
-returnTmpLine, "{", "}", quotePos)
-self.__findBracketPosition(
-returnTmpLine, "[", "]", quotePos)
 except IndexError:
 continue
 returnValue = re.sub(returnPattern, "", returnTmpLine)
 self.returnValueInBody.append(returnValue)

Mercurial Repositories > eric / file comparison

comparison: src/eric7/QScintilla/DocstringGenerator/PyDocstringGenerator.py

src/eric7/QScintilla/DocstringGenerator/PyDocstringGenerator.py