python-esios 0.2.6__tar.gz → 2.0.0__tar.gz

python_esios-2.0.0/.claude-plugin/marketplace.json

@@ -0,0 +1,15 @@
+{
+  "name": "python-esios",
+  "owner": {
+    "name": "Datons AI",
+    "email": "jesus.lopez@datons.ai"
+  },
+  "plugins": [
+    {
+      "name": "esios",
+      "source": ".",
+      "description": "Query Spanish electricity market data (ESIOS/REE) — prices, generation, demand, I90 files, and any ESIOS indicator.",
+      "version": "2.0.0"
+    }
+  ]
+}

python_esios-2.0.0/.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "esios",
+  "description": "Query Spanish electricity market data (ESIOS/REE) — prices, generation, demand, I90 files, and any ESIOS indicator.",
+  "version": "2.0.0",
+  "author": {
+    "name": "Jesús López",
+    "email": "jesus.lopez@datons.ai"
+  },
+  "repository": "https://github.com/datons/python-esios",
+  "license": "GPL-3.0-only",
+  "keywords": ["esios", "ree", "electricity", "energy", "spain", "omie"]
+}

python_esios-2.0.0/.github/workflows/publish.yml

@@ -0,0 +1,26 @@
+name: Publish to PyPI
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write # Required for trusted publishing
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

python_esios-2.0.0/.gitignore

@@ -0,0 +1,47 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+
+# uv
+.venv/
+uv.lock
+
+# Environment
+.env
+.env.*
+
+# OS
+.DS_Store
+Thumbs.db
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Generated docs
+docs/
+
+# Data files (large / sensitive)
+*.xls
+*.xlsx
+data/
+
+# Legacy code (superseded by src/)
+esios_legacy/
+
+# Test / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Config with secrets
+.config/
+
+# Dev scripts
+random/

python_esios-2.0.0/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+## [2.0.0] - 2026-02-27
+
+Complete rewrite of the library with a new architecture, CLI, and caching system.
+
+### Breaking Changes
+
+- New package structure: `from esios import ESIOSClient` (was `from esios.client import Esios`)
+- Indicators return wide-format DataFrames with geo names as columns (e.g., `"España"`)
+- Archives API redesigned with `client.archives.download()`
+
+### Added
+
+- **CLI** (`esios`): full command-line interface with `indicators`, `archives`, `cache`, and `config` commands
+- **Multi-geo support**: indicators with multiple geographies return one column per geo (e.g., España, Francia, Portugal)
+- **`--geo` filter**: filter by geography ID or name in both CLI and Python API
+- **Smart caching**: parquet-based cache with per-column gap detection and sparse column support
+  - Per-indicator directories (`{id}/data.parquet` + `{id}/meta.json`)
+  - Global geo registry (`geos.json`) learned incrementally from API responses
+  - Per-endpoint catalog (`catalog.json`) with 24h TTL
+  - Per-indicator metadata (`meta.json`) with 7-day TTL
+  - Auto-migration from v1 flat cache files
+- **`esios exec`**: ad-hoc pandas expressions on indicator data
+- **`esios indicators meta`**: inspect indicator metadata
+- **`esios cache status`**: Rich panel showing cache health, geos registry, and catalog info
+- **`esios cache geos`**: inspect the global geography registry
+- **`esios config set token`**: store API token in `~/.config/esios/config.toml`
+- **I90 processing**: `I90Book` class for parsing settlement files with automatic frequency detection
+- **Async client**: `AsyncESIOSClient` for concurrent requests
+- **Claude Code plugin**: installable skill with full domain knowledge (`/plugin marketplace add datons/python-esios`)
+
+### Improved
+
+- Automatic date-range chunking for large queries (>3 weeks)
+- Atomic file writes (tempfile + rename) for cache safety
+- TTL-based cache freshness: recent data (48h) re-fetched for electricity market corrections
+- Geo enrichment: learns missing geo mappings from API values (e.g., indicator 600 omits Países Bajos/8828)
+- Custom exceptions: `ESIOSError`, `AuthenticationError`, `APIResponseError`, `NetworkError`
+
+## [0.1.0] - 2024-05-15
+
+Initial release.
+
+- Basic indicator data download
+- Archive file download (I90, Liquicomun, CoefK)
+- I90 preprocessing with sheet access

