python-esios 2.0.2__tar.gz → 2.2.0__tar.gz

python_esios-2.0.2/.github/workflows/publish.yml → python_esios-2.2.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.2 → python_esios-2.2.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.2.0/.release-please-manifest.json

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

{python_esios-2.0.2 → python_esios-2.2.0}/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## [2.2.0](https://github.com/datons/python-esios/compare/python-esios-v2.1.0...python-esios-v2.2.0) (2026-03-04)
+
+
+### Features
+
+* add YAML-backed catalog with enriched indicator metadata ([00cc4b6](https://github.com/datons/python-esios/commit/00cc4b69a66268d6d4d6e63ce7d4d8f91c7e813a))
+
+
+### Bug Fixes
+
+* update skill with catalog commands and Python-first approach ([6051fb3](https://github.com/datons/python-esios/commit/6051fb31cbea2dce0b5eaeb87a561c33d8d8d4e6))
+
+## [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.2.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.2 → python_esios-2.2.0}/PKG-INFO

@@ -1,12 +1,17 @@
 Metadata-Version: 2.4
 Name: python-esios
-Version: 2.0.2
+Version: 2.2.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
@@ -21,6 +27,7 @@ Requires-Dist: pandas>=2.0
 Requires-Dist: pyarrow>=15.0
 Requires-Dist: pydantic>=2.0
 Requires-Dist: python-calamine>=0.2
+Requires-Dist: pyyaml>=6.0
 Requires-Dist: rich>=13.0
 Requires-Dist: tenacity>=8.0
 Requires-Dist: typer>=0.12

{python_esios-2.0.2 → python_esios-2.2.0}/pyproject.toml

@@ -4,15 +4,18 @@ build-backend = "hatchling.build"
 
 [project]
 name = "python-esios"
-version = "2.0.2"
+version = "2.2.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",
@@ -31,6 +35,7 @@ dependencies = [
     "beautifulsoup4>=4.12",
     "typer>=0.12",
     "rich>=13.0",
+    "pyyaml>=6.0",
 ]
 
 [project.scripts]
@@ -39,6 +44,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.2.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.2.0/src/esios/.agents/skills/esios/SKILL.md

@@ -0,0 +1,182 @@
+---
+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: 3.0.0
+---
+
+# ESIOS Data Assistant
+
+You have access to the `python-esios` library and CLI for querying the Spanish electricity market (ESIOS/REE).
+
+## When to use what
+
+- **Python scripts** (default): reproducible, composable, saveable. Use for any data work the user will want to keep or iterate on.
+- **CLI**: quick one-shot lookups, exploration, sanity checks. Use when the user wants a fast answer they won't need again.
+- **If unsure**: ask the user whether they want a script or a quick CLI check.
+
+## Python Library (default)
+
+```python
+from esios import ESIOSClient
+
+client = ESIOSClient()  # reads config file, then ESIOS_API_KEY env var
+
+# --- Indicators ---
+
+# Get indicator handle
+handle = client.indicators.get(600)
+
+# Historical data as DataFrame
+df = handle.historical("2025-01-01", "2025-01-31")
+
+# Filter by geography
+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 indicators
+results = client.indicators.search("precio")
+
+# Compare multiple indicators
+df = client.indicators.compare([600, 10034, 10035], "2025-01-01", "2025-01-07")
+
+# --- I90 Settlement Files ---
+
+from esios.processing.i90 import I90Book
+
+archive = client.archives.get(34)
+books = I90Book.from_archive(archive, start="2025-05-05", end="2025-06-08")
+
+book = books[0]
+sheet = book["I90DIA03"]
+df = sheet.df             # Preprocessed DataFrame with datetime index
+print(sheet.frequency)    # "hourly" or "hourly-quarterly"
+```
+
+### 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 `client.indicators.search("query")` to find more.
+
+### Multi-Geo Indicators
+
+Some indicators (e.g. 600) return data for multiple countries. 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
+```
+
+### Geography Reference
+
+| geo_id | geo_name |
+|--------|----------|
+| 1 | Portugal |
+| 2 | Francia |
+| 3 | España |
+| 8826 | Alemania |
+| 8827 | Bélgica |
+| 8828 | Países Bajos |
+
+### I90 Key Sheets
+
+| Sheet | Description |
+|-------|-------------|
+| 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) |
+
+### Key conventions
+
+- All timestamps are in Europe/Madrid timezone
+- Date ranges > 3 weeks are auto-chunked into smaller API requests
+- 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_ids=[3]` only caches that column
+- Custom exceptions: `ESIOSError`, `AuthenticationError`, `APIResponseError`, `NetworkError`
+
+## CLI Reference (quick lookups)
+
+### Catalog (offline)
+
+```bash
+esios catalog list indicators                   # List cataloged indicators
+esios catalog list indicators "precio"          # Filter by name
+esios catalog list archives                     # List cataloged archives
+esios catalog show indicator 600                # Details for indicator
+esios catalog show archive 34                   # Details for archive
+esios catalog refresh                           # Refresh from live API
+esios catalog refresh --dry-run                 # Preview changes
+```
+
+### Indicators
+
+```bash
+esios indicators list                           # List all indicators
+esios indicators search "precio"                # Search by name
+esios indicators meta 600                       # Show metadata
+esios indicators history 600 -s 2025-01-01 -e 2025-01-31
+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 --format csv --output data.csv
+```
+
+### Archives
+
+```bash
+esios archives list                             # List available archives
+esios archives download 34 -s 2025-05-01 -e 2025-05-31 --output ./data
+esios archives sheets 34 --date 2025-06-01      # List sheets in I90 file
+```
+
+### Exec (ad-hoc pandas)
+
+```bash
+# Indicators
+esios indicators exec 600 -s 2025-01-01 -e 2025-01-31 -x "df.describe()"
+esios indicators exec 600 -s 2025-01-01 -e 2025-01-31 --geo España -x "df.resample('D').mean()"
+esios indicators exec 600 10034 -s 2025-01-01 -e 2025-01-31 -x "df.corr()"
+
+# Archives (I90)
+esios archives exec 34 --sheet I90DIA03 --date 2025-06-01 -x "df.groupby('Sentido')['value'].sum()"
+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()"
+```
+
+### Cache management
+
+```bash
+esios cache status                              # Path, size, registry info
+esios cache geos                                # Global geo_id → geo_name registry
+esios cache clear                               # Clear indicator cache
+esios cache clear --all                         # Clear everything
+esios cache clear --indicator 600               # Clear one indicator
+```
+
+### Output options
+
+```
+--format table|csv|json|parquet   (default: table)
+--output file.csv                 (write to file instead of stdout)
+```
+
+## Configuration
+
+```bash
+esios config set token <API_KEY>
+esios config show
+```
+
+Config file: `~/.config/esios/config.toml`. API key resolution: config file > `ESIOS_API_KEY` env var.