Source code for energy_data_retrieval.pv_catalogue.taipower

"""Stage Taipower public PV sites without equating stations, sites and plants."""

from __future__ import annotations

import csv
import hashlib
import io
import math
import re
from typing import Any

HEADERS = (
    "發電站編號/Number of The Power Station",
    "能源別/Type of Energy",
    "發電站名稱/Name of The Power Station",
    "場址編號/Number of the Site",
    "場址說明/Description fo The Site",
    "型號/Model",
    "裝置容量(瓩)/Installed Capacity(kW)",
    "風機數量/Number of The Windturbine",
    "地址/Address",
    "申設狀態/Application Status",
    "備註/Remarks",
)


[docs] def read_taipower_sites( content: bytes, *, sha256: str, after_station_id: int | None = None, limit: int = 100 ) -> dict[str, Any]: """Read bounded station groups; keep all sites and their native observations. A station can cover separate sites/roofs/phases. IDs are technology-scoped. Installed kW has no established AC/DC basis here. Application status is not current operation. Source addresses are deliberately excluded from staging. """ if hashlib.sha256(content).hexdigest() != sha256: raise ValueError("Taipower source checksum mismatch") if type(limit) is not int or not 1 <= limit <= 1000: raise ValueError("Taipower partition limit must be 1-1000") if after_station_id is not None and (type(after_station_id) is not int or after_station_id < 1): raise ValueError("Taipower cursor must be a positive station ID") reader = csv.reader(io.StringIO(content.decode("utf-8-sig"), newline="")) if tuple(next(reader, ())) != HEADERS: raise ValueError("Taipower site schema changed") groups: dict[str, dict[str, Any]] = {} site_ids: set[str] = set() station_ids: dict[int, str] = {} counts = dict.fromkeys(["source_rows", "blank_rows", "non_pv_rows", "pv_sites"], 0) for number, cells in enumerate(reader, 2): if not cells or not any(value.strip() for value in cells): counts["blank_rows"] += 1 continue if len(cells) != len(HEADERS): raise ValueError("Taipower row width changed") counts["source_rows"] += 1 station, energy, name, site, description, model, power, wind_count, _, status, remark = ( value.strip() for value in cells ) if energy != "太陽能/Solar": counts["non_pv_rows"] += 1 continue if "光電" not in name and "photovoltaic" not in name.lower(): raise ValueError("Taipower generic Solar is insufficient to prove PV") if not re.fullmatch(r"[1-9][0-9]*", site) or site in site_ids: raise ValueError("Taipower missing or repeated PV site ID") site_ids.add(site) if wind_count: raise ValueError("Taipower PV wind-count cell requires review") if not re.fullmatch(r"\d+(?:\.\d+)?", power): raise ValueError("Taipower capacity must be a native nonnegative kW number") capacity = float(power) if not math.isfinite(capacity): raise ValueError("Taipower capacity is not finite") if name not in groups: groups[name] = {"station_name_native": name, "station_id": None, "sites": []} group = groups[name] if station != "-": if not re.fullmatch(r"[1-9][0-9]*", station): raise ValueError("Taipower station ID is invalid") station_id = int(station) if station_id in station_ids and station_ids[station_id] != name: raise ValueError("Taipower station ID has conflicting names") if group["station_id"] not in (None, station_id): raise ValueError("Taipower station name has conflicting IDs") station_ids[station_id] = name group["station_id"] = station_id group["sites"].append( { "site_id": site, "csv_record_number": number, "description_native": description or None, "model_label_native": model or None, "installed_capacity_kw_native": capacity, "capacity_basis": "AC/DC unspecified; no scalar conversion or aggregation", "application_status_native": status or None, "remarks_native": remark or None, } ) counts["pv_sites"] += 1 if any(g["station_id"] is None for g in groups.values()): raise ValueError("Taipower station group has no explicit ID; no forward fill") ordered = sorted(groups.values(), key=lambda g: g["station_id"]) if after_station_id is not None and after_station_id not in station_ids: raise ValueError("Taipower cursor is absent from this source revision") pending = [g for g in ordered if after_station_id is None or g["station_id"] > after_station_id] selected = pending[:limit] for group in selected: group.update( accepted=False, held_reasons=[ "station_site_plant_phase_identity_requires_review", "capacity_ac_dc_basis_unestablished", "source_effective_date_unestablished", "application_status_not_current_operation", "model_labels_not_OEM_verified_equipment_records", ], ) return { "sha256": sha256, "counts": {**counts, "pv_station_groups": len(ordered)}, "candidates": selected, "next_after_station_id": selected[-1]["station_id"] if selected else after_station_id, "remaining_after_partition": len(pending) - len(selected), "accepted_records": 0, "addresses_and_personal_contacts_excluded": True, "no_capacity_sum_or_status_date_inference": True, }
MONTHLY_HEADERS = ( "年度/Year", "月份/Month", "發電站名稱/Name of The Power Station", "裝置容量(瓩)/Installed Capacity(kW)", "發電量(度)/Power Generation(kWh)", "平均單位裝置容量每日發電量/Average of Each Unit Power Generatioon Per Day", )
[docs] def read_taipower_monthly( content: bytes, *, sha256: str, period_start: str, period_end: str, station_names: list[str] | None = None, reviewed_duplicate_keys: list[str] | None = None, after_key: str | None = None, limit: int = 100, ) -> dict[str, Any]: """Stage native station-month observations, never plant nameplate ratings. Dataset29938 supplies monthly energy and reported installed kW. Its station boundaries can change with sites/phases. No annual sums, present operation, AC/DC basis, plant crosswalk or normalized-performance metric is inferred. """ if hashlib.sha256(content).hexdigest() != sha256: raise ValueError("Taipower monthly source checksum mismatch") if type(limit) is not int or not 1 <= limit <= 1000: raise ValueError("Taipower monthly limit must be 1-1000") for period in (period_start, period_end): if not isinstance(period, str) or not re.fullmatch( r"(?:19|20)\d{2}-(?:0[1-9]|1[0-2])", period ): raise ValueError("Taipower monthly period must be Gregorian YYYY-MM") if period_start > period_end: raise ValueError("Taipower monthly period bounds reversed") if station_names is not None and ( not isinstance(station_names, list) or not station_names or any(not isinstance(n, str) or not n.strip() for n in station_names) or len(set(station_names)) != len(station_names) ): raise ValueError("Taipower monthly station names must be unique nonempty strings") if after_key is not None and (not isinstance(after_key, str) or not after_key.strip()): raise ValueError("Taipower monthly cursor must be nonempty") reader = csv.reader(io.StringIO(content.decode("utf-8-sig"), newline="")) if tuple(next(reader, ())) != MONTHLY_HEADERS: raise ValueError("Taipower monthly schema changed") if reviewed_duplicate_keys is not None and ( not isinstance(reviewed_duplicate_keys, list) or any(not isinstance(k, str) or not k.strip() for k in reviewed_duplicate_keys) or len(set(reviewed_duplicate_keys)) != len(reviewed_duplicate_keys) ): raise ValueError("Taipower reviewed duplicate keys must be unique strings") rows: list[dict[str, Any]] = [] key_counts: dict[str, int] = {} keys: set[str] = set() names: set[str] = set() for number, cells in enumerate(reader, 2): if not cells or not any(c.strip() for c in cells): continue if len(cells) != len(MONTHLY_HEADERS): raise ValueError("Taipower monthly row width changed") year, month, name, capacity, energy, average = (v.strip() for v in cells) if not re.fullmatch(r"(?:19|20)\d{2}", year) or not re.fullmatch( r"(?:0?[1-9]|1[0-2])", month ): raise ValueError("Taipower monthly Gregorian year/month invalid") if "光電" not in name and "photovoltaic" not in name.lower(): raise ValueError("Taipower monthly station not explicitly PV") period = f"{year}-{int(month):02d}" key = period + "|" + name key_counts[key] = key_counts.get(key, 0) + 1 keys.add(key) names.add(name) values = [] for value in (capacity, energy, average): if not re.fullmatch(r"\d+(?:\.\d+)?", value): raise ValueError("Taipower monthly value is not native nonnegative number") parsed = float(value) if not math.isfinite(parsed): raise ValueError("Taipower monthly value not finite") values.append(parsed) rows.append( { "key": key, "csv_record_number": number, "period": period, "station_name_native": name, "installed_capacity_kw_native": values[0], "monthly_generation_kwh": values[1], "reported_average_unit_daily_energy_native": values[2], "scope": ( "Named station-month; AC/DC and site/phase boundaries unestablished. " "Average formula/denominator not independently verified." ), "accepted": False, } ) duplicate_keys = {k for k, count in key_counts.items() if count > 1} if duplicate_keys != set(reviewed_duplicate_keys or []): raise ValueError("Taipower monthly duplicate station/period needs exact reviewed hold keys") held_duplicates = [r for r in rows if r["key"] in duplicate_keys] if after_key in duplicate_keys: raise ValueError("Taipower monthly cursor is a held duplicate") if station_names is not None and not set(station_names) <= names: raise ValueError("Taipower monthly requested station absent from source") if after_key is not None and after_key not in keys: raise ValueError("Taipower monthly cursor absent from source revision") selected = sorted( ( r for r in rows if r["key"] not in duplicate_keys and period_start <= r["period"] <= period_end and (station_names is None or r["station_name_native"] in station_names) and (after_key is None or r["key"] > after_key) ), key=lambda r: r["key"], ) return { "sha256": sha256, "source_rows": len(rows), "source_station_names": len(names), "held_duplicate_period_groups": len(duplicate_keys), "held_duplicate_observations": held_duplicates, "source_period_min": min((r["period"] for r in rows), default=None), "source_period_max": max((r["period"] for r in rows), default=None), "selected_period_start": period_start, "selected_period_end": period_end, "candidates": selected[:limit], "next_after_key": selected[min(limit, len(selected)) - 1]["key"] if selected else after_key, "remaining_after_partition": max(0, len(selected) - limit), "accepted_records": 0, "no_annual_sum_or_status_capacity_basis_inference": True, }