detquantlib 5.6.0__tar.gz → 5.7.0__tar.gz

{detquantlib-5.6.0 → detquantlib-5.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: detquantlib
-Version: 5.6.0
+Version: 5.7.0
 Summary: An internal library containing functions and classes that can be used across Quant models.
 License-File: LICENSE.txt
 Author: Dynamic Energy Trading
@@ -83,9 +83,9 @@ poetry run python docs.py
 
 Classes:
 
-- `Battery`:
-  - `from detquantlib.assets import Battery`
-  - `from detquantlib.assets.battery import Battery`
+- `BatteryState`:
+  - `from detquantlib.assets import BatteryState`
+  - `from detquantlib.assets.battery import BatteryState`
 - `DetDatabase`:
   - `from detquantlib.data import DetDatabase`
   - `from detquantlib.data.databases.detdatabase import DetDatabase`
@@ -104,6 +104,18 @@ Classes:
 - `Sftp`:
   - `from detquantlib.data import Sftp`
   - `from detquantlib.data.sftp.sftp import Sftp`
+- `SnowflakeClient`:
+  - `from detquantlib.data import SnowflakeClient`
+  - `from detquantlib.data.databases.snowflake_client import SnowflakeClient`
+- `SnowflakeConfig`:
+  - `from detquantlib.data import SnowflakeConfig`
+  - `from detquantlib.data.databases.snowflake_client import SnowflakeConfig`
+- `TennetAPIError`:
+  - `from detquantlib.data import TennetAPIError`
+  - `from detquantlib.data.tennet.tennet_client import TennetAPIError`
+- `TennetClient`:
+  - `from detquantlib.data import TennetClient`
+  - `from detquantlib.data.tennet.tennet_client import TennetClient`
 - `WindTurbine`:
   - `from detquantlib.assets import WindTurbine`
   - `from detquantlib.assets.wind_turbine import WindTurbine`

{detquantlib-5.6.0 → detquantlib-5.7.0}/README.md

@@ -54,9 +54,9 @@ poetry run python docs.py
 
 Classes:
 
-- `Battery`:
-  - `from detquantlib.assets import Battery`
-  - `from detquantlib.assets.battery import Battery`
+- `BatteryState`:
+  - `from detquantlib.assets import BatteryState`
+  - `from detquantlib.assets.battery import BatteryState`
 - `DetDatabase`:
   - `from detquantlib.data import DetDatabase`
   - `from detquantlib.data.databases.detdatabase import DetDatabase`
@@ -75,6 +75,18 @@ Classes:
 - `Sftp`:
   - `from detquantlib.data import Sftp`
   - `from detquantlib.data.sftp.sftp import Sftp`
+- `SnowflakeClient`:
+  - `from detquantlib.data import SnowflakeClient`
+  - `from detquantlib.data.databases.snowflake_client import SnowflakeClient`
+- `SnowflakeConfig`:
+  - `from detquantlib.data import SnowflakeConfig`
+  - `from detquantlib.data.databases.snowflake_client import SnowflakeConfig`
+- `TennetAPIError`:
+  - `from detquantlib.data import TennetAPIError`
+  - `from detquantlib.data.tennet.tennet_client import TennetAPIError`
+- `TennetClient`:
+  - `from detquantlib.data import TennetClient`
+  - `from detquantlib.data.tennet.tennet_client import TennetClient`
 - `WindTurbine`:
   - `from detquantlib.assets import WindTurbine`
   - `from detquantlib.assets.wind_turbine import WindTurbine`

{detquantlib-5.6.0 → detquantlib-5.7.0}/detquantlib/data/__init__.py

@@ -3,6 +3,7 @@ from .databases.helpers import *
 from .databases.snowflake_client import SnowflakeClient, SnowflakeConfig
 from .entsoe.entsoe import Entsoe
 from .sftp.sftp import Sftp
+from .tennet.tennet_client import TennetAPIError, TennetClient
 
 __all__ = [
     "DetDatabase",
@@ -12,4 +13,6 @@ __all__ = [
     "list_to_sql_columns",
     "SnowflakeClient",
     "SnowflakeConfig",
+    "TennetClient",
+    "TennetAPIError",
 ]

detquantlib-5.7.0/detquantlib/data/tennet/tennet_client.py

@@ -0,0 +1,417 @@
+# Python built-in packages
+import os
+import re
+import time
+from datetime import date, datetime
+from io import StringIO
+from math import ceil
+from typing import Optional, Union
+
+# Third-party packages
+import pandas as pd
+import requests
+
+# Custom data type
+DateLike = Union[str, date, datetime, pd.Timestamp]
+
+
+class TennetAPIError(Exception):
+    """Raised when the TenneT API returns an error response."""
+
+    def __init__(self, message: str, status_code: Optional[int] = None) -> None:
+        """
+        Initialise the error.
+
+        Args:
+            message: Human-readable error message.
+            status_code: HTTP status code of the failed response, if any.
+        """
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class TennetClient:
+    """
+    Thin wrapper around the TenneT publications API (https://developer.tennet.eu).
+
+    Attributes:
+        base_url: Base URL used for all requests (production or acceptance).
+        timeout: Request timeout in seconds.
+        max_retries: Number of retries on HTTP 429 / 5xx responses and connection errors.
+        backoff: Base back-off in seconds used when no ``Retry-After`` header is returned.
+        session: The ``requests.Session`` used for all requests.
+
+    Example:
+        >>> client = TennetClient(api_key="...")  # or set TENNET_API_KEY
+        >>> prices = client.get_settlement_prices("2026-10-01", "2026-10-02")
+        >>> delta = client.get_balance_delta_high_res("2026-10-14 10:00", "2026-10-14 12:00")
+        >>> latest = client.get_balance_delta_high_res_latest()
+    """
+
+    BASE_URL = "https://api.tennet.eu/publications/v1/"
+    ACC_BASE_URL = "https://api.acc.tennet.eu/publications/v1/"
+    LOCAL_TZ = "Europe/Amsterdam"
+    DATE_FORMAT_UTC = "%Y-%m-%dT%H:%M:%SZ"
+
+    # Maximum period TenneT accepts in a single balance delta high res request.
+    BALANCE_DELTA_HIGH_RES_MAX_PERIOD = pd.Timedelta(hours=4)
+
+    _RETRY_STATUS = {429, 500, 502, 503, 504}
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        acceptance: bool = False,
+        timeout: float = 30.0,
+        max_retries: int = 3,
+        backoff: float = 2.0,
+        session: Optional[requests.Session] = None,
+    ) -> None:
+        """
+        Initialise the client.
+
+        Args:
+            api_key: API key from the TenneT developer portal. Falls back to the
+                ``TENNET_API_KEY`` environment variable.
+            acceptance: Use the acceptance (test) environment instead of production.
+            timeout: Request timeout in seconds.
+            max_retries: How many times to retry on HTTP 429 / 5xx responses.
+            backoff: Base back-off in seconds (exponential) when no ``Retry-After``
+                header is returned.
+            session: Optional pre-configured ``requests.Session`` (handy for testing or
+                proxies).
+
+        Raises:
+            ValueError: If no API key is provided or found in the environment.
+        """
+        api_key = api_key or os.environ.get("TENNET_API_KEY")
+        if not api_key:
+            raise ValueError(
+                "No API key provided. Pass `api_key` or set the TENNET_API_KEY "
+                "environment variable."
+            )
+        self.base_url = self.ACC_BASE_URL if acceptance else self.BASE_URL
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.backoff = backoff
+        self.session = session or requests.Session()
+        self.session.headers.update(
+            {"apikey": api_key, "Accept": "text/csv", "User-Agent": "TennetClient/1.0"}
+        )
+
+    # ---------------------------------------------------------------------------------------------
+    # Public
+    # ---------------------------------------------------------------------------------------------
+
+    def get_settlement_prices(
+        self, start: DateLike, end: DateLike, *, chunk_size: Optional[pd.Timedelta] = None
+    ) -> pd.DataFrame:
+        """
+        Get imbalance settlement prices per 15-minute ISP.
+
+        Args:
+            start: Start of the period. Naive values are interpreted as Europe/Amsterdam.
+            end: End of the period. Naive values are interpreted as Europe/Amsterdam.
+            chunk_size: Optional maximum period per request; longer ranges are split.
+
+        Returns:
+            Settlement prices.
+        """
+        return self._query_range(
+            endpoint="settlement-prices",
+            start=start,
+            end=end,
+            resolution=pd.Timedelta(minutes=15),
+            chunk_size=chunk_size,
+        )
+
+    def get_balance_delta_high_res(
+        self,
+        start: DateLike,
+        end: DateLike,
+        *,
+        chunk_size: Optional[pd.Timedelta] = BALANCE_DELTA_HIGH_RES_MAX_PERIOD,
+    ) -> pd.DataFrame:
+        """
+        Get the balance delta at 12-second resolution.
+
+        TenneT accepts at most 4 hours per request, so longer ranges are split into
+        ``chunk_size`` windows (default 4 hours) and concatenated.
+
+        Args:
+            start: Start of the period. Naive values are interpreted as Europe/Amsterdam.
+            end: End of the period. Naive values are interpreted as Europe/Amsterdam.
+            chunk_size: Maximum period per request. Pass ``None`` to send a single request.
+
+        Returns:
+            Balance delta at 12-second resolution.
+        """
+        return self._query_range(
+            endpoint="balance-delta-high-res",
+            start=start,
+            end=end,
+            resolution=pd.Timedelta(seconds=12),
+            chunk_size=chunk_size,
+        )
+
+    def get_balance_delta_high_res_latest(self) -> pd.DataFrame:
+        """
+        Get the most recent balance delta high res publication (roughly the last 30 min).
+
+        Returns:
+            Most recent balance delta at 12-second resolution.
+        """
+        return self._parse_csv(
+            text=self._request(endpoint="balance-delta-high-res/latest"),
+            resolution=pd.Timedelta(seconds=12),
+        )
+
+    # ---------------------------------------------------------------------------------------------
+    # Internal
+    # ---------------------------------------------------------------------------------------------
+
+    def _query_range(
+        self,
+        endpoint: str,
+        start: DateLike,
+        end: DateLike,
+        resolution: pd.Timedelta,
+        chunk_size: Optional[pd.Timedelta],
+    ) -> pd.DataFrame:
+        """
+        Query a date-ranged endpoint, splitting the range into chunks if needed.
+
+        Args:
+            endpoint: Endpoint path relative to the base URL.
+            start: Start of the period.
+            end: End of the period.
+            resolution: Length of one interval, used to rebuild timestamps from ISPs.
+            chunk_size: Maximum period per request, or ``None`` for a single request.
+
+        Returns:
+            Concatenated DataFrame.
+
+        Raises:
+            ValueError: If ``start`` is not before ``end``, or ``chunk_size`` is not positive.
+        """
+        start_ts, end_ts = self._to_utc(start), self._to_utc(end)
+        if start_ts >= end_ts:
+            raise ValueError(f"`start` ({start_ts}) must be before `end` ({end_ts}).")
+        if chunk_size is not None and chunk_size <= pd.Timedelta(0):
+            raise ValueError(f"`chunk_size` ({chunk_size}) must be positive.")
+
+        # Set batch windows
+        chunk_size = end_ts - start_ts if chunk_size is None else chunk_size
+        windows = [
+            (start_ts + chunk_size * t, min(start_ts + chunk_size * (t + 1), end_ts))
+            for t in range(ceil((end_ts - start_ts) / chunk_size))
+        ]
+
+        # Query in batches
+        frames = []
+        for w_start, w_end in windows:
+            params = {
+                "date_from": w_start.strftime(self.DATE_FORMAT_UTC),
+                "date_to": w_end.strftime(self.DATE_FORMAT_UTC),
+            }
+            frames.append(self._parse_csv(self._request(endpoint, params), resolution))
+
+        frames = [f for f in frames if not f.empty]
+        if not frames:
+            return self._empty_frame()
+        df = pd.concat(frames)
+        df = df.sort_values(["timeinterval_start", "timeinterval_end"], ignore_index=True)
+        return df
+
+    @classmethod
+    def _to_utc(cls, value: DateLike) -> pd.Timestamp:
+        """
+        Convert a date-like value to a UTC timestamp.
+
+        Args:
+            value: Date-like value. Naive values are interpreted as Europe/Amsterdam,
+                timezone-aware values are converted.
+
+        Returns:
+            Timezone-aware UTC timestamp.
+        """
+        ts = pd.Timestamp(value)
+        if ts.tzinfo is None:
+            ts = ts.tz_localize(cls.LOCAL_TZ, ambiguous="raise", nonexistent="shift_forward")
+        ts = ts.tz_convert("UTC")
+        return ts
+
+    def _request(self, endpoint: str, params: Optional[dict[str, str]] = None) -> str:
+        """
+        Perform a GET request with retries.
+
+        Args:
+            endpoint: Endpoint path relative to the base URL.
+            params: Optional query parameters.
+
+        Returns:
+            The response body as text.
+
+        Raises:
+            TennetAPIError: If the request fails or the API returns an error status.
+        """
+        url = self.base_url + endpoint
+        for attempt in range(self.max_retries + 1):
+            try:
+                resp = self.session.get(url, params=params, timeout=self.timeout)
+            except requests.RequestException as exc:
+                if attempt >= self.max_retries:
+                    raise TennetAPIError(f"Request to {url} failed: {exc}") from exc
+                time.sleep(self.backoff * 2**attempt)
+                continue
+
+            if resp.status_code in self._RETRY_STATUS and attempt < self.max_retries:
+                time.sleep(self._retry_delay(resp, attempt))
+                continue
+            if resp.status_code >= 400:
+                raise TennetAPIError(
+                    f"TenneT API error {resp.status_code} for {url}: {resp.text[:500]}",
+                    status_code=resp.status_code,
+                )
+            return resp.text
+        raise TennetAPIError(f"Giving up on {url} after {self.max_retries} retries.")
+
+    def _retry_delay(self, resp: requests.Response, attempt: int) -> float:
+        """
+        Compute how long to wait before retrying.
+
+        Args:
+            resp: The response that triggered the retry.
+            attempt: Zero-based attempt number.
+
+        Returns:
+            Delay in seconds, taken from ``Retry-After`` or exponential back-off.
+        """
+        retry_after = (resp.headers or {}).get("Retry-After")
+        try:
+            return float(retry_after)
+        except (TypeError, ValueError):
+            return self.backoff * 2**attempt
+
+    @classmethod
+    def _parse_csv(cls, text: str, resolution: pd.Timedelta) -> pd.DataFrame:
+        """
+        Parse a TenneT CSV response into a DataFrame.
+
+        Interval columns (``timeinterval_start/end_utc`` or ``_loc``) are converted to
+        Europe/Amsterdam timestamps and renamed to ``timeinterval_start`` / ``timeinterval_end``.
+        UTC columns take precedence: if both are present, the local ones are dropped. Rows are
+        then sorted chronologically.
+
+        Args:
+            text: CSV response body.
+            resolution: Length of one interval, used to disambiguate local timestamps via ISPs.
+
+        Returns:
+            DataFrame with snake_case columns and Europe/Amsterdam interval timestamps.
+
+        Raises:
+            TennetAPIError: If only one column of a start/end interval pair is present.
+        """
+        if not text or not text.strip():
+            return cls._empty_frame()
+        df = pd.read_csv(StringIO(text))
+        if df.empty:
+            return cls._empty_frame()
+
+        # Convert column names to snake case
+        df.columns = [cls._snake(c) for c in df.columns]
+
+        # Find complete start/end interval column pairs per suffix
+        cols = ["timeinterval_start", "timeinterval_end"]
+        pairs = {}
+        for sfx in ["utc", "loc"]:
+            pair = {f"{c}_{sfx}": c for c in cols}
+            n_present = sum(c in df.columns for c in pair.keys())
+            if n_present == 1:
+                raise TennetAPIError(
+                    f"Incomplete interval columns in TenneT response: {list(pair.keys())}."
+                )
+            if n_present == 2:
+                pairs[sfx] = pair
+
+        # Convert interval columns to Europe/Amsterdam timestamps (UTC is unambiguous, so it is
+        # preferred over local)
+        if "utc" in pairs:
+            df = df.drop(columns=list(pairs.get("loc", {}).keys())).rename(columns=pairs["utc"])
+            for c in cols:
+                df[c] = pd.to_datetime(df[c], utc=True).dt.tz_convert(cls.LOCAL_TZ)
+        elif "loc" in pairs:
+            df = df.rename(columns=pairs["loc"])
+            df[cols[0]], df[cols[1]] = cls._localize_intervals(df, resolution)
+
+        # Sort chronologically
+        if pairs:
+            df = df.sort_values(cols, ignore_index=True)
+
+        return df
+
+    @classmethod
+    def _localize_intervals(
+        cls, df: pd.DataFrame, resolution: pd.Timedelta
+    ) -> tuple[pd.Series, pd.Series]:
+        """
+        Convert local (Europe/Amsterdam) interval columns to timezone-aware timestamps.
+
+        Local wall-clock times are ambiguous in the repeated hour when DST ends, so:
+        - Start: rebuilt from the delivery date + ISP number (adding a Timedelta to an aware
+          timestamp is absolute-time arithmetic, hence DST-safe), then checked against the
+          wall-clock start times in the response.
+        - End: converted from the response values. For an ambiguous wall-clock time, the
+          earliest reading that falls after the start is used.
+
+        Args:
+            df: DataFrame with naive ``timeinterval_start``, ``timeinterval_end`` and ``isp``
+                columns.
+            resolution: Length of one ISP.
+
+        Returns:
+            Timezone-aware start and end timestamps.
+
+        Raises:
+            TennetAPIError: If the ``isp`` column is missing, if the ISP-based start times don't
+                match the response (e.g. an inconsistent ``resolution``), or if an end time is not
+                after its start time.
+        """
+        if "isp" not in df.columns:
+            raise TennetAPIError(
+                "Cannot parse local date columns without column 'isp', because local "
+                "timestamps are ambiguous around DST."
+            )
+        start_naive = pd.to_datetime(df["timeinterval_start"])
+        end_naive = pd.to_datetime(df["timeinterval_end"])
+
+        # Start: delivery date + ISP number, cross-checked with the response
+        day = start_naive.dt.normalize().dt.tz_localize(cls.LOCAL_TZ)
+        start = day + (df["isp"].astype(int) - 1) * resolution
+        if not (start.dt.tz_localize(None) == start_naive).all():
+            raise TennetAPIError(
+                f"Input resolution '{resolution}' and ISP numbers are inconsistent with TenneT "
+                f"response start timestamps."
+            )
+
+        # End: localize both readings of ambiguous times (DST is the earlier one in absolute
+        # time), and keep the earliest that falls after the start
+        end_dst = end_naive.dt.tz_localize(cls.LOCAL_TZ, ambiguous=True)
+        end_std = end_naive.dt.tz_localize(cls.LOCAL_TZ, ambiguous=False)
+        end = end_dst.where(end_dst > start, end_std)
+        if not (end > start).all():
+            raise TennetAPIError("TenneT response contains intervals that end before they start.")
+
+        return start, end
+
+    @classmethod
+    def _empty_frame(cls) -> pd.DataFrame:
+        """Return an empty DataFrame, used when TenneT returns no data."""
+        return pd.DataFrame()
+
+    @staticmethod
+    def _snake(name: str) -> str:
+        """Convert a column name to snake_case."""
+        return re.sub(r"[^0-9a-z]+", "_", name.strip().lower()).strip("_")

{detquantlib-5.6.0 → detquantlib-5.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "detquantlib"
-version = "5.6.0"
+version = "5.7.0"
 description = "An internal library containing functions and classes that can be used across Quant models."
 authors = ["Dynamic Energy Trading"]
 readme = "README.md"