Replace to_bool calls with boolean function (#4542)

This PR replaces all calls to the to_bool function with the existing
boolean function for consistency.

Changes:
- Replace to_bool function calls with boolean function calls in
config.py and ansi_output.py
- Add optional default parameter to boolean function to return fallback
value for invalid inputs
- Apply default parameter to environment variable parsing to prevent
TypeError exceptions
- Move boolean function tests from test_ansi_output.py to test_util.py
for proper organization
- Add comprehensive test coverage for the new default parameter
functionality
- Update type annotations and add proper docstring documentation

The boolean function now accepts a default parameter that provides
graceful fallback for invalid environment variable values while
maintaining strict behavior when no default is specified.

Author: cidrblock

src/molecule/ansi_output.py

@@ -30,7 +30,7 @@
 
 from molecule.constants import DEFAULT_BORDER_WIDTH, MARKUP_MAP, SCENARIO_RECAP_STATE_ORDER
 from molecule.constants import ANSICodes as A
-from molecule.util import to_bool
+from molecule.util import boolean
 
 
 if TYPE_CHECKING:
@@ -53,7 +53,7 @@ def should_do_markup() -> bool:
     for v in ["PY_COLORS", "CLICOLOR", "FORCE_COLOR", "ANSIBLE_FORCE_COLOR"]:
         value = os.environ.get(v, None)
         if value is not None:
-            py_colors = to_bool(value)
+            py_colors = boolean(value, default=False)
             break
 
     # If deliberately disabled colors
@@ -62,7 +62,7 @@ def should_do_markup() -> bool:
 
     # User configuration requested colors
     if py_colors is not None:
-        return to_bool(py_colors)
+        return boolean(py_colors)
 
     term = os.environ.get("TERM", "")
     if "xterm" in term:

src/molecule/config.py

@@ -40,7 +40,7 @@
 from molecule.dependency import ansible_galaxy, shell
 from molecule.model import schema_v3
 from molecule.provisioner import ansible
-from molecule.util import boolean, sysexit_with_message, to_bool
+from molecule.util import boolean, sysexit_with_message
 
 
 if TYPE_CHECKING:
@@ -61,8 +61,8 @@
     from molecule.verifier.base import Verifier
 
 
-MOLECULE_PARALLEL: bool = boolean(os.environ.get("MOLECULE_PARALLEL", ""))
-MOLECULE_DEBUG: bool = boolean(os.environ.get("MOLECULE_DEBUG", "False"))
+MOLECULE_PARALLEL: bool = boolean(os.environ.get("MOLECULE_PARALLEL", ""), default=False)
+MOLECULE_DEBUG: bool = boolean(os.environ.get("MOLECULE_DEBUG", "False"), default=False)
 MOLECULE_VERBOSITY: int = int(os.environ.get("MOLECULE_VERBOSITY", "0"))
 MOLECULE_DIRECTORY = "molecule"
 MOLECULE_FILE = "molecule.yml"
@@ -187,7 +187,7 @@ def _apply_env_overrides(self) -> None:
 
             try:
                 converted_value = (
-                    to_bool(env_value) if expected_type is bool else expected_type(env_value)
+                    boolean(env_value) if expected_type is bool else expected_type(env_value)
                 )
                 self.command_args[config_attr] = converted_value
             except (ValueError, TypeError):

src/molecule/util.py

@@ -49,7 +49,7 @@
 if TYPE_CHECKING:
     from collections.abc import Generator, Iterable, MutableMapping, Sequence
     from io import TextIOWrapper
-    from typing import Any, AnyStr, NoReturn, TypeVar
+    from typing import Any, NoReturn, TypeVar
     from warnings import WarningMessage
 
     from molecule.types import CollectionData, CommandArgs, ConfigData, Options, PlatformData
@@ -495,18 +495,18 @@ def lookup_config_file(filename: str) -> str | None:
     return None
 
 
-def boolean(value: bool | AnyStr, *, strict: bool = True) -> bool:  # noqa: FBT001
+def boolean(value: object, *, default: bool | None = None) -> bool:
     """Evaluate any object as boolean matching ansible behavior.
 
     Args:
         value: The value to evaluate as a boolean.
-        strict: If True, invalid booleans will raises TypeError instead of returning False.
+        default: If provided, return this value for invalid inputs instead of raising TypeError.
 
     Returns:
-        The boolean value of value.
+        The boolean value of value, or default if value is invalid and default is provided.
 
     Raises:
-        TypeError: If value does not resolve to a valid boolean and strict is True.
+        TypeError: If value does not resolve to a valid boolean and no default is provided.
     """
     # Based on https://github.com/ansible/ansible/blob/devel/lib/ansible/module_utils/parsing/convert_bool.py
 
@@ -525,9 +525,13 @@ def boolean(value: bool | AnyStr, *, strict: bool = True) -> bool:  # noqa: FBT0
 
     if normalized_value in BOOLEANS_TRUE:
         return True
-    if normalized_value in BOOLEANS_FALSE or not strict:
+    if normalized_value in BOOLEANS_FALSE:
         return False
 
+    # If we have a default, return it for invalid values
+    if default is not None:
+        return default
+
     raise TypeError(  # noqa: TRY003
         f"The value '{value!s}' is not a valid boolean.  Valid booleans include: {', '.join(repr(i) for i in BOOLEANS)!s}",  # noqa: EM102
     )

tests/unit/test_ansi_output.py

@@ -6,35 +6,6 @@
 
 from molecule.ansi_output import AnsiOutput, should_do_markup
 from molecule.constants import ANSICodes as A
-from molecule.util import to_bool
-
-
-@pytest.mark.parametrize(
-    ("input_value", "expected"),
-    (
-        (None, False),
-        (True, True),
-        (False, False),
-        ("yes", True),
-        ("YES", True),
-        ("on", True),
-        ("ON", True),
-        ("1", True),
-        ("true", True),
-        ("TRUE", True),
-        ("no", False),
-        ("off", False),
-        ("0", False),
-        ("false", False),
-        ("random", False),
-        (1, True),
-        (0, False),
-        (42, False),
-    ),
-)
-def test_to_bool(input_value: object, expected: bool) -> None:  # noqa: FBT001
-    """Test to_bool function with various inputs."""
-    assert to_bool(input_value) is expected
 
 
 def test_should_do_markup_basic() -> None:

tests/unit/test_util.py

@@ -1,4 +1,4 @@
-#  Copyright (c) 2015-2018 Cisco Systems, Inc.  # noqa: D100
+#  Copyright (c) 2015-2018 Cisco Systems, Inc.
 #
 #  Permission is hereby granted, free of charge, to any person obtaining a copy
 #  of this software and associated documentation files (the "Software"), to
@@ -17,6 +17,10 @@
 #  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 #  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 #  DEALINGS IN THE SOFTWARE.
+"""Test the util module."""
+
+# pylint: disable=too-many-lines
+
 from __future__ import annotations
 
 import binascii
@@ -938,3 +942,75 @@ def test_lookup_config_file_collection_no_extensions_dir(
 
     # Should fall back to home directory since collection extensions dir doesn't exist
     assert result == str(home_config)
+
+
+@pytest.mark.parametrize(
+    ("input_value", "expected"),
+    (
+        (True, True),
+        (False, False),
+        ("yes", True),
+        ("YES", True),
+        ("on", True),
+        ("ON", True),
+        ("1", True),
+        ("true", True),
+        ("TRUE", True),
+        ("no", False),
+        ("off", False),
+        ("0", False),
+        ("false", False),
+        (1, True),
+        (0, False),
+        ("", False),
+    ),
+)
+def test_boolean_valid_inputs(input_value: object, expected: bool) -> None:  # noqa: FBT001
+    """Test boolean function with valid inputs.
+
+    Args:
+        input_value: The input value to test.
+        expected: The expected boolean result.
+    """
+    assert util.boolean(input_value) is expected
+
+
+@pytest.mark.parametrize(
+    "input_value",
+    (
+        None,
+        "random",
+        42,
+        "invalid",
+    ),
+)
+def test_boolean_invalid_values(input_value: object) -> None:
+    """Test boolean function raises TypeError for invalid inputs.
+
+    Args:
+        input_value: The invalid input value to test.
+    """
+    with pytest.raises(TypeError):
+        util.boolean(input_value)
+
+
+@pytest.mark.parametrize(
+    ("input_value", "default_value", "expected"),
+    (
+        (None, False, False),
+        ("random", True, True),
+        (42, False, False),
+        ("invalid", True, True),
+        ("yes", False, True),  # Valid input should ignore default
+        ("no", True, False),  # Valid input should ignore default
+    ),
+)
+def test_boolean_with_default(input_value: object, default_value: bool, expected: bool) -> None:  # noqa: FBT001
+    """Test boolean function with default parameter.
+
+    Args:
+        input_value: The input value to test.
+        default_value: The default value to use for invalid inputs.
+        expected: The expected boolean result.
+    """
+    assert util.boolean(input_value, default=default_value) is expected