Source code for energy_data_retrieval.pv_catalogue.nea

"""Offline staging of NEA monthly centralized-PV registration attachments.

Registration is not commissioning, operation or proof of whole-project scope.
This reader returns review candidates only; it never creates canonical records.
"""

from __future__ import annotations

import hashlib
import io
import math
import re
import xml.etree.ElementTree as ET
import zipfile
from typing import Any

NS = {"w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main"}
HEADERS = ["序号", "项目编码", "项目名称", "装机容量(MW)", "项目所在地"]


def _text(element: ET.Element) -> str:
    return "".join(node.text or "" for node in element.findall(".//w:t", NS)).strip()


[docs] def read_nea_pv_registrations(content: bytes, *, sha256: str) -> list[dict[str, Any]]: """Verify pinned DOCX bytes and the explicitly labelled centralized-PV table.""" if hashlib.sha256(content).hexdigest() != sha256: raise ValueError("NEA source checksum changed") if len(content) > 10_000_000: raise ValueError("NEA attachment exceeds size bound") with zipfile.ZipFile(io.BytesIO(content)) as archive: member = archive.getinfo("word/document.xml") if member.file_size > 5_000_000: raise ValueError("NEA document XML exceeds size bound") xml = archive.read(member) if b"<!DOCTYPE" in xml or b"<!ENTITY" in xml: raise ValueError("Unsupported XML declarations") body = ET.fromstring(xml).find("w:body", NS) if body is None: raise ValueError("Missing document body") heading = "" cohorts = [] for element in body: if element.tag == f"{{{NS['w']}}}p": heading = _text(element) or heading elif element.tag == f"{{{NS['w']}}}tbl": label = re.fullmatch( r"[一二三四五六七八九十]+、集中式光伏发电[\uff08(](\d+)个[\uff09)]", heading ) if label: cohorts.append((element, int(label[1]))) heading = "" if len(cohorts) != 1: raise ValueError("Expected one explicit centralized photovoltaic cohort") table, expected = cohorts[0] rows = [[_text(cell) for cell in row.findall("w:tc", NS)] for row in table.findall("w:tr", NS)] if not rows or rows[0] != HEADERS or not 1 <= expected <= 500 or len(rows) != expected + 1: raise ValueError("NEA public schema or cohort count changed") result = [] seen = set() for index, cells in enumerate(rows[1:], start=1): if len(cells) != 5: raise ValueError("Unexpected/private columns or merged cells") sequence, code, name, power, locality = cells # September 2026 includes an explicitly printed overseas LA code. Keep # this narrow observed form; neither its letters nor the locality field # establish the generating site's country (the notice can list an office). overseas = bool(re.fullmatch(r"PPC\d{8}LA\d{3}[A-Z0-9]", code)) if ( sequence != str(index) or not (re.fullmatch(r"PPC\d{13}[A-Z0-9]", code) or overseas) or code in seen ): raise ValueError("Invalid, duplicate or non-centralized-PV registry code") if not name or not locality or not re.fullmatch(r"\d+(?:\.\d+)?", power): raise ValueError("Missing identity or ambiguous capacity") capacity = float(power) if not math.isfinite(capacity) or capacity <= 0: raise ValueError("Invalid native registered capacity") seen.add(code) result.append( { "registry_code": code, "native_name": name, "native_locality": locality, "registered_capacity_mw": capacity, "capacity_basis": "Native installed MW; AC/DC unspecified", "locator": f"Centralized-PV table; row {index}; project code {code}", "review_flags": [ "Registration does not establish construction, commissioning or operation", "Reconcile project codes, local names and phases before canonical upsert", "Do not derive dates or coordinates from the registry code or locality", *( ["Overseas code: independently verify generating-site country and scope"] if overseas else [] ), ], } ) return result