tesorotools-python 0.0.30__tar.gz → 0.0.32__tar.gz

{tesorotools_python-0.0.30 → tesorotools_python-0.0.32}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tesorotools-python
-Version: 0.0.30
+Version: 0.0.32
 Requires-Python: >=3.13
 Requires-Dist: babel>=2.17
 Requires-Dist: eikon>=1.1

{tesorotools_python-0.0.30 → tesorotools_python-0.0.32}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "tesorotools-python"
 requires-python = ">=3.13"
-version = "0.0.30"
+version = "0.0.32"
 dependencies = [
     # database and ORM
     "psycopg[binary]>=3.1",

{tesorotools_python-0.0.30 → tesorotools_python-0.0.32}/src/tesorotools/artists/line_plot.py

@@ -102,11 +102,17 @@ def annotate_last_values(
     *,
     decimals: int,
     units: str,
+    labels: dict[str, str] | None = None,
     series_styles: dict[str, dict[str, Any]] | None = None,
     annotate_color: str | None = None,
 ) -> None:
     """Label the last non-NaN value of each column on the right.
 
+    ``plot_data.columns`` and ``series_styles`` keys must be
+    canonical series IDs.  ``labels`` maps each ID to the
+    Matplotlib line label used when the axes were drawn; if
+    omitted, the ID itself is used as the line label.
+
     Colour priority (highest first): ``annotate_color``
     (global override), ``series_styles[col]['color']``,
     the Matplotlib line colour.
@@ -120,6 +126,7 @@ def annotate_last_values(
     if fig is None:
         return
     styles = series_styles or {}
+    label_map = labels or {}
 
     lines_by_label = {str(line.get_label()): line for line in ax.lines}
     entries: list[tuple[Any, float, str, Any]] = []
@@ -136,7 +143,7 @@ def annotate_last_values(
             if override is not None:
                 color = override
             else:
-                line = lines_by_label.get(col)
+                line = lines_by_label.get(label_map.get(col, col))
                 color = line.get_color() if line is not None else "black"
         entries.append((last_date, last_val, col, color))
 
@@ -454,7 +461,6 @@ class LinePlot:
         plot_data: pd.DataFrame = self.data.loc[
             slice(start_date, end_date), self.series.keys()
         ]
-        plot_data = plot_data.rename(columns=self.series)
 
         plot_data = plot_data * self.scale
 
@@ -468,12 +474,10 @@ class LinePlot:
             **fig_kw
         )
         ax = fig.add_subplot()
-        if self.series_styles:
-            for col in plot_data.columns:
-                style = self.series_styles.get(col, {})
-                plot_data[col].plot(ax=ax, label=col, **style)
-        else:
-            plot_data.plot(ax=ax)
+        styles = self.series_styles
+        for col in plot_data.columns:
+            style = styles.get(col, {}) if styles else {}
+            plot_data[col].plot(ax=ax, label=self.series[col], **style)
 
         assert self.format is not None
         if self.annotate:
@@ -482,6 +486,7 @@ class LinePlot:
                 plot_data,
                 decimals=self.format.decimals,
                 units=self.format.units,
+                labels=self.series,
                 series_styles=self.series_styles,
                 annotate_color=self.annotate_color,
             )
@@ -497,7 +502,7 @@ class LinePlot:
             style_baseline(ax, reference, **AX_CONFIG["baseline"])
 
         if self.legend is not None:
-            labels = list(plot_data.columns)
+            labels = [self.series[c] for c in plot_data.columns]
             ncol = (
                 self.legend.ncol
                 if self.legend.ncol is not None

{tesorotools_python-0.0.30 → tesorotools_python-0.0.32}/src/tesorotools/artists/stacked.py

@@ -84,7 +84,8 @@ class StackedAreaPlot:
             else self.data.index.max()
         )
 
-        plot_data = self.data.loc[start:end, list(self.series.keys())].dropna()
+        plot_data = self.data.loc[start:end, list(self.series.keys())]
+        plot_data = plot_data.dropna(how="all").fillna(0)
         plot_data = plot_data * self.scale
 
         fig_kw = dict(FIG_CONFIG)
@@ -211,7 +212,8 @@ class StackedBarPlot:
             else self.data.index.max()
         )
         all_cols = list(self.series.keys()) + list(self.overlay_series.keys())
-        plot_data = self.data.loc[start:end, all_cols].dropna()
+        plot_data = self.data.loc[start:end, all_cols]
+        plot_data = plot_data.dropna(how="all").fillna(0)
         return plot_data * self.scale
 
     def _format_xticks(

{tesorotools_python-0.0.30 → tesorotools_python-0.0.32}/src/tesorotools/database/__init__.py

@@ -4,8 +4,11 @@ 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",
 ]

tesorotools_python-0.0.32/src/tesorotools/database/shared.py

@@ -0,0 +1,177 @@
+"""Resolver for shared OneDrive folders used as a team database.
+
+Absorbed from the ``src/bbdd.py`` copies in ``cnmv_python`` and
+``epf`` — both had the same logic with only a per-project env var
+name differing.  The old ``ShortcutDatabase`` (Windows ``.lnk``
+per user) is superseded by this resolver for the ``bbdd/``
+layout: each member of the team gets the same path auto-discovered
+from their OneDrive mount.
+
+Resolution order
+----------------
+1. An explicit override environment variable (``env_var`` argument,
+   e.g. ``"CNMV_BBDD_ROOT"``).  Used for local dev, CI and tests.
+2. ``%OneDriveCommercial%`` + glob for a SharePoint folder whose
+   name contains ``team_marker`` and that contains ``subdir``.
+3. ``%OneDrive%`` as a fallback.
+4. ``RuntimeError`` with a diagnostic listing every attempt.
+
+Callers supply their own ``team_marker`` — this module does not
+assume any specific SharePoint tenant.  The substring match is
+tolerant of the OneDrive client variant (``General - {team}``
+vs. ``{team} - General`` depending on locale).
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from functools import cache
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+#: OneDrive env vars published by the Windows client.
+_ONEDRIVE_ENV_VARS = ("OneDriveCommercial", "OneDrive")
+
+
+@cache
+def resolve_shared_root(
+    *,
+    env_var: str,
+    team_marker: str,
+    subdir: str = "bbdd",
+) -> Path:
+    """Resolve the local path to a shared OneDrive folder.
+
+    Parameters
+    ----------
+    env_var
+        Name of the environment variable for explicit override
+        (e.g. ``"CNMV_BBDD_ROOT"``).  Each project picks its own
+        to avoid collisions on shared dev machines.
+    team_marker
+        Substring matched against the SharePoint folder name.
+    subdir
+        Shared folder subdirectory under the SharePoint mount
+        (default ``"bbdd"``).
+
+    Returns
+    -------
+    Path
+        Absolute path to the existing shared folder.
+
+    Raises
+    ------
+    RuntimeError
+        If none of the resolution steps yields an existing
+        directory.  The message lists every attempt so the user
+        can see what was tried.
+    """
+    tried: list[str] = []
+
+    override = os.environ.get(env_var)
+    if override:
+        p = Path(override)
+        if p.is_dir():
+            logger.info("shared root resolved via %s: %s", env_var, p)
+            return p
+        raise RuntimeError(
+            f"{env_var}={override!r} does not point to an existing directory."
+        )
+    tried.append(f"{env_var} (not set)")
+
+    for var in _ONEDRIVE_ENV_VARS:
+        val = os.environ.get(var)
+        if not val:
+            tried.append(f"%{var}% (not set)")
+            continue
+        root = Path(val)
+        if not root.is_dir():
+            tried.append(f"%{var}%={val!r} (not a directory)")
+            continue
+        matches = sorted(
+            c for c in root.glob(f"*{team_marker}*/{subdir}") if c.is_dir()
+        )
+        if matches:
+            chosen = matches[0]
+            if len(matches) > 1:
+                logger.warning(
+                    "Multiple %s/ candidates under %s: %s. Picking %s.",
+                    subdir,
+                    root,
+                    matches,
+                    chosen,
+                )
+            logger.info(
+                "shared root auto-discovered via %%%s%%: %s", var, chosen
+            )
+            return chosen
+        tried.append(f"%{var}% without '*{team_marker}*/{subdir}' under {root}")
+
+    raise RuntimeError(
+        f"Cannot locate the {subdir}/ folder. Attempts:\n  - "
+        + "\n  - ".join(tried)
+        + f"\nHint: set {env_var} to the local path where OneDrive "
+        f"syncs the shared {subdir}/ folder."
+    )
+
+
+class SharedDatabase:
+    """Per-project view over a shared OneDrive database folder.
+
+    Replaces ``ShortcutDatabase`` (``.lnk`` per user) for the
+    ``bbdd/`` layout: each project has a subtree with
+    ``raw/`` and ``processed/`` conventional subdirectories.
+
+    Parameters
+    ----------
+    project
+        Project name (segment under ``{shared_root}/``, e.g.
+        ``"cnmv"`` or ``"epf"``).
+    env_var
+        Environment variable for explicit override of the shared
+        root (e.g. ``"CNMV_BBDD_ROOT"``).
+    team_marker
+        Substring of the SharePoint folder name (see
+        :func:`resolve_shared_root`).
+    subdir
+        Shared folder subdirectory (default ``"bbdd"``).
+    """
+
+    def __init__(
+        self,
+        project: str,
+        *,
+        env_var: str,
+        team_marker: str,
+        subdir: str = "bbdd",
+    ) -> None:
+        self.project = project
+        self._env_var = env_var
+        self._team_marker = team_marker
+        self._subdir = subdir
+
+    @property
+    def root(self) -> Path:
+        """Resolved path to the shared folder."""
+        return resolve_shared_root(
+            env_var=self._env_var,
+            team_marker=self._team_marker,
+            subdir=self._subdir,
+        )
+
+    @property
+    def project_root(self) -> Path:
+        """``{root}/{project}/`` — subtree reserved for this project."""
+        return self.root / self.project
+
+    @property
+    def processed_root(self) -> Path:
+        """``{root}/{project}/processed/`` — datasets for consumers."""
+        return self.project_root / "processed"
+
+    @property
+    def raw_root(self) -> Path:
+        """``{root}/{project}/raw/`` — original source files."""
+        return self.project_root / "raw"

tesorotools_python-0.0.32/src/tesorotools/manifest.py

@@ -0,0 +1,120 @@
+"""YAML manifest sidecar for published parquet datasets.
+
+Absorbed from the ``src/manifest.py`` copies in ``cnmv_python``
+and ``epf``: both had identical ``write_manifest`` and a slightly
+different provenance builder (kept per-project).  This module
+provides the shared pieces — the YAML writer and the hashing
+helper.
+
+A bare ``data.parquet`` in a shared folder is opaque to consumers:
+schema and provenance are not visible without opening the file.
+The manifest pins both as a YAML sidecar at write time::
+
+    bbdd/cnmv/processed/capa1/concepto=inversiones/ejercicio=2024/
+        data.parquet
+        _MANIFEST.yaml
+
+Structure
+---------
+.. code-block:: yaml
+
+    dataset: cnmv/capa1/inversiones/2024
+    layer: 1
+    row_count: 120013
+    parquet_file: data.parquet
+    generated_at: 2026-04-21T15:30:00+00:00
+    generated_by: cnmv_python
+    schema:
+      - {name: tipo_fichero, dtype: string[pyarrow]}
+      - ...
+    provenance:   # optional, caller-supplied
+      ...
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+import hashlib
+import logging
+from pathlib import Path
+from typing import Any
+
+import pandas as pd
+import yaml
+
+logger = logging.getLogger(__name__)
+
+MANIFEST_FILENAME = "_MANIFEST.yaml"
+
+
+def sha256_file(path: Path, chunk: int = 1 << 20) -> str:
+    """Compute the SHA-256 of a file, streaming in 1 MiB chunks."""
+    h = hashlib.sha256()
+    with path.open("rb") as f:
+        while True:
+            block = f.read(chunk)
+            if not block:
+                break
+            h.update(block)
+    return h.hexdigest()
+
+
+def write_manifest(
+    parquet_path: Path,
+    df: pd.DataFrame,
+    dataset: str,
+    layer: int,
+    provenance: dict[str, Any] | None = None,
+    generated_by: str = "",
+) -> Path:
+    """Write ``_MANIFEST.yaml`` next to *parquet_path*.
+
+    Parameters
+    ----------
+    parquet_path
+        Full path to the ``data.parquet`` that was just written.
+        The manifest is placed in the same directory.
+    df
+        DataFrame used only to derive ``schema`` and ``row_count``
+        — not persisted.
+    dataset
+        Canonical dataset name (e.g. ``"cnmv/capa1/inversiones/2024"``).
+    layer
+        Convention: ``0`` = raw, ``1`` = processed.
+    provenance
+        Optional project-specific dict (source files, hashes, ...).
+        Omitted from the YAML when ``None``.
+    generated_by
+        Identifier of the generating project (e.g. ``"cnmv_python"``).
+
+    Returns
+    -------
+    Path
+        The path of the written manifest.
+    """
+    payload: dict[str, Any] = {
+        "dataset": dataset,
+        "layer": layer,
+        "row_count": int(len(df)),
+        "parquet_file": parquet_path.name,
+        "generated_at": dt.datetime.now(dt.UTC).isoformat(timespec="seconds"),
+        "generated_by": generated_by,
+        "schema": [
+            {"name": str(col), "dtype": str(df[col].dtype)}
+            for col in df.columns
+        ],
+    }
+    if provenance:
+        payload["provenance"] = provenance
+
+    out_path = parquet_path.parent / MANIFEST_FILENAME
+    with out_path.open("w", encoding="utf-8") as f:
+        yaml.safe_dump(
+            payload,
+            f,
+            sort_keys=False,
+            allow_unicode=True,
+            default_flow_style=False,
+        )
+    logger.debug("Manifest written: %s", out_path)
+    return out_path

{tesorotools_python-0.0.30 → tesorotools_python-0.0.32}/src/tesorotools/pipeline/rules.py

@@ -45,6 +45,21 @@ def sum_rule(output: str, sources: list[str]) -> TransformationRule:
     )
 
 
+def mean_rule(output: str, sources: list[str]) -> TransformationRule:
+    """Row-wise arithmetic mean of multiple columns.
+
+    Equivalent to ``=AVERAGE(...)`` in Excel: NaN components
+    are skipped (not treated as zero), so a row with any
+    non-NaN value yields the mean of whatever is present.
+    A row of all NaN yields NaN.
+    """
+    return TransformationRule(
+        output_name=output,
+        dependencies=list(sources),
+        compute=lambda df, cols=list(sources): df[cols].mean(axis=1),
+    )
+
+
 def ratio_rule(
     output: str, numerator: str, denominator: str
 ) -> TransformationRule:
@@ -333,6 +348,7 @@ FACTORIES: dict[
 ] = {
     "scale": scale_rule,
     "sum": sum_rule,
+    "mean": mean_rule,
     "ratio": ratio_rule,
     "difference": difference_rule,
     "inverse": inverse_rule,