python-entsoe 0.1.0__py3-none-any.whl

entsoe/__init__.py

@@ -0,0 +1,13 @@
+"""ENTSO-E Transparency Platform API client library."""
+
+from .client import Client
+from .exceptions import ENTSOEError, InvalidParameterError, NoDataError, RateLimitError
+
+__version__ = "0.1.0"
+__all__ = [
+    "Client",
+    "ENTSOEError",
+    "InvalidParameterError",
+    "NoDataError",
+    "RateLimitError",
+]

entsoe/_http.py

@@ -0,0 +1,201 @@
+"""Low-level HTTP client for the ENTSO-E Transparency Platform API.
+
+Handles:
+- Request construction with proper parameter formatting
+- Automatic year-splitting for long date ranges
+- Retry with exponential backoff on rate limits (429)
+- Response validation
+"""
+
+import io
+import logging
+import time
+import zipfile
+from datetime import timedelta
+
+import pandas as pd
+import requests
+
+from .exceptions import ENTSOEError, InvalidParameterError, RateLimitError
+
+logger = logging.getLogger(__name__)
+
+BASE_URL = "https://web-api.tp.entsoe.eu/api"
+
+# ENTSO-E API limits requests to ~1 year
+MAX_REQUEST_RANGE = timedelta(days=365)
+
+
+def _format_timestamp(ts: pd.Timestamp) -> str:
+    """Format a tz-aware Timestamp to ENTSO-E API format (YYYYMMDDHHmm in UTC)."""
+    utc = ts.tz_convert("UTC")
+    return utc.strftime("%Y%m%d%H%M")
+
+
+def _validate_timestamps(
+    start: pd.Timestamp, end: pd.Timestamp
+) -> tuple[pd.Timestamp, pd.Timestamp]:
+    """Validate and normalize start/end timestamps."""
+    if start.tzinfo is None:
+        raise InvalidParameterError(
+            "start timestamp must be timezone-aware. "
+            "Example: pd.Timestamp('2024-01-01', tz='Europe/Paris')"
+        )
+    if end.tzinfo is None:
+        raise InvalidParameterError(
+            "end timestamp must be timezone-aware. "
+            "Example: pd.Timestamp('2024-01-07', tz='Europe/Paris')"
+        )
+    if start >= end:
+        raise InvalidParameterError("start must be before end.")
+    return start, end
+
+
+def _split_years(
+    start: pd.Timestamp, end: pd.Timestamp
+) -> list[tuple[pd.Timestamp, pd.Timestamp]]:
+    """Split a date range into chunks that don't exceed the API's max range.
+
+    Returns a list of (start, end) tuples.
+    """
+    chunks = []
+    current = start
+    while current < end:
+        chunk_end = min(current + MAX_REQUEST_RANGE, end)
+        chunks.append((current, chunk_end))
+        current = chunk_end
+    return chunks
+
+
+def _extract_xml(response: requests.Response) -> str:
+    """Extract XML from a response, handling ZIP-compressed responses.
+
+    Some ENTSO-E endpoints (imbalance prices/volumes, unavailability)
+    return ZIP archives containing one or more XML files.
+    """
+    content = response.content
+    if content[:2] == b"PK":  # ZIP magic bytes
+        with zipfile.ZipFile(io.BytesIO(content)) as zf:
+            xml_parts = [zf.read(name).decode("utf-8") for name in zf.namelist()]
+        if len(xml_parts) == 1:
+            return xml_parts[0]
+        # Multiple XMLs in ZIP: merge by returning as a list marker
+        # We wrap them so the query() method can handle them like multi-chunk
+        return xml_parts
+    return response.text
+
+
+class HttpClient:
+    """Low-level HTTP client for the ENTSO-E API."""
+
+    def __init__(
+        self,
+        api_key: str,
+        session: requests.Session | None = None,
+        max_retries: int = 3,
+        base_delay: float = 1.0,
+    ):
+        self.api_key = api_key
+        self.session = session or requests.Session()
+        self.session.headers.update({"User-Agent": "entsoe-library/0.1.0"})
+        self.max_retries = max_retries
+        self.base_delay = base_delay
+
+    def query(
+        self,
+        params: dict,
+        start: pd.Timestamp,
+        end: pd.Timestamp,
+    ) -> str | list[str]:
+        """Execute a query against the ENTSO-E API.
+
+        Automatically splits requests spanning more than 1 year and
+        handles ZIP-compressed responses (multiple XMLs inside).
+
+        Args:
+            params: API parameters (documentType, processType, etc.).
+                    Do NOT include securityToken, periodStart, or periodEnd.
+            start: Period start (tz-aware).
+            end: Period end (tz-aware).
+
+        Returns:
+            A single XML string, or a list of XML strings when the
+            response spans multiple chunks or contains a multi-file ZIP.
+
+        Raises:
+            ENTSOEError: On API errors.
+            RateLimitError: When rate limit retries are exhausted.
+        """
+        start, end = _validate_timestamps(start, end)
+        chunks = _split_years(start, end)
+
+        # Collect all XML strings, flattening any lists from ZIP responses
+        xml_parts: list[str] = []
+        for chunk_start, chunk_end in chunks:
+            result = self._single_request(params, chunk_start, chunk_end)
+            if isinstance(result, list):
+                xml_parts.extend(result)
+            else:
+                xml_parts.append(result)
+
+        if len(xml_parts) == 1:
+            return xml_parts[0]
+        return xml_parts
+
+    def query_raw(
+        self,
+        params: dict,
+        start: pd.Timestamp,
+        end: pd.Timestamp,
+    ) -> list[str]:
+        """Execute a query and return a list of XML response strings (one per chunk)."""
+        start, end = _validate_timestamps(start, end)
+        chunks = _split_years(start, end)
+        return [self._single_request(params, cs, ce) for cs, ce in chunks]
+
+    def _single_request(
+        self,
+        params: dict,
+        start: pd.Timestamp,
+        end: pd.Timestamp,
+    ) -> str:
+        """Execute a single API request with retry logic."""
+        request_params = {
+            "securityToken": self.api_key,
+            "periodStart": _format_timestamp(start),
+            "periodEnd": _format_timestamp(end),
+            **params,
+        }
+
+        for attempt in range(self.max_retries + 1):
+            logger.debug(
+                "ENTSO-E request: %s (attempt %d/%d)",
+                request_params.get("documentType", "?"),
+                attempt + 1,
+                self.max_retries + 1,
+            )
+
+            response = self.session.get(BASE_URL, params=request_params)
+
+            if response.status_code == 429:
+                if attempt < self.max_retries:
+                    delay = self.base_delay * (2**attempt)
+                    logger.warning("Rate limited. Retrying in %.1fs...", delay)
+                    time.sleep(delay)
+                    continue
+                raise RateLimitError()
+
+            if response.status_code == 401:
+                raise ENTSOEError(
+                    "Unauthorized. Check your ENTSOE_API_KEY.", status_code=401
+                )
+
+            if response.status_code != 200:
+                raise ENTSOEError(
+                    f"API returned HTTP {response.status_code}: {response.text[:500]}",
+                    status_code=response.status_code,
+                )
+
+            return _extract_xml(response)
+
+        raise ENTSOEError("Max retries exceeded.")

