rnhmjoj/qutebrowser
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Improve some docstrings.

Browse Source
This commit is contained in:
Florian Bruhin 2014-09-13 00:22:27 +02:00
parent 2336b5de43
commit 80ef0782d5
8 changed files with 91 additions and 90 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

79
doc/help/commands.asciidoc
View File

@ -21,7 +21,6 @@
|<<paste,paste>>|Open a page from the clipboard.
|<<prev-page,prev-page>>|Open a "previous" link.
|<<print,print>>|Print the current/[count]th tab.
|<<q,q>>|Quit qutebrowser.
|<<quickmark-add,quickmark-add>>|Add a new quickmark.
|<<quickmark-load,quickmark-load>>|Load a quickmark.
|<<quickmark-save,quickmark-save>>|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

50
qutebrowser/browser/commands.py
View File

@ -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)

8
qutebrowser/browser/quickmarks.py
View File

@ -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,

3
qutebrowser/commands/cmdutils.py
View File

@ -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):

21
qutebrowser/config/config.py
View File

@ -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(

8
qutebrowser/config/keyconfparser.py
View File

@ -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'

10
qutebrowser/utils/utilcmds.py
View File

@ -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))

2
scripts/generate_doc.py
View File

@ -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: