python-entsoe 0.4.2__py3-none-any.whl → 0.6.0__py3-none-any.whl

entsoe/.agents/skills/entsoe/SKILL.md

@@ -1,105 +1,61 @@
 ---
 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
+version: 2.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).
+You have access to the `python-entsoe` library and CLI for querying the ENTSO-E Transparency Platform (European electricity market data).
 
-## CLI Reference
+## When to use what
 
-### Prices
+- **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.
 
-```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
+## Python Library (default)
 
-```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
-```
+```python
+from entsoe import Client
 
-### Exec (ad-hoc pandas expressions)
+client = Client()  # reads config file, then ENTSOE_API_KEY env var
 
-Run any pandas expression against fetched data:
+# --- 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"])
 
-```bash
-# Descriptive statistics on prices
-entsoe exec prices day-ahead -s 2024-06-01 -e 2024-06-08 -c FR -x "df.describe()"
+# --- 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")
 
-# Daily mean load
-entsoe exec load actual -s 2024-06-01 -e 2024-06-08 -c FR -x "df.resample('D').mean()"
+# --- 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")
 
-# 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 ---
+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")
 
-# Transmission analysis
-entsoe exec transmission flows -s 2024-06-01 -e 2024-06-08 --from FR --to ES -x "df.describe()"
+# --- 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")
 ```
 
-### Output formats
+### Key conventions
 
-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
-```
+- **Timezone**: All string dates are interpreted in Europe/Brussels (CET) by default
+- **Auto year-splitting**: Date ranges > 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 `country_from`/`country_to`; multi-value adds a `border` column
+- **No caching**: Data is fetched fresh on each request
+- **Custom exceptions**: `ENTSOEError`, `AuthenticationError`, `APIResponseError`, `InvalidParameterError`, `NetworkError`
 
 ## Country Codes
 
@@ -143,60 +99,78 @@ Bidding zones: `DK_1`, `DK_2`, `NO_1`–`NO_5`, `SE_1`–`SE_4`, `IT_NORTH`, `IT
 | 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`).
+Use shorthands with `psr_type=` (Python) or `--psr` (CLI), e.g. `psr_type="solar"` or `--psr solar`.
 
-## Python Library
+## CLI Reference (quick lookups)
 
-```python
-from entsoe import ENTSOEClient
+### Catalog (offline)
 
-client = ENTSOEClient()  # reads config file, then ENTSOE_API_KEY env var
+```bash
+entsoe catalog list              # All data categories and endpoints
+entsoe catalog show prices       # Detailed info for a category
+entsoe catalog countries         # Country/bidding zone codes
+entsoe catalog psr               # PSR (generation) types
+entsoe catalog borders           # Border groups and interconnections
+```
+
+### Fetch data
 
+```bash
 # 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"])
+entsoe prices day-ahead -s 2024-06-01 -e 2024-06-08 -c FR
+entsoe prices day-ahead -P week -c FR,ES          # Period shorthand
 
 # 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")
+entsoe load actual -P month -c FR
+entsoe load forecast -s 2024-06-01 -e 2024-06-08 -c 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")
+entsoe generation actual -P week -c FR --psr solar --psr wind_onshore
+entsoe generation forecast -P week -c FR
+entsoe generation capacity -s 2024-01-01 -e 2024-12-31 -c FR
+entsoe generation per-plant -P week -c 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")
+entsoe transmission flows -P week --from FR --to ES
+entsoe transmission exchanges -P week --border ES-*,FR-*
 
 # 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")
+entsoe balancing prices -P week -c FR
+entsoe balancing volumes -P week -c FR
 ```
 
-## Configuration
+### Exec (ad-hoc pandas)
+
+`exec` is a subcommand **within each namespace**:
 
 ```bash
-# Store your API key persistently (recommended)
-entsoe config set api-key YOUR_KEY
+entsoe prices exec day-ahead -P week -c FR -x "df.describe()"
+entsoe load exec actual -P 7d -c FR -x "df.resample('D').mean()"
+entsoe generation exec actual -P month -c FR --psr solar -x "df.head(20)"
+entsoe transmission exec flows -P week --from FR --to ES -x "df.describe()"
+entsoe balancing exec prices -P week -c NL -x "df.describe()"
+```
 
-# Verify it's stored
-entsoe config get api-key
+### Period shorthand (`-P`)
+
+All data commands support `-P` as an alternative to `--start`/`--end`:
+
+```
+-P today, -P yesterday, -P week, -P month, -P ytd, -P 14d
+```
+
+### Output options
+
+```
+--format table|csv|json   (default: table)
+--output file.csv         (write to file instead of stdout)
 ```
 
