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