avoid global vs local variable problem for message; standardize versi…

…on printing; add doc

src/aiida/cmdline/utils/decorators.py

@@ -19,8 +19,10 @@
 """
 
 from contextlib import contextmanager
+from typing import Optional
 
 from click_spinner import spinner
+from packaging.version import Version
 from wrapt import decorator
 
 from . import echo
@@ -239,13 +241,17 @@ def do_circus_stuff():
     return wrapped(*args, **kwargs)
 
 
-def deprecated_command(message, version=None):
+def deprecated_command(message: str, version: Optional[str] = '3.0.0'):
     """Function decorator that will mark a click command as deprecated when invoked.
 
+    :param message: The message that should be printed with the deprecation warning.
+    :param version: Specifies the version for which the command will be removed. Any string is valid that is accepted by
+                    :class:`packaging.version.Version`. If None, no information about the version is mentioned.
+
     Example::
 
         @click.command()
-        @deprecated_command('This command has been deprecated in AiiDA v1.0, please use 'foo' instead.)
+        @deprecated_command('This command has been deprecated, please use 'foo' instead.' version='1.0')
         def mycommand():
             pass
     """
@@ -260,7 +266,10 @@ def wrapper(wrapped, _, args, kwargs):
         template = templates.env.get_template('deprecated.tpl')
         width = 80
         if version is not None:
-            extended_message = f'{message} (this will be removed in v{version})'
+            version_object = Version(version)
+            # we print the version always in X.Y.Z format, e.g. "1.2" -> "1.2.0", "1" -> "1.0.0"
+            long_version = f'{version_object.major}.{version_object.minor}.{version_object.micro}'
+            extended_message = f'{message} (this will be removed in v{long_version})'
         else:
             extended_message = f'{message}'
         echo.echo(template.render(msg=wrap(extended_message, width - 4), width=width))