command: Improve deprecation

Add a test and also allow setting a deprecated alias for a command
easily.

3 files changed, 49 insertions, 8 deletions

diff --git a/qutebrowser/api/cmdutils.py b/qutebrowser/api/cmdutils.py
index cc5d68aeb..85a700c43 100644
--- a/qutebrowser/api/cmdutils.py
+++ b/qutebrowser/api/cmdutils.py
@@ -112,6 +112,7 @@ class register:  # noqa: N801,N806 pylint: disable=invalid-name
     def __init__(self, *,
                  instance: str = None,
                  name: str = None,
+                 deprecated_name: str = None,
                  **kwargs: Any) -> None:
         """Save decorator arguments.
 
@@ -122,8 +123,10 @@ class register:  # noqa: N801,N806 pylint: disable=invalid-name
         """
         # The object from the object registry to be used as "self".
         self._instance = instance
-        # The name (as string) or names (as list) of the command.
+        # The name of the command
         self._name = name
+        # A possible deprecated alias (old name) of the command
+        self._deprecated_name = deprecated_name
         # The arguments to pass to Command.
         self._kwargs = kwargs
 
@@ -147,9 +150,28 @@ class register:  # noqa: N801,N806 pylint: disable=invalid-name
             assert isinstance(self._name, str), self._name
             name = self._name
 
-        cmd = command.Command(name=name, instance=self._instance,
-                              handler=func, **self._kwargs)
+        cmd = command.Command(
+            name=name,
+            instance=self._instance,
+            handler=func,
+            **self._kwargs,
+        )
         cmd.register()
+
+        if self._deprecated_name is not None:
+            deprecated_cmd = command.Command(
+                name=self._deprecated_name,
+                instance=self._instance,
+                handler=func,
+                deprecated=f"use {name} instead",
+                **self._kwargs,
+            )
+            deprecated_cmd.register()
+
+        # This is checked by future @cmdutils.argument calls so they fail
+        # (as they'd be silently ignored otherwise)
+        func.qute_args = None  # type: ignore[attr-defined]
+
         return func
 
 
diff --git a/qutebrowser/commands/command.py b/qutebrowser/commands/command.py
index 5ec14b557..653f551ff 100644
--- a/qutebrowser/commands/command.py
+++ b/qutebrowser/commands/command.py
@@ -128,10 +128,7 @@ class Command:
         self._signature = inspect.signature(handler)
         self._type_hints = typing.get_type_hints(handler)
 
-        # This is checked by future @cmdutils.argument calls so they fail
-        # (as they'd be silently ignored otherwise)
         self._qute_args = getattr(self.handler, 'qute_args', {})
-        self.handler.qute_args = None
 
         self._check_func()
         self._inspect_func()
@@ -152,8 +149,7 @@ class Command:
                 "backend.".format(self.name, self.backend.name))
 
         if self.deprecated:
-            message.warning('{} is deprecated - {}'.format(self.name,
-                                                           self.deprecated))
+            message.warning(f'{self.name} is deprecated - {self.deprecated}')
 
     def _check_func(self):
         """Make sure the function parameters don't violate any rules."""
diff --git a/tests/unit/api/test_cmdutils.py b/tests/unit/api/test_cmdutils.py
index 179b2e95f..77e648eed 100644
--- a/tests/unit/api/test_cmdutils.py
+++ b/tests/unit/api/test_cmdutils.py
@@ -512,3 +512,26 @@ class TestRun:
         cmd = objects.commands['fun']
         with pytest.raises(cmdexc.PrerequisitesError, match=r'.* backend\.'):
             cmd.run(win_id=0)
+
+    def test_deprecated(self, caplog, message_mock):
+        cmd = _get_cmd(deprecated='use something else')
+        with caplog.at_level(logging.WARNING):
+            cmd.run(win_id=0)
+
+        msg = message_mock.getmsg(usertypes.MessageLevel.warning)
+        assert msg.text == 'fun is deprecated - use something else'
+
+    def test_deprecated_name(self, caplog, message_mock):
+        @cmdutils.register(deprecated_name='dep')
+        def fun():
+            """Blah."""
+
+        original_cmd = objects.commands['fun']
+        original_cmd.run(win_id=0)
+
+        deprecated_cmd = objects.commands['dep']
+        with caplog.at_level(logging.WARNING):
+            deprecated_cmd.run(win_id=0)
+
+        msg = message_mock.getmsg(usertypes.MessageLevel.warning)
+        assert msg.text == 'dep is deprecated - use fun instead'