From 80ef0782d505829d80e3dd739f6cb0beaaf90ff7 Mon Sep 17 00:00:00 2001 From: Florian Bruhin Date: Sat, 13 Sep 2014 00:22:27 +0200 Subject: [PATCH] Improve some docstrings. --- doc/help/commands.asciidoc | 79 +++++++++++++---------------- qutebrowser/browser/commands.py | 50 +++++++++--------- qutebrowser/browser/quickmarks.py | 8 +-- qutebrowser/commands/cmdutils.py | 3 ++ qutebrowser/config/config.py | 21 ++++---- qutebrowser/config/keyconfparser.py | 8 +-- qutebrowser/utils/utilcmds.py | 10 ++-- scripts/generate_doc.py | 2 + 8 files changed, 91 insertions(+), 90 deletions(-) diff --git a/doc/help/commands.asciidoc b/doc/help/commands.asciidoc index b1408fd6b..bbaf2f97d 100644 --- a/doc/help/commands.asciidoc +++ b/doc/help/commands.asciidoc @@ -21,7 +21,6 @@ |<>|Open a page from the clipboard. |<>|Open a "previous" link. |<>|Print the current/[count]th tab. -|<>|Quit qutebrowser. |<>|Add a new quickmark. |<>|Load a quickmark. |<>|Save the current page as a quickmark. @@ -59,9 +58,9 @@ Syntax: +:bind 'key' 'command' ['mode']+ Bind a key to a command. ==== positional arguments -* +'key'+: The keychain or special key (inside <...>) to bind. +* +'key'+: The keychain or special key (inside `<...>`) to bind. * +'command'+: The command to execute. -* +'mode'+: A comma-separated list of modes to bind the key in (default: normal mode). +* +'mode'+: A comma-separated list of modes to bind the key in (default: `normal`). [[cancel-download]] @@ -78,13 +77,13 @@ Go forward in the history of the current tab. [[get]] === get -Syntax: +:get 'sectname' 'optname'+ +Syntax: +:get 'section' 'option'+ Get the value from a section/option. ==== positional arguments -* +'sectname'+: The section where the option is in. -* +'optname'+: The name of the option. +* +'section'+: The section where the option is in. +* +'option'+: The name of the option. [[help]] === help @@ -123,10 +122,6 @@ Start hinting. - `yank-primary`: Yank the link to the primary selection. - `fill`: Fill the commandline with the command given as argument. - - `cmd-tab`: Fill the commandline with `:open -t` and the - link. - - `cmd-tag-bg`: Fill the commandline with `:open -b` and - the link. - `rapid`: Open the link in a new tab and stay in hinting mode. - `download`: Download the link. - `userscript`: Call an userscript with `$QUTE_URL` set to the @@ -156,13 +151,13 @@ Toggle the web inspector. [[later]] === later -Syntax: +:later 'ms' 'command' ['command' ...]+ +Syntax: +:later 'ms' 'command'+ Execute a command after some time. ==== positional arguments * +'ms'+: How many milliseconds to wait. -* +'command'+: The command/args to run. +* +'command'+: The command to run. [[next-page]] === next-page @@ -170,33 +165,34 @@ Syntax: +:next-page [*--tab*]+ Open a "next" link. -This tries to automatically click on typical "Next Page" links using some heuristics. +This tries to automatically click on typical _Next Page_ links using some heuristics. ==== optional arguments -* +*-t*+, +*--tab*+: Whether to open a new tab. +* +*-t*+, +*--tab*+: Open in a new tab. [[open]] === open -Syntax: +:open [*--bg*] [*--tab*] 'urlstr'+ +Syntax: +:open [*--bg*] [*--tab*] 'url'+ Open a URL in the current/[count]th tab. ==== positional arguments -* +'urlstr'+: The URL to open, as string. +* +'url'+: The URL to open. ==== optional arguments -* +*-b*+, +*--bg*+: Whether to open in a background tab. -* +*-t*+, +*--tab*+: Whether to open in a tab. +* +*-b*+, +*--bg*+: Open in a new background tab. +* +*-t*+, +*--tab*+: Open in a new tab. [[paste]] === paste -Syntax: +:paste [*--sel*] [*--tab*]+ +Syntax: +:paste [*--sel*] [*--tab*] [*--bg*]+ Open a page from the clipboard. ==== optional arguments -* +*-s*+, +*--sel*+: True to use primary selection, False to use clipboard -* +*-t*+, +*--tab*+: True to open in a new tab. +* +*-s*+, +*--sel*+: Use the primary selection instead of the clipboard. +* +*-t*+, +*--tab*+: Open in a new tab. +* +*-b*+, +*--bg*+: Open in a background tab. [[prev-page]] === prev-page @@ -204,10 +200,10 @@ Syntax: +:prev-page [*--tab*]+ Open a "previous" link. -This tries to automaticall click on typical "Previous Page" links using some heuristics. +This tries to automatically click on typical _Previous Page_ links using some heuristics. ==== optional arguments -* +*-t*+, +*--tab*+: Whether to open a new tab. +* +*-t*+, +*--tab*+: Open in a new tab. [[print]] === print @@ -216,22 +212,16 @@ Syntax: +:print [*--preview*]+ Print the current/[count]th tab. ==== optional arguments -* +*-p*+, +*--preview*+: Whether to preview instead of printing. - -[[q]] -=== q -Syntax: +:quit+ - -Quit qutebrowser. +* +*-p*+, +*--preview*+: Show preview instead of printing. [[quickmark-add]] === quickmark-add -Syntax: +:quickmark-add 'urlstr' 'name'+ +Syntax: +:quickmark-add 'url' 'name'+ Add a new quickmark. ==== positional arguments -* +'urlstr'+: The url to add as quickmark, as string. +* +'url'+: The url to add as quickmark. * +'name'+: The name for the new quickmark. [[quickmark-load]] @@ -244,8 +234,8 @@ Load a quickmark. * +'name'+: The name of the quickmark to load. ==== optional arguments -* +*-t*+, +*--tab*+: Whether to load the quickmark in a new tab. -* +*-b*+, +*--bg*+: Whether to load the quickmark in the background. +* +*-t*+, +*--tab*+: Load the quickmark in a new tab. +* +*-b*+, +*--bg*+: Load the quickmark in a new background tab. [[quickmark-save]] === quickmark-save @@ -283,17 +273,17 @@ Save the config file. [[set]] === set -Syntax: +:set [*--temp*] 'sectname' 'optname' 'value'+ +Syntax: +:set [*--temp*] 'section' 'option' 'value'+ Set an option. ==== positional arguments -* +'sectname'+: The section where the option is in. -* +'optname'+: The name of the option. +* +'section'+: The section where the option is in. +* +'option'+: The name of the option. * +'value'+: The value to set. ==== optional arguments -* +*-t*+, +*--temp*+: Set value temporarely. +* +*-t*+, +*--temp*+: Set value temporarily. [[set-cmd-text]] === set-cmd-text @@ -340,7 +330,8 @@ Syntax: +:tab-move ['direction']+ Move the current tab. ==== positional arguments -* +'direction'+: + or - for relative moving, none for absolute. +* +'direction'+: `+` or `-` for relative moving, not given for absolute moving. + [[tab-next]] === tab-next @@ -361,8 +352,8 @@ Syntax: +:unbind 'key' ['mode']+ Unbind a keychain. ==== positional arguments -* +'key'+: The keychain or special key (inside <...>) to bind. -* +'mode'+: A comma-separated list of modes to unbind the key in (default: normal mode). +* +'key'+: The keychain or special key (inside <...>) to unbind. +* +'mode'+: A comma-separated list of modes to unbind the key in (default: `normal`). [[undo]] @@ -376,8 +367,8 @@ Syntax: +:yank [*--title*] [*--sel*]+ Yank the current URL/title to the clipboard or primary selection. ==== optional arguments -* +*-t*+, +*--title*+: Whether to yank the title instead of the URL. -* +*-s*+, +*--sel*+: True to use primary selection, False to use clipboard +* +*-t*+, +*--title*+: Yank the title instead of the URL. +* +*-s*+, +*--sel*+: Use the primary selection instead of the clipboard. [[zoom]] === zoom @@ -600,7 +591,7 @@ The percentage can be given either as argument or as count. If no percentage is * +'perc'+: Percentage to scroll. ==== optional arguments -* +*-x*+, +*--horizontal*+: Whether to scroll horizontally. +* +*-x*+, +*--horizontal*+: Scroll horizontally instead of vertically. [[search-next]] === search-next diff --git a/qutebrowser/browser/commands.py b/qutebrowser/browser/commands.py index 2ee04a72c..97a5f38b1 100644 --- a/qutebrowser/browser/commands.py +++ b/qutebrowser/browser/commands.py @@ -159,17 +159,17 @@ class CommandDispatcher: @cmdutils.register(instance='mainwindow.tabs.cmd', name='open', split=False) - def openurl(self, urlstr, bg=False, tab=False, count=None): + def openurl(self, url, bg=False, tab=False, count=None): """Open a URL in the current/[count]th tab. Args: - urlstr: The URL to open, as string. - bg: Whether to open in a background tab. - tab: Whether to open in a tab. + url: The URL to open. + bg: Open in a new background tab. + tab: Open in a new tab. count: The tab index to open the URL in, or None. """ try: - url = urlutils.fuzzy_url(urlstr) + url = urlutils.fuzzy_url(url) except urlutils.FuzzyUrlError as e: raise cmdexc.CommandError(e) if tab: @@ -216,7 +216,7 @@ class CommandDispatcher: """Print the current/[count]th tab. Args: - preview: Whether to preview instead of printing. + preview: Show preview instead of printing. count: The tab index to print, or None. """ if not qtutils.check_print_compat(): @@ -276,10 +276,6 @@ class CommandDispatcher: - `yank-primary`: Yank the link to the primary selection. - `fill`: Fill the commandline with the command given as argument. - - `cmd-tab`: Fill the commandline with `:open -t` and the - link. - - `cmd-tag-bg`: Fill the commandline with `:open -b` and - the link. - `rapid`: Open the link in a new tab and stay in hinting mode. - `download`: Download the link. - `userscript`: Call an userscript with `$QUTE_URL` set to the @@ -312,11 +308,11 @@ class CommandDispatcher: def prev_page(self, tab=False): """Open a "previous" link. - This tries to automaticall click on typical "Previous Page" links using - some heuristics. + This tries to automatically click on typical _Previous Page_ links + using some heuristics. Args: - tab: Whether to open a new tab. + tab: Open in a new tab. """ self._prevnext(prev=True, newtab=tab) @@ -324,11 +320,11 @@ class CommandDispatcher: def next_page(self, tab=False): """Open a "next" link. - This tries to automatically click on typical "Next Page" links using + This tries to automatically click on typical _Next Page_ links using some heuristics. Args: - tab: Whether to open a new tab. + tab: Open in a new tab. """ self._prevnext(prev=False, newtab=tab) @@ -357,7 +353,7 @@ class CommandDispatcher: Args: perc: Percentage to scroll. - horizontal: Whether to scroll horizontally. + horizontal: Scroll horizontally instead of vertically. count: Percentage to scroll. """ self._scroll_percent(perc, count, @@ -385,8 +381,8 @@ class CommandDispatcher: """Yank the current URL/title to the clipboard or primary selection. Args: - sel: True to use primary selection, False to use clipboard - title: Whether to yank the title instead of the URL. + sel: Use the primary selection instead of the clipboard. + title: Yank the title instead of the URL. """ clipboard = QApplication.clipboard() if title: @@ -490,12 +486,13 @@ class CommandDispatcher: raise cmdexc.CommandError("Last tab") @cmdutils.register(instance='mainwindow.tabs.cmd') - def paste(self, sel=False, tab=False): + def paste(self, sel=False, tab=False, bg=False): """Open a page from the clipboard. Args: - sel: True to use primary selection, False to use clipboard - tab: True to open in a new tab. + sel: Use the primary selection instead of the clipboard. + tab: Open in a new tab. + bg: Open in a background tab. """ clipboard = QApplication.clipboard() if sel and clipboard.supportsSelection(): @@ -513,7 +510,9 @@ class CommandDispatcher: except urlutils.FuzzyUrlError as e: raise cmdexc.CommandError(e) if tab: - self._tabs.tabopen(url, explicit=True) + self._tabs.tabopen(url, background=False, explicit=True) + elif bg: + self._tabs.tabopen(url, background=True, explicit=True) else: widget = self._current_widget() widget.openurl(url) @@ -547,7 +546,8 @@ class CommandDispatcher: """Move the current tab. Args: - direction: + or - for relative moving, none for absolute. + direction: `+` or `-` for relative moving, not given for absolute + moving. count: If moving absolutely: New position (default: 0) If moving relatively: Offset. """ @@ -624,8 +624,8 @@ class CommandDispatcher: Args: name: The name of the quickmark to load. - tab: Whether to load the quickmark in a new tab. - bg: Whether to load the quickmark in the background. + tab: Load the quickmark in a new tab. + bg: Load the quickmark in a new background tab. """ urlstr = quickmarks.get(name) url = QUrl(urlstr) diff --git a/qutebrowser/browser/quickmarks.py b/qutebrowser/browser/quickmarks.py index ec223749e..fe83df188 100644 --- a/qutebrowser/browser/quickmarks.py +++ b/qutebrowser/browser/quickmarks.py @@ -71,21 +71,21 @@ def prompt_save(url): @cmdutils.register() -def quickmark_add(urlstr, name): +def quickmark_add(url, name): """Add a new quickmark. Args: - urlstr: The url to add as quickmark, as string. + url: The url to add as quickmark. name: The name for the new quickmark. """ if not name: raise cmdexc.CommandError("Can't set mark with empty name!") - if not urlstr: + if not url: raise cmdexc.CommandError("Can't set mark with empty URL!") def set_mark(): """Really set the quickmark.""" - marks[name] = urlstr + marks[name] = url if name in marks: message.confirm_async("Override existing quickmark?", set_mark, diff --git a/qutebrowser/commands/cmdutils.py b/qutebrowser/commands/cmdutils.py index ca15f59e8..4afdd3462 100644 --- a/qutebrowser/commands/cmdutils.py +++ b/qutebrowser/commands/cmdutils.py @@ -31,6 +31,7 @@ from qutebrowser.utils import debug as debugutils from qutebrowser.commands import command, cmdexc, argparser cmd_dict = {} +aliases = [] def check_overflow(arg, ctype): @@ -163,6 +164,7 @@ class register: # pylint: disable=invalid-name Return: The original function (unmodified). """ + global aliases, cmd_dict self.func = func names = self._get_names() log.commands.vdebug("Registering command {}".format(names[0])) @@ -186,6 +188,7 @@ class register: # pylint: disable=invalid-name opt_args=self.opt_args, pos_args=self.pos_args) for name in names: cmd_dict[name] = cmd + aliases += names[1:] return func def _get_names(self): diff --git a/qutebrowser/config/config.py b/qutebrowser/config/config.py index 22bd27063..e135d52cf 100644 --- a/qutebrowser/config/config.py +++ b/qutebrowser/config/config.py @@ -283,7 +283,7 @@ class ConfigManager(QObject): @cmdutils.register(name='get', instance='config', completion=[Completion.section, Completion.option]) - def get_wrapper(self, sectname, optname): + def get_command(self, section, option): """Get the value from a section/option. // @@ -291,16 +291,16 @@ class ConfigManager(QObject): Wrapper for the get-command to output the value in the status bar. Args: - sectname: The section where the option is in. - optname: The name of the option. + section: The section where the option is in. + option: The name of the option. """ try: - val = self.get(sectname, optname, transformed=False) + val = self.get(section, option, transformed=False) except (NoOptionError, NoSectionError) as e: raise cmdexc.CommandError("get: {} - {}".format( e.__class__.__name__, e)) else: - message.info("{} {} = {}".format(sectname, optname, val), + message.info("{} {} = {}".format(section, option, val), immediately=True) @functools.lru_cache() @@ -336,7 +336,7 @@ class ConfigManager(QObject): @cmdutils.register(name='set', instance='config', completion=[Completion.section, Completion.option, Completion.value]) - def set_command(self, sectname, optname, value, temp=False): + def set_command(self, section, option, value, temp=False): """Set an option. // @@ -344,13 +344,14 @@ class ConfigManager(QObject): Wrapper for self.set() to output exceptions in the status bar. Args: - sectname: The section where the option is in. - optname: The name of the option. + section: The section where the option is in. + option: The name of the option. value: The value to set. - temp: Set value temporarely. + temp: Set value temporarily. """ try: - self.set('temp' if temp else 'conf', sectname, optname, value) + layer = 'temp' if temp else 'conf' + self.set(layer, section, option, value) except (NoOptionError, NoSectionError, configtypes.ValidationError, ValueError) as e: raise cmdexc.CommandError("set: {} - {}".format( diff --git a/qutebrowser/config/keyconfparser.py b/qutebrowser/config/keyconfparser.py index 108941b48..79efb6b0b 100644 --- a/qutebrowser/config/keyconfparser.py +++ b/qutebrowser/config/keyconfparser.py @@ -124,10 +124,10 @@ class KeyConfigParser(QObject): """Bind a key to a command. Args: - key: The keychain or special key (inside <...>) to bind. + key: The keychain or special key (inside `<...>`) to bind. command: The command to execute. mode: A comma-separated list of modes to bind the key in - (default: normal mode). + (default: `normal`). """ if mode is None: mode = 'normal' @@ -149,9 +149,9 @@ class KeyConfigParser(QObject): """Unbind a keychain. Args: - key: The keychain or special key (inside <...>) to bind. + key: The keychain or special key (inside <...>) to unbind. mode: A comma-separated list of modes to unbind the key in - (default: normal mode). + (default: `normal`). """ if mode is None: mode = 'normal' diff --git a/qutebrowser/utils/utilcmds.py b/qutebrowser/utils/utilcmds.py index 4fd1435ce..38e635861 100644 --- a/qutebrowser/utils/utilcmds.py +++ b/qutebrowser/utils/utilcmds.py @@ -19,6 +19,7 @@ """Misc. utility commands exposed to the user.""" +import shlex import types import functools @@ -41,12 +42,12 @@ def init(): @cmdutils.register() -def later(ms: int, *command: {'nargs': '+'}): +def later(ms: int, command): """Execute a command after some time. Args: ms: How many milliseconds to wait. - command: The command/args to run. + command: The command to run. """ timer = usertypes.Timer(name='later') timer.setSingleShot(True) @@ -58,7 +59,10 @@ def later(ms: int, *command: {'nargs': '+'}): raise cmdexc.CommandError("Numeric argument is too large for internal " "int representation.") _timers.append(timer) - cmdline = ' '.join(command) + try: + cmdline = shlex.split(command) + except ValueError as e: + raise cmdexc.CommandError("Could not split command: {}".format(e)) timer.timeout.connect(functools.partial( _commandrunner.run_safely, cmdline)) timer.timeout.connect(lambda: _timers.remove(timer)) diff --git a/scripts/generate_doc.py b/scripts/generate_doc.py index 0a104b303..cee4bcdda 100755 --- a/scripts/generate_doc.py +++ b/scripts/generate_doc.py @@ -239,6 +239,8 @@ def generate_commands(filename): hidden_cmds = [] debug_cmds = [] for name, cmd in cmdutils.cmd_dict.items(): + if name in cmdutils.aliases: + continue if cmd.hide: hidden_cmds.append((name, cmd)) elif cmd.debug: