tesorotools-python 0.1.7__tar.gz → 0.1.9__tar.gz

{tesorotools_python-0.1.7 → tesorotools_python-0.1.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tesorotools-python
-Version: 0.1.7
+Version: 0.1.9
 Requires-Python: >=3.13
 Requires-Dist: babel>=2.17
 Requires-Dist: matplotlib>=3.10

{tesorotools_python-0.1.7 → tesorotools_python-0.1.9}/src/tesorotools/artists/_common.py

@@ -47,9 +47,21 @@ from matplotlib.dates import (
 from matplotlib.figure import Figure
 from matplotlib.font_manager import FontProperties
 from matplotlib.legend import Legend as MplLegend
-from matplotlib.ticker import FixedLocator, FuncFormatter, MaxNLocator
+from matplotlib.text import Text
+from matplotlib.ticker import (
+    FixedFormatter,
+    FixedLocator,
+    FuncFormatter,
+    MaxNLocator,
+    NullFormatter,
+)
 from yaml.nodes import MappingNode
 
+from tesorotools.artists._dates import (
+    DateLayout,
+    date_layouts,
+    period_label,
+)
 from tesorotools.utils.matplotlib import (
     PLOT_CONFIG,
     apply_house_style,
@@ -110,6 +122,53 @@ def date_maxticks(density: str, *, compact: bool) -> int:
     return int(table.get(density, fallback[density]))
 
 
+# Most date labels an axis shows per date_density level, read from
+# ``compact.date_max_labels`` / ``line.date_max_labels`` in ``plots.yaml``:
+# the finest calendar step (every year, every month...) whose labels fit in
+# the axis width AND stay within this count wins.
+_DATE_MAX_LABELS_FALLBACK_COMPACT: dict[str, int] = {
+    "few": 4,
+    "default": 8,
+    "many": 14,
+}
+_DATE_MAX_LABELS_FALLBACK_LINE: dict[str, int] = {
+    "few": 6,
+    "default": 15,
+    "many": 30,
+}
+
+
+def date_max_labels(density: str, *, compact: bool) -> int:
+    """Most date labels a ``date_density`` level allows on the x-axis.
+
+    Reads ``compact.date_max_labels`` / ``line.date_max_labels`` from
+    ``plots.yaml``, falling back to the built-in table when the config
+    (or a level) is absent.
+    """
+    cfg = COMPACT_CONFIG if compact else LINE_CONFIG
+    fallback = (
+        _DATE_MAX_LABELS_FALLBACK_COMPACT
+        if compact
+        else _DATE_MAX_LABELS_FALLBACK_LINE
+    )
+    table: dict[str, Any] = cfg.get("date_max_labels", fallback)
+    return int(table.get(density, fallback[density]))
+
+
+def _date_axis_config(*, compact: bool) -> tuple[int, float, float]:
+    """Calendar date-axis knobs of a mode, from ``plots.yaml``.
+
+    ``(date_monthly_max_months, date_centered_min_fraction,
+    date_label_gap_em)``.
+    """
+    cfg = COMPACT_CONFIG if compact else LINE_CONFIG
+    return (
+        int(cfg.get("date_monthly_max_months", 24)),
+        float(cfg.get("date_centered_min_fraction", 0.5)),
+        float(cfg.get("date_label_gap_em", 0.3)),
+    )
+
+
 def dynamic_dpi(fig: Figure) -> int:
     """Save DPI adapted to the figure's physical size.
 
@@ -344,9 +403,18 @@ class Legend:
     values work in compact and in full-size charts, so a
     compact chart in a Word table can carry its labels under
     the plot when the text above it already reads as a title.
+    ``font_pt`` fixes the size of the legend text (a slide wants it
+    as big as the ticks) and ``min_entries=2`` drops the legend of a
+    chart with a single series.
     """
 
-    def __init__(self, ncol: int | None = None, position: str = "auto") -> None:
+    def __init__(
+        self,
+        ncol: int | None = None,
+        position: str = "auto",
+        font_pt: float | None = None,
+        min_entries: int = 1,
+    ) -> None:
         if position not in LEGEND_POSITIONS:
             raise ValueError(
                 f"legend position must be one of {LEGEND_POSITIONS}: "
@@ -354,6 +422,12 @@ class Legend:
             )
         self.ncol = ncol
         self.position = position
+        #: Size of the legend text (points); ``None`` keeps the house
+        #: size (``compact.legend_font_pt``, never above the ticks).
+        self.font_pt = font_pt
+        #: Fewer entries than this draw no legend: ``2`` leaves a chart
+        #: of a single series without one.
+        self.min_entries = min_entries
 
     @classmethod
     def from_yaml(cls, loader: TemplateLoader, node: MappingNode) -> Self:
@@ -804,6 +878,188 @@ def _date_label_ha(
     return "right" if rotation > 0 else "left"
 
 
+def _style_date_labels(ax: Axes, rot: float, *, minor: bool) -> None:
+    """Tilt the date labels *rot* degrees with the matching anchor.
+
+    Rotation goes in the axis tick kwargs; ``ha`` and the anchor rotation
+    mode are per-label Text properties, so they are reapplied after every
+    draw or locator swap.
+    """
+    ha = _date_label_ha(None if rot == 0 else rot)
+    ax.tick_params(  # type: ignore[reportUnknownMemberType]
+        axis="x", which="minor" if minor else "major", rotation=rot
+    )
+    for label in ax.get_xticklabels(minor=minor):
+        label.set_horizontalalignment(ha)
+        if rot != 0:
+            label.set_rotation_mode("anchor")
+
+
+def _layout_texts(layout: DateLayout, *, pin_start: bool) -> list[str]:
+    """The label texts of *layout*, as the axis will print them."""
+    if layout.centered:
+        # centred: each label names its period
+        return [
+            period_label(p, layout.step, first=i == 0)
+            for i, p in enumerate(layout.periods)
+        ]
+    values = [float(cast(Any, date2num(t))) for t in layout.ticks]
+    formatter = _tick_formatter(FixedLocator(values), values[0], pin_start)
+    return list(formatter.format_ticks(values))
+
+
+def _tick_formatter(
+    locator: FixedLocator, start: float, pin_start: bool
+) -> ConciseDateFormatter:
+    return (
+        _StartLabeledConcise(locator, start)
+        if pin_start
+        else ConciseDateFormatter(locator)
+    )
+
+
+def calendar_date_axis(
+    ax: Axes,
+    layouts: list[DateLayout],
+    *,
+    pin_start: bool,
+    rotation: float | None = None,
+    auto_rotate: bool = False,
+    gap_em: float = 0.3,
+) -> DateLayout:
+    """Label every year (or month) the axis can hold.
+
+    *layouts* are the candidate calendar steps, finest first (see
+    :func:`tesorotools.artists._dates.date_layouts`).  Each one's labels
+    are measured at their real size and position, and the first whose
+    labels do not overlap wins: a decade shows every year, thirty years
+    fall back to one every two or five.  When none fits, the coarsest is
+    used.  Returns the layout drawn.
+
+    With the start pinned, the first calendar tick gives way to the
+    (wider) start label when they collide and it lies under half a step
+    from the start: a series from October 2015 shows ``oct. 2015``,
+    2017, 2018...  Further away, dropping it would read as a skipped
+    year, so that step counts as not fitting.
+
+    Centred layouts (``date_labels: centered``) put the tick marks on the
+    period boundaries and the labels, as minor ticks without a mark, in
+    the middle of each period.
+
+    ``rotation`` tilts the labels.  ``auto_rotate`` (ignored when a
+    rotation is given) tries 0, 30, 45, 60 and 90 degrees and keeps the
+    flattest tilt that reaches the finest step any of them reaches.
+
+    Neighbouring labels must stay *gap_em* ems apart
+    (``date_label_gap_em`` in ``plots.yaml``).
+    """
+    fig = ax.get_figure()
+    assert fig is not None
+    # settle the layout so dates map to their final pixels
+    fig.canvas.draw()  # type: ignore[reportUnknownMemberType]
+    renderer = fig.canvas.get_renderer()  # type: ignore[reportUnknownMemberType]
+    font = ax.xaxis.get_major_ticks()[0].label1.get_fontproperties()
+    # a fixed share of an em between neighbouring labels, whatever the dpi
+    pad_px = (
+        float(
+            renderer.points_to_pixels(font.get_size_in_points())  # type: ignore[reportUnknownMemberType]
+        )
+        * gap_em
+    )
+
+    def _boxes(layout: DateLayout, rot: float) -> list[Any]:
+        texts = _layout_texts(layout, pin_start=pin_start)
+        ha = _date_label_ha(None if rot == 0 else rot)
+        boxes: list[Any] = []
+        for when, text in zip(layout.labels, texts):
+            x_px = float(
+                ax.transData.transform((float(cast(Any, date2num(when))), 0))[0]
+            )
+            probe = Text(
+                x_px,
+                0.0,
+                text,
+                fontproperties=font,
+                rotation=rot,
+                horizontalalignment=ha,
+                rotation_mode="anchor" if rot != 0 else "default",
+            )
+            probe.set_figure(fig)
+            boxes.append(probe.get_window_extent(renderer))  # type: ignore[reportUnknownArgumentType]
+        return boxes
+
+    def _fit(layout: DateLayout, rot: float) -> list[int] | None:
+        boxes = _boxes(layout, rot)
+        kept = list(range(len(boxes)))
+        centered = layout.centered
+        if pin_start and not centered and len(kept) > 2:
+            # the first calendar tick may give way to the (wider) start
+            # label only when it sits under half a step from the start:
+            # further away, dropping it would open a gap that reads as a
+            # skipped year, so the step does not fit instead
+            when = [float(cast(Any, date2num(t))) for t in layout.ticks]
+            near = when[1] - when[0] < (when[2] - when[1]) / 2
+            if near and boxes[1].x0 <= boxes[0].x1 + pad_px:
+                kept.pop(1)
+        clear = all(
+            boxes[b].x0 > boxes[a].x1 + pad_px for a, b in zip(kept, kept[1:])
+        )
+        return kept if clear else None
+
+    tilts = (
+        (0.0, 30.0, 45.0, 60.0, 90.0)
+        if auto_rotate and rotation is None
+        else (0.0 if rotation is None else float(rotation),)
+    )
+    best: tuple[int, float, list[int]] | None = None
+    for rot in tilts:
+        for i, layout in enumerate(layouts):
+            if best is not None and i >= best[0]:
+                break
+            kept = _fit(layout, rot)
+            if kept is not None:
+                best = (i, rot, kept)
+                break
+        if best is not None and best[0] == 0:
+            break
+    if best is None:
+        coarsest = layouts[-1]
+        best = (len(layouts) - 1, tilts[0], list(range(len(coarsest.labels))))
+    index, rot, kept = best
+    layout = layouts[index]
+    centered = layout.centered
+
+    if centered:
+        major = FixedLocator(
+            [float(cast(Any, date2num(t))) for t in layout.ticks]
+        )
+        ax.xaxis.set_major_locator(major)
+        ax.xaxis.set_major_formatter(NullFormatter())
+        texts = _layout_texts(layout, pin_start=pin_start)
+        ax.xaxis.set_minor_locator(
+            FixedLocator(
+                [float(cast(Any, date2num(layout.labels[k]))) for k in kept]
+            )
+        )
+        ax.xaxis.set_minor_formatter(FixedFormatter([texts[k] for k in kept]))
+        ax.tick_params(  # type: ignore[reportUnknownMemberType]
+            axis="x",
+            which="minor",
+            length=0,
+            labelsize=ax.xaxis.get_major_ticks()[0].label1.get_fontsize(),
+        )
+    else:
+        values = [float(cast(Any, date2num(layout.ticks[k]))) for k in kept]
+        fixed = FixedLocator(values)
+        ax.xaxis.set_major_locator(fixed)
+        ax.xaxis.set_major_formatter(
+            _tick_formatter(fixed, values[0], pin_start)
+        )
+    fig.canvas.draw()  # type: ignore[reportUnknownMemberType]
+    _style_date_labels(ax, rot, minor=centered)
+    return layout
+
+
 def compact_date_axis(
     ax: Axes,
     data_min: Any,
@@ -813,8 +1069,22 @@ def compact_date_axis(
     rotation: float | None = None,
     pin_start: bool | None = None,
     auto_rotate: bool = False,
+    max_labels: int | None = None,
+    step: str = "auto",
+    labels: str = "tick",
 ) -> None:
-    """Compact date x-axis: few ticks, anchored to the data span.
+    """Compact date x-axis: as many calendar dates as fit the narrow figure.
+
+    The axis labels every year (or, over two years at most, every month)
+    that fits in the width without overlapping and within *max_labels*
+    (``None`` reads ``compact.date_max_labels`` for the default density),
+    stepping to one every 2, 5, 10... years only when they do not fit;
+    ``step`` (``"1Y"``, ``"3M"``...) fixes the step instead, and
+    ``labels="centered"`` centres each year over its stretch.  See
+    :func:`calendar_date_axis`.
+
+    Spans too short for a calendar grid (a few weeks of daily data) keep
+    the historical behaviour described below, with *maxticks* ticks.
 
     Ticks are computed over the **data span** ``[data_min,
     data_max]`` and pinned with a ``FixedLocator``, so none
@@ -853,6 +1123,31 @@ def compact_date_axis(
         if pin_start is None
         else pin_start
     )
+    monthly_max, min_fraction, gap_em = _date_axis_config(compact=True)
+    layouts = date_layouts(
+        data_min,
+        data_max,
+        step=step,
+        max_labels=(
+            date_max_labels("default", compact=True)
+            if max_labels is None
+            else max_labels
+        ),
+        monthly_max_months=monthly_max,
+        pin_start=show_start,
+        centered=labels == "centered",
+        min_fraction=min_fraction,
+    )
+    if layouts:
+        calendar_date_axis(
+            ax,
+            layouts,
+            pin_start=show_start,
+            rotation=rotation,
+            auto_rotate=auto_rotate,
+            gap_em=gap_em,
+        )
+        return
     # same span-clipped ticks (and same pinned start) the non-compact axis
     # uses, so both modes answer "when does this start?" identically
     ticks: list[float] = date_span_ticks(
@@ -958,8 +1253,20 @@ def apply_date_axis(
     data_min: Any = None,
     data_max: Any = None,
     pin_start: bool = False,
+    max_labels: int | None = None,
+    step: str = "auto",
+    labels: str = "tick",
 ) -> None:
-    """Native matplotlib date x-axis with a soft tick count and optional slant.
+    """Native matplotlib date x-axis with every year (or month) that fits.
+
+    Given the ``data_min`` / ``data_max`` span, the axis labels every year
+    (or, over two years at most, every month) that fits in the width and
+    within *max_labels* (``None`` reads ``line.date_max_labels`` for the
+    default density), stepping to one every 2, 5, 10... years only when
+    they do not; ``step`` fixes the step and ``labels="centered"`` centres
+    each year over its stretch (see :func:`calendar_date_axis`).  The rest
+    of this docstring describes the fallback for spans too short for a
+    calendar grid, or when no span is given.
 
     The non-compact counterpart to :func:`compact_date_axis`: it takes over the
     x-axis (which must carry a **native** date axis, i.e. the series were
@@ -984,6 +1291,31 @@ def apply_date_axis(
     ``rotation=None`` has to *actively* flatten them to keep the documented
     "horizontal unless asked" behaviour.
     """
+    if data_min is not None and data_max is not None:
+        monthly_max, min_fraction, gap_em = _date_axis_config(compact=False)
+        layouts = date_layouts(
+            data_min,
+            data_max,
+            step=step,
+            max_labels=(
+                date_max_labels("default", compact=False)
+                if max_labels is None
+                else max_labels
+            ),
+            monthly_max_months=monthly_max,
+            pin_start=pin_start,
+            centered=labels == "centered",
+            min_fraction=min_fraction,
+        )
+        if layouts:
+            calendar_date_axis(
+                ax,
+                layouts,
+                pin_start=pin_start,
+                rotation=rotation,
+                gap_em=gap_em,
+            )
+            return
     if pin_start and data_min is not None and data_max is not None:
         ticks = date_span_ticks(
             data_min, data_max, maxticks=maxticks, pin_start=True
@@ -1226,8 +1558,9 @@ def style_compact_axes(
     :func:`declutter_spines`.
     """
     if font_pt is not None:
+        # which="both": centred date labels live on the minor ticks
         ax.tick_params(  # type: ignore[reportUnknownMemberType]
-            axis="both", labelsize=font_pt
+            axis="both", which="both", labelsize=font_pt
         )
     if side == "right":
         ax.yaxis.tick_right()
@@ -1244,6 +1577,8 @@ def place_legend(
     ncol: int | None = None,
     position: str = "auto",
     entries: tuple[list[Any], list[str]] | None = None,
+    font_pt: float | None = None,
+    min_entries: int = 1,
 ) -> MplLegend | None:
     """Place the figure legend, compact-aware, from the labelled artists.
 
@@ -1257,17 +1592,21 @@ def place_legend(
     ``entries`` passes precomputed ``(handles, labels)`` instead of reading
     them off *ax* -- for charts whose series span several axes (a
     ``twinx`` secondary y-axis), in the order the legend should list them.
-    Returns ``None`` (drawing nothing) when there are no labels.
+    ``font_pt`` sets the size of the legend text.  Returns ``None``
+    (drawing nothing) when there are no labels, or fewer than
+    ``min_entries``.
     """
     handles, labels = (
         entries if entries is not None else ax.get_legend_handles_labels()
     )
-    if not labels:
+    if not labels or len(labels) < min_entries:
         return None
     side = resolve_legend_position(position, compact=compact)
     fig_w_px: float = fig.get_size_inches()[0] * fig.dpi
     if compact:
         legend_kw = compact_legend_kwargs(ax)
+        if font_pt is not None:
+            legend_kw["fontsize"] = font_pt
         if ncol is None:
             ncol = auto_ncol(
                 ax, labels, available_width_px=fig_w_px, **legend_kw
@@ -1285,8 +1624,12 @@ def place_legend(
             **legend_kw,
         )
     if ncol is None:
-        ncol = auto_ncol(ax, labels, available_width_px=fig_w_px)
-    return legend_band(ax, handles, labels, ncol=ncol, position=side)
+        ncol = auto_ncol(
+            ax, labels, available_width_px=fig_w_px, fontsize=font_pt
+        )
+    return legend_band(
+        ax, handles, labels, ncol=ncol, position=side, fontsize=font_pt
+    )
 
 
 def legend_layout(legend: Legend | None) -> dict[str, Any]:
@@ -1302,9 +1645,13 @@ def legend_layout(legend: Legend | None) -> dict[str, Any]:
             fig, ax, compact=self.compact, **legend_layout(self.legend)
         )
     """
+    if legend is None:
+        return {"ncol": None, "position": "auto"}
     return {
-        "ncol": legend.ncol if legend is not None else None,
-        "position": legend.position if legend is not None else "auto",
+        "ncol": legend.ncol,
+        "position": legend.position,
+        "font_pt": legend.font_pt,
+        "min_entries": legend.min_entries,
     }