python-esios 2.0.1__tar.gz → 2.1.0__tar.gz

python_esios-2.0.1/.github/workflows/publish.yml → python_esios-2.1.0/.github/workflows/release-please.yml

@@ -1,14 +1,30 @@
-name: Publish to PyPI
+name: Release Please
 
 on:
   push:
     branches: [main]
 
+permissions:
+  contents: write
+  pull-requests: write
+
 jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+    steps:
+      - uses: googleapis/release-please-action@v4
+        id: release
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+
   publish:
+    needs: release-please
+    if: needs.release-please.outputs.release_created == 'true'
     runs-on: ubuntu-latest
     permissions:
-      id-token: write # Required for trusted publishing
+      id-token: write
     steps:
       - uses: actions/checkout@v4
 
@@ -24,5 +40,3 @@ jobs:
 
       - name: Publish to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1
-        with:
-          skip-existing: true

{python_esios-2.0.1 → python_esios-2.1.0}/.gitignore

@@ -24,6 +24,9 @@ Thumbs.db
 *.swp
 *.swo
 
+# Claude Code
+.claude/
+
 # Generated docs
 docs/
 
@@ -46,3 +49,6 @@ htmlcov/
 
 # Dev scripts
 random/
+
+# Backups
+examples_backup/

python_esios-2.1.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "2.1.0"
+}

{python_esios-2.0.1 → python_esios-2.1.0}/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## [2.1.0](https://github.com/datons/python-esios/compare/python-esios-v2.0.2...python-esios-v2.1.0) (2026-03-04)
+
+
+### Features
+
+* add archives sheets and exec CLI commands for I90 processing ([b54f94a](https://github.com/datons/python-esios/commit/b54f94adfa56ee2150fc85f92055b002b0d3e9bb))
+* add static archives catalog (153 archives) and improve download API ([22e6095](https://github.com/datons/python-esios/commit/22e60953fb3d5314452c03807be3e12595b88fd4))
+* replace manual PyPI workflow with release-please ([3c0dcb3](https://github.com/datons/python-esios/commit/3c0dcb35b01a47ea489d5a1ecb891d6805486356))
+
+
+### Bug Fixes
+
+* correct author email to datons.com ([8e17132](https://github.com/datons/python-esios/commit/8e1713248a56928ba61898b5b84b0b4689798ce3))
+* rename release-please config to expected non-dotted filename ([2f53b76](https://github.com/datons/python-esios/commit/2f53b7658c3f3e02e53dcbb3a2fe149b8f16ad7c))
+* update archives test to match static catalog default ([9bbd98b](https://github.com/datons/python-esios/commit/9bbd98b56dee2ae1cfbed24537ad989f5214ae76))
+
+
+### Performance
+
+* lazy sheet loading in I90Book — only read sheets on demand ([2dfe941](https://github.com/datons/python-esios/commit/2dfe941bf71c74bb0bd07c72c90e92b61a0d3059))
+
 ## [2.0.0] - 2026-02-27
 
 Complete rewrite of the library with a new architecture, CLI, and caching system.

python_esios-2.1.0/CLAUDE.md

@@ -0,0 +1,21 @@
+# python-esios
+
+## Releasing
+
+This project uses [release-please](https://github.com/googleapis/release-please) for automated versioning and publishing.
+
+**How it works:**
+
+1. Write conventional commits (`feat:`, `fix:`, `chore:`, etc.)
+2. On push to `main`, release-please auto-opens/updates a **Release PR** with version bump + CHANGELOG
+3. Merge the Release PR → GitHub Release + tag created → PyPI publish via trusted publishing
+
+**Key files:**
+
+- `.release-please-config.json` — release-please configuration (package type, changelog sections)
+- `.release-please-manifest.json` — tracks current version
+- `.github/workflows/release-please.yml` — workflow (release PR management + PyPI publish)
+
+**Version is tracked in** `pyproject.toml` (`project.version`). Release-please bumps it automatically based on commit types (`feat:` → minor, `fix:` → patch).
+
+**Never bump the version manually** — let release-please handle it via the Release PR.

{python_esios-2.0.1 → python_esios-2.1.0}/PKG-INFO

@@ -1,12 +1,17 @@
 Metadata-Version: 2.4
 Name: python-esios
-Version: 2.0.1
+Version: 2.1.0
 Summary: A Python wrapper for the ESIOS API (Spanish electricity market)
 Project-URL: Homepage, https://github.com/datons/python-esios
 Project-URL: Repository, https://github.com/datons/python-esios
-Author-email: Jesús López <jesus.lopez@datons.ai>
+Project-URL: Issues, https://github.com/datons/python-esios/issues
+Project-URL: Changelog, https://github.com/datons/python-esios/releases
+Author-email: Jesús López <jesus.lopez@datons.com>
 License-Expression: GPL-3.0-only
 License-File: LICENSE
+Keywords: api,electricity,energy,esios,ree,spain
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
 Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
@@ -14,6 +19,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
 Requires-Python: >=3.10
 Requires-Dist: beautifulsoup4>=4.12
 Requires-Dist: httpx>=0.27

{python_esios-2.0.1 → python_esios-2.1.0}/pyproject.toml

@@ -4,15 +4,18 @@ build-backend = "hatchling.build"
 
 [project]
 name = "python-esios"
-version = "2.0.1"
+version = "2.1.0"
 description = "A Python wrapper for the ESIOS API (Spanish electricity market)"
 readme = "README.md"
 license = "GPL-3.0-only"
 requires-python = ">=3.10"
 authors = [
-    { name = "Jesús López", email = "jesus.lopez@datons.ai" },
+    { name = "Jesús López", email = "jesus.lopez@datons.com" },
 ]
+keywords = ["esios", "ree", "energy", "electricity", "spain", "api"]
 classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Science/Research",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
@@ -20,6 +23,7 @@ classifiers = [
     "Programming Language :: Python :: 3.13",
     "License :: OSI Approved :: GNU General Public License v3 (GPLv3)",
     "Operating System :: OS Independent",
+    "Topic :: Scientific/Engineering",
 ]
 dependencies = [
     "httpx>=0.27",
@@ -39,6 +43,8 @@ esios = "esios.cli:app"
 [project.urls]
 Homepage = "https://github.com/datons/python-esios"
 Repository = "https://github.com/datons/python-esios"
+Issues = "https://github.com/datons/python-esios/issues"
+Changelog = "https://github.com/datons/python-esios/releases"
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/esios"]

python_esios-2.1.0/release-please-config.json

@@ -0,0 +1,19 @@
+{
+  "packages": {
+    ".": {
+      "release-type": "python",
+      "package-name": "python-esios",
+      "extra-files": [
+        "pyproject.toml"
+      ],
+      "changelog-sections": [
+        { "type": "feat", "section": "Features" },
+        { "type": "fix", "section": "Bug Fixes" },
+        { "type": "perf", "section": "Performance" },
+        { "type": "docs", "section": "Documentation", "hidden": true },
+        { "type": "chore", "section": "Miscellaneous", "hidden": true }
+      ]
+    }
+  },
+  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json"
+}

{python_esios-2.0.1 → python_esios-2.1.0}/src/esios/.agents/skills/esios/SKILL.md

@@ -39,8 +39,22 @@ esios indicators exec 600 -s 2025-01-01 -e 2025-01-31 --expr "df.resample('D').m
 ### Archives
 
 ```bash
+# List all available archives
 esios archives list
-esios archives download 1 --start 2025-01-01 --end 2025-01-31 --output ./data
+
+# Download archive files
+esios archives download 34 --start 2025-05-01 --end 2025-05-31 --output ./data
+esios archives download 34 --date 2025-06-01
+
+# List sheets (table of contents) in an I90 file
+esios archives sheets 34 --date 2025-06-01
+
+# Parse and query archive data (like indicators exec but for archives)
+esios archives exec 34 --sheet I90DIA03 --date 2025-06-01
+esios archives exec 34 --sheet I90DIA03 --date 2025-06-01 -x "df.describe()"
+esios archives exec 34 --sheet I90DIA03 -s 2025-05-05 -e 2025-06-08 \
+  -x "df[df['Sentido']=='Bajar'].groupby('Unidad de Programación')['value'].sum().sort_values()"
+esios archives exec 34 --sheet I90DIA26 --date 2025-06-01 --format csv --output pbf.csv
 ```
 
 ### Cache Management
@@ -132,11 +146,42 @@ df = client.indicators.compare([600, 10034, 10035], "2025-01-01", "2025-01-07")
 
 ## I90 Settlement Files
 
+### CLI (quickest path)
+
+```bash
+# Discover available sheets
+esios archives sheets 34 --date 2025-06-01
+
+# Key I90DIA sheets:
+# I90DIA03 — Restricciones en el Mercado Diario (curtailment)
+# I90DIA08 — Restricciones en Tiempo Real
+# I90DIA26 — Programa Base de Funcionamiento (PBF, generation program)
+# I90DIA01 — Programa PVP
+# I90DIA07 — Regulación Terciaria (mFRR)
+
+# Total curtailment by direction
+esios archives exec 34 --sheet I90DIA03 --date 2025-06-01 \
+  -x "df.groupby('Sentido')['value'].sum()"
+
+# Multi-day curtailment analysis
+esios archives exec 34 --sheet I90DIA03 -s 2025-05-05 -e 2025-06-08 \
+  -x "df[df['Sentido']=='Bajar'].groupby('Unidad de Programación')['value'].sum().sort_values().head(20)"
+```
+
+### Python library
+
 ```python
-from esios.processing import I90Book
+from esios import ESIOSClient
+from esios.processing.i90 import I90Book
+
+# Download + parse in one step
+client = ESIOSClient()
+archive = client.archives.get(34)
+books = I90Book.from_archive(archive, start="2025-05-05", end="2025-06-08")
 
-book = I90Book("path/to/I90DIA_20250101.xls")
-sheet = book["3.1"]       # Access specific sheet
+# Access a sheet
+book = books[0]
+sheet = book["I90DIA03"]
 df = sheet.df             # Preprocessed DataFrame with datetime index
 print(sheet.frequency)    # "hourly" or "hourly-quarterly"
 ```

python_esios-2.1.0/src/esios/cli/archives.py

@@ -0,0 +1,217 @@
+"""CLI subcommands for archives."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+archives_app = typer.Typer(no_args_is_help=True)
+console = Console()
+
+
+@archives_app.command("list")
+def list_archives(
+    token: Optional[str] = typer.Option(None, "--token", "-t"),
+    format: str = typer.Option("table", "--format", "-f"),
+):
+    """List all available ESIOS archives."""
+    from esios.cli.app import get_client
+
+    client = get_client(token)
+    df = client.archives.list()
+
+    if format == "csv":
+        typer.echo(df.to_csv())
+    elif format == "json":
+        typer.echo(df.to_json(orient="records", indent=2))
+    else:
+        table = Table(title="ESIOS Archives")
+        cols = list(df.columns)[:8]
+        for col in cols:
+            table.add_column(str(col))
+        for _, row in df.head(50).iterrows():
+            table.add_row(*[str(row[c]) for c in cols])
+        if len(df) > 50:
+            table.caption = f"Showing 50 of {len(df)} rows"
+        console.print(table)
+
+
+@archives_app.command("download")
+def download_archive(
+    archive_id: int = typer.Argument(..., help="Archive ID"),
+    start: Optional[str] = typer.Option(None, "--start", "-s", help="Start date (YYYY-MM-DD)"),
+    end: Optional[str] = typer.Option(None, "--end", "-e", help="End date (YYYY-MM-DD)"),
+    date: Optional[str] = typer.Option(None, "--date", "-d", help="Single date (YYYY-MM-DD)"),
+    output: str = typer.Option(".", "--output", "-o", help="Output directory"),
+    token: Optional[str] = typer.Option(None, "--token", "-t"),
+):
+    """Download an archive for a date or date range."""
+    from esios.cli.app import get_client
+
+    if not date and not (start and end):
+        typer.echo("Provide --date or both --start and --end.", err=True)
+        raise typer.Exit(1)
+
+    client = get_client(token)
+    client.archives.download(
+        archive_id,
+        start=start,
+        end=end,
+        date=date,
+        output_dir=output,
+    )
+    typer.echo(f"Download complete → {output}")
+
+
+def _download_files(
+    archive_id: int,
+    token: str | None,
+    date: str | None,
+    start: str | None,
+    end: str | None,
+) -> list:
+    """Download archive files (shared by sheets and exec commands)."""
+    from esios.cli.app import get_client
+
+    if not date and not (start and end):
+        typer.echo("Provide --date or both --start and --end.", err=True)
+        raise typer.Exit(1)
+
+    client = get_client(token)
+
+    if date:
+        files = client.archives.download(archive_id, date=date)
+    else:
+        files = client.archives.download(archive_id, start=start, end=end)
+
+    if not files:
+        typer.echo("No files found for the given date range.", err=True)
+        raise typer.Exit(1)
+
+    return files
+
+
+@archives_app.command("sheets")
+def sheets(
+    archive_id: int = typer.Argument(..., help="Archive ID (e.g. 34 for I90DIA)"),
+    date: Optional[str] = typer.Option(None, "--date", "-d", help="Single date (YYYY-MM-DD)"),
+    start: Optional[str] = typer.Option(None, "--start", "-s", help="Start date (YYYY-MM-DD)"),
+    end: Optional[str] = typer.Option(None, "--end", "-e", help="End date (YYYY-MM-DD)"),
+    token: Optional[str] = typer.Option(None, "--token", "-t"),
+):
+    """List sheets (table of contents) in an archive file.
+
+    Downloads and parses the first file to show available sheets.
+
+    \b
+    Examples:
+        esios archives sheets 34 --date 2025-06-01
+        esios archives sheets 34 --start 2025-06-01 --end 2025-06-01
+    """
+    from esios.processing.i90 import I90Book
+
+    files = _download_files(archive_id, token, date, start, end)
+
+    try:
+        book = I90Book(files[0])
+    except Exception as exc:
+        typer.echo(f"Error parsing {files[0].name}: {exc}", err=True)
+        raise typer.Exit(1)
+
+    table = Table(title=f"Sheets in {files[0].name}")
+    table.add_column("Sheet", style="cyan")
+    table.add_column("Description")
+
+    for sheet_name, description in book.table_of_contents.items():
+        if not isinstance(sheet_name, str) or not sheet_name.strip():
+            continue
+        table.add_row(str(sheet_name), str(description))
+
+    console.print(table)
+
+
+@archives_app.command("exec")
+def exec_archive(
+    archive_id: int = typer.Argument(..., help="Archive ID (e.g. 34 for I90DIA)"),
+    sheet: str = typer.Option(..., "--sheet", help="Sheet name (e.g. I90DIA03, I90DIA26)"),
+    date: Optional[str] = typer.Option(None, "--date", "-d", help="Single date (YYYY-MM-DD)"),
+    start: Optional[str] = typer.Option(None, "--start", "-s", help="Start date (YYYY-MM-DD)"),
+    end: Optional[str] = typer.Option(None, "--end", "-e", help="End date (YYYY-MM-DD)"),
+    expr: str = typer.Option("df", "--expr", "-x", help="Python expression to evaluate (df, pd, np available)"),
+    format: str = typer.Option("table", "--format", "-f", help="Output format: table, csv, json"),
+    output: Optional[str] = typer.Option(None, "--output", "-o", help="Output file path"),
+    token: Optional[str] = typer.Option(None, "--token", "-t"),
+):
+    """Parse archive files and evaluate a Python expression on the data.
+
+    Downloads archive files (cached), parses the specified sheet from each
+    file using I90Book, concatenates the DataFrames, and evaluates the
+    expression. The parsed data is available as `df` (pandas DataFrame).
+    `pd` (pandas) and `np` (numpy) are also available.
+
+    \b
+    Examples:
+        # Show curtailment data for a single day
+        esios archives exec 34 --sheet I90DIA03 --date 2025-06-01
+
+        # Curtailment by technology over a month
+        esios archives exec 34 --sheet I90DIA03 -s 2025-05-05 -e 2025-06-08 \\
+          -x "df[df['Sentido']=='Bajar'].groupby('Tecnología')['value'].sum().sort_values()"
+
+        # Export PBF generation program to CSV
+        esios archives exec 34 --sheet I90DIA26 --date 2025-06-01 -f csv -o pbf.csv
+
+        # Descriptive statistics
+        esios archives exec 34 --sheet I90DIA03 --date 2025-06-01 -x "df.describe()"
+    """
+    import numpy as np
+    import pandas as pd
+
+    from esios.processing.i90 import I90Book
+
+    files = _download_files(archive_id, token, date, start, end)
+
+    # Parse all files and extract the requested sheet
+    all_dfs = []
+    for f in files:
+        try:
+            book = I90Book(f)
+            s = book[sheet]
+            if s.df is not None and not s.df.empty:
+                all_dfs.append(s.df.reset_index())
+        except KeyError:
+            # Sheet not found — show available sheets
+            try:
+                book = I90Book(f)
+                available = list(book.table_of_contents.keys())
+            except Exception:
+                available = []
+            typer.echo(f"Sheet '{sheet}' not found in {f.name}.", err=True)
+            if available:
+                typer.echo(f"Available sheets: {', '.join(str(s) for s in available)}", err=True)
+            raise typer.Exit(1)
+        except Exception as exc:
+            typer.echo(f"Warning: skipping {f.name}: {exc}", err=True)
+            continue
+
+    if not all_dfs:
+        typer.echo("No data extracted from the specified sheet.", err=True)
+        raise typer.Exit(1)
+
+    df = pd.concat(all_dfs, ignore_index=True)
+
+    # Evaluate expression
+    namespace = {"df": df, "pd": pd, "np": np}
+    try:
+        result = eval(expr, {"__builtins__": {}}, namespace)  # noqa: S307
+    except Exception as exc:
+        typer.echo(f"Error evaluating expression: {exc}", err=True)
+        raise typer.Exit(1)
+
+    # Render output — reuse _render from exec_cmd
+    from esios.cli.exec_cmd import _render
+
+    _render(result, format, output)

{python_esios-2.0.1 → python_esios-2.1.0}/src/esios/managers/indicators.py

@@ -385,6 +385,11 @@ class IndicatorsManager(BaseManager):
         indicator = Indicator.from_api(raw)
         handle = IndicatorHandle(self, indicator)
 
+        # Enrich geos from values returned in metadata response.
+        # Some indicators (e.g. province-level breakdown) have an empty
+        # "geos" field in the metadata but geo_id/geo_name in the values.
+        handle._enrich_geo_map(raw.get("values", []))
+
         # Persist metadata and geos
         if cache.config.enabled:
             handle._persist_meta()

{python_esios-2.0.1 → python_esios-2.1.0}/src/esios/processing/i90.py

@@ -30,7 +30,7 @@ def _get_idx_column_start(columns: np.ndarray) -> int:
 
 def _any_value_greater_than_30(series: np.ndarray) -> bool:
     """Check if any numeric value exceeds 30 (quarter-hourly indicator)."""
-    return any(v > 30 for v in series if isinstance(v, (int, float)) and not np.isnan(v))
+    return any(v > 30 for v in series if isinstance(v, (int, float, np.integer, np.floating)) and not np.isnan(v))
 
 
 class I90Book:
@@ -164,15 +164,36 @@ class I90Sheet:
         return arr
 
     def _normalize_datetime_columns(self, columns: np.ndarray) -> np.ndarray:
-        """Normalize time column headers to integer period indices."""
+        """Normalize time column headers to integer period indices.
+
+        Handles three column formats found in I90 files:
+        - Sequential integers 1–24 (hourly) or 1–96 (quarterly)
+        - H-Q format with dash notation: "1-1", "1-2", "1-3", "1-4", "2-1", …
+        - NaN-filler format: [1, NaN, NaN, NaN, 2, …] (one label per hour,
+          three trailing NaNs for quarters 2–4)
+        """
         if any(pd.isna(columns)):
             self._n_columns_totals = 3
         else:
             self._n_columns_totals = 2
 
         series = pd.Series(columns, dtype=str).ffill()
-        series = series.str.split("-").str[0]
-        return series.astype(float).astype(int).values
+        parts = series.str.split("-")
+        hours = parts.str[0].astype(float).astype(int)
+
+        # H-Q format: any column carries an explicit quarter suffix (e.g. "1-2")
+        if (parts.str.len() > 1).any():
+            quarters = parts.apply(
+                lambda x: int(x[1]) if len(x) > 1 and str(x[1]).isdigit() else 1
+            )
+            return ((hours - 1) * 4 + quarters).values
+
+        # NaN-filler quarterly format: after ffill the same hour number repeats
+        # four times (quarters share the hour label).  Assign sequential indices.
+        if hours.duplicated().any():
+            return np.arange(1, len(hours) + 1)
+
+        return hours.values
 
     def _preprocess_double_index(
         self, idx: int, columns: np.ndarray

python_esios-2.1.0/tests/test_i90.py

@@ -0,0 +1,167 @@
+"""Tests for I90 file processing — frequency detection and column normalisation."""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock
+
+import numpy as np
+import pytest
+
+from esios.processing.i90 import I90Sheet, _any_value_greater_than_30
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_sheet() -> I90Sheet:
+    """Return a bare I90Sheet instance backed by mocked objects."""
+    wb = MagicMock()
+    sheet = MagicMock()
+    sheet.to_python.return_value = [[""]]
+    wb.get_sheet_by_name.return_value = sheet
+    return I90Sheet("test", wb, "I90DIA_20241001.xls", {})
+
+
+def _full_nan_filler_columns(n_hours: int = 24) -> np.ndarray:
+    """Build NaN-filler quarterly columns: [1, NaN, NaN, NaN, 2, NaN, …]."""
+    cols: list = []
+    for h in range(1, n_hours + 1):
+        cols.append(h)
+        cols.extend([np.nan, np.nan, np.nan])
+    return np.array(cols, dtype=object)
+
+
+def _full_hq_columns(n_hours: int = 24) -> np.ndarray:
+    """Build explicit H-Q columns: ['1-1', '1-2', '1-3', '1-4', '2-1', …]."""
+    return np.array(
+        [f"{h}-{q}" for h in range(1, n_hours + 1) for q in range(1, 5)],
+        dtype=object,
+    )
+
+
+def _mixed_hq_columns(n_hours: int = 24) -> np.ndarray:
+    """First quarter is unlabelled ('1', '2', …); rest carry '-Q' suffix."""
+    cols: list = []
+    for h in range(1, n_hours + 1):
+        cols.append(str(h))
+        for q in range(2, 5):
+            cols.append(f"{h}-{q}")
+    return np.array(cols, dtype=object)
+
+
+# ---------------------------------------------------------------------------
+# _any_value_greater_than_30
+# ---------------------------------------------------------------------------
+
+
+class TestAnyValueGreaterThan30:
+    def test_returns_true_for_value_above_30(self):
+        assert _any_value_greater_than_30(np.array([1, 31, 24])) is True
+
+    def test_returns_false_for_all_values_24_or_less(self):
+        assert _any_value_greater_than_30(np.arange(1, 25)) is False
+
+    def test_works_with_numpy_int64(self):
+        """numpy 2.x broke isinstance(np.int64, int) — make sure we handle it."""
+        arr = np.array([1, 2, 31, 96], dtype=np.int64)
+        assert _any_value_greater_than_30(arr) is True
+
+    def test_ignores_nan(self):
+        arr = np.array([np.nan, 5.0, 20.0])
+        assert _any_value_greater_than_30(arr) is False
+
+    def test_sequential_quarterly_1_to_96(self):
+        assert _any_value_greater_than_30(np.arange(1, 97)) is True
+
+
+# ---------------------------------------------------------------------------
+# _normalize_datetime_columns — hourly (unchanged behaviour)
+# ---------------------------------------------------------------------------
+
+
+class TestNormalizeHourly:
+    def test_sequential_1_to_24(self):
+        s = _make_sheet()
+        cols = np.array([float(i) for i in range(1, 25)], dtype=object)
+        result = s._normalize_datetime_columns(cols)
+        assert list(result) == list(range(1, 25))
+        assert not _any_value_greater_than_30(result)
+
+    def test_n_columns_totals_is_2_when_no_nan(self):
+        s = _make_sheet()
+        cols = np.array([float(i) for i in range(1, 25)], dtype=object)
+        s._normalize_datetime_columns(cols)
+        assert s._n_columns_totals == 2
+
+
+# ---------------------------------------------------------------------------
+# _normalize_datetime_columns — quarterly (new behaviour)
+# ---------------------------------------------------------------------------
+
+
+class TestNormalizeQuarterlySequential:
+    """Columns already in 1–96 sequential form (already worked before the fix)."""
+
+    def test_sequential_1_to_96(self):
+        s = _make_sheet()
+        cols = np.array([float(i) for i in range(1, 97)], dtype=object)
+        result = s._normalize_datetime_columns(cols)
+        assert list(result) == list(range(1, 97))
+        assert _any_value_greater_than_30(result)
+
+
+class TestNormalizeQuarterlyHQFormat:
+    """Columns in explicit 'H-Q' dash notation: '1-1', '1-2', …, '24-4'."""
+
+    def test_full_day_96_periods(self):
+        s = _make_sheet()
+        result = s._normalize_datetime_columns(_full_hq_columns())
+        assert len(result) == 96
+        assert list(result) == list(range(1, 97))
+        assert _any_value_greater_than_30(result)
+
+    def test_time_deltas_are_correct(self):
+        """period 1 → 0 min (00:00), period 96 → 1425 min (23:45)."""
+        s = _make_sheet()
+        result = s._normalize_datetime_columns(_full_hq_columns())
+        time_deltas = (result - 1) * 15
+        assert time_deltas[0] == 0
+        assert time_deltas[-1] == 1425
+
+    def test_mixed_hq_first_quarter_unlabelled(self):
+        """'1', '1-2', '1-3', '1-4', '2', '2-2', … is treated the same."""
+        s = _make_sheet()
+        result = s._normalize_datetime_columns(_mixed_hq_columns())
+        assert len(result) == 96
+        assert list(result) == list(range(1, 97))
+        assert _any_value_greater_than_30(result)
+
+    def test_n_columns_totals_is_2_for_explicit_hq(self):
+        s = _make_sheet()
+        s._normalize_datetime_columns(_full_hq_columns())
+        assert s._n_columns_totals == 2
+
+
+class TestNormalizeQuarterlyNaNFiller:
+    """Columns in NaN-filler form: [1, NaN, NaN, NaN, 2, NaN, …]."""
+
+    def test_full_day_96_periods(self):
+        s = _make_sheet()
+        result = s._normalize_datetime_columns(_full_nan_filler_columns())
+        assert len(result) == 96
+        assert list(result) == list(range(1, 97))
+        assert _any_value_greater_than_30(result)
+
+    def test_time_deltas_are_correct(self):
+        s = _make_sheet()
+        result = s._normalize_datetime_columns(_full_nan_filler_columns())
+        time_deltas = (result - 1) * 15
+        assert time_deltas[0] == 0
+        assert time_deltas[-1] == 1425
+
+    def test_n_columns_totals_is_3_when_nan_present(self):
+        s = _make_sheet()
+        s._normalize_datetime_columns(_full_nan_filler_columns())
+        assert s._n_columns_totals == 3

{python_esios-2.0.1 → python_esios-2.1.0}/tests/test_managers.py

@@ -58,13 +58,20 @@ class TestIndicatorsManager:
 
 
 class TestArchivesManager:
-    def test_list(self, client, mock_httpx, sample_archives_list_response):
+    def test_list_local(self, client):
+        """Default list() returns static catalog (153 archives)."""
+        df = client.archives.list()
+        assert isinstance(df, pd.DataFrame)
+        assert len(df) == 153
+
+    def test_list_api(self, client, mock_httpx, sample_archives_list_response):
+        """list(source='api') queries the ESIOS API."""
         response = MagicMock()
         response.status_code = 200
         response.json.return_value = sample_archives_list_response
         mock_httpx.get.return_value = response
 
-        df = client.archives.list()
+        df = client.archives.list(source="api")
         assert isinstance(df, pd.DataFrame)
         assert len(df) == 2
 
@@ -165,6 +172,53 @@ class TestIndicatorsCaching:
         assert "1" in geos
         assert geos["1"] == "Portugal"
 
+    def test_get_enriches_geos_from_values_when_metadata_geos_empty(
+        self, cached_client, mock_httpx,
+    ):
+        """indicators.get() should populate geos from values when metadata geos is empty.
+
+        Reproduces the bug reported for indicators with province-level breakdown
+        (e.g. indicator 1161) where the API returns ``"geos": []`` in the
+        metadata field but each value carries ``geo_id`` / ``geo_name``.
+        """
+        indicator_response = {
+            "indicator": {
+                "id": 1161,
+                "name": "Generación medida Solar fotovoltaica",
+                "geos": [],
+                "values": [
+                    {
+                        "value": 100.0,
+                        "datetime": "2025-01-01T00:00:00.000+01:00",
+                        "datetime_utc": "2024-12-31T23:00:00Z",
+                        "tz_time": "2025-01-01T00:00:00.000+01:00",
+                        "geo_id": 4,
+                        "geo_name": "Almería",
+                    },
+                    {
+                        "value": 200.0,
+                        "datetime": "2025-01-01T00:00:00.000+01:00",
+                        "datetime_utc": "2024-12-31T23:00:00Z",
+                        "tz_time": "2025-01-01T00:00:00.000+01:00",
+                        "geo_id": 5,
+                        "geo_name": "Cádiz",
+                    },
+                ],
+            }
+        }
+        response = MagicMock()
+        response.status_code = 200
+        response.json.return_value = indicator_response
+        mock_httpx.get.return_value = response
+
+        handle = cached_client.indicators.get(1161)
+
+        # geos must be populated even though the metadata field was empty
+        assert len(handle.geos) == 2
+        geo_ids = {g["geo_id"] for g in handle.geos}
+        assert 4 in geo_ids
+        assert 5 in geo_ids
+
     def test_enrich_geo_map_persists(
         self, cached_client, mock_httpx,
     ):

python_esios-2.0.1/src/esios/cli/archives.py

@@ -1,66 +0,0 @@
-"""CLI subcommands for archives."""
-
-from __future__ import annotations
-
-from typing import Optional
-
-import typer
-from rich.console import Console
-from rich.table import Table
-
-archives_app = typer.Typer(no_args_is_help=True)
-console = Console()
-
-
-@archives_app.command("list")
-def list_archives(
-    token: Optional[str] = typer.Option(None, "--token", "-t"),
-    format: str = typer.Option("table", "--format", "-f"),
-):
-    """List all available ESIOS archives."""
-    from esios.cli.app import get_client
-
-    client = get_client(token)
-    df = client.archives.list()
-
-    if format == "csv":
-        typer.echo(df.to_csv())
-    elif format == "json":
-        typer.echo(df.to_json(orient="records", indent=2))
-    else:
-        table = Table(title="ESIOS Archives")
-        cols = list(df.columns)[:8]
-        for col in cols:
-            table.add_column(str(col))
-        for _, row in df.head(50).iterrows():
-            table.add_row(*[str(row[c]) for c in cols])
-        if len(df) > 50:
-            table.caption = f"Showing 50 of {len(df)} rows"
-        console.print(table)
-
-
-@archives_app.command("download")
-def download_archive(
-    archive_id: int = typer.Argument(..., help="Archive ID"),
-    start: Optional[str] = typer.Option(None, "--start", "-s", help="Start date (YYYY-MM-DD)"),
-    end: Optional[str] = typer.Option(None, "--end", "-e", help="End date (YYYY-MM-DD)"),
-    date: Optional[str] = typer.Option(None, "--date", "-d", help="Single date (YYYY-MM-DD)"),
-    output: str = typer.Option(".", "--output", "-o", help="Output directory"),
-    token: Optional[str] = typer.Option(None, "--token", "-t"),
-):
-    """Download an archive for a date or date range."""
-    from esios.cli.app import get_client
-
-    if not date and not (start and end):
-        typer.echo("Provide --date or both --start and --end.", err=True)
-        raise typer.Exit(1)
-
-    client = get_client(token)
-    client.archives.download(
-        archive_id,
-        start=start,
-        end=end,
-        date=date,
-        output_dir=output,
-    )
-    typer.echo(f"Download complete → {output}")