entsoe/_mappings.py

@@ -0,0 +1,145 @@
+"""ENTSO-E area codes, document types, and PSR type mappings."""
+
+# Country code (ISO 3166-1 alpha-2) → ENTSO-E EIC area code
+AREA_CODES: dict[str, str] = {
+    "AL": "10YAL-KESH-----5",
+    "AT": "10YAT-APG------L",
+    "BA": "10YBA-JPCC-----D",
+    "BE": "10YBE----------2",
+    "BG": "10YCA-BULGARIA-R",
+    "CH": "10YCH-SWISSGRIDZ",
+    "CZ": "10YCZ-CEPS-----N",
+    "DE": "10Y1001A1001A83F",
+    "DE_LU": "10Y1001A1001A82H",
+    "DE_AT_LU": "10Y1001A1001A63L",
+    "DK": "10Y1001A1001A65H",
+    "DK_1": "10YDK-1--------W",
+    "DK_2": "10YDK-2--------M",
+    "EE": "10Y1001A1001A39I",
+    "ES": "10YES-REE------0",
+    "FI": "10YFI-1--------U",
+    "FR": "10YFR-RTE------C",
+    "GB": "10YGB----------A",
+    "GR": "10YGR-HTSO-----Y",
+    "HR": "10YHR-HEP------M",
+    "HU": "10YHU-MAVIR----U",
+    "IE": "10YIE-1001A00010",
+    "IE_SEM": "10Y1001A1001A59C",
+    "IT": "10YIT-GRTN-----B",
+    "IT_NORTH": "10Y1001A1001A73I",
+    "IT_CNOR": "10Y1001A1001A70O",
+    "IT_CSUD": "10Y1001A1001A71M",
+    "IT_SUD": "10Y1001A1001A788",
+    "IT_SICI": "10Y1001A1001A74G",
+    "IT_SARD": "10Y1001A1001A75E",
+    "LT": "10YLT-1001A0008Q",
+    "LU": "10YLU-CEGEDEL-NQ",
+    "LV": "10YLV-1001A00074",
+    "ME": "10YCS-CG-TSO---S",
+    "MK": "10YMK-MEPSO----8",
+    "MT": "10Y1001A1001A93C",
+    "NL": "10YNL----------L",
+    "NO": "10YNO-0--------C",
+    "NO_1": "10YNO-1--------2",
+    "NO_2": "10YNO-2--------T",
+    "NO_3": "10YNO-3--------J",
+    "NO_4": "10YNO-4--------9",
+    "NO_5": "10Y1001A1001A48H",
+    "PL": "10YPL-AREA-----S",
+    "PT": "10YPT-REN------W",
+    "RO": "10YRO-TEL------P",
+    "RS": "10YCS-SERBIATSOV",
+    "SE": "10YSE-1--------K",
+    "SE_1": "10Y1001A1001A44P",
+    "SE_2": "10Y1001A1001A45N",
+    "SE_3": "10Y1001A1001A46L",
+    "SE_4": "10Y1001A1001A47J",
+    "SI": "10YSI-ELES-----O",
+    "SK": "10YSK-SEPS-----K",
+    "TR": "10YTR-TEIAS----W",
+    "UA": "10Y1001C--00003F",
+    "UK": "10Y1001A1001A92E",
+    "XK": "10Y1001C--00100H",
+}
+
+# Document type codes used in API requests
+DOCUMENT_TYPES: dict[str, str] = {
+    # Load
+    "actual_load": "A65",
+    "load_forecast": "A65",
+    # Prices
+    "day_ahead_prices": "A44",
+    # Generation
+    "actual_generation_per_type": "A75",
+    "actual_generation_per_plant": "A73",
+    "generation_forecast_wind_solar": "A69",
+    "generation_forecast": "A71",
+    "installed_capacity": "A68",
+    "installed_capacity_per_unit": "A71",
+    # Transmission
+    "physical_crossborder_flows": "A11",
+    "scheduled_exchanges": "A09",
+    "net_transfer_capacity": "A61",
+    # Balancing
+    "imbalance_prices": "A85",
+    "imbalance_volumes": "A86",
+    "contracted_reserve_prices": "A89",
+    "activated_balancing_energy_prices": "A84",
+}
+
+# Process type codes
+PROCESS_TYPES: dict[str, str] = {
+    "realised": "A16",
+    "day_ahead": "A01",
+    "intraday_total": "A18",
+    "week_ahead": "A31",
+    "month_ahead": "A32",
+    "year_ahead": "A33",
+}
+
+# PSR (Power System Resource) type codes
+PSR_TYPES: dict[str, str] = {
+    "B01": "Biomass",
+    "B02": "Fossil Brown coal/Lignite",
+    "B03": "Fossil Coal-derived gas",
+    "B04": "Fossil Gas",
+    "B05": "Fossil Hard coal",
+    "B06": "Fossil Oil",
+    "B07": "Fossil Oil shale",
+    "B08": "Fossil Peat",
+    "B09": "Geothermal",
+    "B10": "Hydro Pumped Storage",
+    "B11": "Hydro Run-of-river and poundage",
+    "B12": "Hydro Water Reservoir",
+    "B13": "Marine",
+    "B14": "Nuclear",
+    "B15": "Other renewable",
+    "B16": "Solar",
+    "B17": "Waste",
+    "B18": "Wind Offshore",
+    "B19": "Wind Onshore",
+    "B20": "Other",
+}
+
+
+def lookup_area(country: str) -> str:
+    """Resolve a country code to its ENTSO-E EIC area code.
+
+    Args:
+        country: ISO country code (e.g., "FR", "DE_LU").
+
+    Returns:
+        The EIC area code string.
+
+    Raises:
+        InvalidParameterError: If the country code is not recognized.
+    """
+    from .exceptions import InvalidParameterError
+
+    code = country.upper().strip()
+    if code not in AREA_CODES:
+        raise InvalidParameterError(
+            f"Unknown country code: '{country}'. "
+            f"Available: {', '.join(sorted(AREA_CODES.keys()))}"
+        )
+    return AREA_CODES[code]

