tesorotools-python 0.0.42__tar.gz → 0.0.44__tar.gz

{tesorotools_python-0.0.42 → tesorotools_python-0.0.44}/.gitignore

@@ -1,30 +1,27 @@
-.venv/
-.build1/
-
-__pycache__
-
-.vscode/
-
-data/
-config/
-debug/
-tablas/
-
-dist/
-
-*.png
-*.feather
-*.csv
-*.docx
-*.docx#
-
-test/
-
-# font files
-*.otf
-
-# coverage
-.coverage
-
-# ruff
+.venv/
+.build1/
+
+__pycache__
+
+.vscode/
+
+data/
+config/
+debug/
+tablas/
+
+dist/
+
+*.png
+*.feather
+*.csv
+*.docx
+*.docx#
+
+test/
+
+# coverage
+.coverage
+
+# ruff
 .ruff_cache/

{tesorotools_python-0.0.42 → tesorotools_python-0.0.44}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tesorotools-python
-Version: 0.0.42
+Version: 0.0.44
 Requires-Python: >=3.13
 Requires-Dist: babel>=2.17
 Requires-Dist: matplotlib>=3.10

{tesorotools_python-0.0.42 → tesorotools_python-0.0.44}/pyproject.toml

@@ -1,66 +1,69 @@
-[project]
-name = "tesorotools-python"
-requires-python = ">=3.13"
-version = "0.0.42"
-dependencies = [
-    # database and ORM
-    "psycopg[binary]>=3.1",
-    "SQLAlchemy>=2.0",
-
-    # data analysis
-    "pandas>=2.2",
-    "pyarrow>=18.0",
-    "openpyxl>=3.1",
-
-    # utils
-    "PyYAML>=6.0",
-    "babel>=2.17",
-
-    # data visualization
-    "matplotlib>=3.10",
-    "python-docx>=1.1",
-
-    # os dependencies
-    "pywin32>=311; sys_platform == 'win32'",
-]
-
-[project.optional-dependencies]
-bde = ["requests>=2.31"]
-ecb = ["requests>=2.31"]
-lseg = ["lseg-data>=2.1"]
-
-[dependency-groups]
-dev = [
-    "ruff>=0.8",
-    "pyright>=1.1",
-    "pre-commit>=4.0",
-    "pandas-stubs>=2.2",
-    "coverage>=7.0",
-]
-
-[build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
-
-[tool.hatch.build.targets.wheel]
-packages = ["src/tesorotools"]
-artifacts = ["src/tesorotools/assets/fonts/*.otf"]
-
-[tool.hatch.build.targets.sdist]
-include = ["src/tesorotools"]
-artifacts = ["src/tesorotools/assets/fonts/*.otf"]
-
-[tool.coverage.report]
-exclude_lines = [
-    'if __name__ == "__main__"',
-    '^\s*\.\.\.$',
-    'if TYPE_CHECKING',
-]
-
-[tool.ruff]
-line-length = 80
-
-[tool.pyright]
-pythonVersion = "3.13"
-extraPaths = ["src"]
-typeCheckingMode = "strict"
+[project]
+name = "tesorotools-python"
+requires-python = ">=3.13"
+dynamic = ["version"]
+dependencies = [
+    # database and ORM
+    "psycopg[binary]>=3.1",
+    "SQLAlchemy>=2.0",
+
+    # data analysis
+    "pandas>=2.2",
+    "pyarrow>=18.0",
+    "openpyxl>=3.1",
+
+    # utils
+    "PyYAML>=6.0",
+    "babel>=2.17",
+
+    # data visualization
+    "matplotlib>=3.10",
+    "python-docx>=1.1",
+
+    # os dependencies
+    "pywin32>=311; sys_platform == 'win32'",
+]
+
+[project.optional-dependencies]
+bde = ["requests>=2.31"]
+ecb = ["requests>=2.31"]
+lseg = ["lseg-data>=2.1"]
+
+[dependency-groups]
+dev = [
+    "ruff>=0.8",
+    "pyright>=1.1",
+    "pre-commit>=4.0",
+    "pandas-stubs>=2.2",
+    "coverage>=7.0",
+]
+
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tesorotools"]
+artifacts = ["src/tesorotools/assets/fonts/*.otf"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/tesorotools"]
+artifacts = ["src/tesorotools/assets/fonts/*.otf"]
+
+[tool.coverage.report]
+exclude_lines = [
+    'if __name__ == "__main__"',
+    '^\s*\.\.\.$',
+    'if TYPE_CHECKING',
+]
+
+[tool.ruff]
+line-length = 80
+
+[tool.pyright]
+pythonVersion = "3.13"
+extraPaths = ["src"]
+typeCheckingMode = "strict"

{tesorotools_python-0.0.42 → tesorotools_python-0.0.44}/src/tesorotools/__init__.py

@@ -45,6 +45,7 @@ from tesorotools._registry import (
 )
 from tesorotools.artists import (
     Format,
+    GroupedBarChart,
     HorizontalBarChart,
     Legend,
     LinePlot,
@@ -76,6 +77,7 @@ def _register_builtins() -> None:
     register_artist("stacked_area", StackedAreaPlot)
     register_artist("stacked_bar", StackedBarPlot)
     register_artist("barh", HorizontalBarChart)
+    register_artist("grouped_barh", GroupedBarChart)
     register_artist("type_curve", TypeCurve)
 
     register_tag("format", Format)
@@ -102,6 +104,7 @@ __all__ = [
     "DataProvider",
     "EcbProvider",
     "Format",
+    "GroupedBarChart",
     "HorizontalBarChart",
     "Image",
     "Images",

{tesorotools_python-0.0.42 → tesorotools_python-0.0.44}/src/tesorotools/artists/__init__.py

@@ -27,7 +27,7 @@ strictly image output.
 import matplotlib.style
 
 from tesorotools.artists._common import Artist, Format, Legend
-from tesorotools.artists.barh_plot import HorizontalBarChart
+from tesorotools.artists.barh_plot import GroupedBarChart, HorizontalBarChart
 from tesorotools.artists.line_plot import LinePlot
 from tesorotools.artists.stacked import StackedAreaPlot, StackedBarPlot
 from tesorotools.artists.type_curve import TypeCurve
@@ -38,6 +38,7 @@ matplotlib.style.use(STYLE_SHEET)
 __all__ = [
     "Artist",
     "Format",
+    "GroupedBarChart",
     "HorizontalBarChart",
     "Legend",
     "LinePlot",

{tesorotools_python-0.0.42 → tesorotools_python-0.0.44}/src/tesorotools/artists/barh_plot.py

@@ -21,6 +21,7 @@ from pathlib import Path
 from typing import Any, Self
 
 import matplotlib.pyplot as plt
+import numpy as np
 import pandas as pd
 from matplotlib.axes import Axes
 from matplotlib.container import BarContainer
@@ -32,6 +33,9 @@ from tesorotools.artists._common import (
     AX_CONFIG,
     FIG_CONFIG,
     Format,
+    Legend,
+    adjust_figure_for_plot_size,
+    auto_ncol,
     resolve_data,
 )
 from tesorotools.utils.matplotlib import PLOT_CONFIG, format_annotation
@@ -39,7 +43,7 @@ from tesorotools.utils.template import TemplateLoader
 
 BARH_CONFIG: dict[str, Any] = PLOT_CONFIG["barh"]
 
-__all__ = ["HorizontalBarChart"]
+__all__ = ["GroupedBarChart", "HorizontalBarChart"]
 
 
 class _Col(Enum):
@@ -370,3 +374,205 @@ class HorizontalBarChart:
         )
         plt.close(fig)
         return ax
+
+
+class GroupedBarChart:
+    """Grouped (clustered) horizontal bar chart artist.
+
+    Compares two or more series side-by-side within each
+    category -- the "double horizontal bar" the single-series
+    :class:`HorizontalBarChart` cannot express (e.g. rural vs.
+    urban, habitual vs. preferred).  Categories run down the
+    y-axis; each category holds one bar per series, the i-th
+    series coloured with theme colour ``C{i}``.
+
+    The input ``data`` is a flat ``pd.DataFrame`` indexed by
+    category id with one column per series id; ``categories``
+    selects and labels the rows and ``series`` selects and
+    labels the columns, so the same wide frame can feed
+    several charts.
+
+    Parameters
+    ----------
+    out_path
+        ``.png`` path the rendered chart is saved to.
+    data, data_path
+        Provide one.  The DataFrame is indexed by the ids in
+        ``categories`` and carries one column per id in
+        ``series``.
+    categories
+        ``id -> label`` for the y-axis rows, in display order
+        (unless ``sorted``).
+    series
+        ``id -> label`` for the bars within each category, in
+        colour order (first gets ``C0``).
+    fmt, annot_fmt
+        Number formats for the x-axis ticks and the per-bar
+        value annotations.  ``annot_fmt`` defaults to ``fmt``.
+    annotate
+        Label each bar with its formatted value (default
+        ``True``).
+    sorted
+        Sort categories ascending by the first series' value
+        before drawing (default ``False`` -- preserve the
+        declared order, which usually mirrors a questionnaire).
+    group_width
+        Fraction of the category slot occupied by its bar
+        group (default ``0.8``); the rest is inter-group gap.
+    legend
+        Legend layout (``ncol``); when omitted the column
+        count is auto-fitted.
+    figsize, plot_size
+        Override ``FIG_CONFIG['figsize']`` / resize the figure
+        so the axes area matches ``plot_size`` after the
+        legend is placed.
+    """
+
+    def __init__(
+        self,
+        out_path: Path,
+        *,
+        data: pd.DataFrame | None = None,
+        data_path: Path | None = None,
+        categories: dict[str, str],
+        series: dict[str, str],
+        fmt: Format | None = None,
+        annot_fmt: Format | None = None,
+        annotate: bool = True,
+        sorted: bool = False,
+        group_width: float = 0.8,
+        legend: Legend | None = None,
+        figsize: tuple[float, float] | None = None,
+        plot_size: tuple[float, float] | None = None,
+    ) -> None:
+        if out_path.suffix != ".png":
+            raise ValueError(f"out_path must be .png: {out_path}")
+        if not series:
+            raise ValueError("Must declare at least one series")
+        self.out_path = out_path
+        self.data = resolve_data(data, data_path)
+        self.categories = categories
+        self.series = series
+        self.fmt = fmt or Format()
+        self.annot_fmt = annot_fmt or self.fmt
+        self.annotate = annotate
+        self.sorted = sorted
+        self.group_width = group_width
+        self.legend = legend
+        self.figsize = figsize
+        self.plot_size = plot_size
+
+    @classmethod
+    def from_yaml(cls, loader: TemplateLoader, node: MappingNode) -> Self:
+        """Build a :class:`GroupedBarChart` from ``!grouped_barh``.
+
+        Required keys
+        -------------
+        ``out_path``
+            ``.png`` destination path.
+        ``data_path``
+            ``.feather`` file with a DataFrame indexed by
+            category id and one column per series id.
+        ``categories``
+            ``id -> label`` for the y-axis rows.
+        ``series``
+            ``id -> label`` for the bars within each category.
+
+        Optional keys
+        -------------
+        ``fmt`` (``!format``), ``annot_fmt`` (``!format``),
+        ``annotate`` (default ``True``), ``sorted`` (default
+        ``False``), ``group_width`` (default ``0.8``),
+        ``legend`` (``!legend``), ``figsize``, ``plot_size``.
+
+        Example
+        -------
+        .. code-block:: yaml
+
+            mayores_rural_urbano: !grouped_barh
+              out_path: out/b7_mayores.png
+              data_path: data/b7.feather
+              categories:
+                banca_online: "Usa banca online"
+                cajero:       "Usa el cajero"
+                oficina:      "Acude a la oficina"
+              series:
+                rural: "Rural (< 5.000 hab.)"
+                urban: "Mayores (urbano)"
+              fmt: !format {decimals: 1, units: "%"}
+        """
+        cfg: dict[str, Any] = loader.construct_mapping(  # type: ignore[assignment]
+            node, deep=True
+        )
+        cfg.pop("id")
+        cfg["out_path"] = Path(cfg["out_path"])
+        if "data_path" in cfg:
+            cfg["data_path"] = Path(cfg["data_path"])
+        return cls(**cfg)
+
+    def plot(self) -> Axes:
+        """Render the chart and persist it to ``self.out_path``."""
+        cat_ids = list(self.categories.keys())
+        ser_ids = list(self.series.keys())
+        frame = self.data.loc[cat_ids, ser_ids].copy()
+        if self.sorted:
+            frame = frame.sort_values(by=ser_ids[0])
+            cat_ids = list(frame.index)
+        cat_labels = [self.categories[c] for c in cat_ids]
+        ser_labels = list(self.series.values())
+
+        fig_kw = dict(FIG_CONFIG)
+        if self.figsize is not None:
+            fig_kw["figsize"] = self.figsize
+        fig: Figure = plt.figure(  # type: ignore[reportUnknownMemberType]
+            **fig_kw
+        )
+        ax: Axes = fig.add_subplot()
+
+        n = len(ser_ids)
+        y = np.arange(len(cat_ids))
+        height = self.group_width / n
+        for k, sid in enumerate(ser_ids):
+            # First series sits at the top of each category slot;
+            # offsets march downward so colour order reads top-to-bottom.
+            offset = (n - 1) / 2 * height - k * height
+            container: BarContainer = ax.barh(  # type: ignore[reportUnknownMemberType]
+                y=y + offset,
+                width=frame[sid].to_numpy(dtype=np.float64),
+                height=height,
+                color=f"C{k}",
+                label=ser_labels[k],
+            )
+            if self.annotate:
+                _annotate_bars(fig, ax, container, self.annot_fmt)
+
+        ax.set_yticks(y)  # type: ignore[reportUnknownMemberType]
+        ax.set_yticklabels(  # type: ignore[reportUnknownMemberType]
+            cat_labels
+        )
+        _style_axes(ax, self.fmt, **AX_CONFIG["spines"])
+        _style_zero_baseline(ax, **AX_CONFIG["baseline"])
+
+        fig_width_px: float = fig.get_size_inches()[0] * fig.dpi
+        legend_ncol = self.legend.ncol if self.legend else None
+        ncol = (
+            legend_ncol
+            if legend_ncol is not None
+            else auto_ncol(ax, ser_labels, available_width_px=fig_width_px)
+        )
+        handles, label_strs = ax.get_legend_handles_labels()
+        fig.legend(  # type: ignore[reportUnknownMemberType]
+            handles,
+            label_strs,
+            loc="outside lower center",
+            ncol=ncol,
+        )
+
+        if self.plot_size is not None:
+            adjust_figure_for_plot_size(fig, ax, self.plot_size)
+
+        fig.savefig(  # type: ignore[reportUnknownMemberType]
+            self.out_path
+        )
+        plt.close(fig)
+        return ax

{tesorotools_python-0.0.42 → tesorotools_python-0.0.44}/src/tesorotools/assets/README.md

@@ -1,5 +1,5 @@
-En esta carpeta se guardarán todos los *assets* del proyecto, como
-
-- [fonts](fonts/): Fuentes (archivos *.otf).
-- [plots.yaml](plots.yaml): Archivo de configuración general para los gráficos.
+En esta carpeta se guardarán todos los *assets* del proyecto, como
+
+- [fonts](fonts/): Fuentes (archivos *.otf).
+- [plots.yaml](plots.yaml): Archivo de configuración general para los gráficos.
 - [tesoro.mplstyle](tesoro.mplstyle): Archivo de estilos *matplotlib* para los gráficos.

tesorotools_python-0.0.44/src/tesorotools/assets/fonts/README.md

@@ -0,0 +1,4 @@
+Archivos *.otf de fuentes (Cabinet Grotesk). Se versionan con **Git LFS**
+(ver `.gitattributes`), no como blobs en la historia normal de git. El
+checkout los materializa, y `pyproject.toml` los empaqueta en el wheel
+publicado vía `tool.hatch.build ... artifacts`.

{tesorotools_python-0.0.42 → tesorotools_python-0.0.44}/src/tesorotools/assets/plots.yaml

@@ -1,44 +1,44 @@
-# general plot config file
-
-style:
-  font: Cabinet Grotesk
-
-figure:
-  dpi: 500
-  layout: constrained
-
-ax:
-  spines:
-    color: gray
-    linewidth: 1
-  baseline:
-    color: "#d9e1fc"
-    linestyle: solid
-    linewidth: 1
-    zorder: 1
-
-type_curve:
-  last:
-    alpha: 0.2
-    color: C1
-  current:
-    alpha: 0.3
-    color: C0
-  line:
-    linewidth: 2
-    marker: D
-    color: C0
-
-barh:
-  highlight_factor: 0.4
-  padding: 5
-
-line:
-  ncol: 5
-
-table:
-  style: Light Shading Accent 1
-  autofit: False
-  block_separator:
-    fill: "BFBFBF"      # hex color of the inter-block band
-    height_twips: 20    # half-band height; total band = 2 * height_twips
+# general plot config file
+
+style:
+  font: Cabinet Grotesk
+
+figure:
+  dpi: 500
+  layout: constrained
+
+ax:
+  spines:
+    color: gray
+    linewidth: 1
+  baseline:
+    color: "#d9e1fc"
+    linestyle: solid
+    linewidth: 1
+    zorder: 1
+
+type_curve:
+  last:
+    alpha: 0.2
+    color: C1
+  current:
+    alpha: 0.3
+    color: C0
+  line:
+    linewidth: 2
+    marker: D
+    color: C0
+
+barh:
+  highlight_factor: 0.4
+  padding: 5
+
+line:
+  ncol: 5
+
+table:
+  style: Light Shading Accent 1
+  autofit: False
+  block_separator:
+    fill: "BFBFBF"      # hex color of the inter-block band
+    height_twips: 20    # half-band height; total band = 2 * height_twips

{tesorotools_python-0.0.42 → tesorotools_python-0.0.44}/src/tesorotools/assets/tesoro.mplstyle

@@ -1,21 +1,21 @@
-# fonts
-font.size: 12.0
-xtick.labelsize: 12.0
-ytick.labelsize: 12.0
-legend.fontsize: 12.0
-
-# modified dashed_pattern
-lines.dashed_pattern: 10, 5
-
-# markers
-lines.markersize: 8
-
-# grids
-grid.color: d9e1fc
-grid.linestyle: dashed
-grid.linewidth: 0.5
-grid.alpha: 0.5
-
-# color palette
-axes.prop_cycle: cycler('color', ['001e93', 'ffbd4c', '6d6d6d', '000000', 'e6821e', '2957ff', 'fba737', '5da6ff', '00ebb2', '6d0000', '009200', 'df2871', 'd9e1fc', 'ffddab'])
-
+# fonts
+font.size: 12.0
+xtick.labelsize: 12.0
+ytick.labelsize: 12.0
+legend.fontsize: 12.0
+
+# modified dashed_pattern
+lines.dashed_pattern: 10, 5
+
+# markers
+lines.markersize: 8
+
+# grids
+grid.color: d9e1fc
+grid.linestyle: dashed
+grid.linewidth: 0.5
+grid.alpha: 0.5
+
+# color palette
+axes.prop_cycle: cycler('color', ['001e93', 'ffbd4c', '6d6d6d', '000000', 'e6821e', '2957ff', 'fba737', '5da6ff', '00ebb2', '6d0000', '009200', 'df2871', 'd9e1fc', 'ffddab'])
+

{tesorotools_python-0.0.42 → tesorotools_python-0.0.44}/src/tesorotools/database/__init__.py

@@ -1,14 +1,14 @@
-"""
-Módulo de gestión de bases de datos y persistencia para tesorotools.
-Contiene las utilidades para interactuar con bases de datos locales y remotas.
-"""
-
-from tesorotools.database.local import LocalDatabase, ShortcutDatabase
-from tesorotools.database.shared import SharedDatabase, resolve_shared_root
-
-__all__ = [
-    "LocalDatabase",
-    "SharedDatabase",
-    "ShortcutDatabase",
-    "resolve_shared_root",
-]
+"""
+Módulo de gestión de bases de datos y persistencia para tesorotools.
+Contiene las utilidades para interactuar con bases de datos locales y remotas.
+"""
+
+from tesorotools.database.local import LocalDatabase, ShortcutDatabase
+from tesorotools.database.shared import SharedDatabase, resolve_shared_root
+
+__all__ = [
+    "LocalDatabase",
+    "SharedDatabase",
+    "ShortcutDatabase",
+    "resolve_shared_root",
+]