Add docstrings and type hints to verifier subdirectory. (#4334)

.config/pydoclint-baseline.txt

@@ -42,33 +42,6 @@ src/molecule/dependency/shell.py
     DOC107: Method `Shell.__init__`: The option `--arg-type-hints-in-signature` is `True` but not all args in the signature have type hints
     DOC103: Method `Shell.__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: [config: ].
 --------------------
-src/molecule/verifier/base.py
-    DOC601: Class `Verifier`: Class docstring contains fewer class attributes than actual class attributes.  (Please read https://jsh9.github.io/pydoclint/checking_class_attributes.html on how to correctly document class attributes.)
-    DOC603: Class `Verifier`: Class docstring attributes are different from actual class attributes. (Or could be other formatting issues: https://jsh9.github.io/pydoclint/violation_codes.html#notes-on-doc103 ). Attributes in the class definition but not in the docstring: [__metaclass__: ]. (Please read https://jsh9.github.io/pydoclint/checking_class_attributes.html on how to correctly document class attributes.)
-    DOC106: Method `Verifier.__init__`: The option `--arg-type-hints-in-signature` is `True` but there are no argument type hints in the signature
-    DOC107: Method `Verifier.__init__`: The option `--arg-type-hints-in-signature` is `True` but not all args in the signature have type hints
-    DOC101: Method `Verifier.__eq__`: Docstring contains fewer arguments than in function signature.
-    DOC106: Method `Verifier.__eq__`: The option `--arg-type-hints-in-signature` is `True` but there are no argument type hints in the signature
-    DOC107: Method `Verifier.__eq__`: The option `--arg-type-hints-in-signature` is `True` but not all args in the signature have type hints
-    DOC103: Method `Verifier.__eq__`: 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: [other: ].
-    DOC201: Method `Verifier.__eq__` does not have a return section in docstring
-    DOC101: Method `Verifier.__lt__`: Docstring contains fewer arguments than in function signature.
-    DOC106: Method `Verifier.__lt__`: The option `--arg-type-hints-in-signature` is `True` but there are no argument type hints in the signature
-    DOC107: Method `Verifier.__lt__`: The option `--arg-type-hints-in-signature` is `True` but not all args in the signature have type hints
-    DOC103: Method `Verifier.__lt__`: 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: [other: ].
-    DOC201: Method `Verifier.__lt__` does not have a return section in docstring
-    DOC201: Method `Verifier.__hash__` does not have a return section in docstring
-    DOC201: Method `Verifier.__str__` does not have a return section in docstring
-    DOC201: Method `Verifier.__repr__` does not have a return section in docstring
---------------------
-src/molecule/verifier/testinfra.py
-    DOC106: Method `Testinfra.__init__`: The option `--arg-type-hints-in-signature` is `True` but there are no argument type hints in the signature
-    DOC107: Method `Testinfra.__init__`: The option `--arg-type-hints-in-signature` is `True` but not all args in the signature have type hints
-    DOC101: Method `Testinfra._get_tests`: Docstring contains fewer arguments than in function signature.
-    DOC106: Method `Testinfra._get_tests`: The option `--arg-type-hints-in-signature` is `True` but there are no argument type hints in the signature
-    DOC107: Method `Testinfra._get_tests`: The option `--arg-type-hints-in-signature` is `True` but not all args in the signature have type hints
-    DOC103: Method `Testinfra._get_tests`: 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: ].
---------------------
 tests/conftest.py
     DOC101: Function `reset_pytest_vars`: Docstring contains fewer arguments than in function signature.
     DOC106: Function `reset_pytest_vars`: The option `--arg-type-hints-in-signature` is `True` but there are no argument type hints in the signature

src/molecule/config.py

@@ -353,7 +353,7 @@ def _reget_config(self) -> ConfigData:
         Returns:
             dict: The merged config.
         """
-        env = util.merge_dicts(os.environ, self.env)  # type: ignore[type-var]
+        env = util.merge_dicts(os.environ, self.env)
         env = set_env_from_file(env, self.env_file)
 
         return self._combine(env=env)

src/molecule/provisioner/ansible.py

@@ -530,7 +530,7 @@ def default_env(self) -> dict[str, str]:
                 list(map(util.abs_path, os.environ["ANSIBLE_ROLES_PATH"].split(":"))),
             )
 
-        env = util.merge_dicts(  # type: ignore[type-var]
+        env = util.merge_dicts(
             dict(os.environ),
             {
                 "ANSIBLE_CONFIG": self.config_file,
@@ -542,7 +542,7 @@ def default_env(self) -> dict[str, str]:
                 ),
             },
         )
-        env = util.merge_dicts(env, self._config.env)  # type: ignore[type-var]
+        env = util.merge_dicts(env, self._config.env)
 
         return env  # noqa: RET504
 

src/molecule/types.py

@@ -161,18 +161,20 @@ class ScenarioData(TypedDict):
     test_sequence: list[str]
 
 
-class VerifierData(TypedDict):
+class VerifierData(TypedDict, total=False):
     """Molecule verifier configuration.
 
     Attributes:
         name: Name of the verifier.
+        directory: Verifier directory name.
         enabled: Is the verifier enabled.
         options: Options to apply to the verifier.
         env: Applicable environment variables.
         additional_files_or_dirs: Additional paths to verify.
     """
 
     name: str
+    directory: str
     enabled: bool
     options: dict[str, Any]
     env: dict[str, Any]

src/molecule/util.py

@@ -48,11 +48,9 @@
     from typing import Any, AnyStr, NoReturn, TypeVar
     from warnings import WarningMessage
 
-    from ansible_compat.types import JSON
-
     from molecule.types import CommandArgs, ConfigData, PlatformData
 
-    NestedDict = MutableMapping[str, JSON]
+    NestedDict = MutableMapping[str, Any]
     _T = TypeVar("_T", bound=NestedDict)
 
 
@@ -557,7 +555,7 @@ def boolean(value: bool | AnyStr, *, strict: bool = True) -> bool:
     )
 
 
-def dict2args(data: dict[str, str | bool]) -> list[str]:
+def dict2args(data: MutableMapping[str, str | bool]) -> list[str]:
     """Convert a dictionary of options to command like arguments.
 
     Args:

src/molecule/verifier/__init__.py

@@ -1 +1 @@
-# D104  # noqa: D104, ERA001
+# noqa: D104

src/molecule/verifier/ansible.py

@@ -23,10 +23,18 @@
 import logging
 import os
 
+from typing import TYPE_CHECKING, cast
+
 from molecule import util
 from molecule.api import Verifier
 
 
+if TYPE_CHECKING:
+    from collections.abc import MutableMapping
+
+    from molecule.verifier.base import Schema
+
+
 log = logging.getLogger(__name__)
 
 
@@ -61,19 +69,42 @@ class Ansible(Verifier):
     """
 
     @property
-    def name(self):  # type: ignore[no-untyped-def]  # noqa: ANN201, D102
+    def name(self) -> str:
+        """Name of the verifier.
+
+        Returns:
+            The name of the verifier.
+        """
         return "ansible"
 
     @property
-    def default_options(self):  # type: ignore[no-untyped-def]  # noqa: ANN201, D102
+    def default_options(self) -> MutableMapping[str, str | bool]:
+        """Get default CLI arguments provided to ``cmd``.
+
+        Returns:
+            The default verifier options.
+        """
         return {}
 
     @property
-    def default_env(self):  # type: ignore[no-untyped-def]  # noqa: ANN201, D102
-        env = util.merge_dicts(os.environ, self._config.env)
-        return util.merge_dicts(env, self._config.provisioner.env)
-
-    def execute(self, action_args=None):  # type: ignore[no-untyped-def]  # noqa: ANN001, ANN201, D102
+    def default_env(self) -> dict[str, str]:
+        """Get default env variables provided to ``cmd``.
+
+        Returns:
+            The default verifier environment variables.
+        """
+        env = cast(dict[str, str], os.environ)
+        env = util.merge_dicts(env, self._config.env)
+        if self._config.provisioner:
+            env = util.merge_dicts(env, self._config.provisioner.env)
+        return env
+
+    def execute(self, action_args: list[str] | None = None) -> None:
+        """Execute ``cmd``.
+
+        Args:
+            action_args: list of arguments to be passed.
+        """
         if not self.enabled:
             msg = "Skipping, verifier is disabled."
             log.warning(msg)
@@ -82,12 +113,18 @@ def execute(self, action_args=None):  # type: ignore[no-untyped-def]  # noqa: AN
         msg = "Running Ansible Verifier"
         log.info(msg)
 
-        self._config.provisioner.verify(action_args)
+        if self._config.provisioner:
+            self._config.provisioner.verify(action_args)
 
-        msg = "Verifier completed successfully."
-        log.info(msg)
+            msg = "Verifier completed successfully."
+            log.info(msg)
+
+    def schema(self) -> Schema:
+        """Return validation schema.
 
-    def schema(self):  # type: ignore[no-untyped-def]  # noqa: ANN201, D102
+        Returns:
+            Verifier schema.
+        """
         return {
             "verifier": {
                 "type": "dict",