gsplot 0.4.1__tar.gz → 0.4.2__tar.gz

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

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

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

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

{gsplot-0.4.1 → 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 (
@@ -115,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

{gsplot-0.4.1 → 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
@@ -105,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

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

@@ -22,6 +22,7 @@ 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
 
@@ -42,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
@@ -826,18 +827,47 @@ 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,
     )
 
 

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

@@ -473,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."""
 
@@ -488,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,
@@ -498,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,
@@ -557,6 +564,10 @@ def label(
                 "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:

{gsplot-0.4.1 → gsplot-0.4.2}/src/gsplot/_core/types.py

@@ -63,6 +63,8 @@ TickSpec: TypeAlias = Sequence[float]
 LabelRecord: TypeAlias = tuple[str, str] | tuple[str, str, Any, Any] | Sequence[Any]
 # Public type alias: LabelRecords; ordered or exact-key per-target label records.
 LabelRecords: TypeAlias = Sequence[LabelRecord] | Mapping[Any, LabelRecord]
+# Public type alias: TextProps; closed Matplotlib Text property mapping.
+TextProps: TypeAlias = Mapping[str, Any]
 
 _PUBLIC_TYPE_ALIAS_DOCS = MappingProxyType(
     {
@@ -910,6 +912,16 @@ class AxesDict(dict[str, Axes]):
     *args, **kwargs
         Dictionary initialization mapping label strings to Matplotlib Axes.
 
+    Notes
+    -----
+    Mosaic containers iterate in panel-name (alphabetical) order rather than
+    Matplotlib ``subplot_mosaic`` insertion order. ``"ACE;BDE"`` therefore
+    iterates as ``('A', 'B', 'C', 'D', 'E')`` even though ``C`` and ``E``
+    appear before ``B`` and ``D`` in the specification. Iteration, integer
+    indexes, slices, and positional value sequences all follow this order, so
+    generated panel indexes and positional label records land on the matching
+    panel letters, while keyed access such as ``axes["B"]`` is always exact.
+
     Examples
     --------
     >>> import gsplot as gs
@@ -919,6 +931,15 @@ class AxesDict(dict[str, Axes]):
     >>> axes["A"] is axes[0]
     True
     >>> figure.clear()
+
+    Non-alphabetical mosaics still iterate in panel-name order:
+
+    >>> figure, axes = gs.subplots("ACE;BDE")
+    >>> tuple(axes)
+    ('A', 'B', 'C', 'D', 'E')
+    >>> axes[1] is axes["B"]
+    True
+    >>> figure.clear()
     """
 
     @overload

gsplot-0.4.2/src/gsplot/_figure/fit.py

@@ -0,0 +1,365 @@
+"""Figure-local fitting for independent gsplot text annotations."""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Iterable
+from dataclasses import dataclass, field, replace
+from typing import Any, cast
+
+from matplotlib.backend_bases import RendererBase
+from matplotlib.figure import Figure
+from matplotlib.text import Annotation, Text
+from matplotlib.transforms import Bbox, ScaledTranslation, Transform
+
+from .._core.errors import LayoutError
+
+_FIGURE_FIT_STATE = "_gsplot_figure_fit_state"
+_MAX_FIT_PASSES = 4
+_DISPLAY_EPSILON = 1e-6
+
+
+@dataclass(slots=True)
+class _AnnotationRecord:
+    """Base and last-applied placement for one registered annotation."""
+
+    annotation_points: bool
+    base_transform: Transform | None = None
+    base_position: tuple[float, float] | None = None
+    applied_transform: Transform | None = None
+    applied_position: tuple[float, float] | None = None
+
+
+@dataclass(slots=True)
+class _FigureFitState:
+    """Mutable annotation registry owned by one Figure."""
+
+    annotations: dict[Text, _AnnotationRecord] = field(default_factory=dict)
+
+
+def configure_figure_fit(
+    figure: Figure,
+    enabled: bool,
+    *,
+    reset: bool = False,
+) -> None:
+    """Configure one Figure's independent-text fitting policy."""
+
+    if not enabled:
+        setattr(figure, _FIGURE_FIT_STATE, None)
+        return
+    state = None if reset else getattr(figure, _FIGURE_FIT_STATE, None)
+    if not isinstance(state, _FigureFitState):
+        state = _FigureFitState()
+    setattr(figure, _FIGURE_FIT_STATE, state)
+
+
+def _figure_fit_state(figure: Figure) -> _FigureFitState | None:
+    """Return the Figure-local fitting state when the policy is enabled."""
+
+    state = getattr(figure, _FIGURE_FIT_STATE, None)
+    return state if isinstance(state, _FigureFitState) else None
+
+
+def _get_figure_renderer(figure: Figure) -> RendererBase:
+    """Return the renderer for a Figure across Matplotlib backends."""
+
+    try:
+        return cast(RendererBase, cast(Any, figure)._get_renderer())
+    except Exception as exc:
+        raise LayoutError("could not determine the rendered Figure renderer") from exc
+
+
+def _current_position(text: Text) -> tuple[float, float]:
+    """Return a Text position as a finite two-dimensional tuple."""
+
+    raw_position = tuple(text.get_position())
+    if len(raw_position) != 2:
+        raise LayoutError("figure_fit: annotation position is not two-dimensional")
+    position = (float(raw_position[0]), float(raw_position[1]))
+    if not all(math.isfinite(value) for value in position):
+        raise LayoutError("figure_fit: annotation position is not finite")
+    return position
+
+
+def _capture_record(
+    text: Text,
+    annotation_points: bool,
+    previous: _AnnotationRecord | None,
+) -> _AnnotationRecord:
+    """Capture caller placement while avoiding a previous fit translation."""
+
+    if annotation_points:
+        position = _current_position(text)
+        if (
+            previous is not None
+            and previous.annotation_points
+            and previous.applied_position is not None
+            and position == previous.applied_position
+        ):
+            position = previous.base_position or position
+        return _AnnotationRecord(
+            annotation_points=True,
+            base_position=position,
+            applied_position=position,
+        )
+
+    transform = cast(Transform, text.get_transform())
+    if (
+        previous is not None
+        and not previous.annotation_points
+        and previous.applied_transform is transform
+    ):
+        transform = previous.base_transform or transform
+    return _AnnotationRecord(
+        annotation_points=False,
+        base_transform=transform,
+        applied_transform=transform,
+    )
+
+
+def _capture_location(
+    text: Text,
+    annotation_points: bool,
+) -> Transform | tuple[float, float]:
+    """Capture an artist's current position for transactional rollback."""
+
+    return (
+        _current_position(text)
+        if annotation_points
+        else cast(Transform, text.get_transform())
+    )
+
+
+def _restore_location(
+    text: Text,
+    annotation_points: bool,
+    location: Transform | tuple[float, float],
+) -> None:
+    """Restore an artist's exact transform or point position."""
+
+    if annotation_points:
+        cast(Annotation, text).set_position(cast(tuple[float, float], location))
+    else:
+        text.set_transform(cast(Transform, location))
+
+
+def register_figure_annotations(
+    figure: Figure,
+    annotations: Iterable[tuple[Text, bool]],
+) -> None:
+    """Register independent annotations and fit the complete Figure set."""
+
+    state = _figure_fit_state(figure)
+    if state is None:
+        return
+    items = tuple(annotations)
+    previous_annotations = {
+        text: replace(record) for text, record in state.annotations.items()
+    }
+    previous_locations: dict[Text, tuple[bool, Transform | tuple[float, float]]] = {
+        text: (
+            record.annotation_points,
+            _capture_location(text, record.annotation_points),
+        )
+        for text, record in previous_annotations.items()
+        if text.figure is figure
+    }
+    for text, annotation_points in items:
+        if text.figure is figure and text not in previous_locations:
+            previous_locations[text] = (
+                annotation_points,
+                _capture_location(text, annotation_points),
+            )
+    try:
+        for text, annotation_points in items:
+            if text.figure is figure:
+                state.annotations[text] = _capture_record(
+                    text,
+                    annotation_points,
+                    previous_annotations.get(text),
+                )
+        fit_figure_annotations(figure)
+    except Exception:
+        state.annotations.clear()
+        state.annotations.update(previous_annotations)
+        for text, (annotation_points, location) in previous_locations.items():
+            _restore_location(text, annotation_points, location)
+        raise
+
+
+def _live_annotations(figure: Figure) -> tuple[tuple[Text, _AnnotationRecord], ...]:
+    """Return visible registered annotations still attached to one Figure."""
+
+    state = _figure_fit_state(figure)
+    if state is None:
+        return ()
+    live: list[tuple[Text, _AnnotationRecord]] = []
+    stale: list[Text] = []
+    for text, record in state.annotations.items():
+        if text.figure is not figure:
+            stale.append(text)
+        elif text.get_visible():
+            live.append((text, record))
+    for text in stale:
+        del state.annotations[text]
+    return tuple(live)
+
+
+def _reset_annotation(text: Text, record: _AnnotationRecord) -> None:
+    """Remove a previous fit translation while preserving the caller's base."""
+
+    if record.annotation_points:
+        if record.base_position is None:
+            raise LayoutError("figure_fit: annotation has no base position")
+        cast(Annotation, text).set_position(record.base_position)
+        record.applied_position = record.base_position
+        return
+
+    if record.base_transform is None:
+        raise LayoutError("figure_fit: annotation has no base transform")
+    text.set_transform(record.base_transform)
+    record.applied_transform = record.base_transform
+
+
+def _annotation_box(text: Text, renderer: Any) -> Any:
+    """Return one finite rendered text box or raise a layout error."""
+
+    try:
+        boxes = [text.get_window_extent(renderer)]
+        patch = text.get_bbox_patch()
+        if patch is not None and patch.get_visible():
+            boxes.append(patch.get_window_extent(renderer))
+        box = Bbox.union(boxes)
+    except Exception as exc:
+        raise LayoutError("figure_fit: could not measure an annotation") from exc
+    values = (box.x0, box.y0, box.x1, box.y1)
+    if not all(math.isfinite(float(value)) for value in values):
+        raise LayoutError("figure_fit: annotation bounds are not finite")
+    return box
+
+
+def _required_shift(
+    lower: float,
+    upper: float,
+    box_lower: float,
+    box_upper: float,
+    *,
+    dimension: str,
+) -> float:
+    """Return the smallest display-space shift that enters one Figure edge."""
+
+    if box_upper - box_lower > upper - lower + _DISPLAY_EPSILON:
+        raise LayoutError(
+            f"figure_fit: annotation does not fit within the Figure {dimension}"
+        )
+    if box_lower < lower:
+        return lower - box_lower
+    if box_upper > upper:
+        return upper - box_upper
+    return 0.0
+
+
+def _shift_for(
+    figure: Figure,
+    text: Text,
+    renderer: Any,
+    *,
+    record: _AnnotationRecord,
+) -> tuple[float, float]:
+    """Measure one base-position annotation and apply its minimum correction."""
+
+    box = _annotation_box(text, renderer)
+    figure_box = figure.bbox
+    dx = _required_shift(
+        figure_box.x0,
+        figure_box.x1,
+        box.x0,
+        box.x1,
+        dimension="width",
+    )
+    dy = _required_shift(
+        figure_box.y0,
+        figure_box.y1,
+        box.y0,
+        box.y1,
+        dimension="height",
+    )
+    if dx == 0.0 and dy == 0.0:
+        return dx, dy
+
+    if record.annotation_points:
+        if record.base_position is None:
+            raise LayoutError("figure_fit: annotation has no base position")
+        position = record.base_position
+        points_per_display_unit = 72.0 / float(figure.dpi)
+        applied_position = (
+            float(position[0]) + dx * points_per_display_unit,
+            float(position[1]) + dy * points_per_display_unit,
+        )
+        cast(Annotation, text).set_position(applied_position)
+        record.applied_position = applied_position
+    else:
+        if record.base_transform is None:
+            raise LayoutError("figure_fit: annotation has no base transform")
+        record.applied_transform = record.base_transform + ScaledTranslation(
+            dx / float(figure.dpi),
+            dy / float(figure.dpi),
+            figure.dpi_scale_trans,
+        )
+        text.set_transform(record.applied_transform)
+    return dx, dy
+
+
+def fit_figure_annotations(figure: Figure) -> None:
+    """Keep registered independent annotations inside a fixed Figure canvas."""
+
+    annotations = _live_annotations(figure)
+    if not annotations:
+        return
+    canvas = cast(Any, figure.canvas)
+    for _ in range(_MAX_FIT_PASSES):
+        for text, record in annotations:
+            _reset_annotation(text, record)
+        try:
+            canvas.draw()
+            renderer = _get_figure_renderer(figure)
+        except Exception as exc:
+            raise LayoutError("figure_fit: could not render the Figure") from exc
+
+        moved = False
+        for text, record in annotations:
+            dx, dy = _shift_for(
+                figure,
+                text,
+                renderer,
+                record=record,
+            )
+            moved = moved or dx != 0.0 or dy != 0.0
+        if not moved:
+            return
+
+    try:
+        canvas.draw()
+        renderer = _get_figure_renderer(figure)
+    except Exception as exc:
+        raise LayoutError("figure_fit: could not render the Figure") from exc
+    for text, _ in annotations:
+        box = _annotation_box(text, renderer)
+        figure_box = figure.bbox
+        if (
+            box.x0 < figure_box.x0 - _DISPLAY_EPSILON
+            or box.y0 < figure_box.y0 - _DISPLAY_EPSILON
+            or box.x1 > figure_box.x1 + _DISPLAY_EPSILON
+            or box.y1 > figure_box.y1 + _DISPLAY_EPSILON
+        ):
+            raise LayoutError(
+                "figure_fit: annotations could not be placed inside the Figure"
+            )
+
+
+__all__ = [
+    "configure_figure_fit",
+    "fit_figure_annotations",
+    "register_figure_annotations",
+]