feat(plot)!: adopt cleopatra 0.30 typed render groups across all plot methods

docs/examples/dataset/dataset_collection.ipynb

@@ -23,10 +23,10 @@
    "outputs": [],
    "source": [
     "# NBVAL_IGNORE_OUTPUT\n",
-    "from cleopatra.array_glyph import FrameLabel\n",
     "from IPython.display import HTML\n",
     "\n",
     "from pyramids.dataset import DatasetCollection\n",
+    "from pyramids.plot import ColorScaling, FrameLabel\n",
     "\n",
     "%matplotlib inline"
    ]
@@ -256,7 +256,7 @@
     "cleo = m_dataset.plot(\n",
     "    exclude_value=0,\n",
     "    frame_label=FrameLabel(location=(1, 3)),\n",
-    "    color_scale=\"linear\",\n",
+    "    color=ColorScaling.linear(),\n",
     "    vmin=1,\n",
     "    vmax=100,\n",
     ")\n",

docs/examples/netcdf/ugrid/ugrid-river-channel.ipynb

@@ -47,7 +47,8 @@
     "\n",
     "from pyramids.netcdf.ugrid import (\n",
     "    UgridDataset,\n",
-    ")"
+    ")\n",
+    "from pyramids.plot import ColorBar"
    ]
   },
   {
@@ -135,7 +136,7 @@
     "    \"bathymetry\",\n",
     "    cmap=\"ocean_r\",\n",
     "    title=\"River Channel Bathymetry\",\n",
-    "    cbar_label=\"Depth (m)\",\n",
+    "    colorbar=ColorBar(label=\"Depth (m)\"),\n",
     ")\n",
     "plt.show()"
    ]
@@ -151,7 +152,7 @@
     "    \"velocity\",\n",
     "    cmap=\"YlOrRd\",\n",
     "    title=\"Flow Velocity (parabolic cross-section)\",\n",
-    "    cbar_label=\"Velocity (m/s)\",\n",
+    "    colorbar=ColorBar(label=\"Velocity (m/s)\"),\n",
     ")\n",
     "plt.show()"
    ]
@@ -311,7 +312,7 @@
     "    \"bathymetry\",\n",
     "    cmap=\"ocean_r\",\n",
     "    title=\"Meander Bend — Bathymetry\",\n",
-    "    cbar_label=\"Depth (m)\",\n",
+    "    colorbar=ColorBar(label=\"Depth (m)\"),\n",
     ")\n",
     "plt.show()"
    ]
@@ -489,7 +490,7 @@
     "    vmax=1.5,\n",
     "    interval=800,\n",
     "    title=\"Tidal Water Level\",\n",
-    "    cbar_label=\"Water Level (m)\",\n",
+    "    colorbar=ColorBar(label=\"Water Level (m)\"),\n",
     ")\n",
     "\n",
     "from IPython.display import HTML\n",

pyproject.toml

