Finish util

.config/pydoclint-baseline.txt

@@ -442,38 +442,6 @@ src/molecule/status.py
 	DOC601: Class `Status`: 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 `Status`: 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: [converged: str, created: str, driver_name: str, instance_name: str, provisioner_name: str, scenario_name: str]. (Please read https://jsh9.github.io/pydoclint/checking_class_attributes.html on how to correctly document class attributes.)
 --------------------
-src/molecule/util.py
-	DOC101: Function `print_debug`: Docstring contains fewer arguments than in function signature.
-	DOC103: Function `print_debug`: 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: [data: str, title: str].
-	DOC101: Function `sysexit`: Docstring contains fewer arguments than in function signature.
-	DOC103: Function `sysexit`: 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: [code: int].
-	DOC501: Function `run_command` has "raise" statements, but the docstring does not have a "Raises" section
-	DOC402: Function `os_walk` has "yield" statements, but the docstring does not have a "Yields" section
-	DOC404: Function `os_walk` yield type(s) in docstring not consistent with the return annotation. Return annotation exists, but docstring "yields" section does not exist or has 0 type(s).
-	DOC101: Function `molecule_prepender`: Docstring contains fewer arguments than in function signature.
-	DOC103: Function `molecule_prepender`: 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: [content: str].
-	DOC201: Function `molecule_prepender` does not have a return section in docstring
-	DOC101: Function `instance_with_scenario_name`: Docstring contains fewer arguments than in function signature.
-	DOC106: Function `instance_with_scenario_name`: The option `--arg-type-hints-in-signature` is `True` but there are no argument type hints in the signature
-	DOC107: Function `instance_with_scenario_name`: The option `--arg-type-hints-in-signature` is `True` but not all args in the signature have type hints
-	DOC103: Function `instance_with_scenario_name`: 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: [instance_name: , scenario_name: ].
-	DOC201: Function `instance_with_scenario_name` does not have a return section in docstring
-	DOC101: Function `filter_verbose_permutation`: Docstring contains fewer arguments than in function signature.
-	DOC106: Function `filter_verbose_permutation`: The option `--arg-type-hints-in-signature` is `True` but there are no argument type hints in the signature
-	DOC107: Function `filter_verbose_permutation`: The option `--arg-type-hints-in-signature` is `True` but not all args in the signature have type hints
-	DOC103: Function `filter_verbose_permutation`: 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: [options: ].
-	DOC201: Function `filter_verbose_permutation` does not have a return section in docstring
-	DOC101: Function `abs_path`: Docstring contains fewer arguments than in function signature.
-	DOC103: Function `abs_path`: 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: [path: str].
-	DOC201: Function `abs_path` does not have a return section in docstring
-	DOC101: Function `validate_parallel_cmd_args`: Docstring contains fewer arguments than in function signature.
-	DOC106: Function `validate_parallel_cmd_args`: The option `--arg-type-hints-in-signature` is `True` but there are no argument type hints in the signature
-	DOC107: Function `validate_parallel_cmd_args`: The option `--arg-type-hints-in-signature` is `True` but not all args in the signature have type hints
-	DOC103: Function `validate_parallel_cmd_args`: 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: [cmd_args: ].
-	DOC101: Function `lookup_config_file`: Docstring contains fewer arguments than in function signature.
-	DOC103: Function `lookup_config_file`: 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: [filename: str].
-	DOC201: Function `lookup_config_file` does not have a return section in docstring
---------------------
 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.)
@@ -558,6 +526,7 @@ tests/fixtures/integration/test_command/scenarios/verifier/molecule/testinfra-pr
 --------------------
 tests/integration/conftest.py
 	DOC201: Function `_with_scenario` does not have a return section in docstring
+	DOC405: Function `_with_scenario` has both "return" and "yield" statements. Please use Generator[YieldType, SendType, ReturnType] as the return type annotation, and put your yield type in YieldType and return type in ReturnType. More details in https://jsh9.github.io/pydoclint/notes_generator_vs_iterator.html
 --------------------
 tests/integration/test_command.py
 	DOC601: Class `ParamDefault`: 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.)

pyproject.toml

@@ -90,6 +90,7 @@ allow-init-docstring = true
 arg-type-hints-in-docstring = false
 baseline = ".config/pydoclint-baseline.txt"
 check-return-types = false
+check-yield-types = false
 exclude = '\.cache|\.git|\.tox|build|out|venv'
 should-document-private-class-attributes = true
 show-filenames-in-every-violation-message = true