entsoe/_xml.py

@@ -0,0 +1,172 @@
+"""XML parsing utilities for ENTSO-E API responses.
+
+Parses TimeSeries XML documents into pandas DataFrames.
+Handles the various document types returned by the API:
+- GL_MarketDocument (load, generation)
+- Publication_MarketDocument (prices)
+- TransmissionNetwork_MarketDocument (transmission)
+- Balancing_MarketDocument (balancing)
+
+All share the TimeSeries > Period > Point structure.
+"""
+
+import re
+import xml.etree.ElementTree as ET
+from datetime import timedelta
+
+import pandas as pd
+
+from .exceptions import NoDataError
+
+
+def _strip_ns(tag: str) -> str:
+    """Remove XML namespace prefix from a tag name."""
+    return re.sub(r"\{[^}]+\}", "", tag)
+
+
+def _find(element: ET.Element, local_name: str) -> ET.Element | None:
+    """Find a child element by local name, ignoring namespace."""
+    for child in element:
+        if _strip_ns(child.tag) == local_name:
+            return child
+    return None
+
+
+def _findall(element: ET.Element, local_name: str) -> list[ET.Element]:
+    """Find all child elements by local name, ignoring namespace."""
+    return [child for child in element if _strip_ns(child.tag) == local_name]
+
+
+def _find_text(element: ET.Element, local_name: str) -> str | None:
+    """Find a child element's text by local name, ignoring namespace."""
+    child = _find(element, local_name)
+    return child.text if child is not None else None
+
+
+def _parse_resolution(resolution: str) -> timedelta:
+    """Parse ISO 8601 duration to timedelta.
+
+    Common values: PT15M, PT30M, PT60M, P1Y
+    """
+    match = re.match(r"PT?(\d+)([MHDY])", resolution)
+    if not match:
+        raise ValueError(f"Cannot parse resolution: {resolution}")
+    value, unit = int(match.group(1)), match.group(2)
+    if unit == "M":
+        return timedelta(minutes=value)
+    if unit == "H":
+        return timedelta(hours=value)
+    if unit == "D":
+        return timedelta(days=value)
+    if unit == "Y":
+        return timedelta(days=365 * value)
+    raise ValueError(f"Unknown resolution unit: {unit}")
+
+
+def _extract_point_value(point: ET.Element) -> float | None:
+    """Extract the numeric value from a Point element.
+
+    Handles <quantity> (load/generation), <price.amount> (day-ahead prices),
+    and <imbalance_Price.amount> (balancing).
+    """
+    for tag in ("quantity", "price.amount", "imbalance_Price.amount"):
+        text = _find_text(point, tag)
+        if text is not None:
+            return float(text)
+    return None
+
+
+def parse_timeseries(xml_text: str) -> pd.DataFrame:
+    """Parse an ENTSO-E XML response into a DataFrame.
+
+    Handles multiple TimeSeries (e.g., generation per type) and multiple
+    Periods within each TimeSeries (e.g., multi-day responses).
+
+    Returns a DataFrame with columns:
+    - timestamp: tz-aware UTC datetime
+    - value: numeric value (MW or EUR/MWh depending on query)
+    - Plus any metadata columns (psr_type, etc.) if multiple TimeSeries present.
+
+    Raises:
+        NoDataError: If the response contains no TimeSeries data.
+    """
+    root = ET.fromstring(xml_text)
+    timeseries_list = _findall(root, "TimeSeries")
+
+    if not timeseries_list:
+        # Check for reason/text in error responses
+        reason = _find(root, "Reason")
+        if reason is not None:
+            reason_text = _find_text(reason, "text")
+            raise NoDataError(reason_text or "No data available.")
+        raise NoDataError()
+
+    rows: list[dict] = []
+
+    for ts in timeseries_list:
+        # Extract TimeSeries metadata
+        ts_meta: dict = {}
+
+        # PSR type (generation fuel type)
+        mkt_psr = _find(ts, "MktPSRType")
+        if mkt_psr is not None:
+            psr_code = _find_text(mkt_psr, "psrType")
+            if psr_code:
+                ts_meta["psr_type"] = psr_code
+
+        # In/Out domain (useful for transmission)
+        in_domain = _find(ts, "in_Domain.mRID")
+        if in_domain is not None and in_domain.text:
+            ts_meta["in_domain"] = in_domain.text
+        out_domain = _find(ts, "out_Domain.mRID")
+        if out_domain is not None and out_domain.text:
+            ts_meta["out_domain"] = out_domain.text
+
+        # Currency and unit
+        currency = _find_text(ts, "currency_Unit.name")
+        if currency:
+            ts_meta["currency"] = currency
+        price_unit = _find_text(ts, "price_Measure_Unit.name")
+        if price_unit:
+            ts_meta["price_unit"] = price_unit
+        quantity_unit = _find_text(ts, "quantity_Measure_Unit.name")
+        if quantity_unit:
+            ts_meta["quantity_unit"] = quantity_unit
+
+        # Process each Period
+        for period in _findall(ts, "Period"):
+            time_interval = _find(period, "timeInterval")
+            if time_interval is None:
+                continue
+
+            start_text = _find_text(time_interval, "start")
+            if start_text is None:
+                continue
+
+            resolution_text = _find_text(period, "resolution")
+            if resolution_text is None:
+                continue
+
+            period_start = pd.Timestamp(start_text)
+            resolution = _parse_resolution(resolution_text)
+
+            for point in _findall(period, "Point"):
+                position_text = _find_text(point, "position")
+                if position_text is None:
+                    continue
+
+                position = int(position_text)
+                value = _extract_point_value(point)
+
+                timestamp = period_start + resolution * (position - 1)
+
+                row = {"timestamp": timestamp, "value": value, **ts_meta}
+                rows.append(row)
+
+    if not rows:
+        raise NoDataError()
+
+    df = pd.DataFrame(rows)
+    df["timestamp"] = pd.to_datetime(df["timestamp"], utc=True)
+    df = df.sort_values("timestamp").reset_index(drop=True)
+    return df

