Source code for energy_data_retrieval.pv_catalogue.mastr
"""Bounded, privacy-minimal MaStR 26.2 solar-unit review staging.
Read extracted UTF-8 EinheitenSolar XML, never whole-project records. Pin the
original archive checksum before resuming a physical-row cursor. No network
requests, canonical upserts, status inference, aggregation or AC/DC conversion.
Mapping: BNetzA Gesamtdatenexport revision 26.2 (1 October 2026), section 5.5.2
and EinheitenSolar.xsd. Names, operators and addresses are deliberately omitted.
"""
from decimal import Decimal, InvalidOperation
from pathlib import Path
from typing import BinaryIO
from xml.etree import ElementTree as ET
_POWER_FIELDS = ("Bruttoleistung", "Nettonennleistung", "ZugeordneteWirkleistungWechselrichter")
_FIELDS = (
"EinheitMastrNummer",
"LokationMaStRNummer",
"EegMaStRNummer",
"DatumLetzteAktualisierung",
"NetzbetreiberpruefungStatus",
"NetzbetreiberpruefungDatum",
*_POWER_FIELDS,
)
class _DtdFreeReader:
def __init__(self, stream: BinaryIO):
self.stream = stream
self.tail = b""
def read(self, size: int = -1) -> bytes:
data = self.stream.read(size)
scan = self.tail + data
if b"\x00" in scan or b"<!DOCTYPE" in scan.upper():
raise ValueError("Only DTD-free UTF-8 official XML is supported")
self.tail = scan[-9:]
return data
[docs]
def read_mastr_solar_units(
path: Path, *, start_row: int = 0, limit: int = 1000
) -> list[dict[str, str | int | None]]:
"""Stage at most 10,000 units; row offsets require an unchanged source hash.
Preserve native field labels and numeric strings. Bruttoleistung and
Nettonennleistung are documented in kW; the allocated inverter-power row's
unit is not explicit in the inspected definition, so it remains native.
Review-status codes are retained without a reviewed/unreviewed inference.
Duplicate unit IDs within a selected partition raise instead of merging.
This is not full XSD validation or a production archive ingestion adapter.
"""
if start_row < 0 or not 1 <= limit <= 10_000:
raise ValueError("Require nonnegative start_row and limit in 1..10000")
selected = []
seen = set()
with path.open("rb") as stream:
events = ET.iterparse(_DtdFreeReader(stream), events=("start", "end"))
_, root = next(events)
if root.tag != "EinheitenSolar":
raise ValueError("Expected explicit EinheitenSolar technology partition")
position = 0
for event, node in events:
if event != "end" or node.tag != "EinheitSolar":
continue
position += 1
if position <= start_row:
root.remove(node)
continue
values = {}
for child in node:
if child.tag in _FIELDS:
if child.tag in values:
raise ValueError(f"Repeated field: {child.tag}")
values[child.tag] = (child.text or "").strip() or None
identifier = values.get("EinheitMastrNummer")
if not identifier or identifier in seen:
raise ValueError("Missing or duplicate selected unit ID")
seen.add(identifier)
for key in _POWER_FIELDS:
value = values.get(key)
if value is None:
continue
try:
number = Decimal(value)
except InvalidOperation as exc:
raise ValueError(f"Invalid native power: {key}") from exc
if not number.is_finite() or number < 0:
raise ValueError(f"Nonfinite or negative native power: {key}")
selected.append({"source_row": position, **dict.fromkeys(_FIELDS), **values})
root.remove(node)
if len(selected) == limit:
break
return selected