"""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