gsplot 0.4.0__tar.gz → 0.4.2__tar.gz

{gsplot-0.4.0 → gsplot-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gsplot
-Version: 0.4.0
+Version: 0.4.2
 Summary: Concise publication-quality scientific plotting built on Matplotlib
 License-Expression: MIT
 License-File: LICENSE

{gsplot-0.4.0 → gsplot-0.4.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "gsplot"
-version = "0.4.0"
+version = "0.4.2"
 description = "Concise publication-quality scientific plotting built on Matplotlib"
 authors = [
   { name = "Giordano Mattoni" },

{gsplot-0.4.0 → gsplot-0.4.2}/src/gsplot/__init__.py

@@ -7,7 +7,7 @@ configuration, logging, metadata-file, or backend initialization.
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, Callable
 
 from ._compat.root import canonical_names as _canonical_names
 from ._compat.root import legacy_names as _legacy_names
@@ -20,6 +20,8 @@ if TYPE_CHECKING:
     # Runtime lookup stays lazy.  Static analyzers see the canonical source
     # objects instead of an ``Any``-typed dynamic facade, so the shipped
     # ``py.typed`` marker provides useful signatures to downstream callers.
+    from matplotlib.legend import Legend as _Legend
+
     from ._compat.config import load_config
     from ._config.model import Config
     from ._core.errors import (
@@ -75,6 +77,7 @@ if TYPE_CHECKING:
         square,
         style_axes,
         suptitle,
+        ticks,
         title,
     )
     from ._style.legends import cmap_legend, legend, legend_entries, legends
@@ -114,7 +117,7 @@ if TYPE_CHECKING:
     legend_handlers: Any
     legend_reverse: Any
     legend_get_handlers: Any
-    legend_colormap: Any
+    legend_colormap: Callable[..., _Legend]
     ticks_off: Any
     ticks_on: Any
     ticks_on_axes: Any
@@ -139,6 +142,7 @@ __all__ = [
     "title",
     "suptitle",
     "minor_ticks",
+    "ticks",
     "box_aspect",
     "panel_labels",
     "index",

{gsplot-0.4.0 → gsplot-0.4.2}/src/gsplot/__init__.pyi

@@ -1,6 +1,8 @@
 from __future__ import annotations
 
-from typing import Any
+from typing import Any, Callable
+
+from matplotlib.legend import Legend as _Legend
 
 from ._compat.config import load_config as load_config
 from ._config.model import Config as Config
@@ -60,6 +62,7 @@ from ._style.axes import minor_ticks as minor_ticks
 from ._style.axes import square as square
 from ._style.axes import style_axes as style_axes
 from ._style.axes import suptitle as suptitle
+from ._style.axes import ticks as ticks
 from ._style.axes import title as title
 from ._style.legends import cmap_legend as cmap_legend
 from ._style.legends import legend as legend
@@ -104,7 +107,7 @@ legend_axes: Any
 legend_handlers: Any
 legend_reverse: Any
 legend_get_handlers: Any
-legend_colormap: Any
+legend_colormap: Callable[..., _Legend]
 ticks_off: Any
 ticks_on: Any
 ticks_on_axes: Any
@@ -129,6 +132,7 @@ __all__ = [
     "title",
     "suptitle",
     "minor_ticks",
+    "ticks",
     "box_aspect",
     "panel_labels",
     "index",

{gsplot-0.4.0 → gsplot-0.4.2}/src/gsplot/_compat/legacy_api.py

@@ -20,7 +20,9 @@ from typing import Any, Literal, cast
 import numpy as np
 from matplotlib import ticker
 from matplotlib.axes import Axes
+from matplotlib.axes._base import _AxesBase
 from matplotlib.figure import Figure
+from matplotlib.legend import Legend
 from mpl_toolkits.axes_grid1.inset_locator import inset_axes as _mpl_inset_axes
 from numpy.typing import ArrayLike, NDArray
 
@@ -41,7 +43,7 @@ from .._style.axes import box_aspect as _box_aspect
 from .._style.axes import minor_ticks as _minor_ticks
 from .._style.axes import style_axes as _style_axes
 from .._style.axes import title as _title
-from .._style.legends import cmap_legend as _cmap_legend
+from .._style.legends import _create_cmap_legend, _legacy_colormap_values
 from .._style.legends import legend as _legend
 from .._style.legends import legend_entries as _legend_entries
 from .._style.legends import legends as _legends
@@ -310,16 +312,21 @@ def _legacy_limits(
     if value is None:
         return None, "linear", None, None
     if isinstance(value, (str, bytes)):
+        if value in ("", "*"):
+            return None, "linear", None, None
         raise LayoutError("legacy limits must be a finite sequence")
     values = tuple(value)
     if len(values) < 2:
         raise LayoutError("legacy limits must contain two values")
-    try:
-        limits = (float(values[0]), float(values[1]))
-    except (TypeError, ValueError) as exc:
-        raise LayoutError("legacy limits must contain finite values") from exc
-    if not np.all(np.isfinite(limits)) or limits[0] == limits[1]:
-        raise LayoutError("legacy limits must contain finite unequal values")
+    if values[0] in (None, "", "*") and values[1] in (None, "", "*"):
+        limits = None
+    else:
+        try:
+            limits = (float(cast(Any, values[0])), float(cast(Any, values[1])))
+        except (TypeError, ValueError) as exc:
+            raise LayoutError("legacy limits must contain finite values") from exc
+        if not np.all(np.isfinite(limits)) or limits[0] == limits[1]:
+            raise LayoutError("legacy limits must contain finite unequal values")
     scale = values[2] if len(values) > 2 and isinstance(values[2], str) else "linear"
     if scale not in {"linear", "log", "symlog", "logit"}:
         raise LayoutError(f"unsupported legacy scale: {scale!r}")
@@ -820,40 +827,69 @@ def legend_colormap(
     vmax: float = 1,
     reverse: bool = False,
     **props: Any,
-) -> Any:
-    """Adapt legacy colormap legends to :func:`gsplot.cmap_legend`."""
+) -> Legend:
+    """Create a v0.2-compatible horizontal gradient Legend.
+
+    Parameters
+    ----------
+    ax
+        Explicit target Axes.
+    cmap
+        Non-empty registered Matplotlib colormap name.
+    label
+        Optional gradient label. ``None`` returns an empty Legend.
+    num_stripes
+        Positive requested stripe count; values above 256 are clamped.
+    vmin, vmax
+        Finite raw values passed directly to the colormap through
+        ``linspace(vmin, vmax, N_effective)``. Equal and descending bounds are
+        valid and retain their sampled order.
+    reverse
+        Reverse the final sampled RGBA sequence from left to right.
+    **props
+        Finite Matplotlib Legend properties. If omitted, Matplotlib's
+        call-time rcParams provide the defaults.
+
+    Notes
+    -----
+    This deprecated adapter always replaces an existing Legend because the
+    historical function has no ``replace`` keyword. Its rendering helper is
+    shared with :func:`gsplot.cmap_legend`, but its raw ``vmin``/``vmax``
+    sampling is deliberately not translated to canonical ``norm`` semantics.
+    """
 
     _warn("legend_colormap", "cmap_legend")
-    return _cmap_legend(
+    colors = _legacy_colormap_values(cmap, num_stripes, vmin, vmax, reverse)
+    return _create_cmap_legend(
         ax,
-        cmap=cmap,
-        label=label,
-        stripes=num_stripes,
-        norm=(vmin, vmax),
-        reverse=reverse,
-        props=props or None,
+        colors,
+        label,
+        replace=True,
+        props=None,
+        kwargs=props,
+        ambient=True,
     )
 
 
-def ticks_off(ax: Axes, mode: str = "xy") -> None:
+def ticks_off(ax: Axes | _AxesBase, mode: str = "xy") -> None:
     """Adapt legacy minor-tick disabling to the canonical selector."""
 
     _warn("ticks_off", "minor_ticks")
     selected = {"xy": "both"}.get(mode, mode)
     _minor_ticks(
-        ax,
+        cast(Any, ax),
         False,
         axis=cast(Literal["x", "y", "both"], selected),
     )
 
 
-def ticks_on(ax: Axes, mode: str = "xy") -> None:
+def ticks_on(ax: Axes | _AxesBase, mode: str = "xy") -> None:
     """Adapt legacy minor-tick enabling to the canonical selector."""
 
     _warn("ticks_on", "minor_ticks")
     selected = {"xy": "both"}.get(mode, mode)
     _minor_ticks(
-        ax,
+        cast(Any, ax),
         True,
         axis=cast(Literal["x", "y", "both"], selected),
     )

{gsplot-0.4.0 → gsplot-0.4.2}/src/gsplot/_compat/root.py

@@ -86,6 +86,7 @@ _CANONICAL_EXPORTS: Final[dict[str, tuple[str, str]]] = {
     "title": ("gsplot._compat.root_api", "title"),
     "suptitle": ("gsplot._style.axes", "suptitle"),
     "minor_ticks": ("gsplot._style.axes", "minor_ticks"),
+    "ticks": ("gsplot._style.axes", "ticks"),
     "box_aspect": ("gsplot._style.axes", "box_aspect"),
     "panel_labels": ("gsplot._style.panels", "panel_labels"),
     "index": ("gsplot._style.panels", "index"),

{gsplot-0.4.0 → gsplot-0.4.2}/src/gsplot/_compat/root_api.py

@@ -15,6 +15,7 @@ from typing import Any, get_type_hints
 from weakref import WeakKeyDictionary
 
 from matplotlib.axes import Axes
+from matplotlib.axes._base import _AxesBase
 from matplotlib.figure import Figure
 from numpy.typing import ArrayLike
 
@@ -32,7 +33,7 @@ from .._style.legends import legend as _legend
 from .._style.paper import PAPER_CYCLE_RGBA as _LEGACY_COLORS
 
 _UNSET = object()
-_LEGACY_PLOT_COUNTS: WeakKeyDictionary[Axes, int] = WeakKeyDictionary()
+_LEGACY_PLOT_COUNTS: WeakKeyDictionary[Axes | _AxesBase, int] = WeakKeyDictionary()
 
 _LEGACY_LEGEND_KEYS = {
     "handlers",
@@ -389,7 +390,7 @@ def scatter(
 def _legacy_label_records(value: Any) -> tuple[Any, ...] | None:
     """Recognize non-empty historical records without reading pyplot state."""
 
-    if isinstance(value, (str, bytes, Mapping, Axes)):
+    if isinstance(value, (str, bytes, Mapping, Axes, _AxesBase)):
         return None
     try:
         records = tuple(value)
@@ -430,6 +431,14 @@ def label(
     pad: Any = _UNSET,
     xpad: Any = _UNSET,
     ypad: Any = _UNSET,
+    margin: Any = _UNSET,
+    xmargin: Any = _UNSET,
+    ymargin: Any = _UNSET,
+    top: Any = _UNSET,
+    bottom: Any = _UNSET,
+    left: Any = _UNSET,
+    right: Any = _UNSET,
+    direction: Any = _UNSET,
     square: Any = _UNSET,
     index: Any = _UNSET,
     lab_lims: Any = _UNSET,
@@ -464,6 +473,7 @@ def label(
     fontdict: Any = _UNSET,
     labelpad: Any = _UNSET,
     loc: Any = _UNSET,
+    props: Any = _UNSET,
 ) -> Any:
     """Dispatch explicit concise labels or historical current-Figure records."""
 
@@ -479,6 +489,34 @@ def label(
         records = _legacy_label_records(target)
     else:
         records = None
+        text_props = {
+            name: value
+            for name, value in (
+                ("alpha", alpha),
+                ("color", color),
+                ("fontfamily", fontfamily),
+                ("fontproperties", fontproperties),
+                ("fontsize", fontsize),
+                ("fontstretch", fontstretch),
+                ("fontstyle", fontstyle),
+                ("fontvariant", fontvariant),
+                ("fontweight", fontweight),
+                ("ha", ha),
+                ("horizontalalignment", horizontalalignment),
+                ("label", label),
+                ("linespacing", linespacing),
+                ("math_fontfamily", math_fontfamily),
+                ("multialignment", multialignment),
+                ("parse_math", parse_math),
+                ("rotation", rotation),
+                ("rotation_mode", rotation_mode),
+                ("va", va),
+                ("verticalalignment", verticalalignment),
+                ("visible", visible),
+                ("zorder", zorder),
+            )
+            if value is not _UNSET
+        }
         legacy_controls = _provided(
             {
                 "legacy_xpad_layout": legacy_xpad_layout,
@@ -489,28 +527,6 @@ def label(
                 "tight_layout": tight_layout,
                 "xpad_layout": xpad_layout,
                 "ypad_layout": ypad_layout,
-                "alpha": alpha,
-                "color": color,
-                "fontfamily": fontfamily,
-                "fontproperties": fontproperties,
-                "fontsize": fontsize,
-                "fontstretch": fontstretch,
-                "fontstyle": fontstyle,
-                "fontvariant": fontvariant,
-                "fontweight": fontweight,
-                "ha": ha,
-                "horizontalalignment": horizontalalignment,
-                "label": label,
-                "linespacing": linespacing,
-                "math_fontfamily": math_fontfamily,
-                "multialignment": multialignment,
-                "parse_math": parse_math,
-                "rotation": rotation,
-                "rotation_mode": rotation_mode,
-                "va": va,
-                "verticalalignment": verticalalignment,
-                "visible": visible,
-                "zorder": zorder,
                 "fontdict": fontdict,
                 "labelpad": labelpad,
                 "loc": loc,
@@ -536,10 +552,22 @@ def label(
                 "pad": pad,
                 "xpad": xpad,
                 "ypad": ypad,
+                "margin": margin,
+                "xmargin": xmargin,
+                "ymargin": ymargin,
+                "top": top,
+                "bottom": bottom,
+                "left": left,
+                "right": right,
+                "direction": direction,
                 "square": square,
                 "index": index,
             }
         )
+        if props is not _UNSET:
+            canonical["props"] = props
+        elif text_props:
+            canonical["props"] = text_props
         return _label(target, **canonical)
 
     if records is None:
@@ -559,6 +587,14 @@ def label(
             "pad": pad,
             "xpad": xpad,
             "ypad": ypad,
+            "margin": margin,
+            "xmargin": xmargin,
+            "ymargin": ymargin,
+            "top": top,
+            "bottom": bottom,
+            "left": left,
+            "right": right,
+            "direction": direction,
             "square": square,
             "index": index,
         }
@@ -677,11 +713,41 @@ def legend(
 ) -> Any:
     """Dispatch canonical ``legend`` or finite legacy options."""
 
-    legacy = _provided(
+    is_legacy = (
+        legacy_handles is not _UNSET
+        or legacy_labels is not _UNSET
+        or handlers is not _UNSET
+        or ncol is not _UNSET
+    )
+    if is_legacy:
+        if (legacy_handles is not _UNSET or legacy_labels is not _UNSET) and (
+            handles is not None or labels is not None
+        ):
+            raise OptionError("legend cannot combine positional and canonical entries")
+        if handlers is not _UNSET:
+            if handler_map is not None:
+                raise OptionError("legend cannot combine handlers and handler_map")
+            handler_map = handlers
+        if ncol is not _UNSET:
+            if ncols is not _UNSET:
+                raise OptionError(
+                    "legend: props cannot contain both 'ncol' and 'ncols'"
+                )
+            ncols = ncol
+        if legacy_handles is not _UNSET:
+            handles = legacy_handles
+        if legacy_labels is not _UNSET:
+            labels = legacy_labels
+        _warn("legend")
+
+    direct = _provided(
         {
-            "handlers": handlers,
+            "loc": loc,
+            "frameon": frameon,
+            "fancybox": fancybox,
+            "labelspacing": labelspacing,
+            "handlelength": handlelength,
             "ncols": ncols,
-            "ncol": ncol,
             "fontsize": fontsize,
             "title": title,
             "title_fontsize": title_fontsize,
@@ -702,59 +768,6 @@ def legend(
             "labelcolor": labelcolor,
         }
     )
-    if legacy_handles is not _UNSET:
-        legacy["_legacy_handles"] = legacy_handles
-    if legacy_labels is not _UNSET:
-        legacy["_legacy_labels"] = legacy_labels
-    if (legacy_handles is not _UNSET or legacy_labels is not _UNSET) and (
-        handles is not None or labels is not None
-    ):
-        raise OptionError("legend cannot combine positional and canonical entries")
-    if legacy and props is not None:
-        raise OptionError(
-            "gsplot.legend cannot combine canonical props with legacy options"
-        )
-    direct = _provided(
-        {
-            "loc": loc,
-            "frameon": frameon,
-            "fancybox": fancybox,
-            "labelspacing": labelspacing,
-            "handlelength": handlelength,
-        }
-    )
-    if not legacy:
-        return _legend(
-            target,
-            handles=handles,
-            labels=labels,
-            handler_map=handler_map,
-            reverse=reverse,
-            replace=replace,
-            props=props,
-            **direct,
-        )
-    positional_handles = legacy.pop("_legacy_handles", _UNSET)
-    positional_labels = legacy.pop("_legacy_labels", _UNSET)
-    if handlers is not _UNSET:
-        if handler_map is not None:
-            raise OptionError("legend cannot combine handlers and handler_map")
-        handler_map = handlers
-        legacy.pop("handlers", None)
-    translated = _translate_props(
-        "legend",
-        legacy,
-        {"ncol": "ncols"},
-    )
-    if positional_handles is not _UNSET:
-        if handles is not None:
-            raise OptionError("legend received handles twice")
-        handles = positional_handles
-    if positional_labels is not _UNSET:
-        if labels is not None:
-            raise OptionError("legend received labels twice")
-        labels = positional_labels
-    _warn("legend")
     return _legend(
         target,
         handles=handles,
@@ -762,7 +775,7 @@ def legend(
         handler_map=handler_map,
         reverse=reverse,
         replace=replace,
-        props=translated,
+        props=props,
         **direct,
     )
 
@@ -834,10 +847,10 @@ def title(
             "y": y,
         }
     )
-    if isinstance(ax, Axes):
-        if text is _UNSET or title is not _UNSET or legacy:
-            raise OptionError("canonical title requires text and props")
-        return _title(ax, text, props=props)
+    if isinstance(ax, (Axes, _AxesBase)):
+        if text is _UNSET or title is not _UNSET:
+            raise OptionError("canonical title requires an explicit text value")
+        return _title(ax, text, props=props, **legacy)
     if text is not _UNSET:
         raise TypeError("legacy Figure title accepts one text value")
     if title is not _UNSET:

{gsplot-0.4.0 → gsplot-0.4.2}/src/gsplot/_core/plans.py

@@ -7,6 +7,7 @@ from dataclasses import dataclass
 from typing import Any, Generic, Literal, TypeVar
 
 from matplotlib.axes import Axes
+from matplotlib.axes._base import _AxesBase
 from matplotlib.figure import Figure
 
 from .errors import PlotError
@@ -24,7 +25,7 @@ def _operation_name(value: str) -> str:
     return value
 
 
-def _axis_root_figure(axis: Axes) -> Figure | None:
+def _axis_root_figure(axis: Any) -> Figure | None:
     """Return an Axes root Figure without requiring ``root=True`` support."""
 
     owner: Any = axis.get_figure()
@@ -47,7 +48,7 @@ class TargetPlan:
 
     operation: str
     figure: Figure
-    axes: tuple[Axes, ...]
+    axes: tuple[Axes | _AxesBase, ...]
     keys: tuple[object, ...]
     kind: TargetKind
 
@@ -61,7 +62,7 @@ class TargetPlan:
             raise PlotError(f"{self.operation}: target plan is empty or incomplete")
         if self.kind not in {"single", "sequence", "array", "mapping"}:
             raise PlotError(f"{self.operation}: target kind is invalid")
-        if any(not isinstance(axis, Axes) for axis in self.axes):
+        if any(not isinstance(axis, (Axes, _AxesBase)) for axis in self.axes):
             raise PlotError(f"{self.operation}: target contains a non-Axes value")
         if len({id(axis) for axis in self.axes}) != len(self.axes):
             raise PlotError(f"{self.operation}: target contains a duplicate Axes")

{gsplot-0.4.0 → gsplot-0.4.2}/src/gsplot/_core/targets.py

@@ -7,6 +7,7 @@ from typing import Any, TypeVar
 
 import numpy as np
 from matplotlib.axes import Axes
+from matplotlib.axes._base import _AxesBase
 from matplotlib.figure import Figure
 
 from .errors import PlotError
@@ -16,7 +17,7 @@ from .types import AxesTarget
 T = TypeVar("T")
 
 
-def _root_figure(axis: Axes, operation: str) -> Figure:
+def _root_figure(axis: Axes | _AxesBase, operation: str) -> Figure:
     """Resolve an Axes root Figure without version-specific root arguments."""
 
     owner = _axis_root_figure(axis)
@@ -30,7 +31,7 @@ def _snapshot_target(
 ) -> tuple[TargetKind, tuple[object, ...], tuple[Any, ...]]:
     """Snapshot one supported target shape without retaining its container."""
 
-    if isinstance(target, Axes):
+    if isinstance(target, (Axes, _AxesBase)):
         return "single", (target,), (target,)
     if isinstance(target, Mapping):
         items = tuple(target.items())
@@ -67,7 +68,7 @@ def normalize_axes(target: AxesTarget, *, operation: str) -> TargetPlan:
     kind, keys, values = _snapshot_target(target, operation)
     if not values:
         raise PlotError(f"{operation}: target must contain at least one Axes")
-    if any(not isinstance(value, Axes) for value in values):
+    if any(not isinstance(value, (Axes, _AxesBase)) for value in values):
         raise PlotError(f"{operation}: target contains a non-Axes value")
     axes = tuple(values)
     if len({id(axis) for axis in axes}) != len(axes):