chore: replace the remaining enums with literals (3/4)

docs/conf.py

@@ -146,10 +146,6 @@
     ("py:class", "numpy._typing._array_like.NDArray"),
     ("py:class", "np.number"),
     ("py:class", "csr_matrix"),
-    # no idea why those aren’t exported
-    ("py:class", "squidpy._constants._constants.SpatialAutocorr"),
-    ("py:class", "squidpy._constants._constants.CoordType"),
-    ("py:class", "squidpy._constants._constants.Transform"),
     ("py:class", "pandas.core.frame.DataFrame"),
 ]
 # see the solution from: https://github.com/sphinx-doc/sphinx/issues/7369

docs/contributing.md

@@ -171,6 +171,7 @@ Consider enabling this option for [ruff][ruff-editors] and [biome][biome-editors
 
 - **Keyword-only arguments**: a public function takes its data object (`adata`, `sdata` or `data`) positionally, and every other argument is keyword-only, e.g. `def nhood_enrichment(adata, *, cluster_key, ...)`. Avoid catch-all `**kwargs` that forward whatever they are given unchecked.
 - **Parameter bags**: a `*Params` {class}`~typing.TypedDict` in {mod}`squidpy.types`, each key declaring its default as `Annotated[type, Default(value)]`, only when the knobs depend on another argument (one bag per `method`, taken as `method_params`) or several functions share them (taken as `**kwargs: Unpack[XParams]`). Resolve it with `resolve_params` from `squidpy._params`, so unknown keys raise, and keep its keys out of the signature.
+- **String choices** (a `Literal[...]` such as `method="otsu"`) are case-insensitive. Resolve the argument once at the top of the public function with `value = normalize_choice(value, options, name=...)` from `squidpy._validators`, which returns the canonical spelling and raises naming the valid options. Keys the user chose (obs/obsm keys, layer, channel or cluster names, paths) stay case-sensitive. Derive a reused option set from its own annotation with `options_of` rather than retyping it: `_Feature = Literal[...]`, `_FEATURES = options_of(_Feature)`.
 - **Fits**, returned by one function for others to consume, are frozen dataclasses with methods (e.g. `.transform`). Pass them whole.
 - **Results**, returned instead of writing into the input, are {class}`~typing.NamedTuple`s.
 - **Randomness**: take `rng: SeedLike | RNGLike | None = None` ([SPEC 7](https://scientific-python.org/specs/spec-0007/)), never `seed`/`generator`/`random_state`; the exception is `random_state` on sklearn-style estimators (the clusterers), which follow sklearn's `get_params`/`set_params` protocol. Spawn one generator per independent task with `rng.spawn(n)`, and pass `legacy_random(rng)` to APIs that only take an integer seed.

src/squidpy/_constants/_pkg_constants.py

@@ -7,8 +7,6 @@
 
 from anndata import AnnData
 
-from squidpy._constants._constants import Processing, SegmentationBackend
-
 _SEP = "_"
 
 
@@ -23,18 +21,14 @@ def __get__(self, obj: Any, owner: Any) -> str:
 class Key:
     class img:
         @classmethod
-        def segment(cls, backend: str | SegmentationBackend, layer_added: str | None = None) -> str:
-            return f"segmented_{SegmentationBackend(backend).s}" if layer_added is None else layer_added
+        def segment(cls, backend: str, layer_added: str | None = None) -> str:
+            return f"segmented_{backend}" if layer_added is None else layer_added
 
         @classmethod
-        def process(
-            cls, method: str | Processing | Callable[[Any], Any], img_id: str, layer_added: str | None = None
-        ) -> str:
+        def process(cls, method: str | Callable[[Any], Any], img_id: str, layer_added: str | None = None) -> str:
             if layer_added is not None:
                 return layer_added
-            if isinstance(method, Processing):
-                method = method.s
-            elif callable(method):
+            if callable(method):
                 method = getattr(method, "__name__", "custom")
 
             return f"{img_id}_{method}"

src/squidpy/_validators.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from collections.abc import Hashable, Iterable, Sequence
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, cast, get_args, overload
 
 from squidpy._utils import _unique_order_preserving
 
@@ -90,10 +90,39 @@ def assert_isinstance(value: Any, expected_type: type | tuple[type, ...], *, nam
         raise TypeError(f"Expected `{name}` to be of type `{type_names}`, got `{type(value).__name__}`.")
 
 
-def assert_one_of(value: Any, options: Sequence[Any], *, name: str) -> None:
-    """Raise ValueError if *value* is not in *options*."""
-    if value not in options:
-        raise ValueError(f"Expected `{name}` to be one of `{list(options)}`, got `{value!r}`.")
+def options_of(literal: Any) -> tuple[Any, ...]:
+    """Return the members of a `Literal`, so an option list is never retyped beside its annotation.
+
+    Accepts a `type X = Literal[...]` alias too, whose lazy value `typing.get_args` alone would miss.
+    """
+    return get_args(getattr(literal, "__value__", literal))
+
+
+_RAISE = object()
+"""Sentinel: `normalize_choice` raises rather than returning a miss."""
+
+
+@overload
+def normalize_choice[T](value: Any, options: Iterable[T], *, name: str) -> T: ...
+@overload
+def normalize_choice[T, D](value: Any, options: Iterable[T], *, name: str, default: D) -> T | D: ...
+def normalize_choice[T, D](value: Any, options: Iterable[T], *, name: str, default: D | object = _RAISE) -> T | D:
+    """Return the option in *options* matching *value*, ignoring the case of strings.
+
+    Raise ValueError naming the valid options if nothing matches, or return *default*
+    if one was given. `None` is a legal option, so misses are signalled by *default*
+    alone, never by a `None` return.
+    """
+    options = list(options)
+    if isinstance(value, str):
+        for opt in options:
+            if isinstance(opt, str) and opt.casefold() == value.casefold():
+                return opt
+    elif value in options:
+        return value
+    if default is not _RAISE:
+        return cast("D", default)
+    raise ValueError(f"Expected `{name}` to be one of `{options}`, got `{value!r}`.")
 
 
 def assert_key_in(obj: Any, key: str, *, attr: str, obj_name: str, extra_msg: str = "") -> None:

src/squidpy/datasets/_datasets.py

@@ -10,6 +10,7 @@
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, Literal
 
+from squidpy._validators import normalize_choice
 from squidpy.datasets._downloader import download
 from squidpy.datasets._registry import dataset_names, get_registry
 from squidpy.read._utils import PathLike
@@ -123,9 +124,7 @@ def visium(
     # guard against the visium_10x names specifically: a valid-but-wrong-type name
     # (e.g. "imc", an AnnData dataset) would otherwise pass and fail deep in the
     # anndata loader with a confusing ``unexpected keyword argument 'include_hires_tiff'``.
-    visium_samples = dataset_names("visium_10x")
-    if sample_id not in visium_samples:
-        raise ValueError(f"Unknown Visium sample: {sample_id}. Available samples: {visium_samples}")
+    sample_id = normalize_choice(sample_id, dataset_names("visium_10x"), name="sample_id")
 
     # downloads land in <datasetdir>/visium_10x/<sample_id>/
     return download(sample_id, base_dir, include_hires_tiff=include_hires_tiff)

src/squidpy/experimental/im/__init__.py

@@ -4,15 +4,13 @@
 from ._detect_tissue import detect_tissue
 from ._make_tiles import make_tiles, make_tiles_from_spots
 from ._qc_image import qc_image
-from ._qc_metrics import QCMetric
 from ._stain import (
     StainFit,
     estimate_white_point,
     fit_stain_reference,
 )
 
 __all__ = [
-    "QCMetric",
     "StainFit",
     "calculate_image_features",
     "detect_tissue",

src/squidpy/experimental/im/_calculate_image_features.py

@@ -26,6 +26,7 @@
 from spatialdata.transformations import get_transformation
 from threadpoolctl import threadpool_limits
 
+from squidpy._validators import normalize_choice
 from squidpy.experimental.im._tiling import (
     CellInfo,
     _run_tiled,
@@ -775,8 +776,7 @@ def _prepare_lazy(
     """
     _validate_inputs(sdata, image_key=image_key, labels_key=labels_key, shapes_key=shapes_key, scale=scale)
 
-    if align_mode not in ("strict", "rasterize"):
-        raise ValueError(f"`align_mode` must be 'strict' or 'rasterize'; got {align_mode!r}.")
+    align_mode = normalize_choice(align_mode, ("strict", "rasterize"), name="align_mode")
 
     image_da = None
     if image_key is not None: