Source code for energy_data_retrieval.pv_catalogue.navarra

"""Pinned Navarra operating-PV DBF index; explicit reviewed acceptance only."""

from __future__ import annotations

import io
import math
import re
import struct
import zipfile
from collections import Counter
from decimal import Decimal, InvalidOperation
from typing import Any

from .catalogue import canonical_json, stable_id
from .sam import verify_sha256

COLUMNS = [
    "FEATURE",
    "NOMBRE",
    "PROMOTOR",
    "POT_MW",
    "PUESTSERV",
    "EXPEDIENTE",
    "RAIPEE",
    "DIA",
    "EVACUACION",
    "GEOM_AREA",
    "GEOM_PERI",
    "BEGINLIFE",
]


[docs] def read_navarra_archive( content: bytes, *, sha256: str, layer: str = "operating" ) -> list[dict[str, str]]: """Verify original archive, layer-specific rights/definition and DBF framing. FEATURE is not unique. PROMOTOR is deliberately discarded before returning rows: it may identify a natural person. No coordinates or centroid are derived. """ if layer not in {"operating", "permitting"}: raise ValueError("Unknown Navarra layer") suffix = "" if layer == "operating" else "Tra" title = "Plantas solares fotovoltaicas en " + ( "servicio" if layer == "operating" else "tramitación" ) expected_columns = ( COLUMNS if layer == "operating" else [k for k in COLUMNS if k not in {"PUESTSERV", "RAIPEE"}] ) verify_sha256(content, sha256) with zipfile.ZipFile(io.BytesIO(content)) as archive: if sum(f.file_size for f in archive.infolist()) > 10_000_000: raise ValueError("Oversized Navarra archive") meta = archive.read("spaSITNAENERGI_Pol_PSolar" + suffix + ".xml").decode("utf-8") if not all( s in meta for s in ( "CC BY 4.0", "suma de las potencias de los paneles", title, ) ): raise ValueError("Navarra rights or power definition changed") data = archive.read("ENERGI_Pol_PSolar" + suffix + ".dbf") if len(data) < 33: raise ValueError("Truncated Navarra DBF") count, header, width = struct.unpack("<IHH", data[4:12]) if header < 33 or (header - 33) % 32 or header > len(data): raise ValueError("Invalid Navarra DBF header") columns = [] for offset in range(32, header - 1, 32): descriptor = data[offset : offset + 32] columns.append((descriptor[:11].split(b"\0")[0].decode("ascii"), descriptor[16])) if [k for k, _ in columns] != expected_columns or sum(w for _, w in columns) + 1 != width: raise ValueError("Navarra DBF schema changed") if data[header - 1] != 13 or len(data) not in ( header + count * width, header + count * width + 1, ): raise ValueError("Truncated or unexpected Navarra DBF records") rows = [] for i in range(count): record = data[header + i * width : header + (i + 1) * width] if record[0] != 32: raise ValueError("Deleted/unexpected Navarra row requires review") row = {"row_locator": str(i + 1), "source_layer": title} offset = 1 for key, length in columns: value = record[offset : offset + length].decode("cp1252").strip() if key != "PROMOTOR": row[key] = value offset += length try: power = Decimal(row["POT_MW"]) except InvalidOperation as exc: raise ValueError("Invalid Navarra panel power") from exc if ( not math.isfinite(float(power)) or not power.is_finite() or power <= 0 or not row["NOMBRE"] ): raise ValueError("Invalid Navarra panel power or identity") rows.append(row) return rows
[docs] def reviewed_navarra_project( row: dict[str, str], *, rows: list[dict[str, str]], source_id: str, now: str, approved_case: str, ) -> dict[str, Any]: """Build only a manually approved unique single-case facility. Caller must review all incoming and canonical names/IDs/spatial/phase risks. Never use FEATURE, generic RAIPEE text or the row number as project identity. Normalized operating status/service date and exact location stay unknown. """ case = row["EXPEDIENTE"] counts = Counter(r["EXPEDIENTE"] for r in rows) if case != approved_case or not re.fullmatch(r"\d+-CE", case) or counts[case] != 1: raise ValueError("Unreviewed, repeated or aggregate Navarra case") native = { "locator": ( "ENERGI_Pol_PSolarTra.dbf" if "tramitación" in row["source_layer"] else "ENERGI_Pol_PSolar.dbf" ) + " row " + row["row_locator"], "case_reference": case, "panel_power_mw_printed": row["POT_MW"], "power_basis": "sum of panel ratings; not grid/net/export power", "service_year_printed": row.get("PUESTSERV", ""), "service_year_scope": "Generic dictionary year description; not normalized commissioning", "registration_text": row.get("RAIPEE", ""), "environmental_declaration": row["DIA"], "grid_connection_text": row["EVACUACION"], "database_insertion_date": row["BEGINLIFE"], "source_layer": row["source_layer"], "lifecycle_scope": "Layer classification; effective date per row not verified", "privacy": "Promoter omitted; no private owner, address or contact retained", } return { "record_id": stable_id("projects", "ESP", "navarra_case", case), "entity_type": "projects", "name": row["NOMBRE"], "country_code": "ESP", "region": "Comunidad Foral de Navarra", "technology": "photovoltaic", "capacity_dc_mw": float(Decimal(row["POT_MW"])), "capacity_basis": "Sum of panel ratings (MW); source definition", "external_ids_json": canonical_json({"navarra_case": case}), "extensions_json": canonical_json({"navarra": native}), "sources": [source_id], "field_sources_json": canonical_json({"*": source_id}), "quality_status": "reviewed_regional_inventory", "created_at": now, "updated_at": now, "last_verified_at": now, }