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

{tesorotools_python-0.1.9 → tesorotools_python-0.1.10}/.gitignore

@@ -32,8 +32,9 @@ test/
 # ruff
 .ruff_cache/
 
-# uv cache (CI restores it into the repo root)
+# uv cache and verified-tree marks (CI restores them into the repo root)
 .uv-cache/
+.ci-verified/
 
 demo_compacto/
 demo/

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

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

{tesorotools_python-0.1.9 → tesorotools_python-0.1.10}/src/tesorotools/palette.py

@@ -31,6 +31,8 @@ BLUE_PALE = "AEBAE7"
 BLUE_FAINT = "ECF0FD"
 #: Secondary text: captions, metadata, stale rows.
 GREY = "6D6D6D"
+#: Plot area of the slide charts, under white grid lines.
+GREY_PANEL = "EFEFEF"
 #: Tesoro yellow: highlights of the presentations (bands, frames, the
 #: section subtitles of the index) and its light shade for fills.
 YELLOW = "FFBD4C"

{tesorotools_python-0.1.9 → tesorotools_python-0.1.10}/src/tesorotools/presentation/charts.py

@@ -4,7 +4,8 @@ The same artists, palette and axis format as the notes
 (:func:`tesorotools.note.note_palette`, :func:`~tesorotools.note.axis_format`);
 only the size changes: each chart is drawn at the size of its frame in
 the template, with 12-point text that reads on a projected slide, the
-legend too, and on a white background, as the slide::
+legend too, and the data on a grey panel with white grid lines, framed
+by the white of the slide::
 
     with slide_style():
         LinePlot(
@@ -26,6 +27,7 @@ import matplotlib as mpl
 
 from tesorotools.artists._common import Legend
 from tesorotools.note.charts import note_palette
+from tesorotools.palette import GREY_PANEL
 
 __all__ = [
     "SLIDE_CHART_CM",
@@ -49,13 +51,19 @@ SLIDE_CHART_CM: dict[str, tuple[float, float]] = {
     "pareja_estrecho": (10.4, 8.9),
 }
 _CM_TO_IN = 1 / 2.54
-#: What a slide chart changes of the house style: a white background,
-#: the one of the slide, whatever the style of the notes or the machine.
+#: What a slide chart changes of the house style: the figure on white,
+#: the one of the slide, whatever the style of the notes or the machine,
+#: and the plot area grey (:data:`~tesorotools.palette.GREY_PANEL`) with
+#: solid white grid lines.
 SLIDE_STYLE: dict[str, Any] = {
     "figure.facecolor": "white",
-    "axes.facecolor": "white",
+    "axes.facecolor": f"#{GREY_PANEL}",
     "savefig.facecolor": "white",
     "savefig.transparent": False,
+    "grid.color": "white",
+    "grid.linestyle": "solid",
+    "grid.linewidth": 1.0,
+    "grid.alpha": 1.0,
 }
 
 _rc_context: Callable[[dict[str, Any]], Any] = mpl.rc_context  # pyright: ignore[reportUnknownMemberType, reportUnknownVariableType]
@@ -64,9 +72,9 @@ _rc_context: Callable[[dict[str, Any]], Any] = mpl.rc_context  # pyright: ignore
 @contextmanager
 def slide_style() -> Generator[None]:
     """Draw the charts inside the block for a slide: the colours of the
-    guide (:func:`~tesorotools.note.note_palette`) on a white background
-    (:data:`SLIDE_STYLE`).  Only while the block runs: the notes keep
-    their own style."""
+    guide (:func:`~tesorotools.note.note_palette`) on the grey panel of
+    the slides (:data:`SLIDE_STYLE`).  Only while the block runs: the
+    notes keep their own style."""
     with note_palette(), _rc_context(SLIDE_STYLE):
         yield
 

{tesorotools_python-0.1.9 → tesorotools_python-0.1.10}/src/tesorotools/presentation/native.py

@@ -27,11 +27,13 @@ from pptx.enum.chart import (
     XL_MARKER_STYLE,
 )
 from pptx.enum.chart import XL_TICK_LABEL_POSITION as TICKS
-from pptx.oxml.ns import qn
+from pptx.oxml import parse_xml
+from pptx.oxml.ns import nsdecls, qn
 from pptx.util import Emu, Pt
 
 from tesorotools.note.builder import format_number
 from tesorotools.note.charts import NOTE_COLORS, axis_decimals
+from tesorotools.palette import GREY_PANEL
 
 __all__ = [
     "NATIVE_KINDS",
@@ -173,9 +175,10 @@ def add_native_chart(
         else:
             series.format.fill.solid()
             series.format.fill.fore_color.rgb = color
+    _panel(chart)
     values: Any = chart.value_axis
     values.has_major_gridlines = True
-    values.major_gridlines.format.line.color.rgb = _rgb(_GRID)
+    values.major_gridlines.format.line.color.rgb = _rgb("FFFFFF")
     values.format.line.fill.background()
     values.tick_labels.number_format = fmt
     values.tick_labels.number_format_is_linked = False
@@ -198,6 +201,20 @@ def add_native_chart(
     return chart
 
 
+def _panel(chart: Any) -> None:
+    """The plot area on the grey of the slide charts (:data:`SLIDE_STYLE`),
+    under white grid lines.  python-pptx has no call for it: its
+    ``c:spPr`` goes last, after the axes, where the schema wants it (the
+    chart python-pptx writes has no ``c:extLst`` to go before)."""
+    area: Any = chart._chartSpace.chart.plotArea  # pyright: ignore[reportPrivateUsage]
+    area.append(
+        parse_xml(
+            f"<c:spPr {nsdecls('c', 'a')}><a:solidFill><a:srgbClr"
+            f' val="{GREY_PANEL}"/></a:solidFill></c:spPr>'
+        )
+    )
+
+
 def _date_ticks(axis: Any, months: int) -> None:
     """Marks every year, half year or quarter, as the span asks."""
     if months > 48:

{tesorotools_python-0.1.9 → tesorotools_python-0.1.10}/src/tesorotools/presentation/skill/SKILL.md

@@ -403,7 +403,7 @@ from tesorotools.note import axis_format
 from tesorotools.presentation import slide_chart_size, slide_style
 
 series = {"ES10Y": "España", "DE10Y": "Alemania"}  # columna: etiqueta
-with slide_style():                  # colores de la guía, fondo blanco
+with slide_style():                  # colores de la guía, área de datos gris
     LinePlot(
         out_path=Path("graficos/tipos.png"),
         data=df,                     # DataFrame con DatetimeIndex
@@ -430,7 +430,8 @@ with slide_style():                  # colores de la guía, fondo blanco
   `#2957FF`, Azul 3 `#5DA6FF`, Naranja `#E6821E` y Mostaza `#FBA737`) y el
   mismo formato del eje que en las notas: un gráfico de una nota y el de
   una presentación solo cambian de tamaño. `slide_style()` dibuja además
-  sobre fondo blanco, el de la diapositiva.
+  el área de datos en gris claro (`#EFEFEF`) con la rejilla blanca, y el
+  resto del gráfico en blanco, el de la diapositiva.
 - `legend=True` pone la leyenda debajo del eje, a 12 puntos como el resto
   del gráfico, y solo si hay dos series o más (una sola serie no lleva
   leyenda: la nombra el título). Úsalo solo con los artists que admiten

{tesorotools_python-0.1.9 → tesorotools_python-0.1.10}/src/tesorotools/web/__init__.py

@@ -38,15 +38,18 @@ from tesorotools.web.components import (
 )
 from tesorotools.web.formatting import format_number, long_date, short_date
 from tesorotools.web.launcher import launch
+from tesorotools.web.period import Period, PeriodChoice, resolve_period
 
 if TYPE_CHECKING:
     from tesorotools.web.app import (
         Dashboard,
+        PeriodSelector,
         Section,
         block,
         chart,
         download_xlsx,
         html,
+        period_selector,
         xlsx_bytes,
     )
     from tesorotools.web.plotting import (
@@ -63,6 +66,9 @@ __all__ = [
     "FontFace",
     "Kpi",
     "NavLink",
+    "Period",
+    "PeriodChoice",
+    "PeriodSelector",
     "Section",
     "badge_html",
     "block",
@@ -80,6 +86,8 @@ __all__ = [
     "long_date",
     "nav_links_html",
     "notice_html",
+    "period_selector",
+    "resolve_period",
     "short_date",
     "sidebar_logo_html",
     "style_figure",
@@ -94,7 +102,9 @@ _APP = {
     "chart",
     "default_brand",
     "download_xlsx",
+    "PeriodSelector",
     "html",
+    "period_selector",
     "xlsx_bytes",
 }
 _PLOTTING = {"PLOTLY_CONFIG", "line_figure", "style_figure"}

{tesorotools_python-0.1.9 → tesorotools_python-0.1.10}/src/tesorotools/web/app.py

@@ -30,10 +30,12 @@ Marks, fonts, signature and navigation come from a
 
 from __future__ import annotations
 
+import datetime
 import io
 import logging
-from collections.abc import Callable, Sequence
+from collections.abc import Callable, Mapping, Sequence
 from dataclasses import dataclass, field
+from typing import Any
 
 import pandas as pd
 import plotly.graph_objects as go
@@ -52,6 +54,14 @@ from tesorotools.web.components import (
     section_index_markdown,
     sidebar_logo_html,
 )
+from tesorotools.web.period import (
+    CUSTOM,
+    Period,
+    PeriodChoice,
+    Window,
+    as_day,
+    resolve_period,
+)
 from tesorotools.web.plotting import PLOTLY_CONFIG
 from tesorotools.web.theme import DEFAULT_FAMILY, stylesheet
 
@@ -103,6 +113,166 @@ def chart(fig: go.Figure, *, key: str | None = None) -> None:
     )
 
 
+#: Width of each date field, in pixels: fits "31/12/2026" and its icon.
+_DATE_WIDTH = 140
+
+
+def _start_key(key: str) -> str:
+    return f"{key}-desde"
+
+
+def _end_key(key: str) -> str:
+    return f"{key}-hasta"
+
+
+def _as_date(day: pd.Timestamp | None) -> datetime.date | None:
+    return None if day is None else day.date()
+
+
+@dataclass(frozen=True)
+class PeriodSelector:
+    """A period control, resolved but not yet drawn.
+
+    :attr:`period` is the window to draw with; :meth:`render` draws the
+    control.  They are separate because the chart needs the window
+    **before** it is drawn and the control usually goes **under** it::
+
+        selector = period_selector("curva", WINDOWS, default="5 años",
+                                   dates=frame.index)
+        chart(figure(selector.period.clip(frame)))
+        selector.render()
+    """
+
+    key: str
+    choice: PeriodChoice
+    start_label: str = "Desde"
+    end_label: str = "Hasta"
+
+    @property
+    def period(self) -> Period:
+        return self.choice.period
+
+    def render(self) -> None:
+        """The row of buttons and, to its right, the two date fields.
+
+        The date fields get no ``value``: theirs is written in the session
+        before drawing them (the window of the selected button, or what
+        was typed, clamped to the data), because Streamlit warns when a
+        widget gets both, and a day outside ``min_value``/``max_value`` is
+        an exception and not a warning.  On a narrow screen the row wraps
+        and the dates go under the buttons.
+        """
+        choice, state = self.choice, st.session_state
+        if choice.first is None or choice.last is None:
+            st.segmented_control(
+                "Periodo",
+                choice.options[:-1],
+                default=choice.default,
+                required=True,
+                key=self.key,
+                label_visibility="collapsed",
+            )
+            return
+        start, end = _start_key(self.key), _end_key(self.key)
+        if choice.period.warning is None:
+            state[start] = _as_date(choice.shown_start)
+            state[end] = _as_date(choice.shown_end)
+        else:
+            # What was typed stays, only clamped to the data: nobody gets
+            # their input erased for having it the wrong way round.
+            for date_key in (start, end):
+                day = as_day(state.get(date_key))
+                state[date_key] = _as_date(
+                    None
+                    if day is None
+                    else min(max(day, choice.first), choice.last)
+                )
+        # The button also goes through the session and without
+        # ``default``: typing a date writes it there (see
+        # ``_to_custom``), and Streamlit warns about a default and a
+        # stored value at once.
+        if state.get(self.key) not in choice.options:
+            state[self.key] = choice.default
+        with st.container(
+            horizontal=True, vertical_alignment="bottom", gap="small"
+        ):
+            st.segmented_control(
+                "Periodo",
+                choice.options,
+                required=True,
+                key=self.key,
+                label_visibility="collapsed",
+                # Inside a row Streamlit keeps it on one line and scrolls
+                # it; on a phone the custom button fell off the screen.
+                width="content",
+            )
+            for label, date_key in (
+                (self.start_label, start),
+                (self.end_label, end),
+            ):
+                st.date_input(
+                    label,
+                    min_value=_as_date(choice.first),
+                    max_value=_as_date(choice.last),
+                    format="DD/MM/YYYY",
+                    key=date_key,
+                    on_change=_to_custom,
+                    args=(self.key, choice.options[-1]),
+                    width=_DATE_WIDTH,
+                )
+        if choice.period.warning:
+            # No ``icon=``: a Material icon written by name is one more
+            # place where the house font rule can fail.
+            st.warning(choice.period.warning)
+
+
+def _to_custom(key: str, custom_label: str) -> None:
+    """``on_change`` of the date fields: typing selects the custom button.
+
+    It runs before the rerun, so the next pass already reads the new
+    window.  The dates themselves are already in the session.
+    """
+    st.session_state[key] = custom_label
+
+
+def period_selector(
+    key: str,
+    windows: Mapping[str, Window],
+    *,
+    default: str,
+    dates: Sequence[Any] | pd.Index | pd.Series,
+    first: pd.Timestamp | None = None,
+    custom_label: str = CUSTOM,
+    start_label: str = "Desde",
+    end_label: str = "Hasta",
+) -> PeriodSelector:
+    """A row of period buttons with two date fields, read from the session.
+
+    Nothing is drawn here: this reads what the three widgets left in
+    ``st.session_state`` (Streamlit writes it before rerunning the page,
+    so a click shows in that same pass) and resolves the window with
+    :func:`~tesorotools.web.period.resolve_period`.  Draw the control
+    with :meth:`PeriodSelector.render`, wherever it goes.
+
+    Clip what is drawn **and** what is downloaded with the same
+    :attr:`PeriodSelector.period`, so the workbook is what is on screen.
+    To repaint only the chart on a click, put the chart and its control
+    inside an ``st.fragment``.
+    """
+    state = st.session_state
+    choice = resolve_period(
+        windows,
+        default=default,
+        dates=dates,
+        chosen=state.get(key),
+        typed_start=state.get(_start_key(key)),
+        typed_end=state.get(_end_key(key)),
+        first=first,
+        custom_label=custom_label,
+    )
+    return PeriodSelector(key, choice, start_label, end_label)
+
+
 def xlsx_bytes(frame: pd.DataFrame, sheet: str = "datos") -> bytes:
     """*frame* as an ``.xlsx`` workbook (real numbers, not text)."""
     buffer = io.BytesIO()

tesorotools_python-0.1.10/src/tesorotools/web/period.py

@@ -0,0 +1,220 @@
+"""The window of a time-series chart: preset buttons plus a typed range.
+
+A row of preset buttons ("2 años", "5 años", "Todo"...) and, next to it,
+two date fields ("Desde", "Hasta").  They are **one control**:
+
+* a button sets the window and the two dates are rewritten with it, so
+  the dates always say what is being shown;
+* typing a date selects the custom button and the window becomes the one
+  between the two dates, both days included;
+* a date outside the data is clamped to it, and a start later than the
+  end is not drawn: the period falls back to the default button and
+  carries a warning saying so.
+
+This module is the pure part: it decides the window from what the
+widgets left in the session, and needs neither Streamlit nor Plotly.  The
+widgets live in :func:`tesorotools.web.app.period_selector`.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from typing import Any
+
+import numpy as np
+import numpy.typing as npt
+import pandas as pd
+
+#: How far back a preset button looks: whole years before the last
+#: datum, a fixed first day (for instance the last close of the previous
+#: year, for a "year to date" button), or ``None`` for all the data.
+Window = int | pd.Timestamp | None
+
+#: Default label of the button that is selected when dates are typed.
+CUSTOM = "Personalizado"
+
+
+@dataclass(frozen=True)
+class Period:
+    """The chosen window: from which day to which day, both included.
+
+    ``None`` on either side means "no cut on that side".  With a preset
+    button ``end`` is always ``None``: the window ends at the last datum.
+    ``warning`` is what to say under the control when the typed dates
+    could not be used.
+    """
+
+    label: str
+    start: pd.Timestamp | None = None
+    end: pd.Timestamp | None = None
+    custom: bool = False
+    warning: str | None = None
+
+    def describe(self) -> str:
+        """How the window is named in a message: «"5 años"» or a range."""
+        if not self.custom:
+            return f"«{self.label}»"
+        start = "el principio" if self.start is None else _day(self.start)
+        end = "el último dato" if self.end is None else _day(self.end)
+        if self.start is None or self.end is None:
+            return f"el periodo desde {start} hasta {end}"
+        return f"el periodo del {start} al {end}"
+
+    def mask(
+        self, dates: pd.Index | pd.Series[Any] | Sequence[Any]
+    ) -> npt.NDArray[np.bool_]:
+        """Which of *dates* fall inside the window.
+
+        The end day is included whole: an intraday stamp of that day is
+        inside, not only its midnight.
+        """
+        stamps = pd.DatetimeIndex(list(dates))
+        inside = np.ones(len(stamps), dtype=bool)
+        if self.start is not None:
+            inside &= np.asarray(stamps >= self.start, dtype=bool)
+        if self.end is not None:
+            limit = self.end.normalize() + pd.Timedelta(days=1)
+            inside &= np.asarray(stamps < limit, dtype=bool)
+        return inside
+
+    def clip(self, frame: pd.DataFrame) -> pd.DataFrame:
+        """The rows of *frame* (indexed by date) inside the window."""
+        if frame.empty or (self.start is None and self.end is None):
+            return frame
+        return frame.loc[self.mask(frame.index)]
+
+
+@dataclass(frozen=True)
+class PeriodChoice:
+    """A resolved control: the period, and what the widgets must show.
+
+    ``first`` and ``last`` are the bounds of the date fields (``None``
+    when there is no data, and then only the buttons are drawn);
+    ``shown_start`` and ``shown_end`` are the dates the fields display.
+    """
+
+    period: Period
+    options: tuple[str, ...]
+    default: str
+    first: pd.Timestamp | None
+    last: pd.Timestamp | None
+    shown_start: pd.Timestamp | None
+    shown_end: pd.Timestamp | None
+
+
+def _day(stamp: pd.Timestamp) -> str:
+    return f"{stamp:%d/%m/%Y}"
+
+
+def as_day(value: object) -> pd.Timestamp | None:
+    """What a date widget left in the session, as a day; or ``None``."""
+    if value is None or value == "":
+        return None
+    try:
+        day = pd.Timestamp(value)  # pyright: ignore[reportArgumentType]
+    except (TypeError, ValueError):
+        return None
+    return None if pd.isna(day) else day.normalize()
+
+
+def _clamp(
+    day: pd.Timestamp, first: pd.Timestamp, last: pd.Timestamp
+) -> pd.Timestamp:
+    return min(max(day, first), last)
+
+
+def resolve_period(
+    windows: Mapping[str, Window],
+    *,
+    default: str,
+    dates: Sequence[Any] | pd.Index | pd.Series,
+    chosen: object = None,
+    typed_start: object = None,
+    typed_end: object = None,
+    first: pd.Timestamp | None = None,
+    custom_label: str = CUSTOM,
+) -> PeriodChoice:
+    """Decide the window from what the widgets left in the session.
+
+    *windows* are the preset buttons, in order; *default* the one that
+    starts selected.  *dates* are the dates of the data, and give the
+    bounds of the date fields: from the first one (or from *first*, if
+    given and later) to the last one.  *chosen*, *typed_start* and
+    *typed_end* are the session values of the three widgets; anything
+    that is not one of the options, or not a date, counts as unset.
+    """
+    if default not in windows:
+        raise ValueError(f"default {default!r} is not one of the windows")
+    if custom_label in windows:
+        raise ValueError(f"{custom_label!r} is already a window label")
+    index = pd.DatetimeIndex(pd.to_datetime(pd.Series(list(dates)))).dropna()
+    options = (*windows, custom_label)
+    label = str(chosen) if chosen in options else default
+
+    if index.empty:
+        period = _preset(windows, default if label == custom_label else label)
+        return PeriodChoice(period, options, default, None, None, None, None)
+
+    newest = pd.Timestamp(index.max())
+    last = newest.normalize()
+    lower = pd.Timestamp(index.min()).normalize()
+    if first is not None:
+        lower = min(max(first.normalize(), lower), last)
+
+    if label != custom_label:
+        period = _preset(windows, label, newest)
+    else:
+        start = as_day(typed_start)
+        end = as_day(typed_end)
+        start = lower if start is None else _clamp(start, lower, last)
+        end = last if end is None else _clamp(end, lower, last)
+        if start > end:
+            fallback = _preset(windows, default, newest)
+            period = Period(
+                custom_label,
+                fallback.start,
+                fallback.end,
+                custom=True,
+                warning=(
+                    f"«Desde» ({_day(start)}) es posterior a «Hasta» "
+                    f"({_day(end)}): corrige una de las dos. Mientras, el "
+                    f"gráfico enseña «{default}»."
+                ),
+            )
+        else:
+            period = Period(
+                custom_label,
+                None if start == lower else start,
+                None if end == last else end,
+                custom=True,
+            )
+
+    cut = lower if period.start is None else period.start.normalize()
+    return PeriodChoice(
+        period=period,
+        options=options,
+        default=default,
+        first=lower,
+        last=last,
+        shown_start=max(cut, lower),
+        shown_end=last if period.end is None else period.end,
+    )
+
+
+def _preset(
+    windows: Mapping[str, Window],
+    label: str,
+    newest: pd.Timestamp | None = None,
+) -> Period:
+    """The period of a preset button, counted back from *newest*."""
+    window = windows[label]
+    if window is None:
+        return Period(label)
+    if isinstance(window, pd.Timestamp):
+        return Period(label, window)
+    if newest is None:
+        return Period(label)
+    # From the last datum **with its time**, so a button cuts exactly
+    # where a "last N years" filter on the raw data would.
+    return Period(label, newest - pd.DateOffset(years=window))