Add typing to aiida.cmdline.params module (#6952)

* Add typing to src/aiida/cmdline/params/options/multivalue.py
* Add typing to src/aiida/cmdline/params/types/group.py
* Type check src/aiida/cmdline/params/options/interactive.py
* Typecheck src/aiida/cmdline/params/options/main.py
* Typecheck src/aiida/cmdline/params/options/commands/setup.py
* Type AiiDAConfigDir.get and get_config
* Fix type error in src/aiida/cmdline/utils/multi_line_input.py
* Add typing to src/aiida/cmdline/utils/shell.py
* Don't allow sub_classes=None in cmdline/params/types/group.py

Author: danielhollas

.pre-commit-config.yaml

@@ -107,11 +107,6 @@ repos:
         src/aiida/cmdline/commands/cmd_node.py|
         src/aiida/cmdline/commands/cmd_shell.py|
         src/aiida/cmdline/commands/cmd_storage.py|
-        src/aiida/cmdline/params/options/commands/setup.py|
-        src/aiida/cmdline/params/options/interactive.py|
-        src/aiida/cmdline/params/options/main.py|
-        src/aiida/cmdline/params/options/multivalue.py|
-        src/aiida/cmdline/params/types/group.py|
         src/aiida/cmdline/utils/ascii_vis.py|
         src/aiida/cmdline/utils/common.py|
         src/aiida/cmdline/utils/echo.py|

docs/source/nitpick-exceptions

@@ -135,6 +135,7 @@ py:class click.types.Choice
 py:class click.types.Path
 py:class click.types.File
 py:class click.types.StringParamType
+py:class click.parser.OptionParser
 py:func click.shell_completion._start_of_option
 py:meth click.Option.get_default
 py:meth fail

src/aiida/cmdline/params/options/commands/setup.py

@@ -8,20 +8,23 @@
 ###########################################################################
 """Reusable command line interface options for the setup commands."""
 
+from __future__ import annotations
+
 import functools
 import getpass
+import typing as t
 
 import click
 
 from aiida.brokers.rabbitmq.defaults import BROKER_DEFAULTS
 from aiida.cmdline.params import options, types
 from aiida.manage.configuration import Profile, get_config, get_config_option
-from aiida.manage.external.postgres import DEFAULT_DBINFO
+from aiida.manage.external.postgres import DEFAULT_DBINFO  # type: ignore[attr-defined]
 
 PASSWORD_UNCHANGED = '***'
 
 
-def validate_profile_parameter(ctx):
+def validate_profile_parameter(ctx: click.Context) -> None:
     """Validate that the context contains the option `profile` and it contains a `Profile` instance.
 
     :param ctx: click context which should contain the selected profile
@@ -32,10 +35,10 @@ def validate_profile_parameter(ctx):
         raise click.BadParameter('specifying the name of the profile is required', param_hint=f'"--{option}"')
 
 
-def get_profile_attribute_default(attribute_tuple, ctx):
+def get_profile_attribute_default(attribute_tuple: tuple[str, t.Any], ctx: click.Context) -> t.Any:
     """Return the default value for the given attribute of the profile passed in the context.
 
-    :param attribute: attribute for which to get the current value
+    :param attribute_tuple: attribute for which to get the current value, and its default
     :param ctx: click context which should contain the selected profile
     :return: profile attribute default value if set, or None
     """
@@ -58,7 +61,7 @@ def get_profile_attribute_default(attribute_tuple, ctx):
         return default
 
 
-def get_repository_uri_default(ctx):
+def get_repository_uri_default(ctx: click.Context) -> str:
     """Return the default value for the repository URI for the current profile in the click context.
 
     :param ctx: click context which should contain the selected profile
@@ -74,7 +77,7 @@ def get_repository_uri_default(ctx):
     return os.path.join(configure_directory, 'repository', ctx.params['profile'].name)
 
 
-def get_quicksetup_repository_uri(ctx, param, value):
+def get_quicksetup_repository_uri(ctx: click.Context, _param: click.Parameter, _value: t.Any) -> str:
     """Return the repository URI to be used as default in `verdi quicksetup`
 
     :param ctx: click context which should contain the contextual parameters
@@ -83,7 +86,7 @@ def get_quicksetup_repository_uri(ctx, param, value):
     return get_repository_uri_default(ctx)
 
 
-def get_quicksetup_database_name(ctx, param, value):
+def get_quicksetup_database_name(ctx: click.Context, _param: click.Parameter, value: str | None) -> str:
     """Determine the database name to be used as default for the Postgres connection in `verdi quicksetup`
 
     If a value is explicitly passed, that value is returned unchanged.
@@ -109,7 +112,7 @@ def get_quicksetup_database_name(ctx, param, value):
     return database_name
 
 
-def get_quicksetup_username(ctx, param, value):
+def get_quicksetup_username(ctx: click.Context, param: click.Parameter, value: str | None) -> str:
     """Determine the username to be used as default for the Postgres connection in `verdi quicksetup`
 
     If a value is explicitly passed, that value is returned. If there is no value, the name will be based on the
@@ -130,7 +133,7 @@ def get_quicksetup_username(ctx, param, value):
     return username
 
 
-def get_quicksetup_password(ctx, param, value):
+def get_quicksetup_password(ctx: click.Context, param: click.Parameter, value: str | None) -> str:
     """Determine the password to be used as default for the Postgres connection in `verdi quicksetup`
 
     If a value is explicitly passed, that value is returned. If there is no value, the current username in the context

src/aiida/cmdline/params/options/interactive.py

@@ -8,9 +8,12 @@
 ###########################################################################
 """Tools and an option class for interactive parameter entry with additional features such as help lookup."""
 
+from __future__ import annotations
+
 import typing as t
 
 import click
+from click.shell_completion import CompletionItem
 
 from aiida.cmdline.utils import echo
 
@@ -64,7 +67,7 @@ def prompt(self):
         return click.style(self._prompt, fg=self.PROMPT_COLOR)
 
     @prompt.setter
-    def prompt(self, value):
+    def prompt(self, value: str | None) -> None:
         """Set the prompt text."""
         self._prompt = value
 
@@ -86,7 +89,7 @@ def prompt_for_value(self, ctx: click.Context) -> t.Any:
         if not hasattr(ctx, 'prompt_loop_info_printed'):
             echo.echo_report(f'enter {self.CHARACTER_PROMPT_HELP} for help.')
             echo.echo_report(f'enter {self.CHARACTER_IGNORE_DEFAULT} to ignore the default and set no value.')
-            ctx.prompt_loop_info_printed = True
+            ctx.prompt_loop_info_printed = True  # type: ignore[attr-defined]
 
         return super().prompt_for_value(ctx)
 
@@ -101,6 +104,9 @@ def process_value(self, ctx: click.Context, value: t.Any) -> t.Any:
         specified the ``click.Context.get_parameter_source`` method is used. The ``click.Parameter.handle_parse_result``
         method will set this after ``Parameter.consume_value``` is called but before ``Parameter.process_value`` is.
         """
+        if self.name is None:
+            return value
+
         source = ctx.get_parameter_source(self.name)
 
         if source is None:
@@ -127,11 +133,12 @@ def process_value(self, ctx: click.Context, value: t.Any) -> t.Any:
                 return self.prompt_for_value(ctx)
             raise
 
-    def get_help_message(self):
+    def get_help_message(self) -> str:
         """Return a message to be displayed for in-prompt help."""
         message = self.help or f'Expecting {self.type.name}'
 
-        choices = getattr(self.type, 'shell_complete', lambda x, y, z: [])(self.type, None, '')
+        shell_complete: t.Callable = getattr(self.type, 'shell_complete', lambda x, y, z: [])
+        choices: list[CompletionItem] = shell_complete(self.type, None, '')
         choices_string = []
 
         for choice in choices:
@@ -146,7 +153,7 @@ def get_help_message(self):
 
         return message
 
-    def get_default(self, ctx: click.Context, call: bool = True) -> t.Optional[t.Union[t.Any, t.Callable[[], t.Any]]]:
+    def get_default(self, ctx: click.Context, call: bool = True) -> t.Callable[[], t.Any] | None:
         """Provides the functionality of :meth:`click.Option.get_default`"""
         if ctx.resilient_parsing:
             return None
@@ -157,7 +164,7 @@ def get_default(self, ctx: click.Context, call: bool = True) -> t.Optional[t.Uni
             default = super().get_default(ctx, call=call)
 
         try:
-            default = self.type.deconvert_default(default)
+            default = self.type.deconvert_default(default)  # type: ignore[attr-defined]
         except AttributeError:
             pass
 

src/aiida/cmdline/params/options/main.py

@@ -8,13 +8,16 @@
 ###########################################################################
 """Module with pre-defined reusable commandline options that can be used as `click` decorators."""
 
+from __future__ import annotations
+
 import pathlib
+import typing as t
 
 import click
 
 from aiida.brokers.rabbitmq.defaults import BROKER_DEFAULTS
 from aiida.common.log import LOG_LEVELS, configure_logging
-from aiida.manage.external.postgres import DEFAULT_DBINFO
+from aiida.manage.external.postgres import DEFAULT_DBINFO  # type: ignore[attr-defined]
 
 from ...utils import defaults, echo
 from .. import types
@@ -149,21 +152,21 @@
 }
 
 
-def valid_process_states():
+def valid_process_states() -> tuple[str, ...]:
     """Return a list of valid values for the ProcessState enum."""
     from plumpy import ProcessState
 
     return tuple(state.value for state in ProcessState)
 
 
-def valid_calc_job_states():
+def valid_calc_job_states() -> tuple[str, ...]:
     """Return a list of valid values for the CalcState enum."""
     from aiida.common.datastructures import CalcJobState
 
     return tuple(state.value for state in CalcJobState)
 
 
-def active_process_states():
+def active_process_states() -> list[str]:
     """Return a list of process states that are considered active."""
     from plumpy import ProcessState
 
@@ -174,7 +177,7 @@ def active_process_states():
     ]
 
 
-def graph_traversal_rules(rules):
+def graph_traversal_rules(rules: dict) -> t.Callable:
     """Apply the graph traversal rule options to the command."""
 
     def decorator(command):
@@ -191,7 +194,7 @@ def decorator(command):
     return decorator
 
 
-def set_log_level(ctx, _param, value):
+def set_log_level(ctx: click.Context, _param: click.Parameter, value: t.Any) -> t.Any:
     """Configure the logging for the CLI command being executed.
 
     Note that we cannot use the most obvious approach of directly setting the level on the various loggers. The reason

src/aiida/cmdline/params/options/multivalue.py

@@ -15,7 +15,7 @@
 __all__ = ('MultipleValueOption',)
 
 
-def collect_usage_pieces(self, ctx):
+def collect_usage_pieces(self: click.Command, ctx: click.Context) -> list[str]:
     """Returns all the pieces that go into the usage line and returns it as a list of strings."""
     result = [self.options_metavar]
 
@@ -27,11 +27,11 @@ def collect_usage_pieces(self, ctx):
     for param in self.get_params(ctx):
         result.extend(param.get_usage_pieces(ctx))
 
-    return result
+    return result  # type: ignore[return-value]
 
 
 # Override the `collect_usage_pieces` method of the `click.Command` class to automatically affect all commands
-click.Command.collect_usage_pieces = collect_usage_pieces
+click.Command.collect_usage_pieces = collect_usage_pieces  # type: ignore[method-assign]
 
 
 class MultipleValueOption(click.Option):
@@ -57,7 +57,8 @@ def __init__(self, *args, **kwargs):
         self._previous_parser_process = None
         self._eat_all_parser = None
 
-    def add_to_parser(self, parser, ctx):
+    # TODO: add_to_parser has been deprecated in 8.2.0
+    def add_to_parser(self, parser: click.parser.OptionParser, ctx: click.Context) -> None:
         """Override built in click method that allows us to specify a custom parser
         to eat up parameters until the following flag or 'endopt' (i.e. --)
         """
@@ -75,20 +76,20 @@ def parser_process(value, state):
 
             # Grab everything up to the next option or endopts symbol
             while state.rargs and not done:
-                for prefix in self._eat_all_parser.prefixes:
+                for prefix in self._eat_all_parser.prefixes:  # type: ignore[union-attr]
                     if state.rargs[0].startswith(prefix) or state.rargs[0] == ENDOPTS:
                         done = True
                 if not done:
                     value.append(state.rargs.pop(0))
 
             value = tuple(value)
 
-            self._previous_parser_process(value, state)
+            self._previous_parser_process(value, state)  # type: ignore[misc]
 
         for name in self.opts:
             our_parser = parser._long_opt.get(name) or parser._short_opt.get(name)
             if our_parser:
                 self._eat_all_parser = our_parser
                 self._previous_parser_process = our_parser.process
-                our_parser.process = parser_process
+                our_parser.process = parser_process  # type: ignore[method-assign]
                 break

src/aiida/cmdline/params/options/overridable.py

@@ -8,6 +8,8 @@
 ###########################################################################
 """Convenience class which can be used to defined a set of commonly used options that can be easily reused."""
 
+import typing as t
+
 import click
 
 __all__ = ('OverridableOption',)
@@ -48,7 +50,7 @@ def __init__(self, *args, **kwargs):
         self.args = args
         self.kwargs = kwargs
 
-    def __call__(self, **kwargs):
+    def __call__(self, **kwargs) -> t.Callable[[t.Any], t.Any]:
         """Override the stored kwargs, (ignoring args as we do not allow option name changes) and return the option.
 
         :param kwargs: keyword arguments that will override those set in the construction
@@ -58,7 +60,7 @@ def __call__(self, **kwargs):
         kw_copy.update(kwargs)
         return click.option(*self.args, **kw_copy)
 
-    def clone(self, **kwargs):
+    def clone(self, **kwargs) -> 'OverridableOption':
         """Create a new instance of by cloning the current instance and updating the stored kwargs with those passed.
 
         This can be useful when an already predefined OverridableOption needs to be further specified and reused

src/aiida/cmdline/params/types/group.py

@@ -8,6 +8,10 @@
 ###########################################################################
 """Module for custom click param type group."""
 
+from __future__ import annotations
+
+import typing as t
+
 import click
 
 from aiida.cmdline.utils import decorators
@@ -23,7 +27,7 @@ class GroupParamType(IdentifierParamType):
 
     name = 'Group'
 
-    def __init__(self, create_if_not_exist=False, sub_classes=('aiida.groups:core',)):
+    def __init__(self, create_if_not_exist: bool = False, sub_classes: tuple[str] = ('aiida.groups:core',)):
         """Construct the parameter type.
 
         The `sub_classes` argument can be used to narrow the set of subclasses of `Group` that should be matched. By
@@ -60,7 +64,9 @@ def orm_class_loader(self):
         return GroupEntityLoader
 
     @decorators.with_dbenv()
-    def shell_complete(self, ctx, param, incomplete):
+    def shell_complete(
+        self, ctx: click.Context, param: click.Parameter, incomplete: str
+    ) -> list[click.shell_completion.CompletionItem]:
         """Return possible completions based on an incomplete value.
 
         :returns: list of tuples of valid entry points (matching incomplete) and a description
@@ -71,13 +77,13 @@ def shell_complete(self, ctx, param, incomplete):
         ]
 
     @decorators.with_dbenv()
-    def convert(self, value, param, ctx):
+    def convert(self, value: t.Any, param: click.Parameter, ctx: click.Context) -> t.Any:
         try:
             group = super().convert(value, param, ctx)
         except click.BadParameter:
             if self._create_if_not_exist:
                 # The particular subclass to load will be stored in `_sub_classes` as loaded by `convert` of the super.
-                cls = self._sub_classes[0]
+                cls = self._sub_classes[0]  # type: ignore[index]
                 group = cls(label=value).store()
             else:
                 raise

src/aiida/cmdline/params/types/identifier.py

@@ -76,15 +76,15 @@ def _entry_points(self) -> list[EntryPoint]:
 
     @property
     @abstractmethod
-    @with_dbenv()  # type: ignore[misc]
+    @with_dbenv()
     def orm_class_loader(self) -> OrmEntityLoader:
         """Return the orm entity loader class, which should be a subclass of OrmEntityLoader. This class is supposed
         to be used to load the entity for a given identifier
 
         :return: the orm entity loader class for this ParamType
         """
 
-    @with_dbenv()  # type: ignore[misc]
+    @with_dbenv()
     def convert(self, value: t.Any, param: click.Parameter | None, ctx: click.Context) -> t.Any:
         """Attempt to convert the given value to an instance of the orm class using the orm class loader.