added more docs.

Author: pablomarcel

transient_analysis/routhTool/utils.py

@@ -1,65 +1,105 @@
 # transient_analysis/routhTool/utils.py
+"""Utility helpers for :mod:`transient_analysis.routhTool`.
+
+This module intentionally keeps parsing and formatting logic small and
+side-effect free so it can be reused by the CLI, app façade, and API layer.
+"""
+
 from __future__ import annotations
-from typing import List, Union, Sequence
+
+from typing import Any, Sequence, Union
 
 try:
     import sympy as sp
-except Exception:  # pragma: no cover
+except Exception:  # pragma: no cover - SymPy is optional at import time.
     sp = None
 
-def parse_coeffs(raw: str) -> List[str]:
-    s = raw.replace(";", " ").replace("[", "").replace("]", "").replace(",", " ")
-    return [t for t in s.split() if t.strip()]
+NumericOrSymbolic = Union[float, int, "sp.Basic"]
+
+
+def parse_coeffs(raw: str) -> list[str]:
+    """Parse a coefficient string into individual token strings.
+
+    Accepted separators are commas, semicolons, and whitespace. Square brackets
+    are ignored so users can pass values such as ``[1, 5, 6, K]`` from the CLI.
+
+    Args:
+        raw: Coefficients in descending polynomial order.
+
+    Returns:
+        A list of non-empty coefficient tokens.
+    """
+    if raw is None:
+        raise ValueError("Coefficient text cannot be None.")
+
+    text = str(raw).strip()
+    if not text:
+        raise ValueError("Coefficient text cannot be empty.")
 
-def coerce_tokens(
-    tokens: Sequence[str], symbol_names: Sequence[str]
-) -> List[Union[float, int, "sp.Symbol"]]:
-    """Coerce a list of string tokens into floats (when possible) or SymPy Symbols for declared symbols.
+    text = text.replace(";", " ").replace("[", " ").replace("]", " ").replace(",", " ")
+    tokens = [token for token in text.split() if token.strip()]
+    if not tokens:
+        raise ValueError("No coefficient tokens were found.")
+    return tokens
 
-    Design choice:
-    - If *no* symbols are declared, we prefer **pure numeric** (floats) to keep downstream logic numeric,
-      so Routh sign-change counting remains available.
-    - Only when a token cannot be parsed as a float and SymPy is available do we fall back to nsimplify.
-    - If a token is explicitly declared as a symbol, return a SymPy Symbol regardless.
+
+def coerce_tokens(tokens: Sequence[str], symbol_names: Sequence[str] | None) -> list[NumericOrSymbolic]:
+    """Convert coefficient tokens into numeric or symbolic objects.
+
+    The coercion policy is deliberately conservative. Declared symbol names are
+    converted to SymPy symbols. All other tokens are parsed as floats first. If
+    float parsing fails and SymPy is installed, the token is parsed with
+    ``sympy.nsimplify``. This keeps numeric Routh workflows numeric while still
+    supporting symbolic gain parameters such as ``K``.
+
+    Args:
+        tokens: Tokenized coefficient values in descending polynomial order.
+        symbol_names: Names that should be treated as symbolic parameters.
+
+    Returns:
+        A list containing floats and, when SymPy is available, symbolic values.
+
+    Raises:
+        ValueError: If a symbolic token is requested without SymPy, or if a
+            non-numeric token cannot be parsed without SymPy.
     """
-    symbol_set = set(symbol_names or [])
-    coerced = []
-    for tok in tokens:
-        coerced.append(_to_numeric_or_symbol(tok, symbol_set))
-    return coerced
-
-def _to_numeric_or_symbol(token: str, symbol_set: set):
-    # If explicitly marked as a symbol, return SymPy Symbol (if available) or raise.
+    symbol_set = {str(name).strip() for name in (symbol_names or []) if str(name).strip()}
+    return [_to_numeric_or_symbol(str(token).strip(), symbol_set) for token in tokens]
+
+
+def _to_numeric_or_symbol(token: str, symbol_set: set[str]) -> NumericOrSymbolic:
+    """Coerce one token to a float, SymPy expression, or declared symbol."""
+    if not token:
+        raise ValueError("Encountered an empty coefficient token.")
+
     if token in symbol_set:
         if sp is None:
-            raise ValueError(f"Token '{token}' declared as symbol but SymPy is not installed.")
+            raise ValueError(f"Token {token!r} was declared as a symbol, but SymPy is not installed.")
         return sp.Symbol(token, real=True)
 
-    # Prefer numeric first: keep numerics as floats when possible.
     try:
-        # int-like strings become floats (consistent with downstream float usage)
         return float(token)
     except ValueError:
         pass
 
-    # Non-numeric: try SymPy if available (e.g., rational expressions like '3/5')
     if sp is not None:
         try:
             return sp.nsimplify(token, rational=True)
         except Exception:
-            # last resort: a symbol-like token that wasn't declared; create a Symbol to avoid crash
             return sp.Symbol(token, real=True)
 
-    # No SymPy available and not numeric -> cannot coerce
-    raise ValueError(f"Token '{token}' is not numeric and SymPy is not available to parse it.")
+    raise ValueError(f"Token {token!r} is not numeric and SymPy is not available to parse it.")
 
-def fmt_cell(x) -> str:
-    if sp and isinstance(x, sp.Basic):
+
+def fmt_cell(x: Any) -> str:
+    """Format a Routh-table cell for console and JSON-safe output."""
+    if sp is not None and isinstance(x, sp.Basic):
         try:
             return str(sp.simplify(x))
-        except Exception:  # pragma: no cover
+        except Exception:  # pragma: no cover - defensive formatting fallback.
             return str(x)
+
     try:
         return f"{float(x): .6g}"
-    except Exception:  # pragma: no cover
+    except Exception:  # pragma: no cover - defensive formatting fallback.
         return str(x)