feat: add static archives catalog (153 archives) and improve download API

The ESIOS /archives endpoint only returns ~24 archives, hiding 129 others
(including I90DIA, settlements, PVPC, etc.) that are accessible by ID.

- Add static catalog at src/esios/data/catalogs/archives/ with all 153 archives
- Add refresh.py script to regenerate the catalog from the live API
- archives.list() now returns the full catalog by default (source="local")
- archives.download() now returns list[Path] instead of Path
- I90Book.from_archive() classmethod for streamlined I90 workflow
- Update SKILL.md with config file resolution note

Author: jsulopzs

.gitignore

@@ -31,6 +31,7 @@ docs/
 *.xls
 *.xlsx
 data/
+!src/esios/data/
 
 # Legacy code (superseded by src/)
 esios_legacy/

src/esios/data/__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"]

src/esios/data/catalogs/__init__.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()

src/esios/data/catalogs/archives/__init__.py

@@ -76,20 +76,20 @@ def download(
         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 @@ def download(
         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 @@ def download(
                 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,15 +136,15 @@ def download(
             # 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:
                 self._copy_to_output(cache_folder, Path(output_dir))
 
             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 @@ def _copy_to_output(cache_folder: Path, output_dir: Path) -> None:
 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 @@ def download(
         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(

src/esios/data/catalogs/archives/catalog.py

@@ -8,11 +8,15 @@
 
 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")
 
 
@@ -83,6 +87,36 @@ def get_sheet(self, sheet_name: str) -> I90Sheet:
     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)}>"
 
@@ -192,7 +226,7 @@ def _preprocess(self) -> pd.DataFrame:
             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)