refactor: extract parse_bool() utility for CLI boolean parameter handling (#401)

Addresses #397 - Extract boolean parsing logic from getenv_bool() into a
reusable parse_bool() utility function.

Changes:
- Add parse_bool() to nipyapi/utils.py for handling CLI boolean parameters
  where fire passes --flag=false as string 'false'
- Refactor getenv_bool() to use parse_bool() internally
- Remove duplicate _env_bool() from ci/cleanup.py and ci/stop_flow.py
- Update ci/configure_inherited_params.py to use parse_bool()
- Update docs/contributing.rst CLI Boolean Parameters section with examples
- Add comprehensive TestParseBool test class in test_utils.py
- Remove obsolete TestEnvBool from test_ci.py (covered by new tests)

The parse_bool() function handles:
- String values: 'false', '0', 'no', 'off', 'n' -> False
- String values: 'true', '1', 'yes', 'on', 'y' -> True
- Bool passthrough: True/False unchanged
- None handling with default parameter
- Other types: uses Python truthiness

Author: Chaffelson

docs/contributing.rst

@@ -178,8 +178,25 @@ inline with quotes. Line continuation is fine - just avoid nested bullet points.
 The ``fire`` CLI library passes ``--flag=false`` as the **string** ``"false"``, which is
 truthy in Python. This causes unexpected behavior for boolean parameters.
 
-Avoid boolean parameters with default ``True`` that users need to set to ``False`` via CLI.
-Instead:
+Use ``nipyapi.utils.parse_bool()`` to safely handle boolean parameters from CLI::
+
+    from nipyapi.utils import parse_bool
+
+    def my_function(dry_run=False):
+        # Handles CLI --dry_run=false correctly (returns False, not truthy "false")
+        dry_run = parse_bool(dry_run, default=False)
+        # Now safe to use as boolean
+
+For environment variables, use ``nipyapi.utils.getenv_bool()`` which internally uses
+``parse_bool()``::
+
+    from nipyapi.utils import getenv_bool
+
+    # Returns False for "false", "0", "no", "off", "n"
+    # Returns True for "true", "1", "yes", "on", "y", or any other non-falsy string
+    enabled = getenv_bool("MY_FEATURE_ENABLED", default=False)
+
+Alternative approaches (when ``parse_bool()`` is not suitable):
 
 * Return structured results and let the caller decide (preferred)
 * Use ``--noflag`` syntax (fire's native boolean negation): ``nipyapi foo bar --noflag``

nipyapi/ci/cleanup.py

@@ -1,4 +1,4 @@
-# pylint: disable=broad-exception-caught,duplicate-code
+# pylint: disable=broad-exception-caught
 """
 cleanup - stop and delete a deployed process group.
 """
@@ -12,16 +12,6 @@
 log = logging.getLogger(__name__)
 
 
-def _env_bool(name, default=False):
-    """Parse a boolean from environment variable."""
-    value = os.environ.get(name, "").lower()
-    if value in ("true", "1", "yes"):
-        return True
-    if value in ("false", "0", "no"):
-        return False
-    return default
-
-
 # pylint: disable=too-many-arguments,too-many-positional-arguments
 # pylint: disable=too-many-branches,too-many-statements,too-many-locals
 def cleanup(
@@ -81,17 +71,33 @@ def cleanup(
         NIFI_DELETE_PARAMETER_CONTEXT=true NIFI_FORCE_DELETE=true nipyapi ci cleanup
     """
     # Resolve from env vars with safe defaults
+    # Use parse_bool for CLI parameters (fire passes --flag=false as string "false")
+    # Use getenv_bool for environment variable fallbacks
     process_group_id = process_group_id or os.environ.get("NIFI_PROCESS_GROUP_ID")
     if stop_only is None:
-        stop_only = _env_bool("NIFI_STOP_ONLY", default=False)
+        stop_only = nipyapi.utils.getenv_bool("NIFI_STOP_ONLY", default=False)
+    else:
+        stop_only = nipyapi.utils.parse_bool(stop_only, default=False)
     if force is None:
-        force = _env_bool("NIFI_FORCE_DELETE", default=False)
+        force = nipyapi.utils.getenv_bool("NIFI_FORCE_DELETE", default=False)
+    else:
+        force = nipyapi.utils.parse_bool(force, default=False)
     if delete_parameter_context is None:
-        delete_parameter_context = _env_bool("NIFI_DELETE_PARAMETER_CONTEXT", default=False)
+        delete_parameter_context = nipyapi.utils.getenv_bool(
+            "NIFI_DELETE_PARAMETER_CONTEXT", default=False
+        )
+    else:
+        delete_parameter_context = nipyapi.utils.parse_bool(delete_parameter_context, default=False)
     if delete_orphaned_contexts is None:
-        delete_orphaned_contexts = _env_bool("NIFI_DELETE_ORPHANED_CONTEXTS", default=False)
+        delete_orphaned_contexts = nipyapi.utils.getenv_bool(
+            "NIFI_DELETE_ORPHANED_CONTEXTS", default=False
+        )
+    else:
+        delete_orphaned_contexts = nipyapi.utils.parse_bool(delete_orphaned_contexts, default=False)
     if disable_controllers is None:
-        disable_controllers = _env_bool("NIFI_DISABLE_CONTROLLERS", default=True)
+        disable_controllers = nipyapi.utils.getenv_bool("NIFI_DISABLE_CONTROLLERS", default=True)
+    else:
+        disable_controllers = nipyapi.utils.parse_bool(disable_controllers, default=True)
 
     if not process_group_id:
         raise ValueError("process_group_id is required (or set NIFI_PROCESS_GROUP_ID)")

nipyapi/ci/configure_inherited_params.py

@@ -65,16 +65,17 @@ def configure_inherited_params(
     parameters = parameters or os.environ.get("NIFI_PARAMETERS")
     parameters_file = parameters_file or os.environ.get("NIFI_PARAMETERS_FILE")
 
-    # Parse boolean env vars
-    if isinstance(dry_run, str):
-        dry_run = dry_run.lower() in ("true", "1", "yes")
-    if os.environ.get("NIFI_DRY_RUN", "").lower() in ("true", "1", "yes"):
-        dry_run = True
-
-    if isinstance(allow_override, str):
-        allow_override = allow_override.lower() in ("true", "1", "yes")
-    if os.environ.get("NIFI_ALLOW_OVERRIDE", "").lower() in ("true", "1", "yes"):
-        allow_override = True
+    # Parse boolean parameters using parse_bool (handles CLI --flag=false as string "false")
+    # Environment variables can override CLI defaults
+    dry_run = nipyapi.utils.parse_bool(dry_run, default=False)
+    env_dry_run = nipyapi.utils.getenv_bool("NIFI_DRY_RUN", default=None)
+    if env_dry_run is not None:
+        dry_run = env_dry_run
+
+    allow_override = nipyapi.utils.parse_bool(allow_override, default=False)
+    env_allow_override = nipyapi.utils.getenv_bool("NIFI_ALLOW_OVERRIDE", default=None)
+    if env_allow_override is not None:
+        allow_override = env_allow_override
 
     if not process_group_id:
         raise ValueError("process_group_id is required (or set NIFI_PROCESS_GROUP_ID)")

nipyapi/ci/stop_flow.py

@@ -1,4 +1,3 @@
-# pylint: disable=duplicate-code
 """
 stop_flow - stop a running process group.
 """
@@ -12,16 +11,6 @@
 log = logging.getLogger(__name__)
 
 
-def _env_bool(name, default=False):
-    """Parse a boolean from environment variable."""
-    value = os.environ.get(name, "").lower()
-    if value in ("true", "1", "yes"):
-        return True
-    if value in ("false", "0", "no"):
-        return False
-    return default
-
-
 def stop_flow(
     process_group_id: Optional[str] = None,
     disable_controllers: Optional[bool] = None,
@@ -56,9 +45,13 @@ def stop_flow(
         # Stop for deletion (also disable controllers)
         nipyapi ci stop_flow --process_group_id PG_ID --disable_controllers
     """
+    # Use parse_bool for CLI parameters (fire passes --flag=false as string "false")
+    # Use getenv_bool for environment variable fallbacks
     process_group_id = process_group_id or os.environ.get("NIFI_PROCESS_GROUP_ID")
     if disable_controllers is None:
-        disable_controllers = _env_bool("NIFI_DISABLE_CONTROLLERS", default=False)
+        disable_controllers = nipyapi.utils.getenv_bool("NIFI_DISABLE_CONTROLLERS", default=False)
+    else:
+        disable_controllers = nipyapi.utils.parse_bool(disable_controllers, default=False)
 
     if not process_group_id:
         raise ValueError("process_group_id is required (or set NIFI_PROCESS_GROUP_ID)")

nipyapi/utils.py

@@ -46,6 +46,7 @@
     "extract_oidc_user_identity",
     "getenv",
     "getenv_bool",
+    "parse_bool",
     "resolve_relative_paths",
     "format_timestamp",
 ]
@@ -921,12 +922,70 @@ def getenv(name: str, default: Optional[str] = None) -> Optional[str]:
     return val if val is not None else default
 
 
+def parse_bool(value, default=None):  # pylint: disable=too-many-return-statements
+    """
+    Parse a value as boolean.
+
+    Handles string values from CLI parameters (where fire passes --flag=false
+    as the string "false") and environment variables. Also passes through
+    actual bool values unchanged.
+
+    This function addresses the CLI boolean parameter gotcha where fire passes
+    --flag=false as the string "false", which is truthy in Python. Use this
+    to safely convert CLI parameters to boolean.
+
+    Args:
+        value: The value to parse (str, bool, or None)
+        default: Value to return if input is None
+
+    Returns:
+        bool or default value if input is None
+
+    Example::
+
+        >>> parse_bool("false")  # False (handles CLI --flag=false)
+        >>> parse_bool("0")      # False
+        >>> parse_bool("yes")    # True
+        >>> parse_bool(True)     # True (passthrough)
+        >>> parse_bool(None, default=False)  # False
+    """
+    # Handle None
+    if value is None:
+        return default
+
+    # Pass through actual booleans unchanged
+    if isinstance(value, bool):
+        return value
+
+    # Handle string values
+    if isinstance(value, str):
+        val_clean = value.strip().lower()
+
+        # Handle empty string as falsy
+        if val_clean == "":
+            return False
+
+        # Handle JSON-style booleans directly
+        if val_clean in ("true", "false"):
+            return json.loads(val_clean)
+
+        # Handle common falsy patterns
+        if val_clean in ("0", "no", "off", "n"):
+            return False
+
+        # Everything else is truthy (including '1', 'yes', 'on', 'y', etc.)
+        return True
+
+    # For other types, use Python's truthiness
+    return bool(value)
+
+
 def getenv_bool(name: str, default: Optional[bool] = None) -> Optional[bool]:
     """
-    Parse environment variable as boolean using JSON-style interpretation.
+    Parse environment variable as boolean.
 
-    Handles common boolean environment variable patterns and uses json.loads()
-    for the standard 'true'/'false' cases that most programmers understand.
+    Convenience wrapper around parse_bool() for environment variables.
+    Handles common boolean environment variable patterns.
 
     Args:
         name (str): Environment variable name
@@ -946,20 +1005,7 @@ def getenv_bool(name: str, default: Optional[bool] = None) -> Optional[bool]:
     val = os.getenv(name)
     if val is None:
         return default
-
-    # Clean and normalize the value
-    val_clean = val.strip().lower()
-
-    # Handle JSON-style booleans directly
-    if val_clean in ("true", "false"):
-        return json.loads(val_clean)
-
-    # Handle common falsy patterns
-    if val_clean in ("0", "no", "off", "n", ""):
-        return False
-
-    # Everything else is truthy (including '1', 'yes', 'on', 'y', etc.)
-    return True
+    return parse_bool(val)
 
 
 def format_timestamp(ts=None, fmt=None):

tests/test_ci.py

@@ -13,44 +13,8 @@
 # Pure Logic Tests (no NiFi required)
 # =============================================================================
 
-
-class TestEnvBool:
-    """Test _env_bool helper function used by stop_flow and cleanup."""
-
-    def test_env_bool_true_values(self):
-        """Test that true-like values return True."""
-        from nipyapi.ci.stop_flow import _env_bool
-
-        with patch.dict(os.environ, {"TEST_VAR": "true"}):
-            assert _env_bool("TEST_VAR") is True
-        with patch.dict(os.environ, {"TEST_VAR": "1"}):
-            assert _env_bool("TEST_VAR") is True
-        with patch.dict(os.environ, {"TEST_VAR": "yes"}):
-            assert _env_bool("TEST_VAR") is True
-        with patch.dict(os.environ, {"TEST_VAR": "TRUE"}):
-            assert _env_bool("TEST_VAR") is True
-
-    def test_env_bool_false_values(self):
-        """Test that false-like values return False."""
-        from nipyapi.ci.stop_flow import _env_bool
-
-        with patch.dict(os.environ, {"TEST_VAR": "false"}):
-            assert _env_bool("TEST_VAR") is False
-        with patch.dict(os.environ, {"TEST_VAR": "0"}):
-            assert _env_bool("TEST_VAR") is False
-        with patch.dict(os.environ, {"TEST_VAR": "no"}):
-            assert _env_bool("TEST_VAR") is False
-
-    def test_env_bool_default(self):
-        """Test default value when env var not set."""
-        from nipyapi.ci.stop_flow import _env_bool
-
-        # Clear the var if it exists
-        env = os.environ.copy()
-        env.pop("NONEXISTENT_VAR", None)
-        with patch.dict(os.environ, env, clear=True):
-            assert _env_bool("NONEXISTENT_VAR", default=False) is False
-            assert _env_bool("NONEXISTENT_VAR", default=True) is True
+# Note: Tests for parse_bool and getenv_bool are in test_utils.py::TestParseBool
+# and test_utils.py::TestGetenvBool respectively.
 
 
 class TestMaskValue: