python-entsoe 0.3.0__tar.gz → 0.4.0__tar.gz

python_entsoe-0.4.0/.github/workflows/publish.yml

@@ -0,0 +1,28 @@
+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
+        with:
+          skip-existing: true

{python_entsoe-0.3.0 → python_entsoe-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-entsoe
-Version: 0.3.0
+Version: 0.4.0
 Summary: Python client for the ENTSO-E Transparency Platform API
 Project-URL: Repository, https://github.com/datons/python-entsoe
 Author-email: jsulopzs <jesus.lopez@datons.com>
@@ -10,11 +10,16 @@ Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Science/Research
 Classifier: License :: OSI Approved :: MIT License
 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
 Classifier: Topic :: Scientific/Engineering
-Requires-Python: >=3.13
+Requires-Python: >=3.10
 Requires-Dist: pandas>=2.0
 Requires-Dist: requests>=2.28
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.9
 Description-Content-Type: text/markdown
 
 # python-entsoe

{python_entsoe-0.3.0 → python_entsoe-0.4.0}/pyproject.toml

@@ -1,27 +1,35 @@
 [project]
 name = "python-entsoe"
-version = "0.3.0"
+version = "0.4.0"
 description = "Python client for the ENTSO-E Transparency Platform API"
 readme = "README.md"
 license = "MIT"
 authors = [
     { name = "jsulopzs", email = "jesus.lopez@datons.com" },
 ]
-requires-python = ">=3.13"
+requires-python = ">=3.10"
 keywords = ["entsoe", "energy", "electricity", "api", "transparency"]
 classifiers = [
     "Development Status :: 3 - Alpha",
     "Intended Audience :: Science/Research",
     "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
     "Topic :: Scientific/Engineering",
 ]
 dependencies = [
     "pandas>=2.0",
     "requests>=2.28",
+    "typer>=0.9",
+    "rich>=13.0",
 ]
 
+[project.scripts]
+entsoe = "entsoe.cli:app"
+
 [project.urls]
 Repository = "https://github.com/datons/python-entsoe"
 

python_entsoe-0.4.0/skills/entsoe/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: entsoe
+description: Query European electricity market data (ENTSO-E Transparency Platform). Use when the user asks about electricity prices, load, generation, transmission, or balancing data for European countries.
+version: 1.0.0
+---
+
+# ENTSO-E Data Assistant
+
+You have access to the `python-entsoe` CLI and library for querying the ENTSO-E Transparency Platform (European electricity market data).
+
+## CLI Reference
+
+### Prices
+
+```bash
+# Day-ahead prices for one country
+entsoe prices day-ahead -s 2024-06-01 -e 2024-06-08 --country FR
+
+# Multi-country
+entsoe prices day-ahead -s 2024-06-01 -e 2024-06-08 --country FR --country ES
+```
+
+### Load
+
+```bash
+# Actual total system load
+entsoe load actual -s 2024-06-01 -e 2024-06-08 --country FR
+
+# Day-ahead load forecast
+entsoe load forecast -s 2024-06-01 -e 2024-06-08 --country FR
+```
+
+### Generation
+
+```bash
+# Actual generation per type (all types)
+entsoe generation actual -s 2024-06-01 -e 2024-06-08 --country FR
+
+# Filter by PSR type
+entsoe generation actual -s 2024-06-01 -e 2024-06-08 --country FR --psr solar --psr wind_onshore
+
+# Generation forecast (wind/solar)
+entsoe generation forecast -s 2024-06-01 -e 2024-06-08 --country FR
+
+# Installed capacity
+entsoe generation capacity -s 2024-06-01 -e 2024-06-08 --country FR
+
+# Per production unit
+entsoe generation per-plant -s 2024-06-01 -e 2024-06-08 --country FR
+```
+
+### Transmission
+
+```bash
+# Physical cross-border flows
+entsoe transmission flows -s 2024-06-01 -e 2024-06-08 --from FR --to ES
+
+# Scheduled commercial exchanges
+entsoe transmission exchanges -s 2024-06-01 -e 2024-06-08 --from FR --to ES
+
+# Net transfer capacity
+entsoe transmission capacity -s 2024-06-01 -e 2024-06-08 --from FR --to ES
+```
+
+### Balancing
+
+```bash
+# Imbalance prices
+entsoe balancing prices -s 2024-06-01 -e 2024-06-08 --country FR
+
+# Imbalance volumes
+entsoe balancing volumes -s 2024-06-01 -e 2024-06-08 --country FR
+```
+
+### Exec (ad-hoc pandas expressions)
+
+Run any pandas expression against fetched data:
+
+```bash
+# Descriptive statistics on prices
+entsoe exec prices day-ahead -s 2024-06-01 -e 2024-06-08 -c FR -x "df.describe()"
+
+# Daily mean load
+entsoe exec load actual -s 2024-06-01 -e 2024-06-08 -c FR -x "df.resample('D').mean()"
+
+# Generation with PSR filter
+entsoe exec generation actual -s 2024-06-01 -e 2024-06-08 -c FR --psr solar -x "df.head(20)"
+
+# Transmission analysis
+entsoe exec transmission flows -s 2024-06-01 -e 2024-06-08 --from FR --to ES -x "df.describe()"
+```
+
+### Output formats
+
+All commands support:
+
+```bash
+--format table       # Default: Rich table in terminal
+--format csv         # CSV output
+--format json        # JSON output
+--output file.csv    # Write to file instead of stdout
+```
+
+## Country Codes
+
+| Code | Country | Code | Country |
+|------|---------|------|---------|
+| AT | Austria | IT | Italy |
+| BE | Belgium | LT | Lithuania |
+| BG | Bulgaria | LU | Luxembourg |
+| CH | Switzerland | LV | Latvia |
+| CZ | Czech Republic | NL | Netherlands |
+| DE_LU | Germany/Luxembourg | NO | Norway |
+| DK | Denmark | PL | Poland |
+| EE | Estonia | PT | Portugal |
+| ES | Spain | RO | Romania |
+| FI | Finland | RS | Serbia |
+| FR | France | SE | Sweden |
+| GB | Great Britain | SI | Slovenia |
+| GR | Greece | SK | Slovakia |
+| HR | Croatia | TR | Turkey |
+| HU | Hungary | UA | Ukraine |
+
+Bidding zones: `DK_1`, `DK_2`, `NO_1`–`NO_5`, `SE_1`–`SE_4`, `IT_NORTH`, `IT_CNOR`, `IT_CSUD`, `IT_SUD`, `IT_SICI`, `IT_SARD`, `DE_AT_LU`, `IE_SEM`.
+
+## PSR Types (Generation)
+
+| Shorthand | Full Name | Code |
+|-----------|-----------|------|
+| solar | Solar | B16 |
+| wind_onshore | Wind Onshore | B19 |
+| wind_offshore | Wind Offshore | B18 |
+| nuclear | Nuclear | B14 |
+| gas | Fossil Gas | B04 |
+| hard_coal | Fossil Hard coal | B05 |
+| lignite | Fossil Brown coal/Lignite | B02 |
+| hydro_reservoir | Hydro Water Reservoir | B12 |
+| run_of_river | Hydro Run-of-river | B11 |
+| pumped_storage | Hydro Pumped Storage | B10 |
+| biomass | Biomass | B01 |
+| oil | Fossil Oil | B06 |
+| geothermal | Geothermal | B09 |
+| waste | Waste | B17 |
+| other | Other | B20 |
+
+Use shorthands with `--psr` (e.g. `--psr solar --psr wind_onshore`), or ENTSO-E codes (e.g. `--psr B16`).
+
+## Python Library
+
+```python
+from entsoe import Client
+
+client = Client()  # reads config file, then ENTSOE_API_KEY env var
+
+# Prices
+df = client.prices.day_ahead("2024-06-01", "2024-06-08", country="FR")
+df = client.prices.day_ahead("2024-06-01", "2024-06-08", country=["FR", "ES"])
+
+# Load
+df = client.load.actual("2024-06-01", "2024-06-08", country="FR")
+df = client.load.forecast("2024-06-01", "2024-06-08", country="FR")
+
+# Generation
+df = client.generation.actual("2024-06-01", "2024-06-08", country="FR")
+df = client.generation.actual("2024-06-01", "2024-06-08", country="FR", psr_type="solar")
+df = client.generation.actual("2024-06-01", "2024-06-08", country="FR", psr_type=["solar", "wind_onshore"])
+df = client.generation.forecast("2024-06-01", "2024-06-08", country="FR")
+df = client.generation.installed_capacity("2024-06-01", "2024-06-08", country="FR")
+df = client.generation.per_plant("2024-06-01", "2024-06-08", country="FR")
+
+# Transmission
+df = client.transmission.crossborder_flows("2024-06-01", "2024-06-08", country_from="FR", country_to="ES")
+df = client.transmission.scheduled_exchanges("2024-06-01", "2024-06-08", country_from="FR", country_to="ES")
+df = client.transmission.net_transfer_capacity("2024-06-01", "2024-06-08", country_from="FR", country_to="ES")
+
+# Balancing
+df = client.balancing.imbalance_prices("2024-06-01", "2024-06-08", country="FR")
+df = client.balancing.imbalance_volumes("2024-06-01", "2024-06-08", country="FR")
+```
+
+## Configuration
+
+```bash
+# Store your API key persistently (recommended)
+entsoe config set api-key YOUR_KEY
+
+# Verify it's stored
+entsoe config get api-key
+```
+
+The config file is stored at `~/.config/entsoe/config.toml`.
+
+## Key Conventions
+
+- **Timezone**: All string dates are interpreted in Europe/Brussels (CET) by default
+- **Auto year-splitting**: Date ranges exceeding 1 year are automatically split into yearly API requests
+- **Rate limiting**: ENTSO-E has a 400-request/minute limit; the library handles retries
+- **Multi-value support**: Pass lists for country or psr_type to get combined results with label columns
+- **Transmission**: Uses `--from`/`--to` instead of `--country`; multi-value adds a `border` column
+- **API key resolution**: config file (`~/.config/entsoe/config.toml`) > `ENTSOE_API_KEY` env var
+- **No caching**: Data is fetched fresh on each request (unlike python-esios)
+- **Custom exceptions**: `ENTSOEError`, `AuthenticationError`, `APIResponseError`, `InvalidParameterError`, `NetworkError`

{python_entsoe-0.3.0 → python_entsoe-0.4.0}/src/entsoe/__init__.py

@@ -4,7 +4,7 @@ from .client import Client
 from .exceptions import ENTSOEError, InvalidParameterError, NoDataError, RateLimitError
 from ._mappings import COUNTRY_NAMES, PSR_CODES, country_name, psr_name
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"
 __all__ = [
     "Client",
     "COUNTRY_NAMES",

{python_entsoe-0.3.0 → python_entsoe-0.4.0}/src/entsoe/_http.py

@@ -7,6 +7,8 @@ Handles:
 - Response validation
 """
 
+from __future__ import annotations
+
 import io
 import logging
 import time

{python_entsoe-0.3.0 → python_entsoe-0.4.0}/src/entsoe/_mappings.py

@@ -1,5 +1,7 @@
 """ENTSO-E area codes, document types, and PSR type mappings."""
 
+from __future__ import annotations
+
 # Country code (ISO 3166-1 alpha-2) → ENTSO-E EIC area code
 AREA_CODES: dict[str, str] = {
     "AL": "10YAL-KESH-----5",

{python_entsoe-0.3.0 → python_entsoe-0.4.0}/src/entsoe/_xml.py

@@ -10,6 +10,8 @@ Handles the various document types returned by the API:
 All share the TimeSeries > Period > Point structure.
 """
 
+from __future__ import annotations
+
 import re
 import xml.etree.ElementTree as ET
 from datetime import timedelta

python_entsoe-0.4.0/src/entsoe/cli/__init__.py

@@ -0,0 +1,5 @@
+"""ENTSO-E CLI — command-line interface for the ENTSO-E Transparency Platform API."""
+
+from entsoe.cli.app import app
+
+__all__ = ["app"]

python_entsoe-0.4.0/src/entsoe/cli/_output.py

@@ -0,0 +1,100 @@
+"""Shared output helpers for the ENTSO-E CLI."""
+
+from __future__ import annotations
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+console = Console()
+
+
+def _fmt(val) -> str:
+    """Format a value for table display."""
+    if isinstance(val, float):
+        return f"{val:.4f}"
+    return str(val)
+
+
+def output(df, format: str, title: str = "", output_path: str | None = None):
+    """Render DataFrame in the requested format."""
+    import pandas as pd
+
+    if df.empty:
+        typer.echo("No data.")
+        return
+
+    if format == "csv":
+        text = df.to_csv()
+        if output_path:
+            with open(output_path, "w") as f:
+                f.write(text)
+            typer.echo(f"Written to {output_path}")
+        else:
+            typer.echo(text)
+
+    elif format == "json":
+        text = df.to_json(orient="records", indent=2, date_format="iso")
+        if output_path:
+            with open(output_path, "w") as f:
+                f.write(text)
+            typer.echo(f"Written to {output_path}")
+        else:
+            typer.echo(text)
+
+    else:  # table
+        table = Table(title=title)
+        cols = list(df.columns)[:10]  # Limit columns for readability
+        if df.index.name:
+            table.add_column(df.index.name, style="cyan")
+        for col in cols:
+            table.add_column(str(col))
+
+        for idx, row in df.head(50).iterrows():
+            values = [str(idx)] if df.index.name else []
+            values += [_fmt(row[c]) for c in cols]
+            table.add_row(*values)
+
+        if len(df) > 50:
+            table.caption = f"Showing 50 of {len(df)} rows"
+
+        console.print(table)
+
+
+def render_result(result, format: str, output_path: str | None) -> None:
+    """Render an eval result (DataFrame, Series, or scalar)."""
+    import pandas as pd
+
+    if isinstance(result, pd.Series):
+        result = result.to_frame()
+
+    if isinstance(result, pd.DataFrame):
+        if format == "csv":
+            text = result.to_csv()
+        elif format == "json":
+            text = result.to_json(orient="records", indent=2, date_format="iso")
+        else:
+            table = Table()
+            idx_name = result.index.name or ""
+            table.add_column(str(idx_name), style="cyan")
+            for col in result.columns:
+                table.add_column(str(col))
+
+            for idx, row in result.head(100).iterrows():
+                values = [str(idx)]
+                values += [_fmt(row[c]) for c in result.columns]
+                table.add_row(*values)
+
+            if len(result) > 100:
+                table.caption = f"Showing 100 of {len(result)} rows"
+            console.print(table)
+            return
+
+        if output_path:
+            with open(output_path, "w") as f:
+                f.write(text)
+            typer.echo(f"Written to {output_path}")
+        else:
+            typer.echo(text)
+    else:
+        typer.echo(result)

python_entsoe-0.4.0/src/entsoe/cli/app.py

@@ -0,0 +1,56 @@
+"""ENTSO-E CLI — main Typer application."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import typer
+
+from entsoe.cli.config import get_api_key
+
+app = typer.Typer(
+    name="entsoe",
+    help="CLI for the ENTSO-E Transparency Platform (European electricity market data).",
+    no_args_is_help=True,
+)
+
+
+def get_client(api_key: str | None = None):
+    """Lazy import + construct client."""
+    from entsoe.client import Client
+
+    resolved = api_key or get_api_key()
+    if not resolved:
+        typer.echo(
+            "Error: No API key. Set ENTSOE_API_KEY or run: entsoe config set api-key <KEY>",
+            err=True,
+        )
+        raise typer.Exit(1)
+    return Client(api_key=resolved)
+
+
+# -- Register sub-commands ---------------------------------------------------
+
+from entsoe.cli.prices import prices_app  # noqa: E402
+from entsoe.cli.load import load_app  # noqa: E402
+from entsoe.cli.generation import generation_app  # noqa: E402
+from entsoe.cli.transmission import transmission_app  # noqa: E402
+from entsoe.cli.balancing import balancing_app  # noqa: E402
+from entsoe.cli.exec_cmd import exec_app  # noqa: E402
+from entsoe.cli.config_cmd import config_app  # noqa: E402
+
+app.add_typer(prices_app, name="prices", help="Day-ahead electricity prices")
+app.add_typer(load_app, name="load", help="Actual load and load forecasts")
+app.add_typer(generation_app, name="generation", help="Generation data (actual, forecast, capacity, per-plant)")
+app.add_typer(transmission_app, name="transmission", help="Cross-border flows and exchanges")
+app.add_typer(balancing_app, name="balancing", help="Imbalance prices and volumes")
+app.add_typer(exec_app, name="exec", help="Fetch data and evaluate a pandas expression")
+app.add_typer(config_app, name="config", help="Configuration management")
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

python_entsoe-0.4.0/src/entsoe/cli/balancing.py

@@ -0,0 +1,47 @@
+"""CLI subcommands for balancing namespace."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import typer
+
+from entsoe.cli._output import output
+
+balancing_app = typer.Typer(no_args_is_help=True)
+
+
+@balancing_app.command("prices")
+def prices(
+    start: str = typer.Option(..., "--start", "-s", help="Start date (YYYY-MM-DD)"),
+    end: str = typer.Option(..., "--end", "-e", help="End date (YYYY-MM-DD)"),
+    country: list[str] = typer.Option(..., "--country", "-c", help="Country code (e.g. FR, NL). Repeat for multiple."),
+    format: str = typer.Option("table", "--format", "-f", help="Output format: table, csv, json"),
+    output_path: Optional[str] = typer.Option(None, "--output", "-o", help="Output file path"),
+    api_key: Optional[str] = typer.Option(None, "--api-key", help="ENTSO-E API key"),
+):
+    """Query imbalance prices."""
+    from entsoe.cli.app import get_client
+
+    client = get_client(api_key)
+    countries = country[0] if len(country) == 1 else country
+    df = client.balancing.imbalance_prices(start, end, country=countries)
+    output(df, format, title="Imbalance Prices", output_path=output_path)
+
+
+@balancing_app.command("volumes")
+def volumes(
+    start: str = typer.Option(..., "--start", "-s", help="Start date (YYYY-MM-DD)"),
+    end: str = typer.Option(..., "--end", "-e", help="End date (YYYY-MM-DD)"),
+    country: list[str] = typer.Option(..., "--country", "-c", help="Country code (e.g. FR, NL). Repeat for multiple."),
+    format: str = typer.Option("table", "--format", "-f", help="Output format: table, csv, json"),
+    output_path: Optional[str] = typer.Option(None, "--output", "-o", help="Output file path"),
+    api_key: Optional[str] = typer.Option(None, "--api-key", help="ENTSO-E API key"),
+):
+    """Query imbalance volumes."""
+    from entsoe.cli.app import get_client
+
+    client = get_client(api_key)
+    countries = country[0] if len(country) == 1 else country
+    df = client.balancing.imbalance_volumes(start, end, country=countries)
+    output(df, format, title="Imbalance Volumes", output_path=output_path)

python_entsoe-0.4.0/src/entsoe/cli/config.py

@@ -0,0 +1,63 @@
+"""Configuration management — read/write config.toml and env vars."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+CONFIG_DIR = Path.home() / ".config" / "entsoe"
+CONFIG_FILE = CONFIG_DIR / "config.toml"
+
+
+def get_api_key() -> str | None:
+    """Resolve API key: config file > env var."""
+    # Try config file first
+    if CONFIG_FILE.exists():
+        try:
+            import tomllib
+        except ImportError:
+            import tomli as tomllib  # type: ignore[no-redef]
+
+        with open(CONFIG_FILE, "rb") as f:
+            config = tomllib.load(f)
+        key = config.get("api-key")
+        if key:
+            return key
+
+    # Fall back to environment variable
+    return os.getenv("ENTSOE_API_KEY")
+
+
+def set_config(key: str, value: str) -> None:
+    """Write a key-value pair to config.toml."""
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+
+    config: dict = {}
+    if CONFIG_FILE.exists():
+        try:
+            import tomllib
+        except ImportError:
+            import tomli as tomllib  # type: ignore[no-redef]
+
+        with open(CONFIG_FILE, "rb") as f:
+            config = tomllib.load(f)
+
+    config[key] = value
+
+    # Write as simple TOML
+    lines = [f'{k} = "{v}"' for k, v in config.items()]
+    CONFIG_FILE.write_text("\n".join(lines) + "\n")
+
+
+def get_config(key: str) -> str | None:
+    """Read a value from config.toml."""
+    if not CONFIG_FILE.exists():
+        return None
+    try:
+        import tomllib
+    except ImportError:
+        import tomli as tomllib  # type: ignore[no-redef]
+
+    with open(CONFIG_FILE, "rb") as f:
+        config = tomllib.load(f)
+    return config.get(key)

python_entsoe-0.4.0/src/entsoe/cli/config_cmd.py

@@ -0,0 +1,34 @@
+"""CLI subcommands for configuration management."""
+
+from __future__ import annotations
+
+import typer
+
+config_app = typer.Typer(no_args_is_help=True)
+
+
+@config_app.command("set")
+def config_set(
+    key: str = typer.Argument(..., help="Configuration key (e.g., 'api-key')"),
+    value: str = typer.Argument(..., help="Configuration value"),
+):
+    """Set a configuration value."""
+    from entsoe.cli.config import set_config
+
+    set_config(key, value)
+    typer.echo(f"Set {key} = {'***' if 'key' in key.lower() else value}")
+
+
+@config_app.command("get")
+def config_get(
+    key: str = typer.Argument(..., help="Configuration key to read"),
+):
+    """Get a configuration value."""
+    from entsoe.cli.config import get_config
+
+    val = get_config(key)
+    if val is None:
+        typer.echo(f"{key}: (not set)")
+    else:
+        display = "***" if "key" in key.lower() else val
+        typer.echo(f"{key} = {display}")