Source code for energy_data_retrieval.pv_catalogue.electra

"""Read a pinned, bounded Electra search export as candidates, never as projects.

The filtered CSV is only an index. INSTALACIONID is not established as a whole
plant identity; AUTOID is merely an export sequence. No capacity, lifecycle,
owner or technology is inferred from installation names.
"""

from __future__ import annotations

import csv
import io
import json
import re
from collections import Counter
from html.parser import HTMLParser
from typing import Any

from .odre import normal_name
from .sam import verify_sha256

COLUMNS = ["AUTOID", "INSTALACIONID", "REGIMEN", "INSTALACION", "AUTONOMIA"]
PREFIX = "ctl00_ContentPlaceHolder1_"


class _Scope(HTMLParser):
    def __init__(self) -> None:
        super().__init__()
        self.inputs: dict[str, list[str]] = {}
        self.text: list[str] = []

    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
        data = dict(attrs)
        if tag == "input" and data.get("id"):
            self.inputs.setdefault(str(data["id"]), []).append(data.get("value") or "")

    def handle_data(self, data: str) -> None:
        self.text.append(data)


[docs] def read_electra_csv( content: bytes, *, sha256: str, scope_page: bytes, scope_sha256: str, region: str, minimum_net_kw: int, ) -> list[dict[str, str]]: """Check both captures, echoed PV/region/filter, schema, count and identifiers. Reject an unfiltered or truncated export. The query's net-power threshold is retained only as selection provenance, never as a record's capacity value. Network access and canonical acceptance remain explicit separate operations. """ verify_sha256(content, sha256) verify_sha256(scope_page, scope_sha256) if not region.strip() or type(minimum_net_kw) is not int or minimum_net_kw < 0: raise ValueError("Invalid bounded Electra scope") scope = _Scope() scope.feed(scope_page.decode("utf-8-sig")) expected = { "mChkDdlTipoTecnologia_mTxtCheckBoxListCombo": "Fotovoltaica", "mChkDdlAutonomia_mTxtCheckBoxListCombo": region, "mTxtPotenciaNetaMin": str(minimum_net_kw), } if any(scope.inputs.get(PREFIX + key) != [value] for key, value in expected.items()): raise ValueError("Electra echoed query scope differs; do not import") counts = re.findall(r"\d+\s*/\s*\d+\s*\((\d+)\)", " ".join(scope.text)) if len(counts) != 1: raise ValueError("Electra result count missing or ambiguous") reader = csv.DictReader(io.StringIO(content.decode("utf-8-sig")), delimiter=";") if reader.fieldnames != COLUMNS: raise ValueError("Electra filtered-index schema changed; re-review") rows = list(reader) if len(rows) != int(counts[0]): raise ValueError("Electra CSV/result count mismatch") ids: set[str] = set() for index, row in enumerate(rows, start=1): identifier = row.get("INSTALACIONID", "") if ( None in row or any(value is None for value in row.values()) or row["AUTOID"] != str(index) or not re.fullmatch(r"[1-9]\d*", identifier) or identifier in ids or row["AUTONOMIA"] != region or row["REGIMEN"] not in {"ESPECIAL", "ORDINARIO"} or not row["INSTALACION"].strip() ): raise ValueError("Invalid, duplicate or out-of-scope Electra index row") ids.add(identifier) return rows
[docs] def screen_electra_candidates( rows: list[dict[str, str]], *, existing: list[dict[str, Any]] ) -> dict[str, list[str]]: """Return review reasons keyed by registry ID; never auto-merge names. All index rows require phase/privacy/freshness review. Exact normalized name equality only adds a conservative crosswalk flag, never proves identity. Return no installation names or holder/contact information in review output. """ counts = Counter(normal_name(row["INSTALACION"]) for row in rows) names = { normal_name(name) for row in existing if row.get("country_code") == "ESP" for name in [row["name"], *row.get("aliases", [])] } registry_ids = { str(identifier) for row in existing if row.get("country_code") == "ESP" if ( identifier := json.loads(row.get("external_ids_json", "{}")).get( "electra_installation_id" ) ) is not None } result = {} for row in rows: name = normal_name(row["INSTALACION"]) reasons = ["index_only_requires_phase_privacy_freshness_and_power_evidence"] if counts[name] > 1: reasons.append("repeated_incoming_name_distinct_registry_ids") if name in names: reasons.append("existing_name_requires_reviewed_registry_crosswalk") if row["INSTALACIONID"] in registry_ids: reasons.append("existing_registry_id_requires_reviewed_phase_crosswalk") result[row["INSTALACIONID"]] = reasons return result