Mercurial Repositories > eric / file comparison
comparison: eric7/QScintilla/DocstringGenerator/BaseDocstringGenerator.py
eric7/QScintilla/DocstringGenerator/BaseDocstringGenerator.py
- branch
- eric7
- changeset 8312
- 800c432b34c8
- parent 8218
- 7c09585bd960
- child 8318
- 962bce857696
equal
deleted
inserted
replaced
| 8311:4e8b98454baa | 8312:800c432b34c8 |
|---|---|
| 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: | |
| 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 insertDocstringFromShortcut(self, cursorPosition): | |
| 103 """ | |
| 104 Public method to insert a docstring for the function at the cursor | |
| 105 position initiated via a keyboard shortcut. | |
| 106 | |
| 107 @param cursorPosition position of the cursor (line and index) | |
| 108 @type tuple of (int, int) | |
| 109 """ | |
| 110 # just do nothing in the base class | |
| 111 return | |
| 112 | |
| 113 def getDocstringType(self): | |
| 114 """ | |
| 115 Public method to determine the docstring type to be generated. | |
| 116 | |
| 117 @return docstring type (one of 'ericdoc', 'numpydoc', 'googledoc', | |
| 118 'sphinxdoc') | |
| 119 @rtype str | |
| 120 """ | |
| 121 docstringStyle = "" | |
| 122 | |
| 123 project = e5App().getObject("Project") | |
| 124 filename = self.editor.getFileName() | |
| 125 if ( | |
| 126 filename and | |
| 127 project.isOpen() and | |
| 128 project.isProjectFile(filename) | |
| 129 ): | |
| 130 docstringStyle = project.getDocstringType().lower() | |
| 131 | |
| 132 if docstringStyle == "": | |
| 133 docstringStyle = Preferences.getEditor("DocstringType") | |
| 134 | |
| 135 return docstringStyle | |
| 136 | |
| 137 def _generateDocstringList(self, functionInfo, docstringType): | |
| 138 """ | |
| 139 Protected method to generate type specific docstrings based on the | |
| 140 extracted function information. | |
| 141 | |
| 142 @param functionInfo reference to the function info object | |
| 143 @type FunctionInfo | |
| 144 @param docstringType kind of docstring to be generated | |
| 145 @return list of docstring lines | |
| 146 @rtype str | |
| 147 """ | |
| 148 if docstringType == "ericdoc": | |
| 149 from .EricdocGenerator import generateEricDoc | |
| 150 return generateEricDoc(functionInfo) | |
| 151 elif docstringType == "numpydoc": | |
| 152 from .NumpydocGenerator import generateNumpyDoc | |
| 153 return generateNumpyDoc(functionInfo) | |
| 154 elif docstringType == "googledoc": | |
| 155 from .GoogledocGenerator import generateGoogleDoc | |
| 156 return generateGoogleDoc(functionInfo, self.editor) | |
| 157 elif docstringType == "sphinxdoc": | |
| 158 from .SphinxdocGenerator import generateSphinxDoc | |
| 159 return generateSphinxDoc(functionInfo) | |
| 160 else: | |
| 161 return [] | |
| 162 | |
| 163 | |
| 164 class FunctionInfo: | |
| 165 """ | |
| 166 Class implementing an object to store function information. | |
| 167 | |
| 168 Methods to extract the relevant information need to be implemented in | |
| 169 language specific subclasses. | |
| 170 """ | |
| 171 def __init__(self): | |
| 172 """ | |
| 173 Constructor | |
| 174 """ | |
| 175 self.hasInfo = False | |
| 176 self.funcionText = "" | |
| 177 self.argumentsText = "" | |
| 178 | |
| 179 self.functionIndent = "" | |
| 180 # indentation fo function definition | |
| 181 self.argumentsList = [] | |
| 182 # list of tuples with name, type and value | |
| 183 self.returnTypeAnnotated = None | |
| 184 # return type extracted from type annotation | |
| 185 self.returnValueInBody = [] | |
| 186 # return values extracted from function body | |
| 187 self.raiseList = None | |
| 188 # exceptions raised by function | |
| 189 self.hasYield = False | |
| 190 # function is a generator | |
| 191 self.functionType = "" | |
| 192 # function type with these values | |
| 193 # classmethod, staticmethod, qtslot, constructor or empty (i.e. | |
| 194 # standard) | |
| 195 self.isAsync = False | |
| 196 # function is an asynchronous function, i.e. async def f(): | |
| 197 self.visibility = "" | |
| 198 # function visibility with allowed values: | |
| 199 # public, protected, private or special (i.e. starting and | |
| 200 # ending with '__' | |
| 201 | |
| 202 | |
| 203 class DocstringMenuForEnterOnly(QMenu): | |
| 204 """ | |
| 205 Class implementing a special menu reacting to the enter/return keys only. | |
| 206 | |
| 207 If a keyboard input is not the "enter key", the menu is closed and the | |
| 208 input is inserted to the code editor. | |
| 209 """ | |
| 210 def __init__(self, editor): | |
| 211 """ | |
| 212 Constructor | |
| 213 | |
| 214 @param editor reference to the editor | |
| 215 @type Editor | |
| 216 """ | |
| 217 super().__init__(editor) | |
| 218 self.__editor = editor | |
| 219 | |
| 220 def keyPressEvent(self, evt): | |
| 221 """ | |
| 222 Protected method to handle key press events. | |
| 223 | |
| 224 @param evt reference to the key press event object | |
| 225 @type QKeyEvent | |
| 226 """ | |
| 227 key = evt.key() | |
| 228 if key not in (Qt.Key.Key_Enter, Qt.Key.Key_Return): | |
| 229 self.__editor.keyPressEvent(evt) | |
| 230 self.close() | |
| 231 else: | |
| 232 super().keyPressEvent(evt) |