@@ -56,7 +56,7 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
-viz = ["cleopatra[tiles]>=0.28.0"]
+viz = ["cleopatra[tiles]>=0.30.0"]
 lazy = [
     "dask>=2024.1.0",
     "distributed>=2024.1.0",
@@ -234,6 +234,24 @@ exclude = [
     "planning/",
 ]
 
+[[tool.mypy.overrides]]
+# cleopatra ships inline types (the TypedDicts PlotKwargs/AnimateKwargs, the ColorBar /
+# PointOverlay / Basemap dataclasses, ...) but no `py.typed` marker yet, so the global
+# `ignore_missing_imports` would collapse them to `Any` and break `Unpack[PlotKwargs]`.
+# Follow its source types instead. Drop once cleopatra ships `py.typed`.
+module = "cleopatra.*"
+ignore_missing_imports = false
+follow_untyped_imports = true
+
+[[tool.mypy.overrides]]
+# render_array is the single dynamic-dispatch backend: it splits **kwargs into ctor /
+# render buckets at runtime (keyed on ArrayGlyph.option_keys()) and splats them into
+# cleopatra's now-typed plot/animate/facet. mypy cannot verify a runtime-built **dict
+# against a typed signature, so `arg-type` here is a wall of false positives (the 1367
+# plot tests prove the routing). Suppress just that code for this one module.
+module = "pyramids.dataset._plot_helpers"
+disable_error_code = ["arg-type", "no-any-return"]
+
 [[tool.mypy.overrides]]
 module = "pyramids.dataset.ops.*"
 disable_error_code = [

src/pyramids/base/_utils.py

@@ -654,14 +654,14 @@ def require_optional(module_name: str, message: str, *, return_module: bool = Fa
     One nuance for dotted names: `import_basemap` previously spelled
     `from cleopatra import tiles`, which calls
     `__import__("cleopatra", ..., fromlist=("tiles",))`. Here it becomes
-    `__import__("cleopatra.tiles")`, so the parent package resolves internally
+    `__import__("cleopatra.basemap.tiles")`, so the parent package resolves internally
     rather than through `builtins.__import__`. A patch keyed on
     `name == "cleopatra"` no longer intercepts it; key on the dotted name
     instead. No in-tree test depends on this.
 
     Args:
         module_name: Dotted module path to import, e.g. ``"zarr"`` or
-            ``"cleopatra.tiles"``.
+            ``"cleopatra.basemap.tiles"``.
         message: The install hint raised when the import fails. Compose it with
             :func:`lazy_extra_hint` for the ``[lazy]`` extra.
         return_module: When `True` the imported module object is returned so the
@@ -894,8 +894,8 @@ def import_h5py(message: str):
 
 
 def import_basemap(message: str):
-    """Import the web-tile basemap backend (``cleopatra.tiles``, the ``[tiles]`` extra)."""
-    return require_optional("cleopatra.tiles", message)
+    """Import the web-tile basemap backend (``cleopatra.basemap.tiles``, the ``[tiles]`` extra)."""
+    return require_optional("cleopatra.basemap.tiles", message)
 
 
 def ogr_ds_to_gdal_dataset(ogr_ds: ogr.DataSource) -> gdal.Dataset:

src/pyramids/basemap/__init__.py

@@ -3,7 +3,7 @@
 Adds web-tile basemaps (OpenStreetMap, CartoDB, Esri, etc.) underneath
 data plotted on matplotlib axes. :func:`~pyramids.basemap.add_basemap`
 and :func:`~pyramids.basemap.get_provider` are thin wrappers over
-:mod:`cleopatra.tiles` (the cleopatra C-6 helpers) — cleopatra does the
+:mod:`cleopatra.basemap.tiles` (the cleopatra C-6 helpers) — cleopatra does the
 tile fetching, stitching, GDAL CRS warping, and rendering.
 
 The tile functions require the cleopatra ``[tiles]`` extra (which pins
@@ -13,8 +13,8 @@
 - conda-forge: ``conda install -c conda-forge pyramids-viz``
 
 Natural Earth vector layers and the global relief raster have moved to
-:mod:`cleopatra.reference` (the viz layer), where they belong with the rest of
-the map-decoration helpers — use ``cleopatra.reference`` for those backdrops.
+:mod:`cleopatra.basemap.reference` (the viz layer), where they belong with the rest of
+the map-decoration helpers — use ``cleopatra.basemap.reference`` for those backdrops.
 """
 
 from pyramids.basemap.basemap import add_basemap, get_provider

src/pyramids/basemap/basemap.py

@@ -1,7 +1,7 @@
-"""Web-tile basemap helpers — thin wrappers over ``cleopatra.tiles``.
+"""Web-tile basemap helpers — thin wrappers over ``cleopatra.basemap.tiles``.
 
 :func:`add_basemap` and :func:`get_provider` here delegate to
-:func:`cleopatra.tiles.add_tiles` and :func:`cleopatra.tiles.get_provider`
+:func:`cleopatra.basemap.tiles.add_tiles` and :func:`cleopatra.basemap.tiles.get_provider`
 (the cleopatra C-6 helpers, shipped in ``cleopatra >= 0.8.0`` and pinned
 via the ``[viz]`` extra as ``cleopatra[tiles]``). All the real work —
 provider resolution, zoom selection, parallel tile fetching, stitching,
@@ -40,7 +40,7 @@
 def get_provider(name: str | None = None) -> Any:
     """Resolve a web-tile provider by name.
 
-    Thin wrapper over :func:`cleopatra.tiles.get_provider`.
+    Thin wrapper over :func:`cleopatra.basemap.tiles.get_provider`.
 
     Args:
         name (str or None, optional):
@@ -84,10 +84,10 @@ def get_provider(name: str | None = None) -> Any:
     See Also:
         add_basemap: Uses ``get_provider`` internally (via cleopatra) when
             ``source`` is a string.
-        cleopatra.tiles.get_provider: The underlying implementation.
+        cleopatra.basemap.tiles.get_provider: The underlying implementation.
     """
     import_basemap(_BASEMAP_MSG)
-    from cleopatra.tiles import get_provider as _get_provider
+    from cleopatra.basemap.tiles import get_provider as _get_provider
 
     return _get_provider(name)
 
@@ -106,7 +106,7 @@ def add_basemap(
 ) -> Any:
     """Add a web-tile basemap underneath the data plotted on ``ax``.
 
-    Thin wrapper over :func:`cleopatra.tiles.add_tiles`: fetches XYZ web
+    Thin wrapper over :func:`cleopatra.basemap.tiles.add_tiles`: fetches XYZ web
     tiles for the axes' geographic extent, stitches them into a single
     image, reprojects to the data's CRS via GDAL when ``crs`` is not Web
     Mercator, and renders the image beneath the data layer.
@@ -146,7 +146,7 @@ def add_basemap(
 
     Returns:
         matplotlib.axes.Axes: The axes with the basemap added (whatever
-            :func:`cleopatra.tiles.add_tiles` returns).
+            :func:`cleopatra.basemap.tiles.add_tiles` returns).
 
     Raises:
         OptionalPackageDoesNotExist: If the cleopatra ``[tiles]`` extra is
@@ -181,10 +181,10 @@ def add_basemap(
 
     See Also:
         get_provider: Resolve a tile provider name to a ``TileProvider``.
-        cleopatra.tiles.add_tiles: The underlying implementation.
+        cleopatra.basemap.tiles.add_tiles: The underlying implementation.
     """
     import_basemap(_BASEMAP_MSG)
-    from cleopatra.tiles import add_tiles
+    from cleopatra.basemap.tiles import add_tiles
 
     result = add_tiles(
         ax,