entsoe/client.py

@@ -0,0 +1,67 @@
+"""Main Client class for the ENTSO-E Transparency Platform API."""
+
+from __future__ import annotations
+
+import os
+
+from ._http import HttpClient
+from .namespaces import (
+    BalancingNamespace,
+    GenerationNamespace,
+    LoadNamespace,
+    PricesNamespace,
+    TransmissionNamespace,
+)
+
+
+class Client:
+    """ENTSO-E Transparency Platform API client.
+
+    Provides typed, namespace-organized access to European electricity market data.
+
+    Usage::
+
+        from entsoe import Client
+        import pandas as pd
+
+        client = Client()  # reads ENTSOE_API_KEY from env
+
+        start = pd.Timestamp("2024-01-01", tz="Europe/Paris")
+        end = pd.Timestamp("2024-01-07", tz="Europe/Paris")
+
+        df = client.load.actual(start, end, country="FR")
+        df = client.prices.day_ahead(start, end, country="FR")
+        df = client.generation.actual(start, end, country="FR")
+
+    Namespaces:
+        load: Actual load and load forecast.
+        prices: Day-ahead market prices.
+        generation: Actual generation, forecasts, installed capacity.
+        transmission: Cross-border flows and scheduled exchanges.
+        balancing: Imbalance prices and volumes.
+    """
+
+    def __init__(self, api_key: str | None = None) -> None:
+        """Initialize the client.
+
+        Args:
+            api_key: ENTSO-E API key. If not provided, reads from
+                     the ``ENTSOE_API_KEY`` environment variable.
+
+        Raises:
+            ValueError: If no API key is found.
+        """
+        resolved_key = api_key or os.environ.get("ENTSOE_API_KEY")
+        if not resolved_key:
+            raise ValueError(
+                "API key required. Pass api_key= or set the ENTSOE_API_KEY "
+                "environment variable."
+            )
+
+        http = HttpClient(api_key=resolved_key)
+
+        self.load = LoadNamespace(http)
+        self.prices = PricesNamespace(http)
+        self.generation = GenerationNamespace(http)
+        self.transmission = TransmissionNamespace(http)
+        self.balancing = BalancingNamespace(http)

