Document and hint logger.py

.config/pydoclint-baseline.txt

@@ -300,24 +300,6 @@ src/molecule/interpolation.py
     DOC601: Class `TemplateWithDefaults`: 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 `TemplateWithDefaults`: 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: [idpattern: ]. (Please read https://jsh9.github.io/pydoclint/checking_class_attributes.html on how to correctly document class attributes.)
 --------------------
-src/molecule/logger.py
-    DOC101: Function `get_logger`: Docstring contains fewer arguments than in function signature.
-    DOC103: Function `get_logger`: 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: [name: str].
-    DOC201: Function `get_logger` does not have a return section in docstring
-    DOC101: Function `github_actions_groups`: Docstring contains fewer arguments than in function signature.
-    DOC103: Function `github_actions_groups`: 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: [func: Callable].
-    DOC201: Function `github_actions_groups` does not have a return section in docstring
-    DOC101: Function `gitlab_ci_sections`: Docstring contains fewer arguments than in function signature.
-    DOC103: Function `gitlab_ci_sections`: 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: [func: Callable].
-    DOC201: Function `gitlab_ci_sections` does not have a return section in docstring
-    DOC101: Function `travis_ci_folds`: Docstring contains fewer arguments than in function signature.
-    DOC103: Function `travis_ci_folds`: 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: [func: Callable].
-    DOC201: Function `travis_ci_folds` does not have a return section in docstring
-    DOC101: Function `section_logger`: Docstring contains fewer arguments than in function signature.
-    DOC103: Function `section_logger`: 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: [func: Callable].
-    DOC201: Function `section_logger` does not have a return section in docstring
-    DOC201: Function `get_section_loggers` does not have a return section in docstring
---------------------
 src/molecule/model/schema_v3.py
     DOC101: Function `validate`: Docstring contains fewer arguments than in function signature.
     DOC106: Function `validate`: The option `--arg-type-hints-in-signature` is `True` but there are no argument type hints in the signature

src/molecule/logger.py

@@ -25,7 +25,7 @@
 import time
 
 from functools import wraps
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, cast
 
 from ansible_compat.ports import cache
 from enrich.logging import RichHandler
@@ -36,6 +36,23 @@
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Iterable
+    from typing import Any, ParamSpec, Protocol, TypeVar
+
+    from molecule.config import Config
+
+    P = ParamSpec("P")
+    R = TypeVar("R")
+
+    class HasConfig(Protocol):
+        """A class with a _config attribute.
+
+        There are a few such classes in Molecule. We just care that it's one of them.
+
+        Attributes:
+            _config: A Config instance.
+        """
+
+        _config: Config
 
 
 LOG = logging.getLogger(__name__)
@@ -83,16 +100,29 @@ def get_logger(name: str) -> logging.Logger:
     """Return a child logger.
 
     Returned logger inherits configuration from the molecule logger.
+
+    Args:
+        name: Name of the child logger.
+
+    Returns:
+        A child logger of molecule.
     """
     return logging.getLogger("molecule." + name)
 
 
-def github_actions_groups(func: Callable) -> Callable:  # type: ignore[type-arg]
-    """Print group indicators before/after execution of a method."""
+def github_actions_groups(func: Callable[P, R]) -> Callable[P, R]:
+    """Print group indicators before/after execution of a method.
+
+    Args:
+        func: The function to wrap.
+
+    Returns:
+        The wrapped function.
+    """
 
     @wraps(func)
-    def wrapper(*args, **kwargs):  # type: ignore[no-untyped-def]  # noqa: ANN002, ANN003, ANN202
-        self = args[0]
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+        self = cast(HasConfig, args[0])
         scenario = self._config.scenario.name
         subcommand = underscore(self.__class__.__name__)
         console.print(
@@ -111,16 +141,23 @@ def wrapper(*args, **kwargs):  # type: ignore[no-untyped-def]  # noqa: ANN002, A
     return wrapper
 
 
-def gitlab_ci_sections(func: Callable) -> Callable:  # type: ignore[type-arg]
-    """Print group indicators before/after execution of a method."""
+def gitlab_ci_sections(func: Callable[P, R]) -> Callable[P, R]:
+    """Print group indicators before/after execution of a method.
+
+    Args:
+        func: The function to wrap.
+
+    Returns:
+        The wrapped function.
+    """
     # GitLab requires:
     #  - \r (carriage return)
     #  - \e[0K (clear line ANSI escape code. We use \033 for the \e escape char)
     clear_line = "\r\033[0K"
 
     @wraps(func)
-    def wrapper(*args, **kwargs):  # type: ignore[no-untyped-def]  # noqa: ANN002, ANN003, ANN202
-        self = args[0]
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+        self = cast(HasConfig, args[0])
         scenario = self._config.scenario.name
         subcommand = underscore(self.__class__.__name__)
         console.print(
@@ -152,12 +189,19 @@ def wrapper(*args, **kwargs):  # type: ignore[no-untyped-def]  # noqa: ANN002, A
     return wrapper
 
 
-def travis_ci_folds(func: Callable) -> Callable:  # type: ignore[type-arg]
-    """Print group indicators before/after execution of a method."""
+def travis_ci_folds(func: Callable[P, R]) -> Callable[P, R]:
+    """Print group indicators before/after execution of a method.
+
+    Args:
+        func: The function to wrap.
+
+    Returns:
+        The wrapped function.
+    """
 
     @wraps(func)
-    def wrapper(*args, **kwargs):  # type: ignore[no-untyped-def]  # noqa: ANN002, ANN003, ANN202
-        self = args[0]
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+        self = cast(HasConfig, args[0])
         scenario = self._config.scenario.name
         subcommand = underscore(self.__class__.__name__)
         console.print(
@@ -181,12 +225,19 @@ def wrapper(*args, **kwargs):  # type: ignore[no-untyped-def]  # noqa: ANN002, A
     return wrapper
 
 
-def section_logger(func: Callable) -> Callable:  # type: ignore[type-arg]
-    """Wrap effective execution of a method."""
+def section_logger(func: Callable[P, R]) -> Callable[P, R]:
+    """Wrap effective execution of a method.
+
+    Args:
+        func: The function to wrap.
+
+    Returns:
+        The wrapped function.
+    """
 
     @wraps(func)
-    def wrapper(*args, **kwargs):  # type: ignore[no-untyped-def]  # noqa: ANN002, ANN003, ANN202
-        self = args[0]
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+        self = cast(HasConfig, args[0])
         LOG.info(
             "[info]Running [scenario]%s[/] > [action]%s[/][/]",
             self._config.scenario.name,
@@ -201,8 +252,12 @@ def wrapper(*args, **kwargs):  # type: ignore[no-untyped-def]  # noqa: ANN002, A
 
 
 @cache
-def get_section_loggers() -> Iterable[Callable]:  # type: ignore[type-arg]
-    """Return a list of section wrappers to be added."""
+def get_section_loggers() -> Iterable[Callable[..., Any]]:
+    """Return a list of section wrappers to be added.
+
+    Returns:
+        A list of logging decorators.
+    """
     default_section_loggers = [section_logger]
     if not os.getenv("CI"):
         return default_section_loggers