Source code for energy_data_retrieval.sources.taipower.client

"""Taipower's public net-generation snapshot, preserving MW and asset scope."""

from __future__ import annotations

import math
import re
from datetime import datetime

import pandas as pd

from energy_data_retrieval.generation import GenerationResult
from energy_data_retrieval.transport import (
    HTTPClient,
    JSONValue,
    RetrievalError,
    array_value,
    object_value,
)

TAIPOWER_HOSTS = frozenset({"service.taipower.com.tw"})
GENERATION_ENDPOINT = "https://service.taipower.com.tw/data/opendata/apply/file/d006001/001.json"
REFERENCE_IDS = ("taipower_live_generation", "taipower_generation_history")
_COLUMNS = [
    "timestamp",
    "source",
    "area",
    "asset_id",
    "technology",
    "source_technology",
    "value",
    "unit",
    "capacity_mw",
    "aggregation",
    "is_total",
    "is_aggregate",
    "flow",
    "source_status",
    "source_datetime",
    "measurement_kind",
]


def _text(value: JSONValue, name: str) -> str:
    if not isinstance(value, str) or not value.strip():
        raise RetrievalError(f"Taipower omitted {name}")
    return value.strip()


def _number(value: JSONValue, *, subtotal: bool = False) -> float:
    if value is None or (isinstance(value, str) and value.strip() in {"", "-", "--", "N/A"}):
        return float("nan")
    if isinstance(value, bool) or not isinstance(value, (int, float, str)):
        raise RetrievalError("Taipower power/capacity must be numeric or missing")
    if subtotal and isinstance(value, str):
        value = re.sub(r"\([0-9.]+%\)$", "", value.strip())
    try:
        result = float(value)
    except ValueError:
        raise RetrievalError("Taipower power/capacity is not numeric") from None
    if not math.isfinite(result):
        raise RetrievalError("Taipower power/capacity contains a non-finite value")
    return result


def _technology(label: str) -> str:
    for fragment, technology in (
        ("太陽", "solar"),
        ("風力", "wind"),
        ("核能", "nuclear"),
        ("燃氣", "gas"),
        ("燃煤", "coal"),
        ("燃油", "oil"),
        ("燃料油", "oil"),
        ("輕油", "oil"),
        ("儲能", "storage"),
        ("水力", "hydro"),
        ("再生", "other_renewable"),
    ):
        if fragment in label:
            return technology
    return re.sub(r"<[^>]*>", "", label)


[docs] def parse_generation( payload: JSONValue, *, include_aggregates: bool = False, include_storage_load: bool = False, maximum_rows: int = 20_000, ) -> pd.DataFrame: """Parse the actual feed, excluding subtotal/group rows and charging by default. The 10-minute publication cadence is not a documented averaging interval. Values remain power snapshots in MW; they are never converted to MWh. ``asset_id`` is the provider's reported label, which can denote a unit, plant or group. Known groups/subtotals are explicitly marked. No complete plant inventory or unit-to-plant registry is inferred from display names. """ if type(maximum_rows) is not int or maximum_rows < 1: raise ValueError("maximum_rows must be a positive integer") root = object_value(payload) label = _text(root.get("DateTime"), "snapshot datetime") try: parsed = datetime.fromisoformat(label) stamp = pd.Timestamp(parsed) stamp = stamp.tz_localize("Asia/Taipei") if stamp.tzinfo is None else stamp stamp = stamp.tz_convert("UTC") except (ValueError, TypeError): raise RetrievalError("Taipower snapshot datetime is invalid") from None data = array_value(root.get("aaData")) if len(data) > maximum_rows: raise RetrievalError("Taipower response exceeds maximum_rows") rows: list[dict[str, object]] = [] for value in data: item = object_value(value) asset = _text(item.get("機組名稱"), "asset name") category = _text(item.get("機組類型"), "technology") total = any(marker in asset for marker in ("小計", "合計", "總計")) grouped = total or any( marker in asset for marker in ( "其它", "其他", "小水力", "自有地熱", "購電地熱", "生質能", "電池", "&", "、", ) ) flow = "consumption" if "負載" in category or "Load" in category else "generation" if (grouped and not include_aggregates) or ( flow == "consumption" and not include_storage_load ): continue if "淨發電量(MW)" not in item or "裝置容量(MW)" not in item: raise RetrievalError("Taipower feed omitted its MW fields") rows.append( { "timestamp": stamp, "source": "taipower", "area": "TW", "asset_id": asset, "technology": _technology(category), "source_technology": category, "value": _number(item["淨發電量(MW)"], subtotal=total), "unit": "MW", "capacity_mw": _number(item["裝置容量(MW)"], subtotal=total), "aggregation": "technology_total" if total else "reported_group" if grouped else "reported_asset", "is_total": total, "is_aggregate": grouped, "flow": flow, "source_status": item.get("備註"), "source_datetime": label, "measurement_kind": "power_snapshot", } ) frame = pd.DataFrame(rows, columns=_COLUMNS) frame["timestamp"] = pd.to_datetime(frame["timestamp"], utc=True) if frame.duplicated(["timestamp", "source_technology", "asset_id", "flow"]).any(): raise RetrievalError("Taipower feed contains duplicate asset observations") return frame.sort_values(["technology", "asset_id", "flow"]).reset_index(drop=True)
[docs] class TaipowerClient: """Retrieve one uncached live snapshot with bounded response size and rows.""" def __init__(self, http: HTTPClient, *, maximum_rows: int = 20_000) -> None: if type(maximum_rows) is not int or maximum_rows < 1: raise ValueError("maximum_rows must be a positive integer") self.http, self.maximum_rows = http, maximum_rows
[docs] def latest( self, *, include_aggregates: bool = False, include_storage_load: bool = False ) -> GenerationResult: """Read the current publication; no API key is required.""" response = self.http.get_json(GENERATION_ENDPOINT, use_cache=False) frame = parse_generation( response.value, include_aggregates=include_aggregates, include_storage_load=include_storage_load, maximum_rows=self.maximum_rows, ) return GenerationResult(frame, (response.record,))