entsoe/exceptions.py

@@ -0,0 +1,30 @@
+"""Exception hierarchy for the ENTSO-E client."""
+
+
+class ENTSOEError(Exception):
+    """Base exception for all ENTSO-E API errors."""
+
+    def __init__(self, message: str, status_code: int | None = None):
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class NoDataError(ENTSOEError):
+    """Raised when the API returns no data for the requested period/parameters."""
+
+    def __init__(self, message: str = "No data available for the requested parameters."):
+        super().__init__(message)
+
+
+class InvalidParameterError(ENTSOEError):
+    """Raised when invalid parameters are passed (bad country code, naive timestamps, etc.)."""
+
+    def __init__(self, message: str):
+        super().__init__(message)
+
+
+class RateLimitError(ENTSOEError):
+    """Raised when rate limit is exceeded and all retries are exhausted."""
+
+    def __init__(self, message: str = "Rate limit exceeded. Retries exhausted."):
+        super().__init__(message, status_code=429)

entsoe/namespaces/__init__.py

@@ -0,0 +1,15 @@
+"""Domain namespace classes for the ENTSO-E client."""
+
+from .balancing import BalancingNamespace
+from .generation import GenerationNamespace
+from .load import LoadNamespace
+from .prices import PricesNamespace
+from .transmission import TransmissionNamespace
+
+__all__ = [
+    "BalancingNamespace",
+    "GenerationNamespace",
+    "LoadNamespace",
+    "PricesNamespace",
+    "TransmissionNamespace",
+]

entsoe/namespaces/_base.py