-The config file is stored at `~/.config/entsoe/config.toml`.
+## Configuration
 
-## Key Conventions
+```bash
+entsoe config set api-key YOUR_KEY
+entsoe config get api-key
+```
 
-- **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`
+Config file: `~/.config/entsoe/config.toml`. API key resolution: config file > `ENTSOE_API_KEY` env var.

entsoe/__init__.py

@@ -3,6 +3,7 @@
 from .client import Client, ENTSOEClient
 from .exceptions import ENTSOEError, InvalidParameterError, NoDataError, RateLimitError
 from ._mappings import COUNTRY_NAMES, PSR_CODES, country_name, psr_name
+from . import catalog
 
 __version__ = "0.4.2"
 __all__ = [
@@ -14,6 +15,7 @@ __all__ = [
     "NoDataError",
     "PSR_CODES",
     "RateLimitError",
+    "catalog",
     "country_name",
     "psr_name",
 ]

entsoe/_mappings.py

@@ -354,3 +354,150 @@ def psr_name(identifier: str) -> str:
     """
     code = lookup_psr(identifier)
     return PSR_TYPES[code]
+
+
+# ── Border / neighbour data (for CLI --border flag) ───────────────────────
+
+# Direct interconnections between bidding zones used by ENTSO-E.
+# Each key maps to the set of zones it has a physical border with.
+NEIGHBOURS: dict[str, set[str]] = {
+    "ES": {"FR", "PT"},
+    "FR": {"ES", "BE", "CH", "DE_LU", "GB", "IT_NORTH"},
+    "PT": {"ES"},
+    "BE": {"FR", "NL", "DE_LU", "GB"},
+    "NL": {"BE", "DE_LU", "GB", "NO_2", "DK_1"},
+    "DE_LU": {"FR", "BE", "NL", "AT", "CH", "CZ", "DK_1", "DK_2", "PL", "SE_4", "NO_2"},
+    "AT": {"DE_LU", "CH", "CZ", "HU", "SI", "IT_NORTH"},
+    "CH": {"FR", "DE_LU", "AT", "IT_NORTH"},
+    "IT_NORTH": {"FR", "CH", "AT", "SI"},
+    "GB": {"FR", "BE", "NL", "IE_SEM", "NO_2"},
+    "IE_SEM": {"GB"},
+    "DK_1": {"DE_LU", "NL", "NO_2", "SE_3", "DK_2"},
+    "DK_2": {"DE_LU", "DK_1", "SE_4"},
+    "NO_1": {"NO_2", "NO_3", "NO_5", "SE_3"},
+    "NO_2": {"NO_1", "NO_5", "NL", "DK_1", "DE_LU", "GB"},
+    "NO_3": {"NO_1", "NO_4", "NO_5", "SE_2"},
+    "NO_4": {"NO_3", "SE_1", "SE_2", "FI"},
+    "NO_5": {"NO_1", "NO_2", "NO_3"},
+    "SE_1": {"NO_4", "SE_2", "FI"},
+    "SE_2": {"NO_3", "NO_4", "SE_1", "SE_3"},
+    "SE_3": {"NO_1", "DK_1", "SE_2", "SE_4", "FI"},
+    "SE_4": {"DE_LU", "DK_2", "SE_3", "PL", "LT"},
+    "FI": {"NO_4", "SE_1", "SE_3", "EE"},
+    "EE": {"FI", "LV"},
+    "LV": {"EE", "LT"},
+    "LT": {"LV", "SE_4", "PL"},
+    "PL": {"DE_LU", "CZ", "SK", "LT", "SE_4"},
+    "CZ": {"DE_LU", "AT", "PL", "SK"},
+    "SK": {"CZ", "PL", "HU"},
+    "HU": {"AT", "SK", "RO", "HR", "SI", "RS"},
+    "SI": {"AT", "IT_NORTH", "HU", "HR"},
+    "HR": {"HU", "SI", "RS", "BA"},
+    "RS": {"HU", "HR", "BA", "RO", "BG", "MK", "ME", "AL"},
+    "BA": {"HR", "RS", "ME"},
+    "RO": {"HU", "RS", "BG"},
+    "BG": {"RO", "RS", "MK", "GR", "TR"},
+    "MK": {"RS", "BG", "GR", "AL"},
+    "GR": {"BG", "MK", "AL", "IT_SUD", "TR"},
+    "IT_SUD": {"GR"},
+    "AL": {"RS", "MK", "GR", "ME"},
+    "ME": {"RS", "BA", "AL"},
+    "TR": {"BG", "GR"},
+}
+
+# Named border groups for convenient CLI usage.
+# ── Border parsing (library-level) ────────────────────────────────────────
+
+
+def parse_borders(specs: str | list[str]) -> list[tuple[str, str]]:
+    """Parse border specifications into deduplicated (from, to) pairs.
+
+    Supported formats:
+
+    - ``"ES-FR"``          — single border
+    - ``"ES-FR,ES-PT"``    — comma-separated within a string
+    - ``["ES-*", "FR-*"]`` — list with wildcards (all neighbours)
+    - ``"iberian"``        — named group
+
+    Deduplicates pairs while preserving insertion order, so
+    ``"ES-*,FR-*"`` won't produce ``(ES, FR)`` and ``(FR, ES)`` twice
+    if both wildcards expand to include each other.
+
+    Args:
+        specs: A single spec string or list of spec strings.
+
+    Returns:
+        Deduplicated list of ``(country_from, country_to)`` tuples.
+
+    Raises:
+        InvalidParameterError: On unknown country or invalid spec format.
+    """
+    from .exceptions import InvalidParameterError
+
+    if isinstance(specs, str):
+        specs = [specs]
+
+    flat = [v.strip() for raw in specs for v in raw.split(",") if v.strip()]
+    seen: set[tuple[str, str]] = set()
+    pairs: list[tuple[str, str]] = []
+
+    def _add(pair: tuple[str, str]) -> None:
+        if pair not in seen:
+            seen.add(pair)
+            pairs.append(pair)
+
+    for spec in flat:
+        low = spec.lower()
+
+        # Named group
+        if low in BORDER_GROUPS:
+            for p in BORDER_GROUPS[low]:
+                _add(p)
+            continue
+
+        # Pair: A-B or A-*
+        if "-" in spec:
+            parts = spec.split("-", 1)
+            a, b = parts[0].strip().upper(), parts[1].strip().upper()
+            if b == "*":
+                if a not in NEIGHBOURS:
+                    raise InvalidParameterError(
+                        f"No known neighbours for '{a}'. "
+                        f"Available: {', '.join(sorted(NEIGHBOURS.keys()))}"
+                    )
+                for n in sorted(NEIGHBOURS[a]):
+                    _add((a, n))
+            else:
+                _add((a, b))
+            continue
+
+        raise InvalidParameterError(
+            f"Invalid border spec '{spec}'. Use A-B, A-*, or a group name "
+            f"({', '.join(sorted(BORDER_GROUPS.keys()))})."
+        )
+
+    return pairs
+
+
+BORDER_GROUPS: dict[str, list[tuple[str, str]]] = {
+    "iberian": [("ES", "FR"), ("ES", "PT"), ("PT", "ES"), ("FR", "ES")],
+    "nordic": [
+        ("NO_1", "NO_2"), ("NO_1", "NO_3"), ("NO_1", "NO_5"), ("NO_1", "SE_3"),
+        ("NO_2", "NO_1"), ("NO_2", "NO_5"), ("NO_2", "NL"), ("NO_2", "DK_1"), ("NO_2", "DE_LU"), ("NO_2", "GB"),
+        ("NO_3", "NO_1"), ("NO_3", "NO_4"), ("NO_3", "NO_5"), ("NO_3", "SE_2"),
+        ("NO_4", "NO_3"), ("NO_4", "SE_1"), ("NO_4", "SE_2"), ("NO_4", "FI"),
+        ("NO_5", "NO_1"), ("NO_5", "NO_2"), ("NO_5", "NO_3"),
+        ("SE_1", "NO_4"), ("SE_1", "SE_2"), ("SE_1", "FI"),
+        ("SE_2", "NO_3"), ("SE_2", "NO_4"), ("SE_2", "SE_1"), ("SE_2", "SE_3"),
+        ("SE_3", "NO_1"), ("SE_3", "DK_1"), ("SE_3", "SE_2"), ("SE_3", "SE_4"), ("SE_3", "FI"),
+        ("SE_4", "DE_LU"), ("SE_4", "DK_2"), ("SE_4", "SE_3"), ("SE_4", "PL"), ("SE_4", "LT"),
+        ("DK_1", "DK_2"), ("DK_1", "DE_LU"), ("DK_1", "NL"), ("DK_1", "NO_2"), ("DK_1", "SE_3"),
+        ("DK_2", "DK_1"), ("DK_2", "DE_LU"), ("DK_2", "SE_4"),
+        ("FI", "NO_4"), ("FI", "SE_1"), ("FI", "SE_3"), ("FI", "EE"),
+    ],
+    "baltic": [
+        ("EE", "FI"), ("EE", "LV"),
+        ("LV", "EE"), ("LV", "LT"),
+        ("LT", "LV"), ("LT", "SE_4"), ("LT", "PL"),
+    ],
+}