Source code for energy_data_retrieval.pv_catalogue.tenerife

"""Stage the ITER Tenerife inventory and installation-level monthly energy."""

from __future__ import annotations

import calendar
import csv
import io
import json
import math
import re
from dataclasses import dataclass
from datetime import date

from .sam import verify_sha256

INVENTORY_COLUMNS = (
    "instalacion_id",
    "instalacion_nombre",
    "instalacion_tipo",
    "instalacion_potencia",
    "instalacion_unidad_potencia",
    "instalacion_latitud",
    "instalacion_longitud",
)
_ENERGY_FIELDS = {
    "fecha",
    "periodo_inicial",
    "periodo_final",
    "energia_exportada",
    "energia_importada",
}


[docs] @dataclass(frozen=True, slots=True) class TenerifeInstallation: """One positively identified PV installation with nominal kW of unspecified basis.""" source_row: int installation_id: int name: str nominal_kw: float latitude: float longitude: float
[docs] @dataclass(frozen=True, slots=True) class TenerifeEnergyMonth: """Native monthly import and export values pending unit and identity review.""" period_start: date period_end: date exported_as_reported: int | float imported_as_reported: int | float
[docs] def read_tenerife_inventory( content: bytes, *, sha256: str ) -> tuple[int, list[TenerifeInstallation]]: """Read a checksummed CSV and stage only rows explicitly classified as PV. Native IDs must be unique across the complete source, including wind rows. Coordinates are publisher installation points. No AC/DC or status inference and no canonical matching are performed here. """ verify_sha256(content, sha256) reader = csv.DictReader(io.StringIO(content.decode("utf-8-sig"), newline=""), strict=True) if tuple(reader.fieldnames or ()) != INVENTORY_COLUMNS: raise ValueError("Unexpected Tenerife installation columns") seen = set() result = [] for row_number, row in enumerate(reader, 2): if None in row or None in row.values(): raise ValueError("Unexpected Tenerife installation row width") native_id = row["instalacion_id"] if not re.fullmatch(r"[1-9][0-9]*", native_id) or native_id in seen: raise ValueError("Invalid or duplicate Tenerife installation ID") seen.add(native_id) if row["instalacion_tipo"] != "Fotovoltaica": continue name = row["instalacion_nombre"].strip() if not name or row["instalacion_unidad_potencia"] != "kW": raise ValueError("Missing installation name or unexpected nominal power unit") power = float(row["instalacion_potencia"]) latitude = float(row["instalacion_latitud"]) longitude = float(row["instalacion_longitud"]) if not math.isfinite(power) or power <= 0: raise ValueError("Invalid nominal Tenerife installation power") if not 27.9 <= latitude <= 28.7 or not -17.0 <= longitude <= -16.1: raise ValueError("Tenerife installation point outside the island bounds") result.append( TenerifeInstallation(row_number, int(native_id), name, power, latitude, longitude) ) return len(seen), result
def _midnight_date(value: object) -> date: if not isinstance(value, str) or not re.fullmatch(r"\d{4}-\d\d-\d\dT00:00:00", value): raise ValueError("Invalid Tenerife monthly date") return date.fromisoformat(value[:10]) def _native_energy(value: object) -> int | float: if ( isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value) or value < 0 ): raise ValueError("Invalid Tenerife native energy observation") return value
[docs] def read_tenerife_monthly_energy( content: bytes, *, sha256: str, expected_installation_id: int ) -> list[TenerifeEnergyMonth]: """Read one named installation's monthly series without normalizing units. Match the caller's reviewed native ID, reject duplicate or unordered periods and verify that each row covers a complete calendar month. Gaps stay visible. """ verify_sha256(content, sha256) data = json.loads(content) installations = data.get("instalaciones") if isinstance(data, dict) else None if not isinstance(installations, list) or len(installations) != 1: raise ValueError("Expected one Tenerife monthly installation") installation = installations[0] if ( not isinstance(installation, dict) or type(installation.get("instalacion_id")) is not int or installation["instalacion_id"] != expected_installation_id or expected_installation_id <= 0 ): raise ValueError("Unexpected Tenerife monthly installation ID") rows = installation.get("datos_energia") if not isinstance(rows, list) or not rows: raise ValueError("Missing Tenerife monthly series") result: list[TenerifeEnergyMonth] = [] for row in rows: if not isinstance(row, dict) or set(row) != _ENERGY_FIELDS: raise ValueError("Unexpected Tenerife monthly columns") start = _midnight_date(row["periodo_inicial"]) end = _midnight_date(row["periodo_final"]) if ( start != _midnight_date(row["fecha"]) or start.day != 1 or end != start.replace(day=calendar.monthrange(start.year, start.month)[1]) or (result and start <= result[-1].period_end) ): raise ValueError("Invalid or overlapping Tenerife monthly period") result.append( TenerifeEnergyMonth( start, end, _native_energy(row["energia_exportada"]), _native_energy(row["energia_importada"]), ) ) return result