python-esios 2.0.0__py3-none-any.whl → 2.0.2__py3-none-any.whl

esios/.agents/skills/esios/SKILL.md

@@ -0,0 +1,207 @@
+---
+name: esios
+description: Query Spanish electricity market data (ESIOS/REE). Use when the user asks about electricity prices, generation, demand, I90 files, or any ESIOS indicator.
+version: 2.0.0
+---
+
+# ESIOS Data Assistant
+
+You have access to the `python-esios` CLI and library for querying the Spanish electricity market (ESIOS/REE).
+
+## CLI Reference
+
+### Indicators
+
+```bash
+# List all indicators
+esios indicators list
+
+# Search by name
+esios indicators search "precio"
+
+# Show metadata (unit, granularity, geographies)
+esios indicators meta 600
+
+# Historical data
+esios indicators history 600 --start 2025-01-01 --end 2025-01-31
+esios indicators history 600 -s 2025-01-01 -e 2025-01-31 --format csv --output data.csv
+esios indicators history 600 -s 2025-01-01 -e 2025-01-31 --format parquet --output data.parquet
+
+# Filter by geography (ID or name)
+esios indicators history 600 -s 2025-01-01 -e 2025-01-31 --geo España
+esios indicators history 600 -s 2025-01-01 -e 2025-01-31 --geo 3
+
+# Ad-hoc pandas expressions on fetched data
+esios indicators exec 600 -s 2025-01-01 -e 2025-01-31 --expr "df.describe()"
+esios indicators exec 600 -s 2025-01-01 -e 2025-01-31 --expr "df.resample('D').mean()"
+```
+
+### Archives
+
+```bash
+# List all available archives
+esios archives list
+
+# 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
+
+```bash
+esios cache status    # Path, size, geos registry, catalog info
+esios cache geos      # Global geo_id → geo_name registry
+esios cache path      # Print cache directory
+esios cache clear     # Clear indicator cache
+esios cache clear --all  # Clear everything (indicators, archives, geos, catalog)
+esios cache clear --indicator 600  # Clear one indicator
+```
+
+### Configuration
+
+```bash
+esios config set token <API_KEY>
+esios config show
+```
+
+## Common Indicator IDs
+
+| ID | Name | Description | Geos |
+|----|------|-------------|------|
+| 600 | Precio mercado spot | OMIE spot market price | ES, PT, FR, DE, BE, NL |
+| 1001 | Precio mercado diario | Day-ahead market price | ES |
+| 10033 | Demanda real | Real-time electricity demand | ES |
+| 10034 | Generación eólica | Real-time wind generation | ES |
+| 10035 | Generación solar FV | Real-time solar PV generation | ES |
+| 1293 | Demanda prevista | Forecasted demand | ES |
+
+Use `esios indicators search "query"` to find more. Use `esios indicators meta <id>` to see full metadata including geographies and units.
+
+## Multi-Geo Indicators
+
+Some indicators (e.g. 600) return data for multiple countries. The output is pivoted so each geography becomes a column:
+
+```
+datetime                España  Portugal  Francia  Alemania  Bélgica  Países Bajos
+2025-01-01 00:00:00     63.50    63.50     72.10    58.20     58.20     58.20
+2025-01-01 01:00:00     55.80    55.80     60.30    48.90     48.90     48.90
+```
+
+Filter to specific geos with `--geo`:
+```bash
+esios indicators history 600 -s 2025-01-01 -e 2025-01-07 --geo España --geo Portugal
+```
+
+## Geography Reference
+
+| geo_id | geo_name |
+|--------|----------|
+| 1 | Portugal |
+| 2 | Francia |
+| 3 | España |
+| 8826 | Alemania |
+| 8827 | Bélgica |
+| 8828 | Países Bajos |
+
+The `--geo` flag accepts both IDs and names (case-insensitive substring match):
+- `--geo 3` or `--geo España` or `--geo españa`
+- `--geo "Países Bajos"` or `--geo 8828`
+
+## Python Library
+
+```python
+from esios import ESIOSClient
+
+client = ESIOSClient()  # reads config file, then ESIOS_API_KEY env var
+
+# Get indicator handle
+handle = client.indicators.get(600)
+
+# Historical data as DataFrame
+df = handle.historical("2025-01-01", "2025-01-31")
+
+# Filter by geo
+df = handle.historical("2025-01-01", "2025-01-31", geo_ids=[3])  # España only
+
+# Inspect geographies
+handle.geos             # List of {"geo_id": int, "geo_name": str}
+handle.geos_dataframe() # DataFrame with geo_id and geo_name columns
+handle.resolve_geo("España")  # Returns 3
+
+# Search and compare
+results = client.indicators.search("precio")
+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 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")
+
+# Access a sheet
+book = books[0]
+sheet = book["I90DIA03"]
+df = sheet.df             # Preprocessed DataFrame with datetime index
+print(sheet.frequency)    # "hourly" or "hourly-quarterly"
+```
+
+## Caching Behavior
+
+- Data is cached locally as parquet files (`~/.cache/esios/`)
+- Each indicator gets its own directory: `indicators/{id}/data.parquet`
+- Indicator metadata cached in `indicators/{id}/meta.json` (7-day TTL)
+- Indicator catalog cached in `indicators/catalog.json` (24h TTL)
+- Global geo registry at `geos.json` (persisted forever, grows incrementally)
+- Data older than 48h is considered final (won't be re-fetched)
+- Recent data (last 48h) is re-fetched on each request (electricity market corrections)
+- Cache is per-column sparse: fetching `--geo España` only caches that column
+
+## Key Conventions
+
+- All timestamps are in Europe/Madrid timezone
+- Date ranges > 3 weeks are auto-chunked into smaller API requests
+- Archives support skip-existing (won't re-download cached files)
+- I90 sheets detect hourly vs quarter-hourly frequency automatically
+- API token resolution: config file (`~/.config/esios/config.toml`) > `ESIOS_API_KEY` env var
+- Custom exceptions: `ESIOSError`, `AuthenticationError`, `APIResponseError`, `NetworkError`

esios/cli/archives.py

@@ -64,3 +64,154 @@ def download_archive(
         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)

esios/data/catalogs/archives/__init__.py

@@ -0,0 +1,5 @@
+"""Archives catalog — static reference of all known ESIOS archives."""
+
+from esios.data.catalogs.archives.catalog import ARCHIVES_CATALOG
+
+__all__ = ["ARCHIVES_CATALOG"]

esios/data/catalogs/archives/catalog.py

@@ -0,0 +1,163 @@
+"""Static catalog of ESIOS archives.
+
+Auto-generated by refresh.py — do not edit manually.
+"""
+
+from __future__ import annotations
+
+ARCHIVES_CATALOG: dict[int, dict[str, str]] = {
+    2: {"name": "A1_liquicomun", "description": "Avance de liquidación A1", "horizon": "M", "archive_type": "zip"},
+    3: {"name": "A2_liquicomun", "description": "Avance de liquidación A2", "horizon": "M", "archive_type": "zip"},
+    8: {"name": "C2_liquicomun", "description": "Cierre de liquidación C2", "horizon": "M", "archive_type": "zip"},
+    9: {"name": "C3_liquicomun", "description": "Cierre de liquidación C3", "horizon": "M", "archive_type": "zip"},
+    10: {"name": "C4_liquicomun", "description": "Cierre de liquidación C4", "horizon": "M", "archive_type": "zip"},
+    11: {"name": "C5_liquicomun", "description": "Cierre de liquidación C5", "horizon": "M", "archive_type": "zip"},
+    12: {"name": "C6_liquicomun", "description": "Cierre de liquidación C6", "horizon": "M", "archive_type": "zip"},
+    13: {"name": "C7_liquicomun", "description": "Cierre de liquidación C7", "horizon": "M", "archive_type": "zip"},
+    14: {"name": "C8_liquicomun", "description": "Cierre de liquidación C8", "horizon": "M", "archive_type": "zip"},
+    15: {"name": "hemeroteca_DD_ent", "description": "Fichero de hemeroteca de entrada.", "horizon": "D", "archive_type": "zip"},
+    16: {"name": "hemeroteca_DD_sal", "description": "Fichero de hemeroteca de salida", "horizon": "D", "archive_type": "zip"},
+    17: {"name": "liquicierre", "description": "Resultados de la Regulación Secundaria exigidos para la Liquidación", "horizon": "D", "archive_type": "xml"},
+    18: {"name": "totalpdbf", "description": "Programa agregado resultante del PBF", "horizon": "D", "archive_type": "xml"},
+    19: {"name": "totalrpdvpprec", "description": "Solución de Restricciones Técnicas", "horizon": "D", "archive_type": "xml"},
+    20: {"name": "totalpdvp", "description": "PVP Agregado Horizonte Diario", "horizon": "D", "archive_type": "xml"},
+    21: {"name": "totalasigsec", "description": "Asignación Regulación Secundaria", "horizon": "D", "archive_type": "xml"},
+    22: {"name": "totalrpibcirest", "description": "Solución de Restricciones Técnicas MI", "horizon": "H", "archive_type": "xml"},
+    23: {"name": "totalasigdesv", "description": "Mercado de Gestión de Desvíos", "horizon": "H", "archive_type": "xml"},
+    24: {"name": "totalasigter", "description": "Mercado de Regulación Terciaria", "horizon": "D", "archive_type": "xml"},
+    25: {"name": "totalenersec", "description": "Energía Secundaria utilizada", "horizon": "D", "archive_type": "xml"},
+    26: {"name": "totalliquicierre", "description": "Cálculo Variación Coste Fijo", "horizon": "D", "archive_type": "xml"},
+    27: {"name": "totalrp48prec", "description": "Redespachos Seguridad Tiempo Real (Horario)", "horizon": "H", "archive_type": "xml"},
+    28: {"name": "totalrp48preccierre", "description": "Redespachos Seguridad Tiempo Real (Cierre)", "horizon": "D", "archive_type": "xml"},
+    29: {"name": "totalp48", "description": "Programa Agregado P48 (Horario)", "horizon": "H", "archive_type": "xml"},
+    30: {"name": "totalp48cierre", "description": "Programa Agregado P48 (Cierre)", "horizon": "D", "archive_type": "xml"},
+    32: {"name": "I3DIA", "description": "Información agregada diaria por tecnología (I3DIA)", "horizon": "D", "archive_type": "zip"},
+    33: {"name": "IMES", "description": "Cuotas mensuales por Sujetos de Liquidación (IMES)", "horizon": "M", "archive_type": "zip"},
+    34: {"name": "I90DIA", "description": "Información de detalle por Unidad de Programación (I90DIA)", "horizon": "D", "archive_type": "zip"},
+    35: {"name": "COEF_PERD_PEN_MM", "description": "Coeficientes horarios de pérdidas en el sistema peninsular", "horizon": "M", "archive_type": "xls"},
+    36: {"name": "COEF_PERD_MEL_MM", "description": "Coeficientes horarios de pérdidas en el sistema de Melilla", "horizon": "M", "archive_type": "xls"},
+    37: {"name": "COEF_PERD_CEU_MM", "description": "Coeficientes horarios de pérdidas en el sistema de Ceuta", "horizon": "M", "archive_type": "xls"},
+    38: {"name": "COEF_PERD_CAN_MM", "description": "Coeficientes horarios de pérdidas en el sistema de Canarias", "horizon": "M", "archive_type": "xls"},
+    39: {"name": "COEF_PERD_BAL_MM", "description": "Coeficientes horarios de pérdidas en el sistema de Baleares", "horizon": "M", "archive_type": "xls"},
+    40: {"name": "COEF_KEST_MM", "description": "Coeficiente de ajuste horario estimado en el sistema peninsular y no peninsular", "horizon": "M", "archive_type": "xls"},
+    42: {"name": "Espec_Subasta_Diaria_EF", "description": "Especificación de subastas explícitas Diarias de capacidad en la interconexión con Francia", "horizon": "D", "archive_type": "pdf"},
+    43: {"name": "Espec_Subasta_Diaria_FE", "description": "Especificación de subastas explícitas Diarias de capacidad en la interconexión con Francia", "horizon": "D", "archive_type": "pdf"},
+    44: {"name": "Espec_Subasta_Intra1_EF", "description": "Especificación de subastas explícitas Intradiarias 1 de capacidad en la interconexión con Francia", "horizon": "D", "archive_type": "pdf"},
+    45: {"name": "Espec_Subasta_Intra1_FE", "description": "Especificación de subastas explícitas Intradiarias 1 de capacidad en la interconexión con Francia", "horizon": "D", "archive_type": "pdf"},
+    46: {"name": "Espec_Subasta_Intra2_EF", "description": "Especificación de subastas explícitas Intradiarias 2 de capacidad en la interconexión con Francia", "horizon": "D", "archive_type": "pdf"},
+    47: {"name": "Espec_Subasta_Intra2_FE", "description": "Especificación de subastas explícitas Intradiarias 2 de capacidad en la interconexión con Francia", "horizon": "D", "archive_type": "pdf"},
+    48: {"name": "Espec_Subasta_Mensual_EF", "description": "Especificación de subastas explícitas Mensuales de capacidad en la interconexión con Francia", "horizon": "M", "archive_type": "pdf"},
+    49: {"name": "Espec_Subasta_Mensual_FE", "description": "Especificación de subastas explícitas Mensuales de capacidad en la interconexión con Francia", "horizon": "M", "archive_type": "pdf"},
+    50: {"name": "Espec_Subasta_Anual_EF", "description": "Especificación de subastas explícitas Anuales de capacidad en la interconexión con Francia", "horizon": "A", "archive_type": "pdf"},
+    51: {"name": "Espec_Subasta_Anual_FE", "description": "Especificación de subastas explícitas Anuales de capacidad en la interconexión con Francia", "horizon": "A", "archive_type": "pdf"},
+    56: {"name": "Espec_Subasta_Intra2_EF_Cancel", "description": "Especificación de subastas explícitas Intradiarias 2 de capacidad en la interconexión con Francia", "horizon": "D", "archive_type": "pdf"},
+    57: {"name": "Espec_Subasta_Intra2_FE_Cancel", "description": "Especificación de subastas explícitas Intradiarias 2 de capacidad en la interconexión con Francia", "horizon": "D", "archive_type": "pdf"},
+    58: {"name": "Espec_Subasta_Mensual_EF_Cancel", "description": "Especificación de subastas explícitas Mensuales de capacidad en la interconexión con Francia", "horizon": "M", "archive_type": "pdf"},
+    59: {"name": "Espec_Subasta_Mensual_FE_Cancel", "description": "Especificación de subastas explícitas Mensuales de capacidad en la interconexión con Francia", "horizon": "M", "archive_type": "pdf"},
+    62: {"name": "IND_DemandaInterrumpible", "description": "IND_DemandaInterrumpible", "horizon": "D", "archive_type": "json"},
+    63: {"name": "IND_Interconexiones", "description": "IND_Interconexiones", "horizon": "D", "archive_type": "json"},
+    64: {"name": "IND_PotenciaInstalada", "description": "IND_PotenciaInstalada", "horizon": "M", "archive_type": "json"},
+    65: {"name": "IND_PrecioDesvios", "description": "IND_PrecioDesvios", "horizon": "D", "archive_type": "json"},
+    66: {"name": "IND_PrecioFinal", "description": "IND_PrecioFinal", "horizon": "D", "archive_type": "json"},
+    67: {"name": "IND_Umbrales", "description": "IND_Umbrales", "horizon": "D", "archive_type": "json"},
+    68: {"name": "INF_SUBASTA_AA", "description": "Informe anual de subastas de capacidad con Francia", "horizon": "A", "archive_type": "pdf"},
+    69: {"name": "INF_SUBASTA_MM", "description": "Informe mensual de subastas de capacidad con Francia", "horizon": "M", "archive_type": "pdf"},
+    70: {"name": "PVPC_CURV_DD", "description": "Datos origen de curva PVPC", "horizon": "D", "archive_type": "json"},
+    71: {"name": "PVPC_DETALLE_DD", "description": "PVPC Término de facturación energía activa – Desglose", "horizon": "D", "archive_type": "xls"},
+    72: {"name": "PVPC_GEN_P1_DD", "description": "Datos origen de tarifa general P1", "horizon": "D", "archive_type": "json"},
+    73: {"name": "PVPC_NOC_P1_DD", "description": "Datos origen de tarifa nocturna P1", "horizon": "D", "archive_type": "json"},
+    74: {"name": "PVPC_NOC_P2_DD", "description": "Datos origen de tarifa nocturna P2", "horizon": "D", "archive_type": "json"},
+    75: {"name": "PVPC_VHC_P1_DD", "description": "Datos origen de tarifa vehículo eléctrico P1", "horizon": "D", "archive_type": "json"},
+    76: {"name": "PVPC_VHC_P2_DD", "description": "Datos origen de tarifa vehículo eléctrico P2", "horizon": "D", "archive_type": "json"},
+    77: {"name": "PVPC_VHC_P3_DD", "description": "Datos origen de tarifa vehículo eléctrico P3", "horizon": "D", "archive_type": "json"},
+    78: {"name": "perfilconsumo", "description": "PVPC Coeficientes de perfilado", "horizon": "S", "archive_type": "xml"},
+    79: {"name": "preciovoluntariopconsumidor", "description": "PVPC por ciclo de lectura", "horizon": "D", "archive_type": "xml"},
+    80: {"name": "pvpcdesglosehorario", "description": "PVPC Término de facturación energía activa", "horizon": "D", "archive_type": "xml"},
+    81: {"name": "UnidadesFisicas", "description": "Datos Estructurales de unidades físicas", "horizon": "NA", "archive_type": "json"},
+    82: {"name": "UnidadesProgramacion", "description": "Datos estructurales de unidades de programación", "horizon": "NA", "archive_type": "json"},
+    83: {"name": "SujetosMercado", "description": "Datos estructurales de sujetos de mercado", "horizon": "NA", "archive_type": "json"},
+    84: {"name": "ParticipantesSubasta", "description": "Datos estructurales de participantes de subasta", "horizon": "NA", "archive_type": "json"},
+    87: {"name": "Resultado_Subasta_Mensual_FRA", "description": "Subastas mensuales del calendariode subastas de Francia", "horizon": "M", "archive_type": "xls"},
+    88: {"name": "Resultado_Subasta_Anual_FRA", "description": "Subastas anuales del calendariode subastas de Francia", "horizon": "A", "archive_type": "xls"},
+    89: {"name": "Descargos_AND_Planificados", "description": "Descargos Andorra", "horizon": "O", "archive_type": "xml"},
+    91: {"name": "Descargos_MAR_Planificados", "description": "Descargos Marruecos", "horizon": "O", "archive_type": "xml"},
+    93: {"name": "Descargos_POR_Planificados", "description": "Descargos Portugal", "horizon": "O", "archive_type": "xml"},
+    95: {"name": "Descargos_FRA_Planificados", "description": "Descargos Francia", "horizon": "O", "archive_type": "xml"},
+    101: {"name": "REE_InterChangeAvailab_FRA", "description": "Cambios en disponibilidad real de capacidad en interconexión con Francia", "horizon": "O", "archive_type": "xml"},
+    102: {"name": "REE_InterChangeAvailab_POR", "description": "Cambios en disponibilidad real de capacidad en interconexión con Portugal", "horizon": "O", "archive_type": "xml"},
+    105: {"name": "Indisponibilidades", "description": "Indisponibilidades de las unidades de generación y consumo", "horizon": "D", "archive_type": "xls"},
+    106: {"name": "PlanesMantenimiento", "description": "Plan de mantenimiento", "horizon": "M", "archive_type": "xls"},
+    107: {"name": "p48cierre", "description": "Cierre de programa Desagregado P48", "horizon": "D", "archive_type": "xml"},
+    108: {"name": "REE_AggGenOutput", "description": "Generación real por tipo de producción", "horizon": "QM", "archive_type": "xml"},
+    109: {"name": "REE_ActualGenOutput", "description": "Generación real por unidad física", "horizon": "D", "archive_type": "xml"},
+    110: {"name": "GenerationUnits", "description": "Generation Units Structural Data", "horizon": "NA", "archive_type": "json"},
+    111: {"name": "ProgrammingUnits", "description": "Programming Units Structural Data", "horizon": "NA", "archive_type": "json"},
+    112: {"name": "BalanceResponsibleParties", "description": "Balance Responsible Parties Structural Data", "horizon": "NA", "archive_type": "json"},
+    113: {"name": "EntitledParticipants", "description": "Entitled Participants Structural Data", "horizon": "NA", "archive_type": "json"},
+    114: {"name": "IND_DemandaPrevProg", "description": "IND_DemandaPrevProg", "horizon": "D", "archive_type": "json"},
+    115: {"name": "IND_DemandaRealGen", "description": "IND_DemandaRealGen", "horizon": "D", "archive_type": "json"},
+    116: {"name": "IND_MaxMin", "description": "IND_MaxMin", "horizon": "D", "archive_type": "json"},
+    117: {"name": "IND_MaxMinRenovEol", "description": "IND_MaxMinRenovEol", "horizon": "D", "archive_type": "json"},
+    118: {"name": "ActividadesSubactividades", "description": "Informe de actividades y subactividades", "horizon": "NA", "archive_type": "pdf"},
+    119: {"name": "AgregacionesValidas", "description": "Informe de agregaciones válidas", "horizon": "NA", "archive_type": "pdf"},
+    120: {"name": "CNAEValidos", "description": "Informe de códigos CNAE válidos", "horizon": "NA", "archive_type": "pdf"},
+    121: {"name": "Comercializadores", "description": "Informe de comercializadores", "horizon": "NA", "archive_type": "pdf"},
+    122: {"name": "Concentradores", "description": "Informe de concentradores", "horizon": "NA", "archive_type": "pdf"},
+    123: {"name": "DiscriminacionHoraria", "description": "Informe de discriminaciones horarias", "horizon": "NA", "archive_type": "pdf"},
+    124: {"name": "Distribuidores", "description": "Informe de distribuidores", "horizon": "NA", "archive_type": "pdf"},
+    125: {"name": "Fabricantes", "description": "Informe de fabricantes", "horizon": "NA", "archive_type": "pdf"},
+    126: {"name": "Magnitudes", "description": "Informe de magnitudes", "horizon": "NA", "archive_type": "pdf"},
+    127: {"name": "ModeloContadores", "description": "Informe de modelo de contadores", "horizon": "NA", "archive_type": "pdf"},
+    128: {"name": "ModeloRegistradores", "description": "Informe de modelos de registradores", "horizon": "NA", "archive_type": "pdf"},
+    129: {"name": "ModeloTransformadores", "description": "Informe de modelo de transformadores", "horizon": "NA", "archive_type": "pdf"},
+    130: {"name": "NivelesTension", "description": "Informe de niveles de tensión", "horizon": "NA", "archive_type": "pdf"},
+    131: {"name": "Provincias", "description": "Informe de provincias", "horizon": "NA", "archive_type": "pdf"},
+    132: {"name": "Representantes", "description": "Informe de representantes", "horizon": "NA", "archive_type": "pdf"},
+    133: {"name": "Subsistemas", "description": "Informe de subsistemas", "horizon": "NA", "archive_type": "pdf"},
+    134: {"name": "ZonasGeograficas", "description": "Informe de zonas geográficas", "horizon": "NA", "archive_type": "pdf"},
+    135: {"name": "TarifaAcceso", "description": "Informe de tarifas de acceso", "horizon": "NA", "archive_type": "pdf"},
+    136: {"name": "A6_liquicomun", "description": "Avance de liquidación A6", "horizon": "M", "archive_type": "zip"},
+    137: {"name": "A7_liquicomun", "description": "Avance de liquidación A7", "horizon": "M", "archive_type": "zip"},
+    139: {"name": "IND_EnergiaMensual", "description": "IND_EnergiaMensual", "horizon": "M", "archive_type": "json"},
+    140: {"name": "IND_EnergiaAnual", "description": "IND_EnergiaAnual", "horizon": "A", "archive_type": "json"},
+    142: {"name": "ConsumidoresDirectos", "description": "Informe de Consumidores Directos", "horizon": "NA", "archive_type": "pdf"},
+    143: {"name": "MotivosObjecionEdLD", "description": "Informe de Motivos Objeción EdLD", "horizon": "NA", "archive_type": "pdf"},
+    144: {"name": "MotivosObjecionEdLOS", "description": "Informe de Motivos Objeción EdLOS", "horizon": "NA", "archive_type": "pdf"},
+    145: {"name": "TiposMedidaPuntoMedida", "description": "Informe de tipos de medida de punto medida", "horizon": "NA", "archive_type": "pdf"},
+    146: {"name": "TiposMedidaPuntoFrontera", "description": "Informe de tipos de medida de punto frontera", "horizon": "NA", "archive_type": "pdf"},
+    147: {"name": "Espec_Subasta_Mensual_EP", "description": "Especificación de subastas explícitas Mensuales de capacidad en la interconexión con Portugal", "horizon": "M", "archive_type": "pdf"},
+    148: {"name": "Espec_Subasta_Mensual_PE", "description": "Especificación de subastas explícitas Mensuales de capacidad en la interconexión con Portugal", "horizon": "M", "archive_type": "pdf"},
+    149: {"name": "Espec_Subasta_Trimestral_EP", "description": "Especificación de subastas explícitas Trimestrales de capacidad en la interconexión con Portugal", "horizon": "T", "archive_type": "pdf"},
+    150: {"name": "Espec_Subasta_Trimestral_PE", "description": "Especificación de subastas explícitas Trimestrales de capacidad en la interconexión con Portugal", "horizon": "T", "archive_type": "pdf"},
+    151: {"name": "Espec_Subasta_Anual_EP", "description": "Especificación de subastas explícitas Trimestrales de capacidad en la interconexión con Portugal", "horizon": "A", "archive_type": "pdf"},
+    152: {"name": "Espec_Subasta_Anual_PE", "description": "Especificación de subastas explícitas Trimestrales de capacidad en la interconexión con Portugal", "horizon": "A", "archive_type": "pdf"},
+    159: {"name": "Resultado_Subasta_Mensual_POR", "description": "Subastas mensuales del calendario de subastas de Portugal", "horizon": "M", "archive_type": "xls"},
+    160: {"name": "Resultado_Subasta_Anual_POR", "description": "Subastas anuales del calendario de subastas de Portugal", "horizon": "A", "archive_type": "xls"},
+    161: {"name": "Resultado_Subasta_Trimestral_POR", "description": "Subastas trimestrales del calendario de subastas de Portugal", "horizon": "T", "archive_type": "xls"},
+    164: {"name": "CodigosTensiones", "description": "Informe de códigos de tensiones de suministro", "horizon": "NA", "archive_type": "pdf"},
+    165: {"name": "UnidadesConsumoGeneracion", "description": "Informe de unidades de consumo de generación", "horizon": "NA", "archive_type": "pdf"},
+    166: {"name": "CodigosAutoconsumo", "description": "Informe de códigos de autoconsumo", "horizon": "NA", "archive_type": "pdf"},
+    167: {"name": "IND_PotenciaInstaladaNacional", "description": "IND_PotenciaInstaladaNacional", "horizon": "M", "archive_type": "json"},
+    168: {"name": "IND_EnergiaMensualNacional", "description": "IND_EnergiaMensualNacional", "horizon": "M", "archive_type": "json"},
+    169: {"name": "IND_EnergiaAnualNacional", "description": "IND_EnergiaAnualNacional", "horizon": "A", "archive_type": "json"},
+    170: {"name": "IND_CoeficientesCO2", "description": "IND_CoeficientesCO2", "horizon": "NA", "archive_type": "json"},
+    171: {"name": "IND_InformacionApp", "description": "IND_InformacionApp", "horizon": "NA", "archive_type": "json"},
+    172: {"name": "IND_PreguntasApp", "description": "IND_PreguntasApp", "horizon": "NA", "archive_type": "json"},
+    173: {"name": "IND_VersionApp", "description": "IND_VersionApp", "horizon": "NA", "archive_type": "json"},
+    174: {"name": "IND_PrecioMinorista", "description": "IND_PrecioMinorista", "horizon": "D", "archive_type": "json"},
+    181: {"name": "REE_BalancingEnerBids", "description": "Mercado de Regulación Terciaria", "horizon": "QM", "archive_type": "csv"},
+    183: {"name": "IND_EnergiaAnualAutoconsumoNacional", "description": "IND_EnergiaAnualAutoconsumoNacional", "horizon": "A", "archive_type": "json"},
+    184: {"name": "IND_EnergiaMensualAutoconsumoNacional", "description": "IND_EnergiaMensualAutoconsumoNacional", "horizon": "M", "archive_type": "json"},
+    185: {"name": "ActivacionesDelServicio", "description": "Activaciones del Servicio", "horizon": "NA", "archive_type": "json"},
+    186: {"name": "ServiceActivation", "description": "Service Activation", "horizon": "NA", "archive_type": "json"},
+    187: {"name": "C2_PrecioFinal", "description": "Precio final de la energía C2", "horizon": "M", "archive_type": "zip"},
+    188: {"name": "C5_PrecioFinal", "description": "Precio final de la energía C5", "horizon": "M", "archive_type": "zip"},
+    193: {"name": "IND_Novedades", "description": "IND_Novedades", "horizon": "NA", "archive_type": "json"},
+    194: {"name": "IND_Novedades_Paso1", "description": "Json lottie Paso1", "horizon": "NA", "archive_type": "json"},
+    195: {"name": "IND_Novedades_Paso2", "description": "Json lottie Paso2", "horizon": "NA", "archive_type": "json"},
+    196: {"name": "IND_Novedades_Paso3", "description": "Json lottie Paso3", "horizon": "NA", "archive_type": "json"},
+    197: {"name": "IND_Novedades_Paso4", "description": "Json lottie Paso3", "horizon": "NA", "archive_type": "json"},
+    198: {"name": "IND_Novedades_Step1", "description": "Json lottie Step1", "horizon": "NA", "archive_type": "json"},
+    199: {"name": "IND_Novedades_Step2", "description": "Json lottie Step2", "horizon": "NA", "archive_type": "json"},
+}
+

esios/data/catalogs/archives/refresh.py

@@ -0,0 +1,95 @@
+"""Refresh the static archives catalog by scanning the ESIOS API.
+
+Usage:
+    uv run python -m esios.data.catalogs.archives.refresh
+
+Scans archive IDs 1-200 against the live API and regenerates catalog.py.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+
+def scan_archives(max_id: int = 200) -> dict[int, dict[str, str]]:
+    """Scan ESIOS API for all accessible archives."""
+    from esios import ESIOSClient
+
+    client = ESIOSClient()
+    catalog: dict[int, dict[str, str]] = {}
+
+    for i in range(1, max_id + 1):
+        try:
+            data = client.get(f"archives/{i}")
+            a = data.get("archive", {})
+            catalog[i] = {
+                "name": a.get("name", ""),
+                "description": a.get("description", ""),
+                "horizon": a.get("horizon", ""),
+                "archive_type": a.get("archive_type", ""),
+            }
+        except Exception:
+            continue
+
+    return catalog
+
+
+def generate_catalog_py(catalog: dict[int, dict[str, str]]) -> str:
+    """Generate the catalog.py source code."""
+    lines = [
+        '"""Static catalog of ESIOS archives.',
+        "",
+        "Auto-generated by refresh.py — do not edit manually.",
+        '"""',
+        "",
+        "from __future__ import annotations",
+        "",
+        "ARCHIVES_CATALOG: dict[int, dict[str, str]] = {",
+    ]
+
+    for id_ in sorted(catalog):
+        entry = catalog[id_]
+        name = entry["name"]
+        desc = entry["description"].replace('"', '\\"')
+        horizon = entry["horizon"]
+        atype = entry["archive_type"]
+        lines.append(
+            f'    {id_}: {{"name": "{name}", "description": "{desc}", '
+            f'"horizon": "{horizon}", "archive_type": "{atype}"}},'
+        )
+
+    lines.append("}")
+    lines.append("")
+    return "\n".join(lines)
+
+
+def main() -> None:
+    from esios.data.catalogs.archives.catalog import ARCHIVES_CATALOG
+
+    old_ids = set(ARCHIVES_CATALOG.keys())
+
+    print(f"Scanning ESIOS API for archives (IDs 1-200)...")
+    catalog = scan_archives()
+    new_ids = set(catalog.keys())
+
+    # Diff summary
+    added = new_ids - old_ids
+    removed = old_ids - new_ids
+
+    print(f"\nFound {len(catalog)} archives (was {len(old_ids)})")
+    if added:
+        print(f"  Added: {sorted(added)}")
+    if removed:
+        print(f"  Removed: {sorted(removed)}")
+    if not added and not removed:
+        print("  No changes in archive IDs.")
+
+    # Write catalog.py
+    catalog_path = Path(__file__).parent / "catalog.py"
+    catalog_path.write_text(generate_catalog_py(catalog))
+    print(f"\nWrote {catalog_path}")
+
+
+if __name__ == "__main__":
+    main()

esios/managers/archives.py

@@ -76,20 +76,20 @@ class ArchiveHandle:
         date: str | None = None,
         output_dir: str | Path | None = None,
         date_type: str = "datos",
-    ) -> Path:
+    ) -> list[Path]:
         """Download archive files for a single date or date range.
 
         Files are always stored in the cache directory. If ``output_dir`` is
         provided, a copy is placed there as well.
 
-        Returns the cache directory where files were stored.
+        Returns a sorted list of downloaded/cached file paths.
         """
         if date and not (start and end):
             self.configure(date=date, date_type=date_type)
             cache_folder = self._download_single()
             if output_dir:
                 self._copy_to_output(cache_folder, Path(output_dir))
-            return cache_folder
+            return sorted(f for f in cache_folder.iterdir() if f.is_file())
 
         if not (start and end):
             raise ValueError("Provide 'date' or both 'start' and 'end'.")
@@ -101,7 +101,7 @@ class ArchiveHandle:
         horizon = self.metadata.get("archive", {}).get("horizon", "D")
         archive_type = self.metadata.get("archive", {}).get("archive_type", "zip")
         current = start_date
-        last_folder: Path | None = None
+        files: list[Path] = []
 
         while current <= end_date:
             if horizon == "M":
@@ -118,7 +118,7 @@ class ArchiveHandle:
                 logger.info("Cache hit: %s", cache_folder)
                 if output_dir:
                     self._copy_to_output(cache_folder, Path(output_dir))
-                last_folder = cache_folder
+                files.extend(f for f in cache_folder.iterdir() if f.is_file())
                 current = chunk_end + timedelta(days=1)
                 continue
 
@@ -136,7 +136,7 @@ class ArchiveHandle:
             # Write to cache
             cache_folder = self._cache.archive_dir(self.id, self.name, key)
             self._write_content(content, cache_folder, key, archive_type)
-            last_folder = cache_folder
+            files.extend(f for f in cache_folder.iterdir() if f.is_file())
 
             # Copy to output if requested
             if output_dir:
@@ -144,7 +144,7 @@ class ArchiveHandle:
 
             current = chunk_end + timedelta(days=1)
 
-        return last_folder or self._cache.archive_dir(self.id, self.name, "")
+        return sorted(files)
 
     # -- Internal helpers ------------------------------------------------------
 
@@ -199,12 +199,25 @@ class ArchiveHandle:
 class ArchivesManager(BaseManager):
     """Manager for ``/archives`` endpoints."""
 
-    def list(self) -> pd.DataFrame:
-        """List all available archives as a DataFrame."""
-        data = self._get("archives")
-        df = pd.DataFrame(data.get("archives", []))
-        if "id" in df.columns:
-            df = df.set_index("id")
+    def list(self, *, source: str = "local") -> pd.DataFrame:
+        """List all available archives as a DataFrame.
+
+        Args:
+            source: ``"local"`` (default) returns the full static catalog
+                (153 archives including I90, settlements, etc.).
+                ``"api"`` queries the ESIOS API which only returns ~24 archives.
+        """
+        if source == "api":
+            data = self._get("archives", params={"date_type": "publicacion"})
+            df = pd.DataFrame(data.get("archives", []))
+            if "id" in df.columns:
+                df = df.set_index("id")
+            return df
+
+        from esios.data.catalogs.archives import ARCHIVES_CATALOG
+
+        df = pd.DataFrame.from_dict(ARCHIVES_CATALOG, orient="index")
+        df.index.name = "id"
         return df
 
     def get(self, archive_id: int) -> ArchiveHandle:
@@ -225,10 +238,10 @@ class ArchivesManager(BaseManager):
         date: str | None = None,
         output_dir: str | Path | None = None,
         date_type: str = "datos",
-    ) -> Path:
+    ) -> list[Path]:
         """Convenience method: get + download in one call.
 
-        Returns the cache directory where files were stored.
+        Returns a sorted list of downloaded/cached file paths.
         """
         handle = self.get(archive_id)
         return handle.download(

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()

esios/processing/i90.py

@@ -8,11 +8,15 @@ from __future__ import annotations
 
 import logging
 from pathlib import Path
+from typing import TYPE_CHECKING
 
 import numpy as np
 import pandas as pd
 import python_calamine
 
+if TYPE_CHECKING:
+    from esios.managers.archives import ArchiveHandle
+
 logger = logging.getLogger("esios")
 
 
@@ -26,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:
@@ -43,26 +47,34 @@ class I90Book:
         self.path = Path(path)
         self.metadata: dict = {}
         self.table_of_contents: dict[str, str] = {}
-        self.sheets: dict[str, I90Sheet] = {}
+        self._sheets: dict[str, I90Sheet] = {}
+        self._workbook: python_calamine.CalamineWorkbook | None = None
+        self._sheet_names: list[str] = []
         self._extract_metadata_and_toc()
 
-    def _read_excel(self) -> None:
-        with open(self.path, "rb") as f:
-            self.workbook = python_calamine.CalamineWorkbook.from_filelike(f)
-        self.sheets = {
-            name: I90Sheet(name, self.workbook, self.path, self.metadata)
-            for name in self.workbook.sheet_names
-        }
+    @property
+    def sheets(self) -> dict[str, I90Sheet]:
+        """Access already-loaded sheets."""
+        return self._sheets
+
+    def _open_workbook(self) -> python_calamine.CalamineWorkbook:
+        """Open the workbook (cached after first call)."""
+        if self._workbook is None:
+            with open(self.path, "rb") as f:
+                self._workbook = python_calamine.CalamineWorkbook.from_filelike(f)
+            self._sheet_names = self._workbook.sheet_names
+        return self._workbook
 
     def _extract_metadata_and_toc(self) -> None:
         """Extract dates and table of contents from the first sheet."""
-        self._read_excel()
-        first_sheet = self.sheets[next(iter(self.sheets))]
-        rows = first_sheet.rows
+        wb = self._open_workbook()
+        first_name = self._sheet_names[0]
+        first_sheet = I90Sheet(first_name, wb, self.path, self.metadata)
+        self._sheets[first_name] = first_sheet
 
         # Dates from row 4
-        self.metadata["date_data"] = pd.to_datetime(rows[3][0])
-        self.metadata["date_publication"] = pd.to_datetime(rows[3][2])
+        self.metadata["date_data"] = pd.to_datetime(first_sheet.rows[3][0])
+        self.metadata["date_publication"] = pd.to_datetime(first_sheet.rows[3][2])
 
         # Table of contents from row 10 onwards
         df = pd.read_excel(self.path, sheet_name=0, header=None, skiprows=9, usecols="A,B", engine="calamine")
@@ -70,12 +82,13 @@ class I90Book:
         self.table_of_contents = df.set_index("sheet_name")["description"].to_dict()
 
     def get_sheet(self, sheet_name: str) -> I90Sheet:
-        """Get and preprocess a specific sheet by name."""
-        if sheet_name not in self.sheets:
-            self._read_excel()
-        sheet = self.sheets.get(sheet_name)
-        if sheet is None:
-            raise KeyError(f"Sheet '{sheet_name}' not found in {self.path.name}")
+        """Get and preprocess a specific sheet by name (lazy — only reads on demand)."""
+        if sheet_name not in self._sheets:
+            wb = self._open_workbook()
+            if sheet_name not in self._sheet_names:
+                raise KeyError(f"Sheet '{sheet_name}' not found in {self.path.name}")
+            self._sheets[sheet_name] = I90Sheet(sheet_name, wb, self.path, self.metadata)
+        sheet = self._sheets[sheet_name]
         if sheet.df is None:
             sheet.df = sheet._preprocess()
         return sheet
@@ -83,6 +96,36 @@ class I90Book:
     def __getitem__(self, sheet_name: str) -> I90Sheet:
         return self.get_sheet(sheet_name)
 
+    @classmethod
+    def from_archive(
+        cls,
+        archive: ArchiveHandle,
+        *,
+        start: str,
+        end: str,
+    ) -> list[I90Book]:
+        """Download I90 files and parse them into I90Book objects.
+
+        Calls ``archive.download()`` (cache-aware), then parses each file.
+        Files that fail to parse are logged and skipped.
+
+        Args:
+            archive: An :class:`ArchiveHandle` from ``client.archives.get(34)``.
+            start: Start date (``"YYYY-MM-DD"``).
+            end: End date (``"YYYY-MM-DD"``).
+
+        Returns:
+            A list of successfully parsed :class:`I90Book` objects, sorted by date.
+        """
+        files = archive.download(start=start, end=end)
+        books: list[I90Book] = []
+        for f in files:
+            try:
+                books.append(cls(f))
+            except Exception as e:
+                logger.warning("Failed to parse %s: %s", f.name, e)
+        return books
+
     def __repr__(self) -> str:
         return f"<I90Book {self.path.name} sheets={len(self.sheets)}>"
 
@@ -121,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
@@ -192,7 +256,7 @@ class I90Sheet:
             columns_datetime = base_date + pd.to_timedelta(time_deltas, unit="m")
             columns_datetime = pd.DatetimeIndex(columns_datetime).tz_localize(
                 "Europe/Madrid", ambiguous="infer"
-            ).tz_convert("UTC")
+            )
 
             data = pd.DataFrame(self.rows[idx + 1 :], columns=columns)
 

{python_esios-2.0.0.dist-info → python_esios-2.0.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-esios
-Version: 2.0.0
+Version: 2.0.2
 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

{python_esios-2.0.0.dist-info → python_esios-2.0.2.dist-info}/RECORD

@@ -4,18 +4,24 @@ esios/cache.py,sha256=GgbrL9Rc9aLrEWHvXtQOCGQRgq2T4m6VBJDvBJfWMTk,18920
 esios/client.py,sha256=rE06YD70oTFA7Tc9Okf5Rcsntnx9W_3U4A6rbZlfsGc,5695
 esios/constants.py,sha256=pwB2UlBI96zYBA8wAbcCSHcm_E-aIj2hBarDA8t1Vp8,474
 esios/exceptions.py,sha256=AiWLdRDWj50JEsld9CvVBsfLnZZKFmW62_bZmZ7Z_eA,899
+esios/.agents/skills/esios/SKILL.md,sha256=Z7ltdPCtJPA4cMAI8_94jy_12laq-356PJ78TqfY2NQ,6984
 esios/cli/__init__.py,sha256=9gd5ZDIH1-yNP_xcd60ethOFXm9w6un0CJ9CX0Qvb2A,256
 esios/cli/app.py,sha256=JL-4QWlzu5UKd6mq3-bEmWn8YR463edGRNUcv6rv8L8,1370
-esios/cli/archives.py,sha256=gGlPGhVuRddWBWwiaKtL-tFTgNrQMbZdFIiresoEOHc,2100
+esios/cli/archives.py,sha256=Re9ZMauTiJlHdmiE7F3ZlV2wfaEyShS0C7Z4M2X4Ra8,7715
 esios/cli/cache_cmd.py,sha256=TWOn1UrkxK1paq_bbDHfvBd_OrQYcmoYtUG65evohOA,3165
 esios/cli/config.py,sha256=uYnCEy6NPkzX5tCrwYia4L24J-G9qw-rgTrN8KLDBVQ,1676
 esios/cli/config_cmd.py,sha256=KWZ6Uc4VvmP4wHl0CukqMjZirTjf_FiwFEuP8XI-lNA,923
 esios/cli/exec_cmd.py,sha256=BlBzyVaTxg8rwgTfTsMCy5MGrAkeQJ6VB3IE2szOoyA,4485
 esios/cli/indicators.py,sha256=xkR7vZr376W9r43FGAxG1oeq-LyIUA6Iz88HvCYsxa8,6709
+esios/data/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+esios/data/catalogs/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+esios/data/catalogs/archives/__init__.py,sha256=ewGnzX2uPoB4l_ktBSD0UeLPDqc1_tw_6hJ7ueZj8DM,172
+esios/data/catalogs/archives/catalog.py,sha256=P7YpTJAsMKDHE05gjt4T7R5ZrXg-E61SvTMQbSlQatQ,21760
+esios/data/catalogs/archives/refresh.py,sha256=VxuUHdtF4rQgN-jq5ewiOge-J3ok7FivalvYDGQej9A,2662
 esios/managers/__init__.py,sha256=-1AwL7arUf7WEZn1RSiK_DZhY3j6U4GE9_dqjbukCJc,268
-esios/managers/archives.py,sha256=QT16-DaV6IR8X1tCqlLBy2PSqldMeZxB0zYZSNyCCS4,8772
+esios/managers/archives.py,sha256=7mK3BSYEPNygMO2pQCXYqNE90QTqfOGY4byBNn76ikQ,9386
 esios/managers/base.py,sha256=7XcdrUtUOPuqfHYlz4w562TD8o9cNdBWOgs4CHHonoo,835
-esios/managers/indicators.py,sha256=xnTdyvLsRi3DO-7_CckNQuxtq4ghA1ttzPnYQZUoOoA,16387
+esios/managers/indicators.py,sha256=GEyHq09TCPnf3ARULS7olJYC6iiom2XrcyhDAf946po,16653
 esios/managers/offer_indicators.py,sha256=0MjEKkj77YC2fRSHVTEc7FW6E8AuwwciAXK-bOVEL5Q,4187
 esios/models/__init__.py,sha256=oppuTASpf0Dh2KbGMXInULT0F4sELjeo-9UhPiPOZiA,289
 esios/models/archive.py,sha256=P2LaT7_ff4ujwqVn_ofgQP3dbpf7jqON0R22dKwSJ_w,1062
@@ -23,10 +29,10 @@ esios/models/indicator.py,sha256=u1AJyEA3YeOqQFjV08_lzyMaofuCiMoLPjvosls9gfE,111
 esios/models/offer_indicator.py,sha256=nA80Y7Yp0utDaDOdZ-ObcWTsAdhvuXlfJjJBpdVQ7Lo,758
 esios/processing/__init__.py,sha256=1kLt_gO_wDhXM1BbY0zTyfAYo-CjYKW1ljgRRDZ7USM,278
 esios/processing/dataframes.py,sha256=OitzBvAerssGP2VXNC-sSO48XsHdIB2nKTUgByN5eYQ,2524
-esios/processing/i90.py,sha256=-RQh6ZIc01dlcqUjaxcRq9iUtQc7EO1GddRCUC_x0Kg,7884
+esios/processing/i90.py,sha256=k4RH4lIwIm04ASYnubdQwJ3WM98iLj5l14zwxXBQEBo,10443
 esios/processing/zip.py,sha256=12LbFHJTdX_h3JG-clEgQ4Haj-kw0UjfopGLlCRXfGM,1913
-python_esios-2.0.0.dist-info/METADATA,sha256=1eDvpsLpuCWrb4rBX9JxS8yYPcuOVA04urG4HdCMvPU,2803
-python_esios-2.0.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-python_esios-2.0.0.dist-info/entry_points.txt,sha256=7ngseyIyvJ4buTHFL9htaZ4tTFHpG4zzJNkc8B5Jr8U,40
-python_esios-2.0.0.dist-info/licenses/LICENSE,sha256=LorLs1-VeBW70Wo9fLAtLJN7nNd6Poy0xzvqdWVqFlE,35128
-python_esios-2.0.0.dist-info/RECORD,,
+python_esios-2.0.2.dist-info/METADATA,sha256=zGyHPDmU_YJLEry8ltNFkDzw07hpBqVJuvumQoxeKNM,2803
+python_esios-2.0.2.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+python_esios-2.0.2.dist-info/entry_points.txt,sha256=7ngseyIyvJ4buTHFL9htaZ4tTFHpG4zzJNkc8B5Jr8U,40
+python_esios-2.0.2.dist-info/licenses/LICENSE,sha256=LorLs1-VeBW70Wo9fLAtLJN7nNd6Poy0xzvqdWVqFlE,35128
+python_esios-2.0.2.dist-info/RECORD,,