python-entsoe 0.5.0__tar.gz → 0.6.0__tar.gz

python_entsoe-0.6.0/.release-please-manifest.json

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

{python_entsoe-0.5.0 → python_entsoe-0.6.0}/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [0.6.0](https://github.com/datons/python-entsoe/compare/python-entsoe-v0.5.0...python-entsoe-v0.6.0) (2026-03-04)
+
+
+### Features
+
+* add built-in data catalog with CLI and Python API ([987bb18](https://github.com/datons/python-entsoe/commit/987bb181f0d1b6a8d18578b25902b77c7029ac6f))
+* migrate catalog from hardcoded Python to YAML-backed manager ([dcc35f7](https://github.com/datons/python-entsoe/commit/dcc35f7aa6359f49ef9f870d942c6d860c319597))
+
+
+### Bug Fixes
+
+* update skill with correct exec syntax and Python-first approach ([bd6dca7](https://github.com/datons/python-entsoe/commit/bd6dca7a9a8ac74c0f855719cc660a93a918eaf4))
+
 ## [0.5.0](https://github.com/datons/python-entsoe/compare/python-entsoe-v0.4.2...python-entsoe-v0.5.0) (2026-03-04)
 
 

{python_entsoe-0.5.0 → python_entsoe-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-entsoe
-Version: 0.5.0
+Version: 0.6.0
 Summary: Python client for the ENTSO-E Transparency Platform API
 Project-URL: Homepage, https://github.com/datons/python-entsoe
 Project-URL: Repository, https://github.com/datons/python-entsoe
@@ -21,6 +21,7 @@ Classifier: Topic :: Scientific/Engineering
 Requires-Python: >=3.10
 Requires-Dist: pandas>=2.0
 Requires-Dist: pyarrow>=23.0.1
+Requires-Dist: pyyaml>=6.0
 Requires-Dist: requests>=2.28
 Requires-Dist: rich>=13.0
 Requires-Dist: typer>=0.9

{python_entsoe-0.5.0 → python_entsoe-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-entsoe"
-version = "0.5.0"
+version = "0.6.0"
 description = "Python client for the ENTSO-E Transparency Platform API"
 readme = "README.md"
 license = "MIT"
@@ -22,6 +22,7 @@ classifiers = [
 ]
 dependencies = [
     "pandas>=2.0",
+    "pyyaml>=6.0",
     "requests>=2.28",
     "typer>=0.9",
     "rich>=13.0",
@@ -46,6 +47,9 @@ packages = ["src/entsoe"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+markers = [
+    "integration: tests that hit real APIs (deselect with -m 'not integration')",
+]
 
 [dependency-groups]
 dev = [

{python_entsoe-0.5.0 → python_entsoe-0.6.0/src/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
+## Python Library (default)
 
-# 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
-```
+```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 Client
+### Catalog (offline)
 
-client = Client()  # 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
 ```
 
-The config file is stored at `~/.config/entsoe/config.toml`.
+### Output options
 
-## Key Conventions
+```
+--format table|csv|json   (default: table)
+--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 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`
+## Configuration
+
+```bash
+entsoe config set api-key YOUR_KEY
+entsoe config get api-key
+```
+
+Config file: `~/.config/entsoe/config.toml`. API key resolution: config file > `ENTSOE_API_KEY` env var.

{python_entsoe-0.5.0 → python_entsoe-0.6.0}/src/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",
 ]

{python_entsoe-0.5.0 → python_entsoe-0.6.0}/src/entsoe/_mappings.py

@@ -399,6 +399,7 @@ NEIGHBOURS: dict[str, set[str]] = {
     "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"},

python_entsoe-0.6.0/src/entsoe/catalog.py

@@ -0,0 +1,51 @@
+"""Built-in data catalog for ENTSO-E Transparency Platform.
+
+Provides structured metadata about available data categories, endpoints,
+country codes, PSR types, and border groups — so users don't need to
+consult external documentation every time.
+"""
+
+from __future__ import annotations
+
+# Re-export dataclasses for backward compatibility
+from entsoe._models import Category, Endpoint
+from entsoe.catalog_manager import ENTSOECatalogManager as _Manager
+
+__all__ = ["Category", "Endpoint", "CATEGORIES", "get_category", "summary"]
+
+# ── Load categories from YAML ──────────────────────────────────────────
+
+_mgr = _Manager()
+_cats = {c.key: c for c in _mgr._load_categories()}
+
+CATEGORIES: dict[str, Category] = _cats
+
+# Individual constants for backward compatibility
+PRICES = CATEGORIES["prices"]
+LOAD = CATEGORIES["load"]
+GENERATION = CATEGORIES["generation"]
+TRANSMISSION = CATEGORIES["transmission"]
+BALANCING = CATEGORIES["balancing"]
+
+
+def get_category(name: str) -> Category:
+    """Look up a category by name (case-insensitive)."""
+    key = name.lower().strip()
+    if key not in CATEGORIES:
+        raise KeyError(
+            f"Unknown category '{name}'. Available: {', '.join(CATEGORIES.keys())}"
+        )
+    return CATEGORIES[key]
+
+
+def summary() -> str:
+    """Return a human-readable summary of all available data."""
+    lines = ["ENTSO-E Data Catalog", "=" * 50, ""]
+    for key, cat in CATEGORIES.items():
+        lines.append(f"{cat.name} ({cat.namespace})")
+        lines.append(f"  {cat.description}")
+        for ep in cat.endpoints:
+            lines.append(f"    - {ep.name}: {ep.description}")
+            lines.append(f"      Resolution: {ep.resolution} | Units: {ep.units}")
+        lines.append("")
+    return "\n".join(lines)

{python_entsoe-0.5.0 → python_entsoe-0.6.0}/src/entsoe/cli/app.py

@@ -38,6 +38,7 @@ from entsoe.cli.transmission import transmission_app  # noqa: E402
 from entsoe.cli.balancing import balancing_app  # noqa: E402
 from entsoe.cli.config_cmd import config_app  # noqa: E402
 from entsoe.cli.cache_cmd import cache_app  # noqa: E402
+from entsoe.cli.catalog_cmd import catalog_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")
@@ -46,6 +47,7 @@ app.add_typer(transmission_app, name="transmission", help="Cross-border flows an
 app.add_typer(balancing_app, name="balancing", help="Imbalance prices and volumes")
 app.add_typer(config_app, name="config", help="Configuration management")
 app.add_typer(cache_app, name="cache", help="Cache management (status, clear)")
+app.add_typer(catalog_app, name="catalog", help="Browse available data, countries, PSR types, and borders")
 
 
 def main() -> None:

python_entsoe-0.6.0/src/entsoe/cli/catalog_cmd.py

@@ -0,0 +1,148 @@
+"""CLI command: browse the built-in data catalog."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from entsoe._mappings import AREA_CODES, COUNTRY_NAMES, PSR_CODES, PSR_TYPES, BORDER_GROUPS, NEIGHBOURS
+
+catalog_app = typer.Typer(no_args_is_help=True)
+console = Console()
+
+
+@catalog_app.command("list")
+def catalog_list():
+    """List all available data categories and endpoints."""
+    from entsoe.catalog import CATEGORIES
+
+    for key, cat in CATEGORIES.items():
+        console.print(f"\n[bold]{cat.name}[/bold] — {cat.description}")
+        console.print(f"  Python: client.{cat.namespace}.*")
+        console.print(f"  CLI:    entsoe {key} <command>")
+
+        table = Table(show_header=True, padding=(0, 1))
+        table.add_column("Endpoint", style="cyan")
+        table.add_column("CLI Command", style="green")
+        table.add_column("Resolution")
+        table.add_column("Units")
+
+        for ep in cat.endpoints:
+            cli_short = ep.cli.split("entsoe ")[-1].split(" -")[0]
+            table.add_row(ep.name, cli_short, ep.resolution, ep.units)
+
+        console.print(table)
+
+
+@catalog_app.command("countries")
+def catalog_countries(
+    query: Optional[str] = typer.Argument(None, help="Filter by country name or code"),
+):
+    """List available country and bidding zone codes."""
+    table = Table(title="Country / Bidding Zone Codes", show_header=True, padding=(0, 1))
+    table.add_column("Code", style="cyan")
+    table.add_column("Name")
+    table.add_column("Neighbours", style="dim")
+
+    for code in sorted(AREA_CODES.keys()):
+        name = COUNTRY_NAMES.get(code, "")
+        if query:
+            q = query.lower()
+            if q not in code.lower() and q not in name.lower():
+                continue
+        neighbours = ", ".join(sorted(NEIGHBOURS.get(code, set())))
+        table.add_row(code, name, neighbours)
+
+    console.print(table)
+
+
+@catalog_app.command("psr")
+def catalog_psr():
+    """List available PSR (generation) types."""
+    table = Table(title="PSR Types (Generation)", show_header=True, padding=(0, 1))
+    table.add_column("Shorthand", style="cyan")
+    table.add_column("ENTSO-E Code", style="green")
+    table.add_column("Full Name")
+
+    for shorthand, code in sorted(PSR_CODES.items()):
+        full_name = PSR_TYPES.get(code, "")
+        table.add_row(shorthand, code, full_name)
+
+    console.print(table)
+
+
+@catalog_app.command("borders")
+def catalog_borders(
+    country: Optional[str] = typer.Argument(None, help="Show borders for a specific country (e.g. FR, DE_LU)"),
+):
+    """List border groups and interconnections."""
+    if country:
+        code = country.upper().strip()
+        if code not in NEIGHBOURS:
+            console.print(f"[red]Unknown country '{country}'[/red]. Use 'entsoe catalog countries' to list.")
+            raise typer.Exit(1)
+
+        name = COUNTRY_NAMES.get(code, code)
+        console.print(f"\n[bold]{name} ({code})[/bold] — {len(NEIGHBOURS[code])} interconnections:")
+
+        table = Table(show_header=True, padding=(0, 1))
+        table.add_column("Neighbour", style="cyan")
+        table.add_column("Name")
+        table.add_column("CLI (flows)")
+
+        for n in sorted(NEIGHBOURS[code]):
+            n_name = COUNTRY_NAMES.get(n, n)
+            table.add_row(n, n_name, f"entsoe transmission flows --from {code} --to {n}")
+
+        console.print(table)
+        console.print(f"\n[dim]Shortcut: entsoe transmission flows --border {code}-*[/dim]")
+    else:
+        # Show named border groups
+        console.print("\n[bold]Named Border Groups[/bold]")
+        table = Table(show_header=True, padding=(0, 1))
+        table.add_column("Group", style="cyan")
+        table.add_column("Borders")
+
+        for group_name, pairs in sorted(BORDER_GROUPS.items()):
+            unique = set()
+            for a, b in pairs:
+                key = tuple(sorted([a, b]))
+                unique.add(key)
+            border_strs = [f"{a}-{b}" for a, b in sorted(unique)]
+            table.add_row(group_name, ", ".join(border_strs[:8]) + ("..." if len(border_strs) > 8 else ""))
+
+        console.print(table)
+        console.print(f"\n[dim]Use 'entsoe catalog borders <COUNTRY>' for a specific country.[/dim]")
+
+
+@catalog_app.command("show")
+def catalog_show(
+    category: str = typer.Argument(..., help="Category name: prices, load, generation, transmission, balancing"),
+):
+    """Show detailed info for a specific data category."""
+    from entsoe.catalog import get_category
+
+    try:
+        cat = get_category(category)
+    except KeyError as e:
+        console.print(f"[red]{e}[/red]")
+        raise typer.Exit(1)
+
+    console.print(f"\n[bold]{cat.name}[/bold] — {cat.description}")
+    console.print(f"  Python namespace: client.{cat.namespace}")
+    console.print()
+
+    for ep in cat.endpoints:
+        console.print(f"  [cyan]{ep.name}[/cyan]")
+        console.print(f"    {ep.description}")
+        console.print(f"    Resolution: {ep.resolution}")
+        console.print(f"    Units: {ep.units}")
+        console.print(f"    Columns: {', '.join(ep.columns)}")
+        console.print(f"    Python: {ep.method}")
+        console.print(f"    CLI:    {ep.cli}")
+        if ep.notes:
+            console.print(f"    Notes:  {ep.notes}")
+        console.print()

{python_entsoe-0.5.0 → python_entsoe-0.6.0}/src/entsoe/client.py

@@ -7,6 +7,7 @@ from pathlib import Path
 
 from ._http import HttpClient
 from .cache import CacheConfig, CacheStore
+from .catalog_manager import ENTSOECatalogManager
 from .namespaces import (
     BalancingNamespace,
     GenerationNamespace,
@@ -100,6 +101,8 @@ class ENTSOEClient:
         self.transmission = TransmissionNamespace(http, tz=tz, cache=cache_store)
         self.balancing = BalancingNamespace(http, tz=tz, cache=cache_store)
 
+        self.catalog = ENTSOECatalogManager(self)
+
         # Expose for CLI cache commands
         self._cache = cache_store
 

{python_entsoe-0.5.0 → python_entsoe-0.6.0}/uv.lock

@@ -1705,12 +1705,13 @@ wheels = [
 
 [[package]]
 name = "python-entsoe"
-version = "0.4.1"
+version = "0.5.0"
 source = { editable = "." }
 dependencies = [
     { name = "pandas", version = "2.3.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
     { name = "pandas", version = "3.0.0", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" },
     { name = "pyarrow" },
+    { name = "pyyaml" },
     { name = "requests" },
     { name = "rich" },
     { name = "typer" },
@@ -1728,6 +1729,7 @@ dev = [
 requires-dist = [
     { name = "pandas", specifier = ">=2.0" },
     { name = "pyarrow", specifier = ">=23.0.1" },
+    { name = "pyyaml", specifier = ">=6.0" },
     { name = "requests", specifier = ">=2.28" },
     { name = "rich", specifier = ">=13.0" },
     { name = "typer", specifier = ">=0.9" },

python_entsoe-0.5.0/.release-please-manifest.json

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

python_entsoe-0.5.0/src/entsoe/.agents/skills/entsoe/SKILL.md

@@ -1,202 +0,0 @@
----
-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 ENTSOEClient
-
-client = ENTSOEClient()  # 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`