@@ -0,0 +1,45 @@
+"""Base namespace class shared by all domain namespaces."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import pandas as pd
+
+from .._mappings import lookup_area
+from .._xml import parse_timeseries
+
+if TYPE_CHECKING:
+    from .._http import HttpClient
+
+
+class BaseNamespace:
+    """Base class for domain namespaces.
+
+    Holds a reference to the shared HttpClient and provides
+    common helper methods for building queries and parsing responses.
+    """
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def _query(
+        self,
+        params: dict,
+        start: pd.Timestamp,
+        end: pd.Timestamp,
+    ) -> pd.DataFrame:
+        """Execute a query and parse the XML response into a DataFrame."""
+        result = self._http.query(params, start, end)
+
+        # Handle multi-chunk responses (year-splitting)
+        if isinstance(result, list):
+            dfs = [parse_timeseries(xml) for xml in result]
+            return pd.concat(dfs, ignore_index=True).sort_values("timestamp").reset_index(drop=True)
+
+        return parse_timeseries(result)
+
+    @staticmethod
+    def _area(country: str) -> str:
+        """Resolve country code to EIC area code."""
+        return lookup_area(country)

entsoe/namespaces/balancing.py

@@ -0,0 +1,62 @@
+"""Balancing namespace — imbalance price and volume queries."""
+
+from __future__ import annotations
+
+import pandas as pd
+
+from ._base import BaseNamespace
+
+
+class BalancingNamespace(BaseNamespace):
+    """Access balancing market data.
+
+    Methods:
+        imbalance_prices: System imbalance prices.
+        imbalance_volumes: System imbalance volumes.
+    """
+
+    def imbalance_prices(
+        self,
+        start: pd.Timestamp,
+        end: pd.Timestamp,
+        country: str,
+    ) -> pd.DataFrame:
+        """Query imbalance prices.
+
+        Args:
+            start: Period start (tz-aware).
+            end: Period end (tz-aware).
+            country: Country code (e.g., "FR", "DE").
+
+        Returns:
+            DataFrame with columns: timestamp, value (EUR/MWh).
+        """
+        area = self._area(country)
+        params = {
+            "documentType": "A85",
+            "controlArea_Domain": area,
+        }
+        return self._query(params, start, end)
+
+    def imbalance_volumes(
+        self,
+        start: pd.Timestamp,
+        end: pd.Timestamp,
+        country: str,
+    ) -> pd.DataFrame:
+        """Query imbalance volumes.
+
+        Args:
+            start: Period start (tz-aware).
+            end: Period end (tz-aware).
+            country: Country code (e.g., "FR", "DE").
+
+        Returns:
+            DataFrame with columns: timestamp, value (MW).
+        """
+        area = self._area(country)
+        params = {
+            "documentType": "A86",
+            "controlArea_Domain": area,
+        }
+        return self._query(params, start, end)

entsoe/namespaces/generation.py

@@ -0,0 +1,128 @@
+"""Generation namespace — actual generation, forecasts, and capacity queries."""
+
+from __future__ import annotations
+
+import pandas as pd
+
+from ._base import BaseNamespace
+
+
+class GenerationNamespace(BaseNamespace):
+    """Access electricity generation data.
+
+    Methods:
+        actual: Actual generation output per type.
+        forecast: Day-ahead generation forecast (wind/solar).
+        installed_capacity: Installed generation capacity per type.
+        per_plant: Actual generation per production unit.
+    """
+
+    def actual(
+        self,
+        start: pd.Timestamp,
+        end: pd.Timestamp,
+        country: str,
+        psr_type: str | None = None,
+    ) -> pd.DataFrame:
+        """Query actual generation output per type.
+
+        Args:
+            start: Period start (tz-aware).
+            end: Period end (tz-aware).
+            country: Country code (e.g., "FR", "DE").
+            psr_type: Optional PSR type code (e.g., "B16" for Solar,
+                      "B19" for Wind Onshore). If None, returns all types.
+
+        Returns:
+            DataFrame with columns: timestamp, value (MW), psr_type.
+        """
+        params = {
+            "documentType": "A75",
+            "processType": "A16",
+            "in_Domain": self._area(country),
+        }
+        if psr_type:
+            params["psrType"] = psr_type
+        return self._query(params, start, end)
+
+    def forecast(
+        self,
+        start: pd.Timestamp,
+        end: pd.Timestamp,
+        country: str,
+        psr_type: str | None = None,
+    ) -> pd.DataFrame:
+        """Query day-ahead generation forecast (wind and solar).
+
+        Args:
+            start: Period start (tz-aware).
+            end: Period end (tz-aware).
+            country: Country code (e.g., "FR", "DE").
+            psr_type: Optional PSR type code to filter by.
+
+        Returns:
+            DataFrame with columns: timestamp, value (MW), psr_type.
+        """
+        params = {
+            "documentType": "A69",
+            "processType": "A01",
+            "in_Domain": self._area(country),
+        }
+        if psr_type:
+            params["psrType"] = psr_type
+        return self._query(params, start, end)
+
+    def installed_capacity(
+        self,
+        start: pd.Timestamp,
+        end: pd.Timestamp,
+        country: str,
+        psr_type: str | None = None,
+    ) -> pd.DataFrame:
+        """Query installed generation capacity per type.
+
+        Args:
+            start: Period start (tz-aware).
+            end: Period end (tz-aware).
+            country: Country code (e.g., "FR", "DE").
+            psr_type: Optional PSR type code to filter by.
+
+        Returns:
+            DataFrame with columns: timestamp, value (MW), psr_type.
+        """
+        params = {
+            "documentType": "A68",
+            "processType": "A33",
+            "in_Domain": self._area(country),
+        }
+        if psr_type:
+            params["psrType"] = psr_type
+        return self._query(params, start, end)
+
+    def per_plant(
+        self,
+        start: pd.Timestamp,
+        end: pd.Timestamp,
+        country: str,
+        psr_type: str | None = None,
+    ) -> pd.DataFrame:
+        """Query actual generation per production unit.
+
+        Args:
+            start: Period start (tz-aware).
+            end: Period end (tz-aware).
+            country: Country code (e.g., "FR", "DE").
+            psr_type: Optional PSR type code to filter by.
+
+        Returns:
+            DataFrame with columns: timestamp, value (MW), psr_type,
+            and additional unit identifiers.
+        """
+        params = {
+            "documentType": "A73",
+            "processType": "A16",
+            "in_Domain": self._area(country),
+        }
+        if psr_type:
+            params["psrType"] = psr_type
+        return self._query(params, start, end)

entsoe/namespaces/load.py

@@ -0,0 +1,62 @@
+"""Load namespace — actual load and load forecast queries."""
+
+from __future__ import annotations
+
+import pandas as pd
+
+from ._base import BaseNamespace
+
+
+class LoadNamespace(BaseNamespace):
+    """Access electricity load data.
+
+    Methods:
+        actual: Actual total system load.
+        forecast: Day-ahead load forecast.
+    """
+
+    def actual(
+        self,
+        start: pd.Timestamp,
+        end: pd.Timestamp,
+        country: str,
+    ) -> pd.DataFrame:
+        """Query actual total system load.
+
+        Args:
+            start: Period start (tz-aware).
+            end: Period end (tz-aware).
+            country: Country code (e.g., "FR", "DE").
+
+        Returns:
+            DataFrame with columns: timestamp, value (MW).
+        """
+        params = {
+            "documentType": "A65",
+            "processType": "A16",
+            "outBiddingZone_Domain": self._area(country),
+        }
+        return self._query(params, start, end)
+
+    def forecast(
+        self,
+        start: pd.Timestamp,
+        end: pd.Timestamp,
+        country: str,
+    ) -> pd.DataFrame:
+        """Query day-ahead load forecast.
+
+        Args:
+            start: Period start (tz-aware).
+            end: Period end (tz-aware).
+            country: Country code (e.g., "FR", "DE").
+
+        Returns:
+            DataFrame with columns: timestamp, value (MW).
+        """
+        params = {
+            "documentType": "A65",
+            "processType": "A01",
+            "outBiddingZone_Domain": self._area(country),
+        }
+        return self._query(params, start, end)

entsoe/namespaces/prices.py

@@ -0,0 +1,40 @@
+"""Prices namespace — day-ahead price queries."""
+
+from __future__ import annotations
+
+import pandas as pd
+
+from ._base import BaseNamespace
+
+
+class PricesNamespace(BaseNamespace):
+    """Access electricity price data.
+
+    Methods:
+        day_ahead: Day-ahead market prices.
+    """
+
+    def day_ahead(
+        self,
+        start: pd.Timestamp,
+        end: pd.Timestamp,
+        country: str,
+    ) -> pd.DataFrame:
+        """Query day-ahead electricity prices.
+
+        Args:
+            start: Period start (tz-aware).
+            end: Period end (tz-aware).
+            country: Country code (e.g., "FR", "DE").
+
+        Returns:
+            DataFrame with columns: timestamp, value (EUR/MWh),
+            currency, price_unit.
+        """
+        area = self._area(country)
+        params = {
+            "documentType": "A44",
+            "in_Domain": area,
+            "out_Domain": area,
+        }
+        return self._query(params, start, end)

entsoe/namespaces/transmission.py

@@ -0,0 +1,93 @@
+"""Transmission namespace — cross-border flow and exchange queries."""
+
+from __future__ import annotations
+
+import pandas as pd
+
+from ._base import BaseNamespace
+
+
+class TransmissionNamespace(BaseNamespace):
+    """Access cross-border transmission data.
+
+    Methods:
+        crossborder_flows: Physical cross-border flows between two areas.
+        scheduled_exchanges: Scheduled commercial exchanges between two areas.
+        net_transfer_capacity: Net transfer capacity between two areas.
+    """
+
+    def crossborder_flows(
+        self,
+        start: pd.Timestamp,
+        end: pd.Timestamp,
+        country_from: str,
+        country_to: str,
+    ) -> pd.DataFrame:
+        """Query physical cross-border flows.
+
+        Args:
+            start: Period start (tz-aware).
+            end: Period end (tz-aware).
+            country_from: Exporting country code (e.g., "FR").
+            country_to: Importing country code (e.g., "DE").
+
+        Returns:
+            DataFrame with columns: timestamp, value (MW).
+        """
+        params = {
+            "documentType": "A11",
+            "in_Domain": self._area(country_to),
+            "out_Domain": self._area(country_from),
+        }
+        return self._query(params, start, end)
+
+    def scheduled_exchanges(
+        self,
+        start: pd.Timestamp,
+        end: pd.Timestamp,
+        country_from: str,
+        country_to: str,
+    ) -> pd.DataFrame:
+        """Query scheduled commercial exchanges (day-ahead).
+
+        Args:
+            start: Period start (tz-aware).
+            end: Period end (tz-aware).
+            country_from: Exporting country code (e.g., "FR").
+            country_to: Importing country code (e.g., "DE").
+
+        Returns:
+            DataFrame with columns: timestamp, value (MW).
+        """
+        params = {
+            "documentType": "A09",
+            "in_Domain": self._area(country_to),
+            "out_Domain": self._area(country_from),
+        }
+        return self._query(params, start, end)
+
+    def net_transfer_capacity(
+        self,
+        start: pd.Timestamp,
+        end: pd.Timestamp,
+        country_from: str,
+        country_to: str,
+    ) -> pd.DataFrame:
+        """Query day-ahead net transfer capacity.
+
+        Args:
+            start: Period start (tz-aware).
+            end: Period end (tz-aware).
+            country_from: Exporting country code (e.g., "FR").
+            country_to: Importing country code (e.g., "DE").
+
+        Returns:
+            DataFrame with columns: timestamp, value (MW).
+        """
+        params = {
+            "documentType": "A61",
+            "contract_MarketAgreement.Type": "A01",
+            "in_Domain": self._area(country_to),
+            "out_Domain": self._area(country_from),
+        }
+        return self._query(params, start, end)

python_entsoe-0.1.0.dist-info/METADATA

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: python-entsoe
+Version: 0.1.0
+Summary: Python client for the ENTSO-E Transparency Platform API
+Project-URL: Repository, https://github.com/jsulopzs/python-entsoe
+Author-email: jsulopzs <jesus.lopez@datons.com>
+License-Expression: MIT
+Keywords: api,electricity,energy,entsoe,transparency
+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.13
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.13
+Requires-Dist: pandas>=2.0
+Requires-Dist: requests>=2.28

python_entsoe-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+entsoe/__init__.py,sha256=98RqhEtaMPIEBetDsEnIsbFzgYMp0iqNQsB5ZZ_gYKo,312
+entsoe/_http.py,sha256=1Hj04bE-J6-V1ZnQpXpXYynId40hXft-MZxhHlg7GYk,6572
+entsoe/_mappings.py,sha256=v0CQRBpUCu-YWRvYsfsd5ktXMlDBfftlp6Z1nCOnNVE,4174
+entsoe/_xml.py,sha256=6GAAXovbQ5WCv6Twz-Yf32rKzOuQeZsSCta2N_2bfm4,5775
+entsoe/client.py,sha256=prIAYq0uJCldMt7ky24-gdx1ptx9xc9s9Aac3J8KnIk,2048
+entsoe/exceptions.py,sha256=N9BmlzoQY1EIaGXw2x-OhSthTi_ktei9LwbDRYtbYfY,981
+entsoe/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+entsoe/namespaces/__init__.py,sha256=ZVd80s5OVxegLo3A6nI64tHlBA1Iwe2ejqQilGNod5E,399
+entsoe/namespaces/_base.py,sha256=zVeo8XN714oQ7WCcZVIzutnN-P7hvqdh6akuxOSwKcs,1259
+entsoe/namespaces/balancing.py,sha256=llCg6IJH6tqr0m_sDivR797nj7rKUdJIPrNPOd1lN2A,1580
+entsoe/namespaces/generation.py,sha256=HlLwGvwqbTRv15NEPTKILbNG6O3SkVn_OUARFKKIBu4,3831
+entsoe/namespaces/load.py,sha256=-pzP4nbcQ8ASa86tzKkJsSBEAXQDn4Su_DiHn6yiU2g,1578
+entsoe/namespaces/prices.py,sha256=c5Maoix9YJ5t9k5r4T86igcdObovBKBKYN7El1rj_r4,959
+entsoe/namespaces/transmission.py,sha256=OBh58UTwGahts3BOaer1OazzT8uUDmumpeHUpLtGJZE,2809
+python_entsoe-0.1.0.dist-info/METADATA,sha256=RMm6m_Et8NCvnUQtT2X4AhmC8QypiI9JxBTBEKf41eQ,683
+python_entsoe-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+python_entsoe-0.1.0.dist-info/RECORD,,

python_entsoe-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any