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

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

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

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

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

{tesorotools_python-0.0.31 → 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