Document and type hint commands part 4 (#4313)

Covers commands list through prepare

.config/pydoclint-baseline.txt

@@ -14,50 +14,6 @@ src/molecule/command/init/scenario.py
     DOC107: Function `scenario`: The option `--arg-type-hints-in-signature` is `True` but not all args in the signature have type hints
     DOC103: Function `scenario`: Docstring arguments are different from function arguments. (Or could be other formatting issues: https://jsh9.github.io/pydoclint/violation_codes.html#notes-on-doc103 ). Arguments in the function signature but not in the docstring: [ctx: , dependency_name: , driver_name: , provisioner_name: , scenario_name: ].
 --------------------
-src/molecule/command/list.py
-    DOC101: Method `List.execute`: Docstring contains fewer arguments than in function signature.
-    DOC106: Method `List.execute`: The option `--arg-type-hints-in-signature` is `True` but there are no argument type hints in the signature
-    DOC107: Method `List.execute`: The option `--arg-type-hints-in-signature` is `True` but not all args in the signature have type hints
-    DOC103: Method `List.execute`: Docstring arguments are different from function arguments. (Or could be other formatting issues: https://jsh9.github.io/pydoclint/violation_codes.html#notes-on-doc103 ). Arguments in the function signature but not in the docstring: [action_args: ].
-    DOC201: Method `List.execute` does not have a return section in docstring
-    DOC101: Function `list`: Docstring contains fewer arguments than in function signature.
-    DOC106: Function `list`: The option `--arg-type-hints-in-signature` is `True` but there are no argument type hints in the signature
-    DOC107: Function `list`: The option `--arg-type-hints-in-signature` is `True` but not all args in the signature have type hints
-    DOC103: Function `list`: Docstring arguments are different from function arguments. (Or could be other formatting issues: https://jsh9.github.io/pydoclint/violation_codes.html#notes-on-doc103 ). Arguments in the function signature but not in the docstring: [ctx: , format: , scenario_name: ].
-    DOC106: Function `_print_tabulate_data`: The option `--arg-type-hints-in-signature` is `True` but there are no argument type hints in the signature
-    DOC107: Function `_print_tabulate_data`: The option `--arg-type-hints-in-signature` is `True` but not all args in the signature have type hints
---------------------
-src/molecule/command/login.py
-    DOC101: Method `Login.__init__`: Docstring contains fewer arguments than in function signature.
-    DOC106: Method `Login.__init__`: The option `--arg-type-hints-in-signature` is `True` but there are no argument type hints in the signature
-    DOC107: Method `Login.__init__`: The option `--arg-type-hints-in-signature` is `True` but not all args in the signature have type hints
-    DOC103: Method `Login.__init__`: Docstring arguments are different from function arguments. (Or could be other formatting issues: https://jsh9.github.io/pydoclint/violation_codes.html#notes-on-doc103 ). Arguments in the function signature but not in the docstring: [c: ].
-    DOC101: Method `Login.execute`: Docstring contains fewer arguments than in function signature.
-    DOC106: Method `Login.execute`: The option `--arg-type-hints-in-signature` is `True` but there are no argument type hints in the signature
-    DOC107: Method `Login.execute`: The option `--arg-type-hints-in-signature` is `True` but not all args in the signature have type hints
-    DOC103: Method `Login.execute`: Docstring arguments are different from function arguments. (Or could be other formatting issues: https://jsh9.github.io/pydoclint/violation_codes.html#notes-on-doc103 ). Arguments in the function signature but not in the docstring: [action_args: ].
-    DOC101: Function `login`: Docstring contains fewer arguments than in function signature.
-    DOC106: Function `login`: The option `--arg-type-hints-in-signature` is `True` but there are no argument type hints in the signature
-    DOC107: Function `login`: The option `--arg-type-hints-in-signature` is `True` but not all args in the signature have type hints
-    DOC103: Function `login`: Docstring arguments are different from function arguments. (Or could be other formatting issues: https://jsh9.github.io/pydoclint/violation_codes.html#notes-on-doc103 ). Arguments in the function signature but not in the docstring: [ctx: , host: , scenario_name: ].
---------------------
-src/molecule/command/matrix.py
-    DOC101: Function `matrix`: Docstring contains fewer arguments than in function signature.
-    DOC106: Function `matrix`: The option `--arg-type-hints-in-signature` is `True` but there are no argument type hints in the signature
-    DOC107: Function `matrix`: The option `--arg-type-hints-in-signature` is `True` but not all args in the signature have type hints
-    DOC103: Function `matrix`: Docstring arguments are different from function arguments. (Or could be other formatting issues: https://jsh9.github.io/pydoclint/violation_codes.html#notes-on-doc103 ). Arguments in the function signature but not in the docstring: [ctx: , scenario_name: , subcommand: ].
---------------------
-src/molecule/command/prepare.py
-    DOC101: Method `Prepare.execute`: Docstring contains fewer arguments than in function signature.
-    DOC106: Method `Prepare.execute`: The option `--arg-type-hints-in-signature` is `True` but there are no argument type hints in the signature
-    DOC107: Method `Prepare.execute`: The option `--arg-type-hints-in-signature` is `True` but not all args in the signature have type hints
-    DOC103: Method `Prepare.execute`: Docstring arguments are different from function arguments. (Or could be other formatting issues: https://jsh9.github.io/pydoclint/violation_codes.html#notes-on-doc103 ). Arguments in the function signature but not in the docstring: [action_args: ].
-    DOC201: Method `Prepare.execute` does not have a return section in docstring
-    DOC101: Function `prepare`: Docstring contains fewer arguments than in function signature.
-    DOC106: Function `prepare`: The option `--arg-type-hints-in-signature` is `True` but there are no argument type hints in the signature
-    DOC107: Function `prepare`: The option `--arg-type-hints-in-signature` is `True` but not all args in the signature have type hints
-    DOC103: Function `prepare`: Docstring arguments are different from function arguments. (Or could be other formatting issues: https://jsh9.github.io/pydoclint/violation_codes.html#notes-on-doc103 ). Arguments in the function signature but not in the docstring: [ctx: , driver_name: , force: , scenario_name: ].
---------------------
 src/molecule/command/reset.py
     DOC101: Function `reset`: Docstring contains fewer arguments than in function signature.
     DOC106: Function `reset`: The option `--arg-type-hints-in-signature` is `True` but there are no argument type hints in the signature

src/molecule/command/base.py

@@ -342,14 +342,18 @@ def click_group_ex() -> ClickGroup:
     )
 
 
-def click_command_ex() -> ClickCommand:
+def click_command_ex(name: str | None = None) -> ClickCommand:
     """Return extended version of click.command().
 
+    Args:
+        name: A replacement name in the case the automatic one is insufficient.
+
     Returns:
         Click command group.
     """
     return click.command(
         cls=HelpColorsCommand,
+        name=name,
         help_headers_color="yellow",
         help_options_color="green",
     )

src/molecule/command/list.py

@@ -22,7 +22,7 @@
 
 import logging
 
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Literal
 
 import click
 
@@ -38,7 +38,7 @@
 
 
 if TYPE_CHECKING:
-    from molecule.types import CommandArgs
+    from molecule.types import CommandArgs, MoleculeArgs
 
 
 LOG = logging.getLogger(__name__)
@@ -47,12 +47,22 @@
 class List(base.Base):
     """List command shows information about current scenarios."""
 
-    def execute(self, action_args=None):  # type: ignore[no-untyped-def]  # noqa: ANN001, ANN201, ARG002
-        """Execute the actions necessary to perform a `molecule list` and returns None."""
-        return self._config.driver.status()  # type: ignore[no-untyped-call]
+    def execute(  # type: ignore[override]
+        self,
+        action_args: list[str] | None = None,  # noqa: ARG002
+    ) -> list[Status]:
+        """Execute the actions necessary to perform a `molecule list`.
 
+        Args:
+            action_args: Arguments for this command. Unused.
 
-@base.click_command_ex()
+        Returns:
+            List of statuses.
+        """
+        return self._config.driver.status()  # type: ignore[no-untyped-call, no-any-return]
+
+
+@base.click_command_ex(name="list")
 @click.pass_context
 @click.option("--scenario-name", "-s", help="Name of the scenario to target.")
 @click.option(
@@ -62,9 +72,19 @@ def execute(self, action_args=None):  # type: ignore[no-untyped-def]  # noqa: AN
     default="simple",
     help="Change output format. (simple)",
 )
-def list(ctx, scenario_name, format):  # type: ignore[no-untyped-def] # pragma: no cover  # noqa: ANN001, ANN201, A001, A002
-    """List status of instances."""
-    args = ctx.obj.get("args")
+def list_(
+    ctx: click.Context,
+    scenario_name: str,
+    format: Literal["simple", "plain", "yaml"],  # noqa: A002
+) -> None:  # pragma: no cover
+    """List status of instances.
+
+    Args:
+        ctx: Click context object holding commandline arguments.
+        scenario_name: Name of the scenario to target.
+        format: Output format type.
+    """
+    args: MoleculeArgs = ctx.obj.get("args")
     subcommand = base._get_subcommand(__name__)  # noqa: SLF001
     command_args: CommandArgs = {"subcommand": subcommand, "format": format}
 
@@ -78,18 +98,21 @@ def list(ctx, scenario_name, format):  # type: ignore[no-untyped-def] # pragma:
 
     headers = [text.title(name) for name in Status._fields]
     if format in ["simple", "plain"]:
-        table_format = format  # "simple"
+        table_format = format
 
         if format == "plain":
             headers = []
-            table_format = format
-        _print_tabulate_data(headers, statuses, table_format)  # type: ignore[no-untyped-call]
+        _print_tabulate_data(headers, statuses, table_format)
     else:
-        _print_yaml_data(headers, statuses)  # type: ignore[no-untyped-call]
+        _print_yaml_data(headers, statuses)
 
 
-def _print_tabulate_data(headers, data, table_format):  # type: ignore[no-untyped-def] # pragma: no cover  # noqa: ANN001, ANN202
-    """Show the tabulate data on the screen and returns None.
+def _print_tabulate_data(
+    headers: list[str],
+    data: list[Status],
+    table_format: str,
+) -> None:  # pragma: no cover
+    """Show the tabulate data on the screen.
 
     Args:
         headers: A list of column headers.
@@ -108,7 +131,16 @@ def _print_tabulate_data(headers, data, table_format):  # type: ignore[no-untype
         console.print(t)
 
 
-def _print_yaml_data(headers, data):  # type: ignore[no-untyped-def] # pragma: no cover  # noqa: ANN001, ANN202
+def _print_yaml_data(
+    headers: list[str],
+    data: list[Status],
+) -> None:  # pragma: no cover
+    """Show the tabulate data on the screen in yaml format.
+
+    Args:
+        headers: A list of column headers.
+        data: A list of tabular data to display.
+    """
     l = [  # noqa: E741
         dict(zip(headers, [getattr(datum, field) for field in datum._fields], strict=False))
         for datum in data

src/molecule/command/login.py

@@ -34,6 +34,7 @@
 
 
 if TYPE_CHECKING:
+    from molecule import config
     from molecule.types import CommandArgs
 
 
@@ -43,22 +44,30 @@
 class Login(base.Base):
     """Login Command Class."""
 
-    def __init__(self, c) -> None:  # type: ignore[no-untyped-def]  # noqa: ANN001
-        """Construct Login."""
+    def __init__(self, c: config.Config) -> None:
+        """Construct Login.
+
+        Args:
+            c: An instance of a Molecule config.
+        """
         super().__init__(c)
         self._pt = None
 
-    def execute(self, action_args=None):  # type: ignore[no-untyped-def]  # noqa: ANN001, ANN201, ARG002
-        """Execute the actions necessary to perform a `molecule login` and returns None."""
+    def execute(self, action_args: list[str] | None = None) -> None:  # noqa: ARG002
+        """Execute the actions necessary to perform a `molecule login`.
+
+        Args:
+            action_args: Arguments for this command. Unused.
+        """
         c = self._config
         if (not c.state.created) and c.driver.managed:
             base.execute_subcommand(c, "create")
 
         hosts = [d["name"] for d in self._config.platforms.instances]
-        hostname = self._get_hostname(hosts)  # type: ignore[no-untyped-call]
-        self._get_login(hostname)  # type: ignore[no-untyped-call]
+        hostname = self._get_hostname(hosts)
+        self._get_login(hostname)
 
-    def _get_hostname(self, hosts):  # type: ignore[no-untyped-def]  # noqa: ANN001, ANN202
+    def _get_hostname(self, hosts: list[str]) -> str:
         hostname = self._config.command_args.get("host")
         host_list = "\n".join(sorted(hosts))
         if hostname is None:
@@ -93,7 +102,7 @@ def _get_hostname(self, hosts):  # type: ignore[no-untyped-def]  # noqa: ANN001,
 
         return match[0]
 
-    def _get_login(self, hostname):  # type: ignore[no-untyped-def] # pragma: no cover  # noqa: ANN001, ANN202
+    def _get_login(self, hostname: str) -> None:  # pragma: no cover
         # ruff: noqa: S605,S607
         lines, columns = os.popen("stty size", "r").read().split()
         login_options = self._config.driver.login_options(hostname)  # type: ignore[no-untyped-call]
@@ -121,8 +130,18 @@ def _get_login(self, hostname):  # type: ignore[no-untyped-def] # pragma: no cov
     default=base.MOLECULE_DEFAULT_SCENARIO_NAME,
     help=f"Name of the scenario to target. ({base.MOLECULE_DEFAULT_SCENARIO_NAME})",
 )
-def login(ctx, host, scenario_name):  # type: ignore[no-untyped-def] # pragma: no cover  # noqa: ANN001, ANN201
-    """Log in to one instance."""
+def login(
+    ctx: click.Context,
+    host: str,
+    scenario_name: str,
+) -> None:  # pragma: no cover
+    """Log in to one instance.
+
+    Args:
+        ctx: Click context object holding commandline arguments.
+        host: Host to access.
+        scenario_name: Name of the scenario to target.
+    """
     args = ctx.obj.get("args")
     subcommand = base._get_subcommand(__name__)  # noqa: SLF001
     command_args: CommandArgs = {"subcommand": subcommand, "host": host}

src/molecule/command/matrix.py

@@ -31,7 +31,7 @@
 
 
 if TYPE_CHECKING:
-    from molecule.types import CommandArgs
+    from molecule.types import CommandArgs, MoleculeArgs
 
 
 LOG = logging.getLogger(__name__)
@@ -79,9 +79,19 @@ class Matrix(base.Base):
 # NOTE(retr0h): Cannot introspect base.Base for `click.Choice`, since
 # subclasses have not all loaded at this point.
 @click.argument("subcommand", nargs=1, type=click.UNPROCESSED)
-def matrix(ctx, scenario_name, subcommand):  # type: ignore[no-untyped-def] # pragma: no cover  # noqa: ANN001, ANN201
-    """List matrix of steps used to test instances."""
-    args = ctx.obj.get("args")
+def matrix(
+    ctx: click.Context,
+    scenario_name: str,
+    subcommand: str,
+) -> None:  # pragma: no cover
+    """List matrix of steps used to test instances.
+
+    Args:
+        ctx: Click context object holding commandline arguments.
+        scenario_name: Name of the scenario to target.
+        subcommand: Subcommand to target.
+    """
+    args: MoleculeArgs = ctx.obj.get("args")
     command_args: CommandArgs = {"subcommand": subcommand}
 
     s = scenarios.Scenarios(base.get_configs(args, command_args), scenario_name)

src/molecule/command/prepare.py

@@ -32,7 +32,7 @@
 
 
 if TYPE_CHECKING:
-    from molecule.types import CommandArgs
+    from molecule.types import CommandArgs, MoleculeArgs
 
 
 LOG = logging.getLogger(__name__)
@@ -91,20 +91,25 @@ class Prepare(base.Base):
         molecule.yml.
     """
 
-    def execute(self, action_args=None):  # type: ignore[no-untyped-def]  # noqa: ANN001, ANN201, ARG002
-        """Execute the actions necessary to prepare the instances and returns None."""
+    def execute(self, action_args: list[str] | None = None) -> None:  # noqa: ARG002
+        """Execute the actions necessary to prepare the instances.
+
+        Args:
+            action_args: Arguments for this command. Unused.
+        """
         if self._config.state.prepared and not self._config.command_args.get("force"):
             msg = "Skipping, instances already prepared."
             LOG.warning(msg)
             return
 
-        if not self._config.provisioner.playbooks.prepare:  # type: ignore[union-attr]
-            msg = "Skipping, prepare playbook not configured."
-            LOG.warning(msg)
-            return
+        if self._config.provisioner:
+            if not self._config.provisioner.playbooks.prepare:
+                msg = "Skipping, prepare playbook not configured."
+                LOG.warning(msg)
+                return
 
-        self._config.provisioner.prepare()  # type: ignore[union-attr]
-        self._config.state.change_state("prepared", True)  # noqa: FBT003
+            self._config.provisioner.prepare()  # type: ignore[no-untyped-call]
+            self._config.state.change_state("prepared", value=True)
 
 
 @base.click_command_ex()
@@ -127,9 +132,21 @@ def execute(self, action_args=None):  # type: ignore[no-untyped-def]  # noqa: AN
     default=False,
     help="Enable or disable force mode. Default is disabled.",
 )
-def prepare(ctx, scenario_name, driver_name, force):  # type: ignore[no-untyped-def] # pragma: no cover  # noqa: ANN001, ANN201
-    """Use the provisioner to prepare the instances into a particular starting state."""
-    args = ctx.obj.get("args")
+def prepare(
+    ctx: click.Context,
+    scenario_name: str,
+    driver_name: str,
+    force: bool,  # noqa: FBT001
+) -> None:  # pragma: no cover
+    """Use the provisioner to prepare the instances into a particular starting state.
+
+    Args:
+        ctx: Click context object holding commandline arguments.
+        scenario_name: Name of the scenario to target.
+        driver_name: Name of the Molecule driver to use.
+        force: Whether to use force mode.
+    """
+    args: MoleculeArgs = ctx.obj.get("args")
     subcommand = base._get_subcommand(__name__)  # noqa: SLF001
     command_args: CommandArgs = {
         "subcommand": subcommand,

src/molecule/shell.py

@@ -181,7 +181,7 @@ def main(
 main.add_command(command.drivers.drivers)
 main.add_command(command.idempotence.idempotence)
 main.add_command(command.init.init)
-main.add_command(command.list.list)
+main.add_command(command.list.list_)
 main.add_command(command.login.login)
 main.add_command(command.matrix.matrix)
 main.add_command(command.prepare.prepare)

src/molecule/util.py

@@ -134,7 +134,7 @@ def sysexit_with_message(
     code: int = 1,
     detail: MutableMapping[str, Any] | None = None,
     warns: Iterable[WarningMessage] = (),
-) -> None:
+) -> NoReturn:
     """Exit with an error message.
 
     Args: