Source code for energy_data_retrieval.pv_catalogue.boe

"""Stage explicit PV mentions from a checksummed Spanish BOE daily summary."""

from __future__ import annotations

import hashlib
import json
import re
from datetime import date
from typing import Any

_PV = re.compile(r"\bfotovoltaic[oa]s?\b", re.IGNORECASE)
_NOTICE = re.compile(r"BOE-([AB])-([0-9]{4})-([0-9]+)")


def _objects(value: Any) -> list[dict[str, Any]]:
    # The API emits single elements as objects and repeated elements as arrays.
    items = [value] if isinstance(value, dict) else value
    if (
        not isinstance(items, list)
        or not items
        or not all(isinstance(item, dict) for item in items)
    ):
        raise ValueError("Invalid BOE summary element")
    return items


def _department_items(department: dict[str, Any]) -> list[dict[str, Any]]:
    text = department.get("texto")
    if isinstance(text, dict):
        department = text
    if "item" in department:
        return _objects(department["item"])
    if "epigrafe" in department:
        return [
            item
            for heading in _objects(department["epigrafe"])
            for item in _objects(heading.get("item"))
        ]
    if isinstance(text, str):
        return []
    raise ValueError("Missing BOE department items")


[docs] def read_boe_pv_summary(raw: bytes, *, sha256: str, publication_date: date) -> list[dict[str, str]]: """Return notice pointers only, including hybrids and ancillary PV mentions. Neither a title nor a notice ID establishes a canonical plant identity, capacity, decision type or operating status. Review the cited notice itself. """ if hashlib.sha256(raw).hexdigest() != sha256: raise ValueError("BOE summary checksum does not match") try: payload = json.loads(raw) summary = payload["data"]["sumario"] metadata = summary["metadatos"] status = payload["status"]["code"] issues = _objects(summary["diario"]) except (KeyError, TypeError) as error: raise ValueError("Missing BOE summary envelope") from error if ( status != "200" or not isinstance(metadata, dict) or metadata.get("publicacion") != "BOE" or metadata.get("fecha_publicacion") != publication_date.strftime("%Y%m%d") ): raise ValueError("Unexpected BOE publication or date") candidates: list[dict[str, str]] = [] seen = set() for issue in issues: number = issue.get("numero") if not isinstance(number, str) or not number.isdecimal(): raise ValueError("Missing BOE issue number") for section in _objects(issue.get("seccion")): text = section.get("texto") container = text if isinstance(text, dict) else section departments = ( _objects(container["departamento"]) if "departamento" in container else [section] ) for department in departments: for item in _department_items(department): title = item.get("titulo") if not isinstance(title, str) or not title.strip(): raise ValueError("Missing BOE notice title") if not _PV.search(title): continue notice_id = item.get("identificador") if not isinstance(notice_id, str): raise ValueError("Invalid BOE PV notice ID") match = _NOTICE.fullmatch(notice_id) if not match or int(match[2]) != publication_date.year: raise ValueError("Invalid BOE PV notice ID") if notice_id in seen: raise ValueError("Duplicate BOE PV notice ID") xml_url = f"https://www.boe.es/diario_boe/xml.php?id={notice_id}" if item.get("url_xml") != xml_url: raise ValueError("Unexpected BOE notice XML URL") seen.add(notice_id) candidates.append( { "notice_id": notice_id, "publication_date": publication_date.isoformat(), "issue_number": number, "xml_url": xml_url, } ) return candidates