Make it possible to deprecate commands.

See #448.

qutebrowser/commands/cmdutils.py

@@ -110,11 +110,13 @@ class register:  # pylint: disable=invalid-name
         _needs_js: If javascript is needed for this command.
         _debug: Whether this is a debugging command (only shown with --debug).
         _ignore_args: Whether to ignore the arguments of the function.
+        _deprecated: False, or a string describing why a command is deprecated.
     """
 
     def __init__(self, instance=None, name=None, maxsplit=None, hide=False,
                  completion=None, modes=None, not_modes=None, needs_js=False,
-                 debug=False, ignore_args=False, scope='global'):
+                 debug=False, ignore_args=False, deprecated=False,
+                 scope='global'):
         """Save decorator arguments.
 
         Gets called on parse-time with the decorator arguments.
@@ -134,6 +136,7 @@ class register:  # pylint: disable=invalid-name
         self._modes = modes
         self._not_modes = not_modes
         self._needs_js = needs_js
+        self._deprecated = deprecated
         self._debug = debug
         self._ignore_args = ignore_args
         if modes is not None:
@@ -192,7 +195,8 @@ class register:  # pylint: disable=invalid-name
             instance=self._instance, scope=self._scope,
             completion=self._completion, modes=self._modes,
             not_modes=self._not_modes, needs_js=self._needs_js,
-            is_debug=self._debug, ignore_args=self._ignore_args, handler=func)
+            is_debug=self._debug, ignore_args=self._ignore_args,
+            deprecated=self._deprecated, handler=func)
         for name in names:
             cmd_dict[name] = cmd
         aliases += names[1:]

qutebrowser/commands/command.py

@@ -37,6 +37,7 @@ class Command:
         maxsplit: The maximum amount of splits to do for the commandline, or
                   None.
         hide: Whether to hide the arguments or not.
+        deprecated: False, or a string to describe why a command is deprecated.
         desc: The description of the command.
         handler: The handler function to call.
         completion: Completions to use for arguments, as a list of strings.
@@ -63,13 +64,14 @@ class Command:
                                              'special'])
 
     def __init__(self, name, maxsplit, hide, instance, completion, modes,
-                 not_modes, needs_js, is_debug, ignore_args,
+                 not_modes, needs_js, is_debug, ignore_args, deprecated,
                  handler, scope):
         # I really don't know how to solve this in a better way, I tried.
         # pylint: disable=too-many-arguments,too-many-locals
         self.name = name
         self.maxsplit = maxsplit
         self.hide = hide
+        self.deprecated = deprecated
         self._instance = instance
         self.completion = completion
         self._modes = modes
@@ -121,6 +123,9 @@ class Command:
                 QWebSettings.JavascriptEnabled):
             raise cmdexc.PrerequisitesError(
                 "{}: This command needs javascript enabled.".format(self.name))
+        if self.deprecated:
+            message.warning(win_id, '{} is deprecated - {}'.format(
+                self.name, self.deprecated))
 
     def _check_func(self):
         """Make sure the function parameters don't violate any rules."""

qutebrowser/completion/models/completion.py

@@ -159,7 +159,8 @@ class CommandCompletionModel(base.BaseCompletionModel):
         assert cmdutils.cmd_dict
         cmdlist = []
         for obj in set(cmdutils.cmd_dict.values()):
-            if obj.hide or (obj.debug and not objreg.get('args').debug):
+            if (obj.hide or (obj.debug and not objreg.get('args').debug) or
+                    obj.deprecated):
                 pass
             else:
                 cmdlist.append((obj.name, obj.desc))
@@ -186,7 +187,8 @@ class HelpCompletionModel(base.BaseCompletionModel):
         assert cmdutils.cmd_dict
         cmdlist = []
         for obj in set(cmdutils.cmd_dict.values()):
-            if obj.hide or (obj.debug and not objreg.get('args').debug):
+            if (obj.hide or (obj.debug and not objreg.get('args').debug) or
+                    obj.deprecated):
                 pass
             else:
                 cmdlist.append((':' + obj.name, obj.desc))

scripts/src2asciidoc.py

@@ -248,7 +248,7 @@ def generate_commands(filename):
                 hidden_cmds.append((name, cmd))
             elif cmd.debug:
                 debug_cmds.append((name, cmd))
-            else:
+            elif not cmd.deprecated:
                 normal_cmds.append((name, cmd))
         normal_cmds.sort()
         hidden_cmds.sort()