Auto infer label legend span

.github/workflows/build-ultraplot.yml

@@ -22,7 +22,7 @@ jobs:
       run:
         shell: bash -el {0}
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
@@ -58,7 +58,7 @@ jobs:
       run:
         shell: bash -el {0}
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
 
       - uses: mamba-org/setup-micromamba@v2.0.7
         with:
@@ -98,7 +98,7 @@ jobs:
       # Return the html output of the comparison even if failed
       - name: Upload comparison failures
         if: always()
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v6
         with:
           name: failed-comparisons-${{ inputs.python-version }}-${{ inputs.matplotlib-version }}-${{ github.sha }}
           path: results/*

.github/workflows/main.yml

@@ -11,7 +11,7 @@ jobs:
     outputs:
       run: ${{ (github.event_name == 'push' && github.ref_name == 'main') && 'true' || steps.filter.outputs.python }}
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - uses: dorny/paths-filter@v3
         id: filter
         with:
@@ -28,7 +28,7 @@ jobs:
       python-versions: ${{ steps.set-versions.outputs.python-versions }}
       matplotlib-versions: ${{ steps.set-versions.outputs.matplotlib-versions }}
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
 

.github/workflows/publish-pypi.yml

@@ -15,7 +15,7 @@ jobs:
     name: Build packages
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
@@ -54,7 +54,7 @@ jobs:
         shell: bash
 
       - name: Upload artifacts
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v6
         with:
           name: dist-${{ github.sha }}-${{ github.run_id }}-${{ github.run_number }}
           path: dist/*
@@ -73,7 +73,7 @@ jobs:
       contents: read
     steps:
       - name: Download artifacts
-        uses: actions/download-artifact@v5
+        uses: actions/download-artifact@v7
         with:
           name: dist-${{ github.sha }}-${{ github.run_id }}-${{ github.run_number }}
           path: dist
@@ -105,7 +105,7 @@ jobs:
       contents: read
     steps:
       - name: Download artifacts
-        uses: actions/download-artifact@v5
+        uses: actions/download-artifact@v7
         with:
           name: dist-${{ github.sha }}-${{ github.run_id }}-${{ github.run_number }}
           path: dist

.pre-commit-config.yaml

@@ -11,6 +11,6 @@ ci:
 
 repos:
   - repo: https://github.com/psf/black-pre-commit-mirror
-    rev: 25.9.0
+    rev: 25.11.0
     hooks:
       - id: black

docs/2dplots.py

@@ -77,9 +77,10 @@
 #    setting and the :ref:`user guide <ug_1dstd>`).
 
 # %%
-import ultraplot as uplt
 import numpy as np
 
+import ultraplot as uplt
+
 # Sample data
 state = np.random.RandomState(51423)
 x = y = np.array([-10, -5, 0, 5, 10])
@@ -110,9 +111,10 @@
     axs[3].contourf(xedges, yedges, data)
 
 # %%
-import ultraplot as uplt
 import numpy as np
 
+import ultraplot as uplt
+
 # Sample data
 cmap = "turku_r"
 state = np.random.RandomState(51423)
@@ -184,9 +186,9 @@
 #    `~pint.UnitRegistry.setup_matplotlib` so that the axes become unit-aware.
 
 # %%
-import xarray as xr
 import numpy as np
 import pandas as pd
+import xarray as xr
 
 # DataArray
 state = np.random.RandomState(51423)
@@ -261,13 +263,14 @@
 # ``diverging=True``, ``cyclic=True``, or ``qualitative=True`` to any plotting
 # command. If the colormap type is not explicitly specified, `sequential` is
 # used with the default linear normalizer when data is strictly positive
-# or negative, and `diverging` is used with the :ref:`diverging normalizer <ug_norm>`
+# or negative, and `diverging` is used with the :ref:`diverging normalizer <ug_apply_norm>`
 # when the data limits or colormap levels cross zero (see :ref:`below <ug_autonorm>`).
 
 # %%
-import ultraplot as uplt
 import numpy as np
 
+import ultraplot as uplt
+
 # Sample data
 N = 18
 state = np.random.RandomState(51423)
@@ -294,9 +297,10 @@
 uplt.rc.reset()
 
 # %%
-import ultraplot as uplt
 import numpy as np
 
+import ultraplot as uplt
+
 # Sample data
 N = 20
 state = np.random.RandomState(51423)
@@ -322,9 +326,10 @@
     colorbar="b",
 )
 
-import ultraplot as uplt
 import numpy as np
 
+import ultraplot as uplt
+
 # Sample data
 N = 20
 state = np.random.RandomState(51423)
@@ -347,7 +352,7 @@
 # Special normalizers
 # -------------------
 #
-# UltraPlot includes two new :ref:`"continuous" normalizers <ug_norm>`. The
+# UltraPlot includes two new :ref:`"continuous" normalizers <ug_apply_norm>`. The
 # `~ultraplot.colors.SegmentedNorm` normalizer provides even color gradations with respect
 # to index for an arbitrary monotonically increasing or decreasing list of levels. This
 # is automatically applied if you pass unevenly spaced `levels` to a plotting command,
@@ -372,9 +377,10 @@
 # affect the interpretation of different datasets.
 
 # %%
-import ultraplot as uplt
 import numpy as np
 
+import ultraplot as uplt
+
 # Sample data
 state = np.random.RandomState(51423)
 data = 11 ** (2 * state.rand(20, 20).cumsum(axis=0) / 7)
@@ -395,9 +401,10 @@
     )
     ax.format(title=norm.title() + " normalizer")
 # %%
-import ultraplot as uplt
 import numpy as np
 
+import ultraplot as uplt
+
 # Sample data
 state = np.random.RandomState(51423)
 data1 = (state.rand(20, 20) - 0.485).cumsum(axis=1).cumsum(axis=0)
@@ -434,7 +441,7 @@
 # commands (e.g., :func:`~ultraplot.axes.PlotAxes.contourf`, :func:`~ultraplot.axes.PlotAxes.pcolor`).
 # This is analogous to `matplotlib.colors.BoundaryNorm`, except
 # `~ultraplot.colors.DiscreteNorm` can be paired with arbitrary
-# continuous normalizers specified by `norm` (see :ref:`above <ug_norm>`).
+# continuous normalizers specified by `norm` (see :ref:`above <ug_apply_norm>`).
 # Discrete color levels can help readers discern exact numeric values and
 # tend to reveal qualitative structure in the data. `~ultraplot.colors.DiscreteNorm`
 # also repairs the colormap end-colors by ensuring the following conditions are met:
@@ -463,9 +470,10 @@
 # the zero level (useful for single-color :func:`~ultraplot.axes.PlotAxes.contour` plots).
 
 # %%
-import ultraplot as uplt
 import numpy as np
 
+import ultraplot as uplt
+
 # Sample data
 state = np.random.RandomState(51423)
 data = 10 + state.normal(0, 1, size=(33, 33)).cumsum(axis=0).cumsum(axis=1)
@@ -485,9 +493,10 @@
 axs[2].format(title="Imshow plot\ndiscrete=False (default)", yformatter="auto")
 
 # %%
-import ultraplot as uplt
 import numpy as np
 
+import ultraplot as uplt
+
 # Sample data
 state = np.random.RandomState(51423)
 data = (20 * (state.rand(20, 20) - 0.4).cumsum(axis=0).cumsum(axis=1)) % 360
@@ -547,7 +556,7 @@
 # the 2D :class:`~ultraplot.axes.PlotAxes` commands will apply the diverging colormap
 # :rc:`cmap.diverging` (rather than :rc:`cmap.sequential`) and the diverging
 # normalizer `~ultraplot.colors.DivergingNorm` (rather than :class:`~matplotlib.colors.Normalize`
-# -- see :ref:`above <ug_norm>`) if the following conditions are met:
+# -- see :ref:`above <ug_apply_norm>`) if the following conditions are met:
 #
 # #. If discrete levels are enabled (see :ref:`above <ug_discrete>`) and the
 #    level list includes at least 2 negative and 2 positive values.
@@ -560,9 +569,10 @@
 # setting :rcraw:`cmap.autodiverging` to ``False``.
 
 # %%
-import ultraplot as uplt
 import numpy as np
 
+import ultraplot as uplt
+
 N = 20
 state = np.random.RandomState(51423)
 data = N * 2 + (state.rand(N, N) - 0.45).cumsum(axis=0).cumsum(axis=1) * 10
@@ -605,9 +615,10 @@
 # command documentation for details.
 
 # %%
-import ultraplot as uplt
-import pandas as pd
 import numpy as np
+import pandas as pd
+
+import ultraplot as uplt
 
 # Sample data
 state = np.random.RandomState(51423)
@@ -663,10 +674,11 @@
 # `~ultraplot.axes.CartesianAxes`.
 
 # %%
-import ultraplot as uplt
 import numpy as np
 import pandas as pd
 
+import ultraplot as uplt
+
 # Covariance data
 state = np.random.RandomState(51423)
 data = state.normal(size=(10, 10)).cumsum(axis=0)

docs/colorbars_legends.py

@@ -78,9 +78,10 @@
 #    complex arrangements of subplots, colorbars, and legends.
 
 # %%
-import ultraplot as uplt
 import numpy as np
 
+import ultraplot as uplt
+
 state = np.random.RandomState(51423)
 fig = uplt.figure(share=False, refwidth=2.3)
 
@@ -183,9 +184,10 @@
 )
 
 # %%
-import ultraplot as uplt
 import numpy as np
 
+import ultraplot as uplt
+
 N = 10
 state = np.random.RandomState(51423)
 fig, axs = uplt.subplots(
@@ -232,9 +234,10 @@
 # and the tight layout padding can be controlled with the `pad` keyword.
 
 # %%
-import ultraplot as uplt
 import numpy as np
 
+import ultraplot as uplt
+
 state = np.random.RandomState(51423)
 fig, axs = uplt.subplots(ncols=3, nrows=3, refwidth=1.4)
 for ax in axs:
@@ -254,9 +257,10 @@
 fig.colorbar(m, label="colorbar with length <1", ticks=0.1, loc="r", length=0.7)
 
 # %%
-import ultraplot as uplt
 import numpy as np
 
+import ultraplot as uplt
+
 state = np.random.RandomState(51423)
 fig, axs = uplt.subplots(
     ncols=2, nrows=2, order="F", refwidth=1.7, wspace=2.5, share=False
@@ -299,7 +303,7 @@
 #   will build the required `~matplotlib.cm.ScalarMappable` on-the-fly. Lists
 #   of :class:`~matplotlib.artist.Artists`\ s are used when you use the `colorbar`
 #   keyword with :ref:`1D commands <ug_1dplots>` like :func:`~ultraplot.axes.PlotAxes.plot`.
-# * The associated :ref:`colormap normalizer <ug_norm>` can be specified with the
+# * The associated :ref:`colormap normalizer <ug_apply_norm>` can be specified with the
 #   `vmin`, `vmax`, `norm`, and `norm_kw` keywords. The `~ultraplot.colors.DiscreteNorm`
 #   levels can be specified with `values`, or UltraPlot will infer them from the
 #   :class:`~matplotlib.artist.Artist` labels (non-numeric labels will be applied to
@@ -332,9 +336,10 @@
 # See :func:`~ultraplot.axes.Axes.colorbar` for details.
 
 # %%
-import ultraplot as uplt
 import numpy as np
 
+import ultraplot as uplt
+
 fig = uplt.figure(share=False, refwidth=2)
 
 # Colorbars from lines
@@ -427,9 +432,10 @@
 # (or use the `handle_kw` keyword). See `ultraplot.axes.Axes.legend` for details.
 
 # %%
-import ultraplot as uplt
 import numpy as np
 
+import ultraplot as uplt
+
 uplt.rc.cycle = "538"
 fig, axs = uplt.subplots(ncols=2, span=False, share="labels", refwidth=2.3)
 labels = ["a", "bb", "ccc", "dddd", "eeeee"]

docs/why.rst

@@ -499,9 +499,9 @@ like :func:`~ultraplot.axes.PlotAxes.pcolor` and :func:`~ultraplot.axes.PlotAxes
   plots. This can be disabled by setting :rcraw:`cmap.discrete` to ``False`` or
   by passing ``discrete=False`` to :class:`~ultraplot.axes.PlotAxes` commands.
 * The :class:`~ultraplot.colors.DivergingNorm` normalizer is perfect for data with a
-  :ref:`natural midpoint <ug_norm>` and offers both "fair" and "unfair" scaling.
+  :ref:`natural midpoint <ug_apply_norm>` and offers both "fair" and "unfair" scaling.
   The :class:`~ultraplot.colors.SegmentedNorm` normalizer can generate
-  uneven color gradations useful for :ref:`unusual data distributions <ug_norm>`.
+  uneven color gradations useful for :ref:`unusual data distributions <ug_apply_norm>`.
 * The :func:`~ultraplot.axes.PlotAxes.heatmap` command invokes
   :func:`~ultraplot.axes.PlotAxes.pcolormesh` then applies an `equal axes apect ratio
   <https://matplotlib.org/stable/gallery/subplots_axes_and_figures/axis_equal_demo.html>`__,
@@ -882,7 +882,7 @@ Limitation
 ----------
 
 Matplotlib :obj:`~matplotlib.rcParams` can be changed persistently by placing
-`matplotlibrc` :ref:`ug_mplrc` files in the same directory as your python script.
+ref:`matplotlibrc <ug_mplrc>` files in the same directory as your python script.
 But it can be difficult to design and store your own colormaps and color cycles for
 future use. It is also difficult to get matplotlib to use custom ``.ttf`` and
 ``.otf`` font files, which may be desirable when you are working on