"""Reviewed BOE turbine-position tables; proposed layouts are not operating fleets."""
from __future__ import annotations
import hashlib
import math
import re
from html.parser import HTMLParser
from typing import Any
from energy_data_retrieval.pv_catalogue.catalogue import canonical_json
from .catalogue import stable_id
from .gppd import evidence_record
REFERENCE_IDS = ("boe_b_2026_15548", "boe_b_2026_14921", "boe_b_2026_12797")
class _Tables(HTMLParser):
def __init__(self, *, position_header: bool = False) -> None:
super().__init__()
self.position_header = position_header
self.tables: list[list[list[str]]] = []
self.merged: list[bool] = []
self.table_merged = False
self.table: list[list[str]] | None = None
self.row: list[str] | None = None
self.cell: list[str] | None = None
def handle_starttag(self, tag, attrs):
if tag == "table":
if self.table is not None:
raise ValueError("Nested layout table")
self.table = []
self.table_merged = False
elif tag == "tr" and self.table is not None:
self.row = []
elif tag in {"td", "th"} and self.row is not None:
if any(
k in {"rowspan", "colspan"}
and v != "1"
and not (
self.position_header
and k == "colspan"
and v == "2"
and self.table == []
and len(self.row) == 1
)
for k, v in attrs
):
self.table_merged = True
self.cell = []
def handle_data(self, data):
if self.cell is not None:
self.cell.append(data)
def handle_endtag(self, tag):
if tag in {"td", "th"} and self.cell is not None:
assert self.row is not None
self.row.append(" ".join(" ".join(self.cell).split()))
self.cell = None
elif tag == "tr" and self.row is not None:
assert self.table is not None
self.table.append(self.row)
self.row = None
elif tag == "table" and self.table is not None:
self.tables.append(self.table)
self.merged.append(self.table_merged)
self.table = None
[docs]
def stage_layout(
original: bytes, review: dict[str, Any], project: dict[str, Any], *, now: str
) -> list[dict[str, Any]]:
"""Require a complete, explicitly reviewed coordinate table and parent source.
Preserve the published projected CRS and metre resolution. Do not guess a
geographic transform, exact OEM model, commissioned capacity or met-mast type.
"""
if hashlib.sha256(original).hexdigest() != review["sha256"]:
raise ValueError("Layout original checksum mismatch")
if (
project.get("entity_type") != "projects"
or project.get("country_code") != "ESP"
or review["source_id"] not in project["sources"]
or project.get("status") not in {"announced", "permitted"}
or review["crs"] not in {"EPSG:25829", "EPSG:25830"}
or not review.get("crs_locator")
):
raise ValueError("Reviewed proposed Spanish layout, CRS and parent source required")
xy = review.get("table_format") == "position_xy"
municipality = review.get("table_format") == "number_xy_municipality"
if review.get("table_format") not in {None, "position_xy", "number_xy_municipality"}:
raise ValueError("Unreviewed layout table format")
text = original.decode("utf-8")
if municipality:
if review["crs"] != "EPSG:25829" or "ETRS89 Huso 29N" not in text:
raise ValueError("Municipality format requires explicit ETRS89 zone 29N evidence")
elif review["crs"] != "EPSG:25830":
raise ValueError("Existing formats are reviewed only for zone 30N")
parser = _Tables(position_header=xy)
parser.feed(text)
if parser.table is not None:
raise ValueError("Truncated table")
headers = ["Aerogenerador", "UTM X (m)", "UTM Y (m)", "Altitud (m)", "Término Municipal"]
if municipality:
headers = ["Núm. Aero", "Coord X", "Coord Y", "Municipio"]
tables = [
(t, merged)
for t, merged in zip(parser.tables, parser.merged, strict=True)
if (
t[:2] == [["Aerogenerador", "Posición"], ["", "X (UTM)", "Y (UTM)"]]
if xy
else bool(t) and t[0] == headers
)
]
if len(tables) != 1:
raise ValueError("Expected exactly one turbine-position table")
table, merged = tables[0]
if merged:
raise ValueError("Merged layout cells need explicit review")
data = table[2 if xy else 1 :]
if xy:
if any(len(r) != 3 for r in data):
raise ValueError("Expected three position columns")
data = [[*r, None, None] for r in data]
if municipality:
if any(len(r) != 4 for r in data):
raise ValueError("Expected four municipality position columns")
data = [[r[0], r[1], r[2], None, r[3]] for r in data]
expected = review["expected_ids"]
ids = [r[0] for r in data if len(r) == 5]
if (
len(ids) != len(data)
or len(set(ids)) != len(ids)
or len(set(expected)) != len(expected)
or set(ids) != set(expected)
or len(ids) != project.get("turbine_count")
):
raise ValueError("Incomplete or duplicate turbine layout")
records = []
for label, east, north, altitude, locality in data:
if not isinstance(label, str) or not isinstance(east, str) or not isinstance(north, str):
raise ValueError("Layout label and coordinates must be strings")
if xy and any(
not re.fullmatch(r"[0-9]{1,3}(?:\.[0-9]{3})*,[0-9]{2}", v) for v in (east, north)
):
raise ValueError("Expected reviewed Spanish decimal coordinates")
if municipality and any(
not re.fullmatch(r"[0-9]{1,3}(?:\.[0-9]{3})+", v) for v in (east, north)
):
raise ValueError("Expected reviewed Spanish integer coordinates")
x, y = (
float(v.replace(".", "").replace(",", "."))
if xy or municipality
else float(v.replace(",", "."))
for v in (east, north)
)
z = None if altitude is None else float(altitude.replace(",", "."))
if not all(math.isfinite(v) for v in (x, y, z) if v is not None) or not (
100000 <= x <= 900000 and 3000000 <= y <= 5000000
):
raise ValueError("Invalid published coordinate")
locator = f"Turbine-position table / {label}"
records.append(
evidence_record(
{
"record_id": stable_id("turbines", project["record_id"], label),
"entity_type": "turbines",
"record_scope": "turbine",
"project_record_id": project["record_id"],
"name": f"{project['name']} / {label}",
"country_code": "ESP",
"locality": locality,
"status": project["status"],
"status_as_of": project.get("status_as_of"),
"status_date_basis": project.get("status_date_basis"),
"capacity_scope": "Individual proposed layout position; no installed MW",
"external_ids_json": canonical_json({"boe_layout_label": label}),
"extensions_json": canonical_json(
{
"published_layout": {
"label": label,
"source_id": review["source_id"],
"locator": locator,
"published_at": review["published_at"],
"crs": review["crs"],
"crs_locator": review["crs_locator"],
"easting": x,
"northing": y,
"original_easting": east,
"original_northing": north,
"number_normalization": "Spanish thousands separator removed"
if xy or municipality
else "decimal comma normalized",
"altitude": z,
"coordinate_unit": "m",
"published_resolution_m": 0.01 if xy else 1,
"position_accuracy_m": None,
"altitude_datum": "above sea level; vertical datum unspecified"
if z is not None
else None,
"boundary": "proposed position, not as-built turbine",
}
}
),
"notes": "Published metre coordinates retained in original CRS. Geographic "
"coordinates and exact OEM model unresolved; no model inferred "
"from dimensions.",
},
source_id=review["source_id"],
now=now,
locator=locator,
)
)
return sorted(records, key=lambda r: r["record_id"])