From 6349a6a2139ac68fb7fbf2970a233ffbe4aa4c2d Mon Sep 17 00:00:00 2001 From: Florian Bruhin Date: Tue, 7 Oct 2014 23:08:37 +0200 Subject: [PATCH] Remove Emit:/Raise: from docstrings. They got out-of-sync fast and provided no real benefit. --- doc/HACKING.asciidoc | 9 ++------- qutebrowser/browser/signalfilter.py | 3 --- qutebrowser/browser/webpage.py | 7 +------ qutebrowser/commands/cmdutils.py | 7 ------- qutebrowser/commands/command.py | 3 --- qutebrowser/commands/runners.py | 12 ------------ qutebrowser/commands/userscripts.py | 6 +----- qutebrowser/config/config.py | 8 -------- qutebrowser/config/configtypes.py | 4 ---- qutebrowser/keyinput/basekeyparser.py | 6 ------ qutebrowser/keyinput/modeman.py | 6 ------ qutebrowser/keyinput/modeparsers.py | 6 ------ qutebrowser/models/basecompletion.py | 3 --- qutebrowser/models/cmdhistory.py | 8 -------- qutebrowser/network/schemehandler.py | 7 ------- qutebrowser/test/stubs.py | 3 --- qutebrowser/utils/completer.py | 3 --- qutebrowser/utils/docutils.py | 2 -- qutebrowser/utils/editor.py | 6 ------ qutebrowser/utils/qtutils.py | 9 +-------- qutebrowser/utils/urlutils.py | 6 ------ qutebrowser/utils/usertypes.py | 14 +------------- qutebrowser/utils/utilcmds.py | 4 ---- qutebrowser/utils/utils.py | 6 ------ qutebrowser/widgets/statusbar/bar.py | 6 ------ qutebrowser/widgets/statusbar/command.py | 15 +-------------- qutebrowser/widgets/statusbar/prompter.py | 3 --- qutebrowser/widgets/tabbedbrowser.py | 15 +-------------- qutebrowser/widgets/webview.py | 12 +----------- 29 files changed, 9 insertions(+), 190 deletions(-) diff --git a/doc/HACKING.asciidoc b/doc/HACKING.asciidoc index 2f5f19bc4..550db683c 100644 --- a/doc/HACKING.asciidoc +++ b/doc/HACKING.asciidoc @@ -431,12 +431,13 @@ Style conventions qutebrowser's coding conventions are based on http://legacy.python.org/dev/peps/pep-0008/[PEP8] and the https://google-styleguide.googlecode.com/svn/trunk/pyguide.html[Google Python style guidelines] with some additions: +* The _Raise:_ section is not added to the docstring. * Methods overriding Qt methods (obviously!) don't follow the naming schemes. * Everything else does though, even slots. * Docstrings should look like described in http://legacy.python.org/dev/peps/pep-0257/[PEP257] and the google guidelines. * Class docstrings have additional _Attributes:_, _Class attributes:_ and - _Signals:_ sections, method/function docstrings have an _Emit:_ section. + _Signals:_ sections. * In docstrings of command handlers (registered via `@cmdutils.register`), the description should be split into two parts by using `//` - the first part is the description of the command like it will appear in the documentation, the @@ -475,12 +476,6 @@ Args: Return: True if something, False if something else. - -Raise: - ValueError if foo is None - -Emit: - value_changed """ ---- + diff --git a/qutebrowser/browser/signalfilter.py b/qutebrowser/browser/signalfilter.py index 3c59b7e63..ebd52a002 100644 --- a/qutebrowser/browser/signalfilter.py +++ b/qutebrowser/browser/signalfilter.py @@ -75,9 +75,6 @@ class SignalFilter(QObject): signal: The signal to emit if the sender was the current widget. tab: The WebView which the filter belongs to. *args: The args to pass to the signal. - - Emit: - The target signal if the sender was the current widget. """ log_signal = debug.signal_name(signal) not in self.BLACKLIST tabbed_browser = objreg.get('tabbed-browser', scope='window', diff --git a/qutebrowser/browser/webpage.py b/qutebrowser/browser/webpage.py index cf396583b..fe3cdd3f4 100644 --- a/qutebrowser/browser/webpage.py +++ b/qutebrowser/browser/webpage.py @@ -166,12 +166,7 @@ class BrowserPage(QWebPage): @pyqtSlot('QNetworkRequest') def on_download_requested(self, request): - """Called when the user wants to download a link. - - Emit: - start_download: Emitted with the QNetworkReply associated with the - passed request. - """ + """Called when the user wants to download a link.""" reply = self.networkAccessManager().get(request) self.start_download.emit(reply) diff --git a/qutebrowser/commands/cmdutils.py b/qutebrowser/commands/cmdutils.py index ea9f7aeaf..757072dad 100644 --- a/qutebrowser/commands/cmdutils.py +++ b/qutebrowser/commands/cmdutils.py @@ -36,10 +36,6 @@ def check_overflow(arg, ctype): Args: arg: The argument to check ctype: The C/Qt type to check as a string. - - Raise: - CommandError if the argument is out of bounds. - ValueError if the given ctype is unknown. """ try: qtutils.check_overflow(arg, ctype) @@ -63,9 +59,6 @@ def arg_or_count(arg, count, default=None, countzero=None): Return: The value to use. - - Raise: - ValueError: If nothing was set. """ if count is not None and arg is not None: raise ValueError("Both count and argument given!") diff --git a/qutebrowser/commands/command.py b/qutebrowser/commands/command.py index 17dc2f8f2..a5c9ce9fe 100644 --- a/qutebrowser/commands/command.py +++ b/qutebrowser/commands/command.py @@ -100,9 +100,6 @@ class Command: Args: win_id: The window ID the command is run in. - - Raise: - PrerequisitesError if the command can't be called currently. """ mode_manager = objreg.get('mode-manager', scope='window', window=win_id) diff --git a/qutebrowser/commands/runners.py b/qutebrowser/commands/runners.py index e7971454e..001b5aa12 100644 --- a/qutebrowser/commands/runners.py +++ b/qutebrowser/commands/runners.py @@ -74,9 +74,6 @@ class SearchRunner(QObject): Args: text: The text to search for. rev: Search direction, True if reverse, else False. - - Emit: - do_search: If a search should be started. """ if self._text is not None and self._text != text: # We first clear the marked text, then the highlights @@ -124,9 +121,6 @@ class SearchRunner(QObject): Args: count: How many elements to ignore. - - Emit: - do_search: If a search should be started. """ if self._text is not None: for _ in range(count): @@ -138,9 +132,6 @@ class SearchRunner(QObject): Args: count: How many elements to ignore. - - Emit: - do_search: If a search should be started. """ if self._text is None: return @@ -209,9 +200,6 @@ class CommandRunner(QObject): unknown. alias_no_args: Whether to apply an alias if there are no arguments. - Raise: - NoSuchCommandError if a command wasn't found. - Return: A split string commandline, e.g ['open', 'www.google.com'] """ diff --git a/qutebrowser/commands/userscripts.py b/qutebrowser/commands/userscripts.py index c38ff1478..8849f52cb 100644 --- a/qutebrowser/commands/userscripts.py +++ b/qutebrowser/commands/userscripts.py @@ -268,11 +268,7 @@ class _WindowsUserscriptRunner(_BaseUserscriptRunner): self._oshandle = None def on_proc_finished(self): - """Read back the commands when the process finished. - - Emit: - got_cmd: Emitted for every command in the file. - """ + """Read back the commands when the process finished.""" log.procs.debug("proc finished") with open(self._filepath, 'r', encoding='utf-8') as f: for line in f: diff --git a/qutebrowser/config/config.py b/qutebrowser/config/config.py index b3f234784..60ce3d7e6 100644 --- a/qutebrowser/config/config.py +++ b/qutebrowser/config/config.py @@ -476,14 +476,6 @@ class ConfigManager(QObject): sectname: The name of the section to change. optname: The name of the option to change. value: The new value. - - Raise: - NoSectionError: If the specified section doesn't exist. - NoOptionError: If the specified option doesn't exist. - - Emit: - changed: If the config was changed. - style_changed: When style caches need to be invalidated. """ try: value = self._interpolation.before_set(self, sectname, optname, diff --git a/qutebrowser/config/configtypes.py b/qutebrowser/config/configtypes.py index 50f4f6aac..f1b4fd1b7 100644 --- a/qutebrowser/config/configtypes.py +++ b/qutebrowser/config/configtypes.py @@ -127,10 +127,6 @@ class BaseType: Args: value: The value to validate. - - Raise: - ValidationError if the value was invalid. - NotImplementedError if self.valid_values is not defined and this method should be overridden. """ if not value and self._none_ok: diff --git a/qutebrowser/keyinput/basekeyparser.py b/qutebrowser/keyinput/basekeyparser.py index b451d32d3..911d50234 100644 --- a/qutebrowser/keyinput/basekeyparser.py +++ b/qutebrowser/keyinput/basekeyparser.py @@ -278,9 +278,6 @@ class BaseKeyParser(QObject): Args: command/count: As if passed to self.execute() - - Emit: - keystring_updated to do a delayed update. """ self._debug_log("Executing delayed command now!") self._timer = None @@ -293,9 +290,6 @@ class BaseKeyParser(QObject): Args: e: the KeyPressEvent from Qt - - Emit: - keystring_updated: If a new keystring should be set. """ handled = self._handle_special_key(e) if handled or not self._supports_chains: diff --git a/qutebrowser/keyinput/modeman.py b/qutebrowser/keyinput/modeman.py index 7abd06e15..9c4baedbb 100644 --- a/qutebrowser/keyinput/modeman.py +++ b/qutebrowser/keyinput/modeman.py @@ -269,9 +269,6 @@ class ModeManager(QObject): mode: The mode to enter as a KeyMode member. reason: Why the mode was entered. override: Override a locked mode. - - Emit: - entered: With the new mode name. """ if not isinstance(mode, usertypes.KeyMode): raise TypeError("Mode {} is no KeyMode member!".format(mode)) @@ -314,9 +311,6 @@ class ModeManager(QObject): Args: mode: The name of the mode to leave. reason: Why the mode was left. - - Emit: - left: With the old mode name. """ try: self._mode_stack.remove(mode) diff --git a/qutebrowser/keyinput/modeparsers.py b/qutebrowser/keyinput/modeparsers.py index 29505f04d..c514f8796 100644 --- a/qutebrowser/keyinput/modeparsers.py +++ b/qutebrowser/keyinput/modeparsers.py @@ -105,9 +105,6 @@ class HintKeyParser(keyparser.CommandKeyParser): Return: True if event has been handled, False otherwise. - - Emit: - keystring_updated: Emitted when keystring has been changed. """ log.keyboard.debug("Got special key 0x{:x} text {}".format( e.key(), e.text())) @@ -143,9 +140,6 @@ class HintKeyParser(keyparser.CommandKeyParser): Args: e: the KeyPressEvent from Qt - - Emit: - keystring_updated: If a new keystring should be set. """ handled = self._handle_single_key(e) if handled and self._keystring: diff --git a/qutebrowser/models/basecompletion.py b/qutebrowser/models/basecompletion.py index 685d2cc2d..9430efe10 100644 --- a/qutebrowser/models/basecompletion.py +++ b/qutebrowser/models/basecompletion.py @@ -144,8 +144,5 @@ class BaseCompletionModel(QStandardItemModel): """Sort the data in column according to order. Override QAbstractItemModel::sort. - - Raise: - NotImplementedError, should be overwritten in a superclass. """ raise NotImplementedError diff --git a/qutebrowser/models/cmdhistory.py b/qutebrowser/models/cmdhistory.py index dda2678c0..2d55e1bf5 100644 --- a/qutebrowser/models/cmdhistory.py +++ b/qutebrowser/models/cmdhistory.py @@ -94,10 +94,6 @@ class History: """Get the previous item in the temp history. start() needs to be called before calling this. - - Raise: - ValueError if start() wasn't called. - HistoryEndReachedError if the first item was reached. """ if not self.is_browsing(): raise ValueError("Currently not browsing history") @@ -110,10 +106,6 @@ class History: """Get the next item in the temp history. start() needs to be called before calling this. - - Raise: - ValueError if start() wasn't called. - HistoryEndReachedError if the last item was reached. """ if not self.is_browsing(): raise ValueError("Currently not browsing history") diff --git a/qutebrowser/network/schemehandler.py b/qutebrowser/network/schemehandler.py index 8256162eb..d309fed7b 100644 --- a/qutebrowser/network/schemehandler.py +++ b/qutebrowser/network/schemehandler.py @@ -48,10 +48,6 @@ class SchemeHandler(QObject): Return: A QNetworkReply. - - Raise: - NotImplementedError because this needs to be overwritten by - subclasses. """ raise NotImplementedError @@ -68,9 +64,6 @@ class SpecialNetworkReply(QNetworkReply): fileData: reference to the data buffer (QByteArray) mimeType: for the reply (string) parent: reference to the parent object (QObject) - - Emit: - metaDataChanged and readyRead and finished after initializing. """ super().__init__(parent) diff --git a/qutebrowser/test/stubs.py b/qutebrowser/test/stubs.py index df27030a8..8d9e99399 100644 --- a/qutebrowser/test/stubs.py +++ b/qutebrowser/test/stubs.py @@ -50,9 +50,6 @@ class ConfigStub: Args: name: The section name to get. - Raise: - ValueError if section isn't test1/test2. - Return: The section as dict. """ diff --git a/qutebrowser/utils/completer.py b/qutebrowser/utils/completer.py index 4c5256896..71e6c898c 100644 --- a/qutebrowser/utils/completer.py +++ b/qutebrowser/utils/completer.py @@ -161,9 +161,6 @@ class Completer(QObject): Args: selected: New selection. _delected: Previous selection. - - Emit: - change_completed_part: Emitted when there's data for the new item. """ indexes = selected.indexes() if not indexes: diff --git a/qutebrowser/utils/docutils.py b/qutebrowser/utils/docutils.py index a7725a4e9..575bd6fb8 100644 --- a/qutebrowser/utils/docutils.py +++ b/qutebrowser/utils/docutils.py @@ -128,8 +128,6 @@ class DocstringParser: """Parse the long description in the docstring.""" if line.startswith('Args:'): self._state = self.State.arg_start - elif line.startswith('Emit:') or line.startswith('Raise:'): - self._state = self.State.misc elif line.strip() == '//': self._state = self.State.desc_hidden elif line.strip(): diff --git a/qutebrowser/utils/editor.py b/qutebrowser/utils/editor.py index 32ac9affb..ddb3992e7 100644 --- a/qutebrowser/utils/editor.py +++ b/qutebrowser/utils/editor.py @@ -65,9 +65,6 @@ class ExternalEditor(QObject): """Write the editor text into the form field and clean up tempfile. Callback for QProcess when the editor was closed. - - Emit: - editing_finished: If process exited normally. """ log.procs.debug("Editor closed") if exitstatus != QProcess.NormalExit: @@ -113,9 +110,6 @@ class ExternalEditor(QObject): Args: text: The initial text to edit. - - Emit: - editing_finished with the new text if editing finshed successfully. """ if self._text is not None: raise ValueError("Already editing a file!") diff --git a/qutebrowser/utils/qtutils.py b/qutebrowser/utils/qtutils.py index 207bb587c..60f4c0f7a 100644 --- a/qutebrowser/utils/qtutils.py +++ b/qutebrowser/utils/qtutils.py @@ -68,9 +68,6 @@ def check_overflow(arg, ctype, fatal=True): Return The truncated argument if fatal=False The original argument if it's in bounds. - - Raise: - OverflowError if the argument is out of bounds and fatal=True. """ maxval = MAXVALS[ctype] minval = MINVALS[ctype] @@ -119,11 +116,7 @@ def check_print_compat(): def ensure_valid(obj): - """Ensure a Qt object with an .isValid() method is valid. - - Raise: - QtValueError if the object is invalid. - """ + """Ensure a Qt object with an .isValid() method is valid.""" if not obj.isValid(): raise QtValueError(obj) diff --git a/qutebrowser/utils/urlutils.py b/qutebrowser/utils/urlutils.py index beef63c6c..15231d9ce 100644 --- a/qutebrowser/utils/urlutils.py +++ b/qutebrowser/utils/urlutils.py @@ -43,9 +43,6 @@ def _get_search_url(txt): Return: The search URL as a QUrl. - - Raise: - FuzzyUrlError if there is no template or no search term was found. """ log.url.debug("Finding search engine for '{}'".format(txt)) r = re.compile(r'(^|\s+)!(\w+)($|\s+)') @@ -186,9 +183,6 @@ def is_url(urlstr): Return: True if it is a valid URL, False otherwise. - - Raise: - ValueError if the autosearch config value is invalid. """ autosearch = config.get('general', 'auto-search') diff --git a/qutebrowser/utils/usertypes.py b/qutebrowser/utils/usertypes.py index 845c7190f..409fac36c 100644 --- a/qutebrowser/utils/usertypes.py +++ b/qutebrowser/utils/usertypes.py @@ -128,10 +128,6 @@ class NeighborList(collections.abc.Sequence): Return: The new item. - - Raise: - IndexError if the border of the list is reached and mode is - exception. """ try: if self._idx + offset >= 0: @@ -164,10 +160,6 @@ class NeighborList(collections.abc.Sequence): Return: The new item. - - Raise: - IndexError if the border of the list is reached and mode is - exception. """ log.misc.debug("{} items, idx {}, offset {}".format( len(self._items), self._idx, offset)) @@ -324,11 +316,7 @@ class Question(QObject): self.completed.emit() def abort(self): - """Abort the question. - - Emit: - aborted: Always emitted. - """ + """Abort the question.""" self.is_aborted = True try: self.aborted.emit() diff --git a/qutebrowser/utils/utilcmds.py b/qutebrowser/utils/utilcmds.py index 32aad6af1..11f71b408 100644 --- a/qutebrowser/utils/utilcmds.py +++ b/qutebrowser/utils/utilcmds.py @@ -61,10 +61,6 @@ def debug_crash(typ: ('exception', 'segfault')='exception'): Args: typ: either 'exception' or 'segfault'. - - Raises: - raises Exception when typ is not segfault. - segfaults when typ is (you don't say...) """ if typ == 'segfault': # From python's Lib/test/crashers/bogus_code_obj.py diff --git a/qutebrowser/utils/utils.py b/qutebrowser/utils/utils.py index d1d8f3eff..f713cbb70 100644 --- a/qutebrowser/utils/utils.py +++ b/qutebrowser/utils/utils.py @@ -289,9 +289,6 @@ def _get_color_percentage(a_c1, a_c2, a_c3, b_c1, b_c2, b_c3, percent): Return: A (c1, c2, c3) tuple with the interpolated color components. - - Raise: - ValueError if the percentage was invalid. """ if not 0 <= percent <= 100: raise ValueError("percent needs to be between 0 and 100!") @@ -313,9 +310,6 @@ def interpolate_color(start, end, percent, colorspace=QColor.Rgb): Return: The interpolated QColor, with the same spec as the given start color. - - Raise: - ValueError if invalid parameters are passed. """ qtutils.ensure_valid(start) qtutils.ensure_valid(end) diff --git a/qutebrowser/widgets/statusbar/bar.py b/qutebrowser/widgets/statusbar/bar.py index c21aa93b8..65d36d0d5 100644 --- a/qutebrowser/widgets/statusbar/bar.py +++ b/qutebrowser/widgets/statusbar/bar.py @@ -411,9 +411,6 @@ class StatusBar(QWidget): Args: e: The QResizeEvent. - - Emit: - resized: Always emitted. """ super().resizeEvent(e) self.resized.emit(self.geometry()) @@ -423,9 +420,6 @@ class StatusBar(QWidget): Args: e: The QMoveEvent. - - Emit: - moved: Always emitted. """ super().moveEvent(e) self.moved.emit(e.pos()) diff --git a/qutebrowser/widgets/statusbar/command.py b/qutebrowser/widgets/statusbar/command.py index 06b93798a..3248c5fbb 100644 --- a/qutebrowser/widgets/statusbar/command.py +++ b/qutebrowser/widgets/statusbar/command.py @@ -145,9 +145,6 @@ class Command(misc.MinimalLineEditMixin, misc.CommandLineEdit): Args: text: The text to set as string. - - Emit: - update_completion: Emitted if the text changed. """ old_text = self.text() self.setText(text) @@ -248,13 +245,7 @@ class Command(misc.MinimalLineEditMixin, misc.CommandLineEdit): @cmdutils.register(instance='status-command', hide=True, modes=[usertypes.KeyMode.command], scope='window') def command_accept(self): - """Execute the command currently in the commandline. - - Emit: - got_cmd: If a new cmd was entered. - got_search: If a new search was entered. - got_search_rev: If a new reverse search was entered. - """ + """Execute the command currently in the commandline.""" signals = { ':': self.got_cmd, '/': self.got_search, @@ -285,10 +276,6 @@ class Command(misc.MinimalLineEditMixin, misc.CommandLineEdit): Args: mode: The mode which was left. - - Emit: - clear_completion_selection: Always emitted. - hide_completion: Always emitted so the completion is hidden. """ if mode == usertypes.KeyMode.command: self.setText('') diff --git a/qutebrowser/widgets/statusbar/prompter.py b/qutebrowser/widgets/statusbar/prompter.py index 193eb93bc..55ea8720f 100644 --- a/qutebrowser/widgets/statusbar/prompter.py +++ b/qutebrowser/widgets/statusbar/prompter.py @@ -132,9 +132,6 @@ class Prompter(QObject): Return: The mode which should be entered. - - Raise: - ValueError if the set PromptMode is invalid. """ prompt = objreg.get('prompt', scope='window', window=self._win_id) if self._question.mode == usertypes.PromptMode.yesno: diff --git a/qutebrowser/widgets/tabbedbrowser.py b/qutebrowser/widgets/tabbedbrowser.py index f751aa831..6b69d1bc2 100644 --- a/qutebrowser/widgets/tabbedbrowser.py +++ b/qutebrowser/widgets/tabbedbrowser.py @@ -188,9 +188,6 @@ class TabbedBrowser(tabwidget.TabWidget): Return: The current URL as QUrl. - - Raise: - CommandError if the current URL is invalid. """ widget = self.currentWidget() if widget is None: @@ -208,11 +205,7 @@ class TabbedBrowser(tabwidget.TabWidget): return url def shutdown(self): - """Try to shut down all tabs cleanly. - - Emit: - shutdown_complete if the shutdown completed successfully. - """ + """Try to shut down all tabs cleanly.""" try: self.currentChanged.disconnect() except TypeError: @@ -240,9 +233,6 @@ class TabbedBrowser(tabwidget.TabWidget): Args: tab: The QWebView to be closed. - - Raise: - ValueError if the tab is not in the QTabWidget. """ idx = self.indexOf(tab) if idx == -1: @@ -553,9 +543,6 @@ class TabbedBrowser(tabwidget.TabWidget): Args: e: The QResizeEvent - - Emit: - resize: Always emitted. """ super().resizeEvent(e) self.resized.emit(self.geometry()) diff --git a/qutebrowser/widgets/webview.py b/qutebrowser/widgets/webview.py index 5197121e0..09faf7e38 100644 --- a/qutebrowser/widgets/webview.py +++ b/qutebrowser/widgets/webview.py @@ -128,11 +128,7 @@ class WebView(QWebView): return utils.get_repr(self, tab_id=self.tab_id, url=url) def _set_load_status(self, val): - """Setter for load_status. - - Emit: - load_status_changed - """ + """Setter for load_status.""" if not isinstance(val, LoadStatus): raise TypeError("Type {} is no LoadStatus member!".format(val)) log.webview.debug("load status for {}: {}".format(repr(self), val)) @@ -279,9 +275,6 @@ class WebView(QWebView): Return: Return status of self.load - - Emit: - titleChanged """ qtutils.ensure_valid(url) urlstr = url.toDisplayString() @@ -412,9 +405,6 @@ class WebView(QWebView): Args: e: The QPaintEvent. - Emit: - scroll_pos_changed; If the scroll position changed. - Return: The superclass event return value. """