feat: migrate catalog from hardcoded Python to YAML-backed manager

Replace inline catalog definitions with YAML-backed ENTSOECatalogManager,
add IT_SUD neighbour mapping for GR, expose catalog on client, add pyyaml
dependency, and mark integration tests.

Author: jsulopzs

pyproject.toml

@@ -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 = [

src/entsoe/_mappings.py

@@ -399,6 +399,7 @@ def psr_name(identifier: str) -> 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"},

src/entsoe/catalog.py

@@ -7,202 +7,25 @@
 
 from __future__ import annotations
 
-from dataclasses import dataclass, field
+# 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"]
 
-@dataclass(frozen=True)
-class Endpoint:
-    """A queryable data endpoint."""
+# ── Load categories from YAML ──────────────────────────────────────────
 
-    name: str
-    description: str
-    method: str  # Python client method name
-    cli: str  # CLI command
-    resolution: str  # e.g. "15min", "hourly", "daily"
-    columns: tuple[str, ...]  # key columns returned
-    units: str
-    notes: str = ""
+_mgr = _Manager()
+_cats = {c.key: c for c in _mgr._load_categories()}
 
+CATEGORIES: dict[str, Category] = _cats
 
-@dataclass(frozen=True)
-class Category:
-    """A top-level data category grouping related endpoints."""
-
-    name: str
-    description: str
-    namespace: str  # Python client namespace (e.g. "prices")
-    endpoints: tuple[Endpoint, ...]
-
-
-# ── Prices ──────────────────────────────────────────────────────────────
-
-PRICES = Category(
-    name="Prices",
-    description="Day-ahead electricity market prices",
-    namespace="prices",
-    endpoints=(
-        Endpoint(
-            name="Day-Ahead Prices",
-            description="Hourly day-ahead market clearing prices per bidding zone",
-            method="client.prices.day_ahead(start, end, country='FR')",
-            cli="entsoe prices day-ahead -s 2024-06-01 -e 2024-06-08 -c FR",
-            resolution="hourly",
-            columns=("timestamp", "country", "value", "currency", "quantity_unit"),
-            units="EUR/MWh",
-        ),
-    ),
-)
-
-# ── Load ────────────────────────────────────────────────────────────────
-
-LOAD = Category(
-    name="Load",
-    description="Actual system load and day-ahead load forecasts",
-    namespace="load",
-    endpoints=(
-        Endpoint(
-            name="Actual Total Load",
-            description="Actual total electricity consumption per control area",
-            method="client.load.actual(start, end, country='FR')",
-            cli="entsoe load actual -s 2024-06-01 -e 2024-06-08 -c FR",
-            resolution="15min or hourly (varies by country)",
-            columns=("timestamp", "country", "value", "quantity_unit"),
-            units="MW",
-        ),
-        Endpoint(
-            name="Day-Ahead Load Forecast",
-            description="Day-ahead forecast of total electricity consumption",
-            method="client.load.forecast(start, end, country='FR')",
-            cli="entsoe load forecast -s 2024-06-01 -e 2024-06-08 -c FR",
-            resolution="15min or hourly (varies by country)",
-            columns=("timestamp", "country", "value", "quantity_unit"),
-            units="MW",
-        ),
-    ),
-)
-
-# ── Generation ──────────────────────────────────────────────────────────
-
-GENERATION = Category(
-    name="Generation",
-    description="Actual generation, forecasts, installed capacity, and per-plant output",
-    namespace="generation",
-    endpoints=(
-        Endpoint(
-            name="Actual Generation per Type",
-            description="Actual electricity generation broken down by fuel/technology type (PSR)",
-            method="client.generation.actual(start, end, country='FR')",
-            cli="entsoe generation actual -s 2024-06-01 -e 2024-06-08 -c FR",
-            resolution="15min or hourly",
-            columns=("timestamp", "country", "psr_type", "value", "quantity_unit"),
-            units="MW",
-            notes="Filter by PSR type: --psr solar --psr wind_onshore",
-        ),
-        Endpoint(
-            name="Generation Forecast (Wind/Solar)",
-            description="Day-ahead forecast for wind and solar generation",
-            method="client.generation.forecast(start, end, country='FR')",
-            cli="entsoe generation forecast -s 2024-06-01 -e 2024-06-08 -c FR",
-            resolution="15min or hourly",
-            columns=("timestamp", "country", "psr_type", "value", "quantity_unit"),
-            units="MW",
-        ),
-        Endpoint(
-            name="Installed Generation Capacity",
-            description="Installed generation capacity per type (updated annually or on change)",
-            method="client.generation.installed_capacity(start, end, country='FR')",
-            cli="entsoe generation capacity -s 2024-06-01 -e 2024-06-08 -c FR",
-            resolution="yearly (point-in-time)",
-            columns=("timestamp", "country", "psr_type", "value", "quantity_unit"),
-            units="MW",
-        ),
-        Endpoint(
-            name="Actual Generation per Plant",
-            description="Generation output per individual production unit (>= 100 MW)",
-            method="client.generation.per_plant(start, end, country='FR')",
-            cli="entsoe generation per-plant -s 2024-06-01 -e 2024-06-08 -c FR",
-            resolution="15min or hourly",
-            columns=("timestamp", "country", "unit_name", "psr_type", "value", "quantity_unit"),
-            units="MW",
-        ),
-    ),
-)
-
-# ── Transmission ────────────────────────────────────────────────────────
-
-TRANSMISSION = Category(
-    name="Transmission",
-    description="Cross-border physical flows, scheduled exchanges, and transfer capacity",
-    namespace="transmission",
-    endpoints=(
-        Endpoint(
-            name="Physical Cross-Border Flows",
-            description="Actual measured electricity flows between bidding zones",
-            method="client.transmission.crossborder_flows(start, end, country_from='FR', country_to='DE_LU')",
-            cli="entsoe transmission flows -s 2024-06-01 -e 2024-06-08 --from FR --to DE_LU",
-            resolution="15min or hourly",
-            columns=("timestamp", "in_domain", "value", "quantity_unit"),
-            units="MW",
-            notes="Use --border for multi-border queries: --border FR-*, --border iberian",
-        ),
-        Endpoint(
-            name="Scheduled Commercial Exchanges",
-            description="Day-ahead scheduled commercial power exchanges between zones",
-            method="client.transmission.scheduled_exchanges(start, end, country_from='FR', country_to='ES')",
-            cli="entsoe transmission exchanges -s 2024-06-01 -e 2024-06-08 --from FR --to ES",
-            resolution="hourly",
-            columns=("timestamp", "in_domain", "value", "quantity_unit"),
-            units="MW",
-        ),
-        Endpoint(
-            name="Net Transfer Capacity",
-            description="Available transfer capacity (NTC) between bidding zones",
-            method="client.transmission.net_transfer_capacity(start, end, country_from='FR', country_to='ES')",
-            cli="entsoe transmission capacity -s 2024-06-01 -e 2024-06-08 --from FR --to ES",
-            resolution="hourly",
-            columns=("timestamp", "in_domain", "value", "quantity_unit"),
-            units="MW",
-        ),
-    ),
-)
-
-# ── Balancing ───────────────────────────────────────────────────────────
-
-BALANCING = Category(
-    name="Balancing",
-    description="System imbalance prices and volumes",
-    namespace="balancing",
-    endpoints=(
-        Endpoint(
-            name="Imbalance Prices",
-            description="System imbalance settlement prices",
-            method="client.balancing.imbalance_prices(start, end, country='FR')",
-            cli="entsoe balancing prices -s 2024-06-01 -e 2024-06-08 -c FR",
-            resolution="15min or hourly (varies by country)",
-            columns=("timestamp", "country", "value", "quantity_unit"),
-            units="EUR/MWh",
-        ),
-        Endpoint(
-            name="Imbalance Volumes",
-            description="Net system imbalance volumes",
-            method="client.balancing.imbalance_volumes(start, end, country='FR')",
-            cli="entsoe balancing volumes -s 2024-06-01 -e 2024-06-08 -c FR",
-            resolution="15min or hourly (varies by country)",
-            columns=("timestamp", "country", "value", "quantity_unit"),
-            units="MW",
-        ),
-    ),
-)
-
-# ── Full catalog ────────────────────────────────────────────────────────
-
-CATEGORIES: dict[str, Category] = {
-    "prices": PRICES,
-    "load": LOAD,
-    "generation": GENERATION,
-    "transmission": TRANSMISSION,
-    "balancing": BALANCING,
-}
+# 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:

src/entsoe/client.py

@@ -7,6 +7,7 @@
 
 from ._http import HttpClient
 from .cache import CacheConfig, CacheStore
+from .catalog_manager import ENTSOECatalogManager
 from .namespaces import (
     BalancingNamespace,
     GenerationNamespace,
@@ -100,6 +101,8 @@ def __init__(
         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