python_esios-2.0.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: python-esios
+Version: 2.0.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>
+License-Expression: GPL-3.0-only
+License-File: LICENSE
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: beautifulsoup4>=4.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: pandas>=2.0
+Requires-Dist: pyarrow>=15.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-calamine>=0.2
+Requires-Dist: rich>=13.0
+Requires-Dist: tenacity>=8.0
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# python-esios
+
+A Python library and CLI to query the Spanish electricity market API (ESIOS/REE).
+
+Download indicators (prices, generation, demand), archives (I90 settlement files), and more.
+
+## Install
+
+```shell
+pip install python-esios
+```
+
+## Configure your token
+
+Request a personal token from [REE](https://www.esios.ree.es/es/pagina/api), then:
+
+```shell
+esios config set token YOUR_TOKEN
+```
+
+This stores the token in `~/.config/esios/config.toml`. Alternatively, set the `ESIOS_API_KEY` environment variable.
+
+## CLI usage
+
+```shell
+# Search indicators
+esios indicators search "precio"
+
+# Download historical data
+esios indicators history 600 --start 2025-01-01 --end 2025-01-31
+
+# Export to CSV
+esios indicators history 600 -s 2025-01-01 -e 2025-01-31 --format csv --output prices.csv
+
+# List archives
+esios archives list
+
+# Download I90 settlement files
+esios archives download 1 --start 2025-01-01 --end 2025-01-31
+
+# Cache status
+esios cache status
+```
+
+## Python usage
+
+```python
+from esios import ESIOSClient
+
+client = ESIOSClient()
+
+# Get indicator data as DataFrame
+handle = client.indicators.get(600)  # PVPC price
+df = handle.historical("2025-01-01", "2025-01-31")
+
+# Search indicators
+results = client.indicators.search("precio")
+
+# Download archives
+client.archives.download(1, start="2025-01-01", end="2025-01-31", output_dir="./data")
+```
+
+## Common indicators
+
+| ID | Name | Description |
+|----|------|-------------|
+| 600 | PVPC | Voluntary price for small consumers |
+| 1001 | Day-ahead price | OMIE spot market price |
+| 10033 | Demand | Real-time electricity demand |
+| 10034 | Wind generation | Real-time wind generation |
+| 10035 | Solar PV generation | Real-time solar generation |
+
+## License
+
+GPL-3.0

python_esios-2.0.0/README.md

@@ -0,0 +1,75 @@
+# python-esios
+
+A Python library and CLI to query the Spanish electricity market API (ESIOS/REE).
+
+Download indicators (prices, generation, demand), archives (I90 settlement files), and more.
+
+## Install
+
+```shell
+pip install python-esios
+```
+
+## Configure your token
+
+Request a personal token from [REE](https://www.esios.ree.es/es/pagina/api), then:
+
+```shell
+esios config set token YOUR_TOKEN
+```
+
+This stores the token in `~/.config/esios/config.toml`. Alternatively, set the `ESIOS_API_KEY` environment variable.
+
+## CLI usage
+
+```shell
+# Search indicators
+esios indicators search "precio"
+
+# Download historical data
+esios indicators history 600 --start 2025-01-01 --end 2025-01-31
+
+# Export to CSV
+esios indicators history 600 -s 2025-01-01 -e 2025-01-31 --format csv --output prices.csv
+
+# List archives
+esios archives list
+
+# Download I90 settlement files
+esios archives download 1 --start 2025-01-01 --end 2025-01-31
+
+# Cache status
+esios cache status
+```
+
+## Python usage
+
+```python
+from esios import ESIOSClient
+
+client = ESIOSClient()
+
+# Get indicator data as DataFrame
+handle = client.indicators.get(600)  # PVPC price
+df = handle.historical("2025-01-01", "2025-01-31")
+
+# Search indicators
+results = client.indicators.search("precio")
+
+# Download archives
+client.archives.download(1, start="2025-01-01", end="2025-01-31", output_dir="./data")
+```
+
+## Common indicators
+
+| ID | Name | Description |
+|----|------|-------------|
+| 600 | PVPC | Voluntary price for small consumers |
+| 1001 | Day-ahead price | OMIE spot market price |
+| 10033 | Demand | Real-time electricity demand |
+| 10034 | Wind generation | Real-time wind generation |
+| 10035 | Solar PV generation | Real-time solar generation |
+
+## License
+
+GPL-3.0

python_esios-2.0.0/examples/.gitignore

@@ -0,0 +1,5 @@
+# Generated artifacts from running notebooks
+*.csv
+*.xlsx
+*.parquet
+data/