src/molecule/logger.py

@@ -94,7 +94,7 @@ def github_actions_groups(func: Callable) -> Callable:  # type: ignore[type-arg]
     def wrapper(*args, **kwargs):  # type: ignore[no-untyped-def]  # noqa: ANN002, ANN003, ANN202
         self = args[0]
         scenario = self._config.scenario.name
-        subcommand = underscore(self.__class__.__name__)  # type: ignore[no-untyped-call]
+        subcommand = underscore(self.__class__.__name__)
         console.print(
             "::group::",
             f"[ci_info]Molecule[/] [scenario]{scenario}[/] > [action]{subcommand}[/]",
@@ -122,7 +122,7 @@ def gitlab_ci_sections(func: Callable) -> Callable:  # type: ignore[type-arg]
     def wrapper(*args, **kwargs):  # type: ignore[no-untyped-def]  # noqa: ANN002, ANN003, ANN202
         self = args[0]
         scenario = self._config.scenario.name
-        subcommand = underscore(self.__class__.__name__)  # type: ignore[no-untyped-call]
+        subcommand = underscore(self.__class__.__name__)
         console.print(
             f"section_start:{int(time.time())}:{scenario}.{subcommand}",
             end=clear_line,
@@ -159,7 +159,7 @@ def travis_ci_folds(func: Callable) -> Callable:  # type: ignore[type-arg]
     def wrapper(*args, **kwargs):  # type: ignore[no-untyped-def]  # noqa: ANN002, ANN003, ANN202
         self = args[0]
         scenario = self._config.scenario.name
-        subcommand = underscore(self.__class__.__name__)  # type: ignore[no-untyped-call]
+        subcommand = underscore(self.__class__.__name__)
         console.print(
             f"travis_fold:start:{scenario}.{subcommand}",
             f"[ci_info]Molecule[/] [scenario]{scenario}[/] > [action]{subcommand}[/]",
@@ -190,7 +190,7 @@ def wrapper(*args, **kwargs):  # type: ignore[no-untyped-def]  # noqa: ANN002, A
         LOG.info(
             "[info]Running [scenario]%s[/] > [action]%s[/][/]",
             self._config.scenario.name,
-            underscore(self.__class__.__name__),  # type: ignore[no-untyped-call]
+            underscore(self.__class__.__name__),
             extra={"markup": True},
         )
         rt = func(*args, **kwargs)

src/molecule/util.py

@@ -68,7 +68,12 @@ def increase_indent(
 
 
 def print_debug(title: str, data: str) -> None:
-    """Print debug information."""
+    """Print debug information.
+
+    Args:
+        title: A title to describe the data.
+        data: The data to print.
+    """
     console.print(f"DEBUG: {title}:\n{data}")
 
 
@@ -107,7 +112,11 @@ def do_report() -> None:
 
 
 def sysexit(code: int = 1) -> NoReturn:
-    """Perform a system exit with given code, default 1."""
+    """Perform a system exit with given code.
+
+    Args:
+        code: The return code to emit.
+    """
     sys.exit(code)
 
 
@@ -160,6 +169,9 @@ def run_command(  # noqa: PLR0913
 
     Returns:
         A completed process object.
+
+    Raises:
+        CalledProcessError: If return code is nonzero and check is True.
     """
     args = cmd
 
@@ -197,6 +209,9 @@ def os_walk(
         pattern: A pattern against which to match files on.
         excludes: A list of directory names to not look in.
         followlinks: Whether or not to follow symbolic links.
+
+    Yields:
+        File paths that match the filters provided.
     """
     if excludes is None:
         excludes = []
@@ -245,17 +260,27 @@ def write_file(filename: str, content: str, header: str | None = None) -> None:
 
 
 def molecule_prepender(content: str) -> str:
-    """Return molecule identification header."""
+    """Return molecule identification header.
+
+    Args:
+        content: Molecule content to prepend.
+
+    Returns:
+        Provided content prepended with MOLECULE_HEADER.
+    """
     return MOLECULE_HEADER + "\n\n" + content
 
 
-def file_prepender(filename: str) -> None:
+def file_prepender(filename: str | Path) -> None:
     """Prepend an informational header on files managed by Molecule and returns None.
 
     Args:
         filename: A string containing the target filename.
     """
-    with open(filename, "r+") as f:  # noqa: PTH123
+    if isinstance(filename, str):
+        filename = Path(filename)
+
+    with filename.open("r+") as f:
         content = f.read()
         f.seek(0, 0)
         f.write(molecule_prepender(content))
@@ -311,8 +336,16 @@ def safe_load_file(filename: str | Path) -> dict[str, Any]:
         return safe_load(stream)
 
 
-def instance_with_scenario_name(instance_name, scenario_name):  # type: ignore[no-untyped-def]  # noqa: ANN001, ANN201
-    """Format instance name that includes scenario."""
+def instance_with_scenario_name(instance_name: str, scenario_name: str) -> str:
+    """Format instance name that includes scenario.
+
+    Args:
+        instance_name: Name of the instance.
+        scenario_name: Name of the scenario.
+
+    Returns:
+        Combined instance and scenario names.
+    """
     return f"{instance_name}-{scenario_name}"
 
 
@@ -339,19 +372,39 @@ def verbose_flag(options: dict[str, str | bool]) -> list[str]:
     return flags
 
 
-def filter_verbose_permutation(options):  # type: ignore[no-untyped-def]  # noqa: ANN001, ANN201
-    """Clean verbose information."""
+def filter_verbose_permutation(options: dict[str, Any]) -> dict[str, Any]:
+    """Clean verbose information.
+
+    Args:
+        options: Dictionary of commandline options.
+
+    Returns:
+        Dictionary of options without verbose options included.
+    """
     return {k: options[k] for k in options if not re.match("^[v]+$", k)}
 
 
-def abs_path(path: str) -> str | None:
-    """Return absolute path."""
+def abs_path(path: str | Path) -> str | None:
+    """Return absolute path.
+
+    Args:
+        path: File path to resolve absolute path from.
+
+    Returns:
+        Absolute path of path.
+    """
     if path:
-        return os.path.abspath(path)  # noqa: PTH100
+        if isinstance(path, str):
+            path = Path(path)
+
+        return str(path.resolve())
     return None
 
 
-def merge_dicts(a: MutableMapping, b: MutableMapping) -> MutableMapping:  # type: ignore[type-arg]
+def merge_dicts(
+    a: MutableMapping[str, Any],
+    b: MutableMapping[str, Any],
+) -> MutableMapping[str, Any]:
     """Merge the values of b into a and returns a new dict.
 
     This function uses the same algorithm as Ansible's `combine(recursive=True)` filter.
@@ -361,7 +414,7 @@ def merge_dicts(a: MutableMapping, b: MutableMapping) -> MutableMapping:  # type
         b: the dictionary to import
 
     Returns:
-        dict
+        A dictionary with b applied on to a
     """
     result = copy.deepcopy(a)
 
@@ -374,8 +427,12 @@ def merge_dicts(a: MutableMapping, b: MutableMapping) -> MutableMapping:  # type
     return result
 
 
-def validate_parallel_cmd_args(cmd_args):  # type: ignore[no-untyped-def]  # noqa: ANN001, ANN201
-    """Prevents use of options incompatible with parallel mode."""
+def validate_parallel_cmd_args(cmd_args: dict[str, Any]) -> None:
+    """Prevents use of options incompatible with parallel mode.
+
+    Args:
+        cmd_args: Arguments to validate.
+    """
     if cmd_args.get("parallel") and cmd_args.get("destroy") == "never":
         msg = 'Combining "--parallel" and "--destroy=never" is not supported'
         sysexit_with_message(msg)
@@ -401,8 +458,8 @@ def _filter_platforms(config, platform_name):  # type: ignore[no-untyped-def]  #
 def find_vcs_root(
     location: str | Path = "",
     dirs: tuple[str, ...] = (".git", ".hg", ".svn"),
-    default: str | None = None,
-) -> str | None:
+    default: str = "",
+) -> str:
     """Return current repository root directory.
 
     Args:
@@ -427,12 +484,19 @@ def find_vcs_root(
 
 
 def lookup_config_file(filename: str) -> str | None:
-    """Return config file PATH."""
+    """Return config file PATH.
+
+    Args:
+        filename: Config file name to find.and
+
+    Returns:
+        Path to config file or None if not found.
+    """
     for path in [find_vcs_root(default="~"), "~"]:
-        f = os.path.expanduser(f"{path}/{filename}")  # noqa: PTH111
-        if os.path.isfile(f):  # noqa: PTH113
+        f = (Path(path) / filename).expanduser()
+        if f.is_file():
             LOG.info("Found config file %s", f)
-            return f
+            return str(f)
     return None