CLI: Deprecate the deprecated_command decorator (#6461)

In an ironic turn of events, the `deprecated_command` decorator is
itself deprecated. The current way of deprecating `verdi` commands is by
passing the deprecation message in the `deprecated` argument in the
`command` decorator when the command is declared. New functionality in
`VerdiCommandGroup` then ensures that a deprecation message is printed
when the command is invoked and the help text is updated accordingly.

docs/source/reference/command_line.rst

@@ -409,7 +409,7 @@ Below is a list with all available subcommands.
 
     Usage:  [OPTIONS]
 
-      Setup a new profile in a fully automated fashion.
+      (Deprecated) Setup a new profile in a fully automated fashion.
 
     Options:
       -n, --non-interactive           In non-interactive mode, the CLI never prompts but

src/aiida/cmdline/commands/cmd_archive.py

@@ -78,15 +78,13 @@ def archive_info(path, detailed):
     echo.echo_dictionary(data, sort_keys=False, fmt='yaml')
 
 
-@verdi_archive.command('inspect', hidden=True)
+@verdi_archive.command(
+    'inspect', hidden=True, deprecated='Use `verdi archive version` or `verdi archive info` instead.'
+)
 @click.argument('archive', nargs=1, type=click.Path(exists=True, readable=True))
 @click.option('-v', '--version', is_flag=True, help='Print the archive format version and exit.')
 @click.option('-m', '--meta-data', is_flag=True, help='Print the meta data contents and exit.')
 @click.option('-d', '--database', is_flag=True, help='Include information on entities in the database.')
-@decorators.deprecated_command(
-    'This command has been deprecated and will be removed soon. '
-    'Please call `verdi archive version` or `verdi archive info` instead.\n'
-)
 @click.pass_context
 def inspect(ctx, archive, version, meta_data, database):
     """Inspect contents of an archive without importing it.

src/aiida/cmdline/commands/cmd_data/cmd_upf.py

@@ -23,9 +23,9 @@ def upf():
     """Manipulate UpfData objects (UPF-format pseudopotentials)."""
 
 
-@upf.command('uploadfamily')
-@decorators.deprecated_command(
-    'See https://aiida-pseudo.readthedocs.io/en/latest/howto.html#migrate-from-legacy-upfdata-from-aiida-core'
+@upf.command(
+    'uploadfamily',
+    deprecated='See https://aiida-pseudo.readthedocs.io/en/latest/howto.html#migrate-from-legacy-upfdata-from-aiida-core',
 )
 @click.argument('folder', type=click.Path(exists=True, file_okay=False, resolve_path=True))
 @click.argument('group_label', type=click.STRING)
@@ -50,9 +50,9 @@ def upf_uploadfamily(folder, group_label, group_description, stop_if_existing):
     echo.echo_success(f'UPF files found: {files_found}. New files uploaded: {files_uploaded}')
 
 
-@upf.command('listfamilies')
-@decorators.deprecated_command(
-    'See https://aiida-pseudo.readthedocs.io/en/latest/howto.html#migrate-from-legacy-upfdata-from-aiida-core'
+@upf.command(
+    'listfamilies',
+    deprecated='See https://aiida-pseudo.readthedocs.io/en/latest/howto.html#migrate-from-legacy-upfdata-from-aiida-core',
 )
 @click.option(
     '-d',
@@ -96,9 +96,9 @@ def upf_listfamilies(elements, with_description):
         echo.echo_warning('No valid UPF pseudopotential family found.')
 
 
-@upf.command('exportfamily')
-@decorators.deprecated_command(
-    'See https://aiida-pseudo.readthedocs.io/en/latest/howto.html#migrate-from-legacy-upfdata-from-aiida-core'
+@upf.command(
+    'exportfamily',
+    deprecated='See https://aiida-pseudo.readthedocs.io/en/latest/howto.html#migrate-from-legacy-upfdata-from-aiida-core',
 )
 @click.argument('folder', type=click.Path(exists=True, file_okay=False, resolve_path=True))
 @arguments.GROUP()
@@ -119,9 +119,9 @@ def upf_exportfamily(folder, group):
             echo.echo_warning(f'File {node.filename} is already present in the destination folder')
 
 
-@upf.command('import')
-@decorators.deprecated_command(
-    'See https://aiida-pseudo.readthedocs.io/en/latest/howto.html#migrate-from-legacy-upfdata-from-aiida-core'
+@upf.command(
+    'import',
+    deprecated='See https://aiida-pseudo.readthedocs.io/en/latest/howto.html#migrate-from-legacy-upfdata-from-aiida-core',
 )
 @click.argument('filename', type=click.Path(exists=True, dir_okay=False, resolve_path=True))
 @decorators.with_dbenv()
@@ -133,9 +133,9 @@ def upf_import(filename):
     echo.echo_success(f'Imported: {node}')
 
 
-@upf.command('export')
-@decorators.deprecated_command(
-    'See https://aiida-pseudo.readthedocs.io/en/latest/howto.html#migrate-from-legacy-upfdata-from-aiida-core'
+@upf.command(
+    'export',
+    deprecated='See https://aiida-pseudo.readthedocs.io/en/latest/howto.html#migrate-from-legacy-upfdata-from-aiida-core',
 )
 @arguments.DATUM(type=types.DataParamType(sub_classes=('aiida.data:core.upf',)))
 @options.EXPORT_FORMAT(

src/aiida/cmdline/commands/cmd_rabbitmq.py

@@ -222,10 +222,9 @@ def cmd_tasks_list(broker):
         echo.echo(pk)
 
 
-@cmd_tasks.command('analyze')
+@cmd_tasks.command('analyze', deprecated='Use `verdi process repair` instead.')
 @click.option('--fix', is_flag=True, help='Attempt to fix the inconsistencies if any are detected.')
 @decorators.only_if_daemon_not_running()
-@decorators.deprecated_command('Use `verdi process repair` instead.')
 @click.pass_context
 def cmd_tasks_analyze(ctx, fix):
     """Perform analysis of process tasks.

src/aiida/cmdline/commands/cmd_setup.py

@@ -13,7 +13,7 @@
 from aiida.cmdline.commands.cmd_verdi import verdi
 from aiida.cmdline.params import options
 from aiida.cmdline.params.options.commands import setup as options_setup
-from aiida.cmdline.utils import decorators, echo
+from aiida.cmdline.utils import echo
 from aiida.manage.configuration import Profile, load_profile
 
 
@@ -136,10 +136,10 @@ def setup(
     echo.echo_success(f'created new profile `{profile.name}`.')
 
 
-@verdi.command('quicksetup')
-@decorators.deprecated_command(
-    'This command is deprecated. For a fully automated alternative, use `verdi presto --use-postgres` instead. '
-    'For full control, use `verdi profile setup core.psql_dos`.'
+@verdi.command(
+    'quicksetup',
+    deprecated='This command is deprecated. For a fully automated alternative, use `verdi presto --use-postgres` '
+    'instead. For full control, use `verdi profile setup core.psql_dos`.',
 )
 @options.NON_INTERACTIVE()
 # Cannot use `default` because that will fail validation of the `ProfileParamType` if the profile already exists and it

src/aiida/cmdline/utils/decorators.py

@@ -248,7 +248,16 @@ def deprecated_command(message):
         @deprecated_command('This command has been deprecated in AiiDA v1.0, please use 'foo' instead.)
         def mycommand():
             pass
+
+    .. deprecated:: 2.6
+
+        Ironically, this decorator itself has been deprecated. ``verdi`` commands that should be deprecated should
+        simply use the ``deprecated`` argument in the ``command`` decorator and specify the deprecation message.
+
     """
+    from aiida.common.warnings import warn_deprecation
+
+    warn_deprecation('The `deprecated_command` decorator is deprecated', version=3)
 
     @decorator
     def wrapper(wrapped, _, args, kwargs):