Source code for energy_data_retrieval.pv_catalogue.cne

"""Stage the CNE Chile Capacidad Instalada de Gx CSV for identity review.

The CSV mixes plant and unit observations. Preserve the source grain, and keep
net and gross MW separate. This reader never accepts a canonical identity.
"""

import csv
import hashlib
import io
import re
from collections import Counter
from dataclasses import dataclass
from datetime import date, datetime
from pathlib import Path

HEADERS: tuple[str, ...] = (
    "sistema",
    "subsistema",
    "propietario",
    "razon_social",
    "rut",
    "central",
    "estado",
    "fecha_puesta_servicio_central",
    "anio_servicio_central",
    "region_nombre",
    "comuna_nombre",
    "cod_unidad",
    "tipo_unidad",
    "fecha_servicio_unidad",
    "unidades",
    "marca_modelo",
    "clasificacion",
    "tipo_de_energia",
    "potencia_bruta_mw",
    "potencia_neta_mw",
    "ley_ernc",
    "medio_generacion",
    "distribuidora",
    "punto_conexion",
    "combustible_1",
    "consumo_1",
    "unidad_1",
    "combustible_2",
    "consumo_2",
    "unidad_2",
    "combustible_3",
    "consumo_3",
    "unidad_3",
    "tipo_turbina_hidraulica",
    "gasto_m3_por_s",
    "caida_m",
    "coord_este_utm",
    "coord_norte_utm",
    "huso_utm",
    "tipo_final",
    "orden",
    "fecha_act",
)
SITE_FIELDS = ("sistema", "subsistema", "central", "region_nombre", "comuna_nombre")


[docs] @dataclass(frozen=True, slots=True) class CnePvObservation: """Safe, source-qualified candidate without owner, tax or coordinate fields.""" row_number: int site_key: tuple[str, ...] site_rows: int unit_label: str | None technology: str gross_mw: float | None net_mw: float | None native_status: str | None update_date: str reported_plant_service_date: str | None review_flags: tuple[str, ...]
def _mw(raw: str) -> float | None: if not raw: return None if not re.fullmatch(r"[0-9]+(?:,[0-9]+)?", raw): raise ValueError("CNE malformed MW value") value = float(raw.replace(",", ".")) if not 0 <= value < 1e6: raise ValueError("CNE MW value outside allowed range") return value
[docs] def read_cne_csv(path: Path, *, sha256: str) -> list[CnePvObservation]: """Read an exact source revision, staging only explicit photovoltaic rows. The native final technology field distinguishes PV from generic solar or CSP. Conflicting classifications, repeated site keys and inconsistent capacity bases stay visible as review flags. No rows are aggregated. """ data = path.read_bytes() if hashlib.sha256(data).hexdigest() != sha256: raise ValueError("CNE checksum mismatch") reader = csv.DictReader(io.StringIO(data.decode("utf-8-sig"), newline=""), strict=True) if tuple(reader.fieldnames or ()) != HEADERS: raise ValueError("CNE CSV header drift") sites: Counter[tuple[str, ...]] = Counter() candidates = [] for row_number, row in enumerate(reader, 2): if None in row or any(value is None for value in row.values()): raise ValueError("CNE CSV row width") site = tuple(row[key].strip() for key in SITE_FIELDS) sites[tuple(value.casefold() for value in site)] += 1 if row["tipo_final"].strip().casefold() == "solar fotovoltaica": candidates.append((row_number, row, site)) result = [] for row_number, row, site in candidates: site_rows = sites[tuple(value.casefold() for value in site)] gross = _mw(row["potencia_bruta_mw"].strip()) net = _mw(row["potencia_neta_mw"].strip()) native_date = row["fecha_act"].strip() update_date = date.fromisoformat(native_date).isoformat() if update_date != native_date: raise ValueError("CNE noncanonical update date") service = row["fecha_puesta_servicio_central"].strip() service_date = ( datetime.strptime(service, "%d/%m/%Y").date().isoformat() if service else None ) flags = [] if not all(site[i] for i in (0, 2, 3, 4)): flags.append("incomplete_site_key") if site_rows != 1: flags.append("multiple_native_rows_for_site") if row["tipo_de_energia"].strip().casefold() not in {"", "solar", "solar fotovoltaica"}: flags.append("conflicting_technology") fuels = {row[f"combustible_{i}"].strip().casefold() for i in range(1, 4)} if fuels - {"", "solar"}: flags.append("conflicting_fuel_label") if re.match(r"(?:pmgd\s+ter|pe)\s+", site[2], re.IGNORECASE): flags.append("potential_non_pv_plant_label") if gross is not None and net is not None and net > gross: flags.append("net_exceeds_gross") result.append( CnePvObservation( row_number=row_number, site_key=site, site_rows=site_rows, unit_label=row["cod_unidad"].strip() or None, technology=row["tipo_final"].strip(), gross_mw=gross, net_mw=net, native_status=row["estado"].strip() or None, update_date=update_date, reported_plant_service_date=service_date, review_flags=tuple(flags), ) ) return result