Accept both 'location' and 'loc' in legend_params

matplotlib.legend.Legend natively uses 'loc' while Figure.colorbar and
matplotlib_scalebar both use 'location', which would force users to
remember a different key name for legend_params than for colorbar_params
and scalebar_params. We accept both spellings so the three escape-hatch
dicts read consistently; 'location' is documented as canonical and wins
when both are passed.

Inline comments at the merge site and the validation whitelist explain
the matplotlib quirk so future maintainers don't 'simplify' the alias
away.

Author: timtreis

src/spatialdata_plot/pl/basic.py

@@ -968,10 +968,11 @@ def show(
             See the matplotlib-scalebar documentation for the full list of options.
         legend_params : dict[str, Any] | None
             Bundled legend options. Mirrors ``colorbar_params`` / ``scalebar_params``. Accepted keys:
-            ``loc``, ``fontsize``, ``fontweight``, ``fontoutline``, ``na_in_legend`` — all forwarded
-            to the corresponding flat ``legend_*`` mechanics. When a key is set both as a flat
-            kwarg (e.g. ``legend_fontsize=12``) and inside this dict, the dict value wins. Unknown
-            keys raise ``ValueError`` to surface typos early.
+            ``location`` (canonical, alias ``loc`` accepted to match
+            :class:`matplotlib.legend.Legend`), ``fontsize``, ``fontweight``, ``fontoutline``,
+            ``na_in_legend``. When a key is set both as a flat kwarg (e.g. ``legend_fontsize=12``)
+            and inside this dict, the dict value wins. Unknown keys raise ``ValueError`` to surface
+            typos early.
 
         Returns
         -------
@@ -1141,10 +1142,14 @@ def show(
         )
         # Merge dict-form legend_params over the flat legend_* kwargs (dict wins). Unknown keys
         # have already been rejected by _validate_show_parameters; treat the dict as authoritative.
+        # Note: matplotlib.legend.Legend uses `loc`, while Figure.colorbar and matplotlib_scalebar
+        # use `location`. We accept both spellings so legend_params reads consistently with
+        # colorbar_params / scalebar_params; `location` is the canonical name and wins if both are
+        # passed.
         if legend_params:
             legend_fontsize = legend_params.get("fontsize", legend_fontsize)
             legend_fontweight = legend_params.get("fontweight", legend_fontweight)
-            legend_loc = legend_params.get("loc", legend_loc)
+            legend_loc = legend_params.get("location", legend_params.get("loc", legend_loc))
             legend_fontoutline = legend_params.get("fontoutline", legend_fontoutline)
             na_in_legend = legend_params.get("na_in_legend", na_in_legend)
 

src/spatialdata_plot/pl/utils.py

@@ -2277,7 +2277,10 @@ def _validate_show_parameters(
     if legend_params is not None:
         if not isinstance(legend_params, dict):
             raise TypeError("Parameter 'legend_params' must be a dictionary or None.")
-        allowed_legend_keys = {"loc", "fontsize", "fontweight", "fontoutline", "na_in_legend"}
+        # `location` is the canonical name (matches colorbar_params / scalebar_params); `loc` is
+        # accepted as an alias because that is what matplotlib.legend.Legend natively uses, so
+        # copy-paste from matplotlib examples keeps working.
+        allowed_legend_keys = {"loc", "location", "fontsize", "fontweight", "fontoutline", "na_in_legend"}
         unknown = set(legend_params) - allowed_legend_keys
         if unknown:
             raise ValueError(

tests/pl/test_show.py

@@ -316,11 +316,28 @@ def test_legend_params_default_none_is_noop(sdata_blobs: SpatialData):
         ({"legend_params": []}, TypeError),
         ({"legend_params": "loc=upper right"}, TypeError),
         ({"legend_params": {"loc": "upper right", "frameon": True}}, ValueError),
-        ({"legend_params": {"location": "upper right"}}, ValueError),  # matplotlib uses "loc", not "location"
+        ({"legend_params": {"locaton": "upper right"}}, ValueError),  # typo of "location"
     ],
 )
 def test_legend_params_validation_rejects_bad_inputs(sdata_blobs: SpatialData, kwargs, exc):
     """_validate_show_parameters surfaces actionable errors for bad legend_params inputs."""
     with pytest.raises(exc):
         sdata_blobs.pl.render_shapes(element="blobs_circles").pl.show(show=False, **kwargs)
     plt.close("all")
+
+
+def test_legend_params_location_alias_for_loc(sdata_blobs: SpatialData):
+    """legend_params accepts both 'location' (canonical) and 'loc' (matplotlib-native alias)."""
+    # Both spellings reach LegendParams.legend_loc; verify by confirming neither raises and the
+    # canonical 'location' takes precedence when both are passed (the alias resolution is a small
+    # consequence of mirroring colorbar_params / scalebar_params naming).
+    sdata_blobs.pl.render_shapes(element="blobs_circles").pl.show(
+        legend_params={"loc": "upper right"}, return_ax=True, show=False
+    )
+    sdata_blobs.pl.render_shapes(element="blobs_circles").pl.show(
+        legend_params={"location": "upper right"}, return_ax=True, show=False
+    )
+    sdata_blobs.pl.render_shapes(element="blobs_circles").pl.show(
+        legend_params={"loc": "upper left", "location": "lower right"}, return_ax=True, show=False
+    )
+    plt.close("all")