Source code for energy_data_retrieval.pv_catalogue.nve

"""Stage checksum-pinned NVE solar concession candidates for identity review."""

import hashlib
import json
from collections import Counter
from dataclasses import dataclass
from datetime import UTC, datetime
from pathlib import Path
from typing import Any
from urllib.parse import parse_qs, urlsplit


[docs] @dataclass(frozen=True, slots=True) class NveSolarCase: """One source observation, without personal details or geometries.""" feature_number: int plant_number: int case_id: int name: str municipality: str county: str case_url: str stage: str status_code: str proposed_mw: float | None in_service_mw: float | None forecast_gwh: float | None stage_timestamp: str | None first_service_timestamp: str | None data_capture_timestamp: str | None review_flags: tuple[str, ...]
[docs] @dataclass(frozen=True, slots=True) class NveSolarPartition: """Candidate page; a transfer limit marks the page as incomplete.""" cases: tuple[NveSolarCase, ...] exceeded_transfer_limit: bool excluded_non_solar: int
def _identifier(value: object) -> int: if type(value) is not int or not 0 < value < 2**31: raise ValueError("NVE invalid native identifier") return value def _label(value: object) -> str: if not isinstance(value, str) or not value.strip(): raise ValueError("NVE missing source label") return value.strip() def _quantity(value: object) -> float | None: if value is None: return None if not isinstance(value, (float, int)) or isinstance(value, bool) or not 0 <= value < 1e6: raise ValueError("NVE invalid native quantity") return float(value) def _timestamp(value: object) -> str | None: if value is None: return None if type(value) is not int or not 0 < value < 4_102_444_800_000: raise ValueError("NVE invalid epoch milliseconds") return datetime.fromtimestamp(value / 1000, tz=UTC).isoformat() def _case_url(value: object, case_id: int) -> str: url = _label(value) parts = urlsplit(url) if ( parts.scheme != "https" or parts.netloc != "www.nve.no" or parts.path != "/konsesjon/konsesjonssaker/konsesjonssak" or parse_qs(parts.query) != {"type": ["A-6"], "id": [str(case_id)]} or parts.fragment ): raise ValueError("NVE case URL does not match native case identifier") return url
[docs] def read_nve_solar_cases(path: Path, *, sha256: str) -> NveSolarPartition: """Read a pinned ArcGIS layer-2 response without inferring AC/DC or operation. Only the explicit Solkraftverk object type is staged. Repeated case/plant IDs remain visible as holds. The caller must check the catalogue and the exact phase/site scope before upserting. Native MW and GWh are not recast as AC, DC, measured generation, or a canonical lifecycle state. """ data = path.read_bytes() if hashlib.sha256(data).hexdigest() != sha256: raise ValueError("NVE checksum mismatch") document = json.loads(data) if not isinstance(document, dict) or not isinstance(document.get("features"), list): raise ValueError("NVE expected ArcGIS feature collection") exceeded = document.get("exceededTransferLimit", False) if type(exceeded) is not bool: raise ValueError("NVE invalid transfer limit flag") entries: list[tuple[int, int, int, dict[str, Any]]] = [] excluded = 0 for number, feature in enumerate(document["features"], start=1): if not isinstance(feature, dict) or not isinstance(feature.get("attributes"), dict): raise ValueError("NVE malformed feature attributes") attrs = feature["attributes"] if _label(attrs.get("objekttype")) != "Solkraftverk": excluded += 1 continue entries.append( (number, _identifier(attrs.get("anleggsnr")), _identifier(attrs.get("saksid")), attrs) ) plants = Counter(plant for _, plant, _, _ in entries) cases = Counter(case for _, _, case, _ in entries) out = [] for number, plant, case, attrs in entries: flags = [] if plants[plant] != 1: flags.append("repeated_plant_number") if cases[case] != 1: flags.append("repeated_case_id") out.append( NveSolarCase( feature_number=number, plant_number=plant, case_id=case, name=_label(attrs.get("anleggnavn")), municipality=_label(attrs.get("kommune")), county=_label(attrs.get("fylkenavn")), case_url=_case_url(attrs.get("sakslenke"), case), stage=_label(attrs.get("stadium")), status_code=_label(attrs.get("status")), proposed_mw=_quantity(attrs.get("effekt_mw")), in_service_mw=_quantity(attrs.get("effekt_mw_idrift")), forecast_gwh=_quantity(attrs.get("forventetproduksjon_gwh")), stage_timestamp=_timestamp(attrs.get("stadiumdato")), first_service_timestamp=_timestamp(attrs.get("forsteidriftdato")), data_capture_timestamp=_timestamp(attrs.get("datafangstdato")), review_flags=tuple(flags), ) ) return NveSolarPartition(tuple(out), exceeded, excluded)