Mercurial Repositories > eric / file comparison
comparison: eric6/QScintilla/DocstringGenerator/BaseDocstringGenerator.py
eric6/QScintilla/DocstringGenerator/BaseDocstringGenerator.py
- changeset 7998
- cd41c844862f
- child 8000
- 47b15df088e4
equal
deleted
inserted
replaced
| 7997:2ca23396c25c | 7998:cd41c844862f |
|---|---|
| 1 # -*- coding: utf-8 -*- | |
| 2 | |
| 3 # Copyright (c) 2021 Detlev Offenbach <detlev@die-offenbachs.de> | |
| 4 # | |
| 5 | |
| 6 """ | |
| 7 Module implementing a docstring generator base class. | |
| 8 """ | |
| 9 | |
| 10 import re | |
| 11 | |
| 12 from PyQt5.QtCore import Qt | |
| 13 from PyQt5.QtWidgets import QMenu | |
| 14 | |
| 15 from E5Gui.E5Application import e5App | |
| 16 | |
| 17 import Preferences | |
| 18 | |
| 19 | |
| 20 def getIndentStr(text): | |
| 21 """ | |
| 22 Function to get the indentation of a text. | |
| 23 | |
| 24 @param text text to extract indentation from | |
| 25 @type str | |
| 26 @return indentation string | |
| 27 @rtype str | |
| 28 """ | |
| 29 indent = '' | |
| 30 | |
| 31 ret = re.match(r'(\s*)', text) | |
| 32 if ret: | |
| 33 indent = ret.group(1) | |
| 34 | |
| 35 return indent | |
| 36 | |
| 37 | |
| 38 class BaseDocstringGenerator(object): | |
| 39 """ | |
| 40 Class implementing a docstring generator base class. | |
| 41 """ | |
| 42 def __init__(self, editor): | |
| 43 """ | |
| 44 Constructor | |
| 45 | |
| 46 @param editor reference to the editor widget | |
| 47 @type Editor | |
| 48 """ | |
| 49 self.editor = editor | |
| 50 | |
| 51 def isFunctionStart(self, text): | |
| 52 """ | |
| 53 Public method to test, if a text is the start of a function or method | |
| 54 definition. | |
| 55 | |
| 56 @param text line of text to be tested | |
| 57 @type str | |
| 58 @return flag indicating that the given text starts a function or | |
| 59 method definition (always False) | |
| 60 @rtype bool | |
| 61 """ | |
| 62 return False | |
| 63 | |
| 64 def hasFunctionDefinition(self, cursorPosition): | |
| 65 """ | |
| 66 Public method to test, if the cursor is right below a function | |
| 67 definition. | |
| 68 | |
| 69 @param cursorPosition current cursor position (line and column) | |
| 70 @type tuple of (int, int) | |
| 71 @return flag indicating cursor is right below a function definition | |
| 72 @rtype bool | |
| 73 """ | |
| 74 return False | |
| 75 | |
| 76 def isDocstringIntro(self, cursorPosition): | |
| 77 """ | |
| 78 Public function to test, if the line up to the cursor position might be | |
| 79 introducing a docstring. | |
| 80 | |
| 81 @param cursorPosition current cursor position (line and column) | |
| 82 @type tuple of (int, int) | |
| 83 @return flag indicating a potential start of a docstring | |
| 84 @rtype bool | |
| 85 """ | |
| 86 return False | |
| 87 | |
| 88 def insertDocstring(self, cursorPosition, fromStart=True): | |
| 89 """ | |
| 90 Public method to insert a docstring for the function at the cursor | |
| 91 position. | |
| 92 | |
| 93 @param cursorPosition position of the cursor (line and index) | |
| 94 @type tuple of (int, int) | |
| 95 @param fromStart flag indicating that the editor text cursor is placed | |
| 96 on the line starting the function definition | |
| 97 @type bool | |
| 98 """ | |
| 99 # just do nothing in the base class | |
| 100 return | |
| 101 | |
| 102 def getDocstringType(self): | |
| 103 """ | |
| 104 Public method to determine the docstring type to be generated. | |
| 105 | |
| 106 @return docstring type (one of 'ericdoc', 'numpydoc', 'googledoc', | |
| 107 'sphinxdoc') | |
| 108 @rtype str | |
| 109 """ | |
| 110 docstringStyle = "" | |
| 111 | |
| 112 project = e5App().getObject("Project") | |
| 113 filename = self.editor.getFileName() | |
| 114 if ( | |
| 115 filename and | |
| 116 project.isOpen() and | |
| 117 project.isProjectFile(filename) | |
| 118 ): | |
| 119 docstringStyle = project.getDocstringType().lower() | |
| 120 | |
| 121 if docstringStyle == "": | |
| 122 docstringStyle = Preferences.getEditor("DocstringType") | |
| 123 | |
| 124 return docstringStyle | |
| 125 | |
| 126 def _generateDocstringList(self, functionInfo, docstringType): | |
| 127 """ | |
| 128 Protected method to generate type specific docstrings based on the | |
| 129 extracted function information. | |
| 130 | |
| 131 @param functionInfo reference to the function info object | |
| 132 @type FunctionInfo | |
| 133 @param docstringType kind of docstring to be generated | |
| 134 @return list of docstring lines | |
| 135 @rtype str | |
| 136 """ | |
| 137 if docstringType == "ericdoc": | |
| 138 from .EricdocGenerator import generateEricDoc | |
| 139 return generateEricDoc(functionInfo) | |
| 140 elif docstringType == "numpydoc": | |
| 141 from .NumpydocGenerator import generateNumpyDoc | |
| 142 return generateNumpyDoc(functionInfo) | |
| 143 elif docstringType == "googledoc": | |
| 144 from .GoogledocGenerator import generateGoogleDoc | |
| 145 return generateGoogleDoc(functionInfo, self.editor) | |
| 146 elif docstringType == "sphinxdoc": | |
| 147 from .SphinxdocGenerator import generateSphinxDoc | |
| 148 return generateSphinxDoc(functionInfo) | |
| 149 else: | |
| 150 return [] | |
| 151 | |
| 152 | |
| 153 class FunctionInfo(object): | |
| 154 """ | |
| 155 Class implementing an object to store function information. | |
| 156 | |
| 157 Methods to extract the relevant information need to be implemented in | |
| 158 language specific subclasses. | |
| 159 """ | |
| 160 def __init__(self): | |
| 161 """ | |
| 162 Constructor | |
| 163 """ | |
| 164 self.hasInfo = False | |
| 165 self.funcionText = "" | |
| 166 self.argumentsText = "" | |
| 167 | |
| 168 self.functionIndent = "" | |
| 169 # indentation fo function definition | |
| 170 self.argumentsList = [] | |
| 171 # list of tuples with name, type and value | |
| 172 self.returnTypeAnnotated = None | |
| 173 # return type extracted from type annotation | |
| 174 self.returnValueInBody = [] | |
| 175 # return values extracted from function body | |
| 176 self.raiseList = None | |
| 177 # exceptions raised by function | |
| 178 self.hasYield = False | |
| 179 # function is a generator | |
| 180 self.functionType = "" | |
| 181 # function type with these values | |
| 182 # classmethod, staticmethod, qtslot, constructor or empty (i.e. | |
| 183 # standard) | |
| 184 self.isAsync = False | |
| 185 # function is an asynchronous function, i.e. async def f(): | |
| 186 self.visibility = "" | |
| 187 # function visibility with allowed values: | |
| 188 # public, protected, private or special (i.e. starting and | |
| 189 # ending with '__' | |
| 190 | |
| 191 | |
| 192 class DocstringMenuForEnterOnly(QMenu): | |
| 193 """ | |
| 194 Class implementing a special menu reacting to the enter/return keys only. | |
| 195 | |
| 196 If a keyboard input is not the "enter key", the menu is closed and the | |
| 197 input is inserted to the code editor. | |
| 198 """ | |
| 199 def __init__(self, editor): | |
| 200 """ | |
| 201 Constructor | |
| 202 | |
| 203 @param editor reference to the editor | |
| 204 @type Editor | |
| 205 """ | |
| 206 super(DocstringMenuForEnterOnly, self).__init__(editor) | |
| 207 self.__editor = editor | |
| 208 | |
| 209 def keyPressEvent(self, evt): | |
| 210 """ | |
| 211 Protected method to handle key press events. | |
| 212 | |
| 213 @param evt reference to the key press event object | |
| 214 @type QKeyEvent | |
| 215 """ | |
| 216 key = evt.key() | |
| 217 if key not in (Qt.Key_Enter, Qt.Key_Return): | |
| 218 self.__editor.keyPressEvent(evt) | |
| 219 self.close() | |
| 220 else: | |
| 221 super(DocstringMenuForEnterOnly, self).keyPressEvent(evt) |
