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

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"
 ```

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/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

@@ -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.0.1.dist-info → python_esios-2.0.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-esios
-Version: 2.0.1
+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.1.dist-info → python_esios-2.0.2.dist-info}/RECORD

@@ -4,10 +4,10 @@ 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=XFamz2-8QbM95gTh-wry9YSE5qc-58RWx9CqwFzY_co,5412
+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
@@ -21,7 +21,7 @@ esios/data/catalogs/archives/refresh.py,sha256=VxuUHdtF4rQgN-jq5ewiOge-J3ok7Fiva
 esios/managers/__init__.py,sha256=-1AwL7arUf7WEZn1RSiK_DZhY3j6U4GE9_dqjbukCJc,268
 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
@@ -29,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=2MaevdYECAj55ShqpHehoD0c2rLQ97avUfM2qBw7eso,9499
+esios/processing/i90.py,sha256=k4RH4lIwIm04ASYnubdQwJ3WM98iLj5l14zwxXBQEBo,10443
 esios/processing/zip.py,sha256=12LbFHJTdX_h3JG-clEgQ4Haj-kw0UjfopGLlCRXfGM,1913
-python_esios-2.0.1.dist-info/METADATA,sha256=kirS790d42WBJrzA_aaAXT61w7ycKAzNGeT27sea_XQ,2803
-python_esios-2.0.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-python_esios-2.0.1.dist-info/entry_points.txt,sha256=7ngseyIyvJ4buTHFL9htaZ4tTFHpG4zzJNkc8B5Jr8U,40
-python_esios-2.0.1.dist-info/licenses/LICENSE,sha256=LorLs1-VeBW70Wo9fLAtLJN7nNd6Poy0xzvqdWVqFlE,35128
-python_esios-2.0.1.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,,