CLI: Enable deprecation warnings before the prompts

`click.Command`s have a deprecated flag that results in a printed
deprecation warning on usage (and adaptions of help page). The
`click.option` prompts are however invoked before that warning is
printed. Therefore we consume the `deprecated` flag of the
`click.Command` in `VerdiCommandGroup.get_command` and handle the
deprecation logic there.

Add deprecation info of `verdi code setup` to help page

Add deprecation warning decoratior to `verdi setup`

Add deprecation info of `verdi setup` to help page

docs/source/reference/command_line.rst

@@ -80,7 +80,7 @@ Below is a list with all available subcommands.
       list       List the available codes.
       relabel    Relabel a code.
       reveal     Reveal one or more hidden codes in `verdi code list`.
-      setup      Setup a new code.
+      setup      (Deprecated: Use `verdi code create`) Setup a new code.
       show       Display detailed information for a code.
       test       Run tests for the given code to check whether it is usable.
 
@@ -512,7 +512,7 @@ Below is a list with all available subcommands.
 
     Usage:  [OPTIONS]
 
-      Setup a new profile.
+      (Deprecated: Use `verdi profile setup`) Setup a new profile.
 
       This method assumes that an empty PSQL database has been created and that the database
       user has been created.

src/aiida/cmdline/commands/cmd_code.py

@@ -15,10 +15,11 @@
 
 from aiida.cmdline.commands.cmd_verdi import verdi
 from aiida.cmdline.groups.dynamic import DynamicEntryPointCommandGroup
+from aiida.cmdline.groups.verdi import VerdiCommand
 from aiida.cmdline.params import arguments, options, types
 from aiida.cmdline.params.options.commands import code as options_code
 from aiida.cmdline.utils import echo, echo_tabulate
-from aiida.cmdline.utils.decorators import deprecated_command, with_dbenv
+from aiida.cmdline.utils.decorators import with_dbenv
 from aiida.common import exceptions
 
 
@@ -89,7 +90,7 @@ def set_code_builder(ctx, param, value):
 # because the ``LABEL`` option has a callback that relies on the computer being already set. Execution order is
 # guaranteed only for the interactive case, however. For the non-interactive case, the callback is called explicitly
 # once more in the command body to cover the case when the label is specified before the computer.
-@verdi_code.command('setup')
+@verdi_code.command('setup', verdi_deprecated=True, cls=VerdiCommand)
 @options_code.ON_COMPUTER()
 @options_code.COMPUTER()
 @options_code.LABEL()
@@ -105,9 +106,8 @@ def set_code_builder(ctx, param, value):
 @options.CONFIG_FILE()
 @click.pass_context
 @with_dbenv()
-@deprecated_command('This command will be removed soon, use `verdi code create` instead.')
 def setup_code(ctx, non_interactive, **kwargs):
-    """Setup a new code."""
+    """(Deprecated: Use `verdi code create`) Setup a new code."""
     from aiida.orm.utils.builders.code import CodeBuilder
 
     options_code.validate_label_uniqueness(ctx, None, kwargs['label'])

src/aiida/cmdline/commands/cmd_setup.py

@@ -11,13 +11,14 @@
 import click
 
 from aiida.cmdline.commands.cmd_verdi import verdi
+from aiida.cmdline.groups.verdi import VerdiCommand
 from aiida.cmdline.params import options
 from aiida.cmdline.params.options.commands import setup as options_setup
 from aiida.cmdline.utils import echo
 from aiida.manage.configuration import Profile, load_profile
 
 
-@verdi.command('setup')
+@verdi.command('setup', verdi_deprecated=True, cls=VerdiCommand)
 @options.NON_INTERACTIVE()
 @options_setup.SETUP_PROFILE()
 @options_setup.SETUP_USER_EMAIL()
@@ -67,7 +68,7 @@ def setup(
     test_profile,
     profile_uuid,
 ):
-    """Setup a new profile.
+    """(Deprecated: Use `verdi profile setup`) Setup a new profile.
 
     This method assumes that an empty PSQL database has been created and that the database user has been created.
     """

src/aiida/cmdline/groups/verdi.py

@@ -9,6 +9,7 @@
 
 import click
 
+from aiida.cmdline.utils.echo import echo_deprecated
 from aiida.common.exceptions import ConfigurationError
 from aiida.common.extendeddicts import AttributeDict
 from aiida.manage.configuration import get_config
@@ -70,6 +71,54 @@ def __getattr__(self, attr: str) -> t.Any:
         return super().__getattr__(attr)
 
 
+class VerdiCommand(click.Command):
+    """
+    Adds the boolean flag `verdi_deprecated` to handle deprecation in verdi.
+    The `deprecated` flag in `click.Command` is used to handle deprecated
+    commands within click, but it prints warnings after the prompts. To not
+    mess with click's internal logic but add the ability to print a warning
+    before the prompts we add another deprecation flag.
+
+    :param verdi_deprecated:
+    """
+
+    def __init__(
+        self,
+        name: t.Optional[str],
+        context_settings: t.Optional[t.MutableMapping[str, t.Any]] = None,
+        callback: t.Optional[t.Callable[..., t.Any]] = None,
+        params: t.Optional[t.List['click.Parameter']] = None,
+        help: t.Optional[str] = None,
+        epilog: t.Optional[str] = None,
+        short_help: t.Optional[str] = None,
+        options_metavar: t.Optional[str] = '[OPTIONS]',
+        add_help_option: bool = True,
+        no_args_is_help: bool = False,
+        hidden: bool = False,
+        deprecated: bool = False,
+        verdi_deprecated: bool = False,
+    ) -> None:
+        super().__init__(
+            name,
+            context_settings,
+            callback,
+            params,
+            help,
+            epilog,
+            short_help,
+            options_metavar,
+            add_help_option,
+            no_args_is_help,
+            hidden,
+            deprecated,
+        )
+        self._verdi_deprecated = verdi_deprecated
+
+    @property
+    def verdi_deprecated(self):
+        return self._verdi_deprecated
+
+
 class VerdiContext(click.Context):
     """Custom context implementation that defines the ``obj`` user object and adds the ``Config`` instance."""
 
@@ -132,6 +181,8 @@ def get_command(self, ctx: click.Context, cmd_name: str) -> click.Command | None
         cmd = super().get_command(ctx, cmd_name)
 
         if cmd is not None:
+            if hasattr(cmd, 'verdi_deprecated') and cmd.verdi_deprecated:
+                echo_deprecated('This command is deprecated. Please refer to help page for new usage.')
             return self.add_verbosity_option(cmd)
 
         # If this command is called during tab-completion, we do not want to print an error message if the command can't