ultraplot 2.1.0__tar.gz → 2.1.3__tar.gz

{ultraplot-2.1.0 → ultraplot-2.1.3}/.github/workflows/build-ultraplot.yml

@@ -327,7 +327,7 @@ jobs:
       # Return the html output of the comparison even if failed
       - name: Upload comparison failures
         if: always()
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@v7
         with:
           name: failed-comparisons-${{ inputs.python-version }}-${{ inputs.matplotlib-version }}-${{ github.sha }}
           path: results/*

{ultraplot-2.1.0 → ultraplot-2.1.3}/.github/workflows/publish-pypi.yml

@@ -54,7 +54,7 @@ jobs:
         shell: bash
 
       - name: Upload artifacts
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@v7
         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@v7
+        uses: actions/download-artifact@v8
         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@v7
+        uses: actions/download-artifact@v8
         with:
           name: dist-${{ github.sha }}-${{ github.run_id }}-${{ github.run_number }}
           path: dist

{ultraplot-2.1.0/ultraplot.egg-info → ultraplot-2.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ultraplot
-Version: 2.1.0
+Version: 2.1.3
 Summary: A succinct matplotlib wrapper for making beautiful, publication-quality graphics.
 Author-email: Casper van Elteren <caspervanelteren@gmail.com>, Luke Davis <lukelbd@gmail.com>
 Maintainer-email: Casper van Elteren <caspervanelteren@gmail.com>, "Matthew R. Becker" <becker.mr@gmail.com>

{ultraplot-2.1.0 → ultraplot-2.1.3}/codecov.yml

@@ -23,6 +23,8 @@ coverage:
           - "!logo/*"
           - "!docs/*"
           - "!ultraplot/tests/*"
+          - "!ultraplot/demos.py"
+
 
       tests:
         target: 95.0%

ultraplot-2.1.3/ultraplot/_version.py

@@ -0,0 +1 @@
+__version__ = '2.1.3'

{ultraplot-2.1.0 → ultraplot-2.1.3}/ultraplot/axes/base.py

@@ -515,9 +515,12 @@ format, formatter, ticklabels : formatter-spec, optional
     constructor function.
 formatter_kw : dict-like, optional
     Keyword arguments passed to `matplotlib.ticker.Formatter` class.
-frame, frameon : bool, default: :rc:`colorbar.frameon`
-    For inset colorbars only. Indicates whether to draw a "frame",
-    just like `~matplotlib.axes.Axes.legend`.
+frame, frameon : bool, optional
+    For inset colorbars, indicates whether to draw a background "frame",
+    just like `~matplotlib.axes.Axes.legend`. Defaults to
+    :rc:`colorbar.frameon` for inset colorbars. For outer colorbars, this is a
+    backwards-compatible alias for `outline`; when omitted, outer colorbars
+    still default to :rc:`colorbar.outline`.
 tickminor : bool, optional
     Whether to add minor ticks using `~matplotlib.colorbar.ColorbarBase.minorticks_on`.
 tickloc, ticklocation : {'bottom', 'top', 'left', 'right'}, optional
@@ -553,7 +556,9 @@ rasterize : bool, default: :rc:`colorbar.rasterized`
     but ultraplot changes this to ``False`` since rasterization can cause misalignment
     between the color patches and the colorbar outline.
 outline : bool, None default : None
-    Controls the visibility of the frame. When set to False, the spines of the colorbar are hidden. If set to `None` it uses the `rc['colorbar.outline']` value.
+    Controls the visibility of the outer colorbar outline. When set to False,
+    the spines of the colorbar are hidden. If set to `None` it uses the
+    `rc['colorbar.outline']` value.
 labelrotation : str, float, default: None
     Controls the rotation of the colorbar label. When set to None it takes on the value of `rc["colorbar.labelrotation"]`. When set to auto it produces a sensible default where the rotation is adjusted to where the colorbar is located. For example, a horizontal colorbar with a label to the left or right will match the horizontal alignment and rotate the label to 0 degrees. Users can provide a float to rotate to any arbitrary angle.
 
@@ -1130,6 +1135,8 @@ class Axes(_ExternalModeMixin, maxes.Axes):
         linewidth=None,
         edgefix=None,
         rasterized=None,
+        frame: Optional[bool] = None,
+        frameon: Optional[bool] = None,
         outline: Union[bool, None] = None,
         labelrotation: Union[str, float] = None,
         center_levels=None,
@@ -1191,6 +1198,8 @@ class Axes(_ExternalModeMixin, maxes.Axes):
             linewidth=linewidth,
             edgefix=edgefix,
             rasterized=rasterized,
+            frame=frame,
+            frameon=frameon,
             outline=outline,
             labelrotation=labelrotation,
             center_levels=center_levels,
@@ -1903,7 +1912,9 @@ class Axes(_ExternalModeMixin, maxes.Axes):
         Return the axes and adjusted keyword args for an inset colorbar.
         """
         # Basic colorbar properties
-        frame = _not_none(frame=frame, frameon=frameon, default=rc["colorbar.frameon"])
+        frame_enabled = _not_none(
+            frame=frame, frameon=frameon, default=rc["colorbar.frameon"]
+        )
         length = _not_none(
             length=length, shrink=shrink, default=rc["colorbar.insetlength"]
         )  # noqa: E501
@@ -1967,8 +1978,9 @@ class Axes(_ExternalModeMixin, maxes.Axes):
         ax.set_axes_locator(locator)
         self.add_child_axes(ax)
         kw_frame, kwargs = self._parse_frame("colorbar", **kwargs)
-        if frame:
-            frame = self._add_guide_frame(
+        frame_artist = None
+        if frame_enabled:
+            frame_artist = self._add_guide_frame(
                 *bounds_frame, fontsize=tick_fontsize, **kw_frame
             )
         ax._inset_colorbar_layout = {
@@ -1984,7 +1996,7 @@ class Axes(_ExternalModeMixin, maxes.Axes):
             "pad_raw": pad_raw,
         }
         ax._inset_colorbar_parent = self
-        ax._inset_colorbar_frame = frame
+        ax._inset_colorbar_frame = frame_artist
 
         kwargs.update({"orientation": orientation, "ticklocation": ticklocation})
         return ax, kwargs
@@ -3149,19 +3161,31 @@ class Axes(_ExternalModeMixin, maxes.Axes):
             self._colorbar_fill.update_ticks(manual_only=True)  # only if needed
         if self._inset_parent is not None and self._inset_zoom:
             self.indicate_inset_zoom()
+        needs_inset_reflow = bool(getattr(self, "_inset_colorbar_needs_reflow", False))
+        has_inset_frame = bool(
+            getattr(self, "_inset_colorbar_frame", None) is not None
+            and getattr(self, "_inset_colorbar_obj", None)
+        )
         super().draw(renderer, *args, **kwargs)
-        if getattr(self, "_inset_colorbar_obj", None) and getattr(
-            self, "_inset_colorbar_needs_reflow", False
-        ):
-            self._inset_colorbar_needs_reflow = False
+        if has_inset_frame:
+            if not needs_inset_reflow:
+                needs_inset_reflow = _inset_colorbar_frame_needs_reflow(
+                    self._inset_colorbar_obj,
+                    labelloc=getattr(self, "_inset_colorbar_labelloc", None),
+                    renderer=renderer,
+                )
+        if has_inset_frame and needs_inset_reflow:
             _reflow_inset_colorbar_frame(
                 self._inset_colorbar_obj,
                 labelloc=getattr(self, "_inset_colorbar_labelloc", None),
                 ticklen=getattr(
                     self, "_inset_colorbar_ticklen", units(rc["tick.len"], "pt")
                 ),
+                renderer=renderer,
             )
-            self.figure.canvas.draw_idle()
+            self._inset_colorbar_needs_reflow = False
+            # Re-draw synchronously so the current render pass sees reflowed bounds.
+            super().draw(renderer, *args, **kwargs)
 
     def get_tightbbox(self, renderer, *args, **kwargs):
         # Perform extra post-processing steps
@@ -4581,11 +4605,71 @@ def _apply_inset_colorbar_layout(
         frame.set_bounds(*bounds_frame)
 
 
+def _inset_colorbar_frame_needs_reflow(colorbar, *, labelloc: str, renderer) -> bool:
+    cax = colorbar.ax
+    layout = getattr(cax, "_inset_colorbar_layout", None)
+    frame = getattr(cax, "_inset_colorbar_frame", None)
+    if not layout or frame is None:
+        return False
+
+    orientation = layout["orientation"]
+    loc = layout["loc"]
+    ticklocation = layout["ticklocation"]
+    labelloc_layout = labelloc if isinstance(labelloc, str) else ticklocation
+    bboxes = []
+
+    longaxis = _get_colorbar_long_axis(colorbar)
+    try:
+        bbox = longaxis.get_tightbbox(renderer)
+    except Exception:
+        bbox = None
+    if bbox is not None:
+        bboxes.append(bbox)
+
+    label_axis = _get_axis_for(
+        labelloc_layout, loc, orientation=orientation, ax=colorbar
+    )
+    if label_axis.label.get_text():
+        try:
+            bboxes.append(label_axis.label.get_window_extent(renderer=renderer))
+        except Exception:
+            pass
+
+    for artist in (
+        getattr(colorbar, "outline", None),
+        getattr(colorbar, "solids", None),
+        getattr(colorbar, "dividers", None),
+    ):
+        if artist is None:
+            continue
+        try:
+            bboxes.append(artist.get_window_extent(renderer=renderer))
+        except Exception:
+            pass
+
+    if not bboxes:
+        return False
+
+    x0 = min(bbox.x0 for bbox in bboxes)
+    y0 = min(bbox.y0 for bbox in bboxes)
+    x1 = max(bbox.x1 for bbox in bboxes)
+    y1 = max(bbox.y1 for bbox in bboxes)
+    frame_bbox = frame.get_window_extent(renderer=renderer)
+    tol = 1.0
+    return (
+        frame_bbox.x0 > x0 + tol
+        or frame_bbox.y0 > y0 + tol
+        or frame_bbox.x1 < x1 - tol
+        or frame_bbox.y1 < y1 - tol
+    )
+
+
 def _reflow_inset_colorbar_frame(
     colorbar,
     *,
     labelloc: str,
     ticklen: float,
+    renderer=None,
 ):
     cax = colorbar.ax
     layout = getattr(cax, "_inset_colorbar_layout", None)
@@ -4623,7 +4707,7 @@ def _reflow_inset_colorbar_frame(
         cb_width = width
         cb_height = length
 
-    renderer = cax.figure._get_renderer()
+    renderer = renderer or cax.figure._get_renderer()
     if hasattr(colorbar, "update_ticks"):
         colorbar.update_ticks(manual_only=True)
     bboxes = []

{ultraplot-2.1.0 → ultraplot-2.1.3}/ultraplot/axes/plot.py

@@ -4141,6 +4141,7 @@ class PlotAxes(base.Axes):
         # NOTE: Unlike xarray, but like matplotlib, vmin and vmax only approximately
         # determine level range. Levels are selected with Locator.tick_values().
         levels = None  # unused
+        explicit_limits = False
         isdiverging = False
         if not discrete and not skip_autolev:
             vmin, vmax, kwargs = self._parse_level_lim(
@@ -4150,7 +4151,15 @@ class PlotAxes(base.Axes):
                 if abs(np.sign(vmax) - np.sign(vmin)) == 2:
                     isdiverging = True
         if discrete:
-            levels, vmin, vmax, norm, norm_kw, kwargs = self._parse_level_vals(
+            (
+                levels,
+                vmin,
+                vmax,
+                norm,
+                norm_kw,
+                explicit_limits,
+                kwargs,
+            ) = self._parse_level_vals(
                 *args,
                 vmin=vmin,
                 vmax=vmax,
@@ -4199,6 +4208,7 @@ class PlotAxes(base.Axes):
                 center_levels=center_levels,
                 extend=extend,
                 min_levels=min_levels,
+                explicit_limits=explicit_limits,
                 **kwargs,
             )
         params = _pop_params(kwargs, *self._level_parsers, ignore_internal=True)
@@ -4462,7 +4472,6 @@ class PlotAxes(base.Axes):
         center_levels = _not_none(center_levels, rc["colorbar.center_levels"])
         vmin = _not_none(vmin=vmin, norm_kw_vmin=norm_kw.pop("vmin", None))
         vmax = _not_none(vmax=vmax, norm_kw_vmax=norm_kw.pop("vmax", None))
-        norm = constructor.Norm(norm or "linear", **norm_kw)
         symmetric = _not_none(
             symmetric=symmetric,
             locator_kw_symmetric=locator_kw.pop("symmetric", None),
@@ -4555,6 +4564,8 @@ class PlotAxes(base.Axes):
         nozero=False,
         norm=None,
         norm_kw=None,
+        vmin=None,
+        vmax=None,
         skip_autolev=False,
         min_levels=None,
         center_levels=None,
@@ -4577,7 +4588,9 @@ class PlotAxes(base.Axes):
             Whether to remove out non-positive, non-negative, and zero-valued
             levels. The latter is useful for single-color contour plots.
         norm, norm_kw : optional
-            Passed to `Norm`. Used to possbily infer levels or to convert values.
+            Passed to `Norm`. Used to possibly infer levels or to convert values.
+        vmin, vmax : float, optional
+            The user input normalization range.
         skip_autolev : bool, optional
             Whether to skip automatic level generation.
         min_levels : int, optional
@@ -4587,6 +4600,8 @@ class PlotAxes(base.Axes):
         -------
         levels : list of float
             The level edges.
+        explicit_limits : bool
+            Whether the user explicitly provided `vmin` and/or `vmax`.
         **kwargs
             Unused arguments.
         """
@@ -4625,7 +4640,9 @@ class PlotAxes(base.Axes):
             return array
 
         # Parse input arguments and resolve incompatibilities
-        vmin = vmax = None
+        explicit_limits = vmin is not None or vmax is not None
+        line_contours = min_levels == 1
+        keep_explicit_line_limits = line_contours and explicit_limits
         levels = _not_none(N=N, levels=levels, norm_kw_levs=norm_kw.pop("levels", None))
         if positive and negative:
             warnings._warn_ultraplot(
@@ -4684,6 +4701,8 @@ class PlotAxes(base.Axes):
             levels, kwargs = self._parse_level_num(
                 *args,
                 levels=levels,
+                vmin=vmin,
+                vmax=vmax,
                 norm=norm,
                 norm_kw=norm_kw,
                 extend=extend,
@@ -4696,8 +4715,8 @@ class PlotAxes(base.Axes):
             levels = values = None
 
         # Determine default colorbar locator and norm and apply filters
-        # NOTE: DiscreteNorm does not currently support vmin and
-        # vmax different from level list minimum and maximum.
+        # NOTE: Preserve explicit vmin/vmax only for line contours, where levels
+        # represent contour values rather than filled bins.
         # NOTE: The level restriction should have no effect if levels were generated
         # automatically. However want to apply these to manual-input levels as well.
         if levels is not None:
@@ -4705,15 +4724,21 @@ class PlotAxes(base.Axes):
             if len(levels) == 0:  # skip
                 pass
             elif len(levels) == 1:  # use central colormap color
-                vmin, vmax = levels[0] - 1, levels[0] + 1
+                if not keep_explicit_line_limits or vmin is None:
+                    vmin = levels[0] - 1
+                if not keep_explicit_line_limits or vmax is None:
+                    vmax = levels[0] + 1
             else:  # use minimum and maximum
-                vmin, vmax = np.min(levels), np.max(levels)
+                if not keep_explicit_line_limits or vmin is None:
+                    vmin = np.min(levels)
+                if not keep_explicit_line_limits or vmax is None:
+                    vmax = np.max(levels)
                 if not np.allclose(levels[1] - levels[0], np.diff(levels)):
                     norm = _not_none(norm, "segmented")
             if norm in ("segments", "segmented"):
                 norm_kw["levels"] = levels
 
-        return levels, vmin, vmax, norm, norm_kw, kwargs
+        return levels, vmin, vmax, norm, norm_kw, explicit_limits, kwargs
 
     @staticmethod
     def _parse_level_norm(
@@ -4726,6 +4751,7 @@ class PlotAxes(base.Axes):
         discrete_ticks=None,
         discrete_labels=None,
         center_levels=None,
+        explicit_limits=False,
         **kwargs,
     ):
         """
@@ -4748,11 +4774,14 @@ class PlotAxes(base.Axes):
             The colorbar locations to tick.
         discrete_labels : array-like, optional
             The colorbar tick labels.
+        explicit_limits : bool, optional
+            Whether `vmin`/`vmax` were explicitly provided by the user.
 
         Returns
         -------
-        norm : `~ultraplot.colors.DiscreteNorm`
-            The discrete normalizer.
+        norm : `~ultraplot.colors.DiscreteNorm` or `~matplotlib.colors.Normalize`
+            The discrete normalizer, or the original continuous normalizer when
+            line contours have explicit limits or use qualitative color lists.
         cmap : `~matplotlib.colors.Colormap`
             The possibly-modified colormap.
         kwargs
@@ -4814,10 +4843,16 @@ class PlotAxes(base.Axes):
                 elif extend == "max":
                     unique = "neither"
 
-        # Generate DiscreteNorm and update "child" norm with vmin and vmax from
-        # levels. This lets the colorbar set tick locations properly!
+        # Generate DiscreteNorm for filled-contour style bins. For line contours
+        # with explicit limits or qualitative color lists, keep the continuous
+        # normalizer to preserve one-to-one value->color mapping.
         center_levels = _not_none(center_levels, rc["colorbar.center_levels"])
-        if not isinstance(norm, mcolors.BoundaryNorm) and len(levels) > 1:
+        preserve_line_mapping = min_levels == 1 and (explicit_limits or qualitative)
+        if (
+            not preserve_line_mapping
+            and not isinstance(norm, mcolors.BoundaryNorm)
+            and len(levels) > 1
+        ):
             norm = pcolors.DiscreteNorm(
                 levels,
                 norm=norm,

{ultraplot-2.1.0 → ultraplot-2.1.3}/ultraplot/axes/three.py

@@ -33,3 +33,11 @@ class ThreeAxes(shared._SharedAxes, base.Axes, Axes3D):
 
         kwargs.setdefault("alpha", 0.0)
         super().__init__(*args, **kwargs)
+
+    def graph(self, *args, **kwargs):
+        """
+        Draw network graphs on 3D projections.
+        """
+        from .plot import PlotAxes
+
+        return PlotAxes.graph(self, *args, **kwargs)

{ultraplot-2.1.0 → ultraplot-2.1.3}/ultraplot/colorbar.py

@@ -99,6 +99,8 @@ class UltraColorbar:
         linewidth: Optional[Union[float, str]] = None,
         edgefix: Optional[bool] = None,
         rasterized: Optional[bool] = None,
+        frame: Optional[bool] = None,
+        frameon: Optional[bool] = None,
         outline: Union[bool, None] = None,
         labelrotation: Optional[Union[str, float]] = None,
         center_levels: Optional[bool] = None,
@@ -160,7 +162,9 @@ class UltraColorbar:
         # Generate and prepare the colorbar axes
         # NOTE: The inset axes function needs 'label' to know how to pad the box
         # TODO: Use seperate keywords for frame properties vs. colorbar edge properties?
+        frame = _not_none(frame=frame, frameon=frameon)
         if loc in ("fill", "left", "right", "top", "bottom"):
+            outline = _not_none(outline=outline, frame=frame)
             length = _not_none(length, rc["colorbar.length"])  # for _add_guide_panel
             kwargs.update({"align": align, "length": length})
             extendsize = _not_none(extendsize, rc["colorbar.extend"])
@@ -183,6 +187,7 @@ class UltraColorbar:
             extendsize = _not_none(extendsize, rc["colorbar.insetextend"])
             cax, kwargs = ax._parse_colorbar_inset(
                 loc=loc,
+                frame=frame,
                 labelloc=labelloc,
                 labelrotation=labelrotation,
                 labelsize=labelsize,
@@ -347,7 +352,9 @@ class UltraColorbar:
             cax._inset_colorbar_obj = obj
             cax._inset_colorbar_labelloc = labelloc
             cax._inset_colorbar_ticklen = ticklen
-            _register_inset_colorbar_reflow(ax.figure)
+            has_frame = getattr(cax, "_inset_colorbar_frame", None) is not None
+            if has_frame:
+                _register_inset_colorbar_reflow(ax.figure)
         kw_outline = {"edgecolor": color, "linewidth": linewidth}
         if obj.outline is not None:
             obj.outline.update(kw_outline)
@@ -958,6 +965,7 @@ def _reflow_inset_colorbar_frame(
     *,
     labelloc: Optional[str],
     ticklen: float,
+    renderer=None,
 ):
     cax = colorbar.ax
     layout = getattr(cax, "_inset_colorbar_layout", None)
@@ -995,7 +1003,7 @@ def _reflow_inset_colorbar_frame(
         cb_width = width
         cb_height = length
 
-    renderer = cax.figure._get_renderer()
+    renderer = renderer or cax.figure._get_renderer()
     if hasattr(colorbar, "update_ticks"):
         colorbar.update_ticks(manual_only=True)
     bboxes = []

{ultraplot-2.1.0 → ultraplot-2.1.3}/ultraplot/gridspec.py

@@ -1988,9 +1988,11 @@ class SubplotGrid(MutableSequence, list):
         elif not isinstance(objs, list):
             objs = [objs]
 
+        # Spanning subplots can appear more than once in the sliced slot grid.
+        # De-duplicate while preserving order so method dispatch does not repeat.
+        objs = list(dict.fromkeys(objs))
         if len(objs) == 1:
             return objs[0]
-        objs = [obj for obj in objs if obj is not None]
         return SubplotGrid(objs)
 
     def __setitem__(self, key, value):

{ultraplot-2.1.0 → ultraplot-2.1.3}/ultraplot/internals/__init__.py

@@ -4,6 +4,7 @@ Internal utilities.
 """
 
 # Import statements
+import functools
 import inspect
 from importlib import import_module
 from numbers import Integral, Real
@@ -155,6 +156,40 @@ _alias_maps = {
     },
 }
 
+
+_INTERNAL_POP_PARAMS = frozenset(
+    {
+        "default_cmap",
+        "default_discrete",
+        "inbounds",
+        "plot_contours",
+        "plot_lines",
+        "skip_autolev",
+        "to_centers",
+    }
+)
+
+
+@functools.lru_cache(maxsize=256)
+def _signature_cached(func):
+    """
+    Cache inspect.signature lookups for hot utility paths.
+    """
+    return inspect.signature(func)
+
+
+def _get_signature(func):
+    """
+    Return a signature, normalizing bound methods to their underlying function.
+    """
+    key = getattr(func, "__func__", func)
+    try:
+        return _signature_cached(key)
+    except TypeError:
+        # Some callable objects may be unhashable for lru_cache keys.
+        return inspect.signature(func)
+
+
 _LAZY_ATTRS = {
     "benchmarks": ("benchmarks", None),
     "context": ("context", None),
@@ -224,28 +259,19 @@ def _pop_params(kwargs, *funcs, ignore_internal=False):
     """
     Pop parameters of the input functions or methods.
     """
-    internal_params = {
-        "default_cmap",
-        "default_discrete",
-        "inbounds",
-        "plot_contours",
-        "plot_lines",
-        "skip_autolev",
-        "to_centers",
-    }
     output = {}
     for func in funcs:
         if isinstance(func, inspect.Signature):
             sig = func
         elif callable(func):
-            sig = inspect.signature(func)
+            sig = _get_signature(func)
         elif func is None:
             continue
         else:
             raise RuntimeError(f"Internal error. Invalid function {func!r}.")
         for key in sig.parameters:
             value = kwargs.pop(key, None)
-            if ignore_internal and key in internal_params:
+            if ignore_internal and key in _INTERNAL_POP_PARAMS:
                 continue
             if value is not None:
                 output[key] = value