refactor(validate): decompose _type_check_params into per-parameter helpers (#716)

Split the 372-line, CCN~164 _type_check_params into 19 module-private
_check_* helpers, each validating one parameter group in place; the function
is now a flat ordered sequence of calls. Behavior-preserving: the call order
(hence the first-raised error for any input) and all param_dict mutations are
identical. Verified by a 370-case old-vs-new differential (0 mismatches) and
the full non-visual suite (510 passed).

Notable: contour_px keeps two checks at their original positions (type before
color, range after outline) and _check_contour_px_range re-fetches contour_px
from param_dict; the interleaved cmap/palette/groups region stays one helper.

Adds a direct order-preservation test (color before contour_px range).

Author: timtreis

src/spatialdata_plot/pl/_validate.py

@@ -368,7 +368,7 @@ def _validate_col_for_column_table(
     return col_for_color, table_name
 
 
-def _type_check_params(param_dict: dict[str, Any], element_type: str) -> dict[str, Any]:
+def _check_colorbar(param_dict: dict[str, Any]) -> None:
     colorbar = param_dict.get("colorbar", "auto")
     if colorbar not in {True, False, None, "auto"}:
         raise TypeError("Parameter 'colorbar' must be one of True, False or 'auto'.")
@@ -377,6 +377,8 @@ def _type_check_params(param_dict: dict[str, Any], element_type: str) -> dict[st
     if colorbar_params is not None and not isinstance(colorbar_params, dict):
         raise TypeError("Parameter 'colorbar_params' must be a dictionary or None.")
 
+
+def _check_element(param_dict: dict[str, Any], element_type: str) -> None:
     element = param_dict.get("element")
     if element is not None and not isinstance(element, str):
         raise ValueError(
@@ -392,6 +394,8 @@ def _type_check_params(param_dict: dict[str, Any], element_type: str) -> dict[st
     elif element_type == "shapes":
         param_dict["element"] = [element] if element is not None else list(param_dict["sdata"].shapes.keys())
 
+
+def _check_channel(param_dict: dict[str, Any]) -> None:
     channel = param_dict.get("channel")
     if channel is not None and not isinstance(channel, list | str | int):
         raise TypeError("Parameter 'channel' must be a string, an integer, or a list of strings or integers.")
@@ -404,10 +408,14 @@ def _type_check_params(param_dict: dict[str, Any], element_type: str) -> dict[st
     elif "channel" in param_dict:
         param_dict["channel"] = [channel] if channel is not None else None
 
+
+def _check_contour_px_type(param_dict: dict[str, Any]) -> None:
     contour_px = param_dict.get("contour_px")
     if contour_px and not isinstance(contour_px, int):
         raise TypeError("Parameter 'contour_px' must be an integer.")
 
+
+def _check_color(param_dict: dict[str, Any], element_type: str) -> None:
     color = param_dict.get("color")
     if color and element_type in {
         "shapes",
@@ -440,6 +448,8 @@ def _type_check_params(param_dict: dict[str, Any], element_type: str) -> dict[st
     elif "color" in param_dict and element_type != "images":
         param_dict["col_for_color"] = None
 
+
+def _check_outline(param_dict: dict[str, Any], element_type: str) -> None:
     outline_width = param_dict.get("outline_width")
     if outline_width:
         # outline_width only exists for shapes at the moment
@@ -520,12 +530,17 @@ def _type_check_params(param_dict: dict[str, Any], element_type: str) -> dict[st
         else:
             param_dict["outline_color"] = Color(outline_color)
 
+
+def _check_contour_px_range(param_dict: dict[str, Any]) -> None:
+    contour_px = param_dict.get("contour_px")
     if contour_px is not None and contour_px < 2:
         raise ValueError(
             "Parameter 'contour_px' must be >= 2; values below 2 produce no visible outline "
             "(a 1x1 erosion is the identity transformation)."
         )
 
+
+def _check_alpha(param_dict: dict[str, Any], element_type: str) -> None:
     alpha = param_dict.get("alpha")
     if alpha is not None:
         if not isinstance(alpha, float | int):
@@ -536,6 +551,8 @@ def _type_check_params(param_dict: dict[str, Any], element_type: str) -> dict[st
         # set default alpha for points if not given by user explicitly or implicitly (as part of color)
         param_dict["alpha"] = 1.0
 
+
+def _check_fill_alpha(param_dict: dict[str, Any], element_type: str) -> None:
     fill_alpha = param_dict.get("fill_alpha")
     if fill_alpha is not None:
         if not isinstance(fill_alpha, float | int):
@@ -549,6 +566,8 @@ def _type_check_params(param_dict: dict[str, Any], element_type: str) -> dict[st
         # set default fill_alpha for labels if not given by user explicitly or implicitly (as part of color)
         param_dict["fill_alpha"] = 0.4
 
+
+def _check_cmap_palette_groups(param_dict: dict[str, Any], element_type: str) -> None:
     cmap = param_dict.get("cmap")
     palette = param_dict.get("palette")
     if cmap is not None and palette is not None:
@@ -597,10 +616,14 @@ def _type_check_params(param_dict: dict[str, Any], element_type: str) -> dict[st
     else:
         raise TypeError("Parameter 'cmap' must be a string, a Colormap, or a list of these types.")
 
+
+def _check_na_color(param_dict: dict[str, Any]) -> None:
     # validation happens within Color constructor (images don't use na_color)
     if "na_color" in param_dict:
         param_dict["na_color"] = Color(param_dict.get("na_color"))
 
+
+def _check_norm(param_dict: dict[str, Any], element_type: str) -> None:
     norm = param_dict.get("norm")
     if norm is not None:
         if element_type == "images":
@@ -618,6 +641,8 @@ def _type_check_params(param_dict: dict[str, Any], element_type: str) -> dict[st
         if element_type == "graph" and not isinstance(norm, Normalize):
             raise TypeError("Parameter 'norm' must be a Normalize instance.")
 
+
+def _check_scale(param_dict: dict[str, Any], element_type: str) -> None:
     scale = param_dict.get("scale")
     if scale is not None:
         if element_type in {"images", "labels"} and not isinstance(scale, str):
@@ -628,13 +653,17 @@ def _type_check_params(param_dict: dict[str, Any], element_type: str) -> dict[st
             if scale < 0:
                 raise ValueError("Parameter 'scale' must be a positive number.")
 
+
+def _check_size(param_dict: dict[str, Any]) -> None:
     size = param_dict.get("size")
     if size:
         if not isinstance(size, float | int):
             raise TypeError("Parameter 'size' must be numeric.")
         if size < 0:
             raise ValueError("Parameter 'size' must be a positive number.")
 
+
+def _check_shape(param_dict: dict[str, Any], element_type: str) -> None:
     shape = param_dict.get("shape")
     if element_type == "shapes" and shape is not None:
         valid_shapes = {"circle", "hex", "visium_hex", "square"}
@@ -643,6 +672,8 @@ def _type_check_params(param_dict: dict[str, Any], element_type: str) -> dict[st
         if shape not in valid_shapes:
             raise ValueError(f"'{shape}' is not supported for 'shape', please choose from {valid_shapes}.")
 
+
+def _check_table(param_dict: dict[str, Any]) -> None:
     table_name = param_dict.get("table_name")
     table_layer = param_dict.get("table_layer")
     if table_name and not isinstance(param_dict["table_name"], str):
@@ -690,10 +721,14 @@ def _ensure_table_and_layer_exist_in_sdata(
 
     _ensure_table_and_layer_exist_in_sdata(param_dict.get("sdata"), table_name, table_layer)
 
+
+def _check_method(param_dict: dict[str, Any]) -> None:
     method = param_dict.get("method")
     if method not in ["matplotlib", "datashader", None]:
         raise ValueError("If specified, parameter 'method' must be either 'matplotlib' or 'datashader'.")
 
+
+def _check_ds_reduction(param_dict: dict[str, Any]) -> None:
     valid_ds_reduction_methods = [
         "sum",
         "mean",
@@ -710,6 +745,8 @@ def _ensure_table_and_layer_exist_in_sdata(
     if ds_reduction and (ds_reduction not in valid_ds_reduction_methods):
         raise ValueError(f"Parameter 'ds_reduction' must be one of the following: {valid_ds_reduction_methods}.")
 
+
+def _check_graph_params(param_dict: dict[str, Any], element_type: str) -> None:
     if element_type == "graph":
         for key in ("connectivity_key",):
             val = param_dict.get(key)
@@ -739,6 +776,28 @@ def _ensure_table_and_layer_exist_in_sdata(
             if val is not None and not isinstance(val, bool):
                 raise TypeError(f"Parameter '{key}' must be a boolean.")
 
+
+def _type_check_params(param_dict: dict[str, Any], element_type: str) -> dict[str, Any]:
+    # Call order is the contract: the first-raised error and in-place mutations must match the pre-split form.
+    _check_colorbar(param_dict)
+    _check_element(param_dict, element_type)
+    _check_channel(param_dict)
+    _check_contour_px_type(param_dict)
+    _check_color(param_dict, element_type)
+    _check_outline(param_dict, element_type)
+    _check_contour_px_range(param_dict)  # must stay after outline (preserves first-error order)
+    _check_alpha(param_dict, element_type)
+    _check_fill_alpha(param_dict, element_type)
+    _check_cmap_palette_groups(param_dict, element_type)
+    _check_na_color(param_dict)
+    _check_norm(param_dict, element_type)
+    _check_scale(param_dict, element_type)
+    _check_size(param_dict)
+    _check_shape(param_dict, element_type)
+    _check_table(param_dict)
+    _check_method(param_dict)
+    _check_ds_reduction(param_dict)
+    _check_graph_params(param_dict, element_type)
     return param_dict
 
 

tests/pl/test_utils.py

@@ -273,6 +273,21 @@ def test_extract_scalar_value():
     assert _extract_scalar_value([], default=1.0) == 1.0
 
 
+def test_type_check_params_preserves_validation_order():
+    """#716: decomposition must preserve call order, so the first error for a multiply-invalid input is
+    unchanged -- `color` is validated before the `contour_px < 2` range check.
+    """
+    from spatialdata_plot.pl._validate import _type_check_params
+
+    # color=5 raises in the color block, before the contour_px range check -> color error wins.
+    with pytest.raises(TypeError, match="Parameter 'color' must be a string or a tuple/list of floats."):
+        _type_check_params({"element": "x", "color": 5, "contour_px": 1, "sdata": None}, "labels")
+
+    # a valid RGB tuple (no sdata-dependent collision check) lets the same input reach contour_px.
+    with pytest.raises(ValueError, match="Parameter 'contour_px' must be >= 2"):
+        _type_check_params({"element": "x", "color": (1.0, 0.0, 0.0), "contour_px": 1, "sdata": None}, "labels")
+
+
 def test_plot_can_handle_rgba_color_specifications(sdata_blobs: SpatialData):
     """Test handling of RGBA color specifications."""
     # Test with RGBA tuple