"""Stage scoped GreenPower workbook observations for Australian PV identity review."""
import hashlib
import math
import re
from collections import Counter
from datetime import date, datetime
from io import BytesIO
from pathlib import Path
from typing import Any
from .australia import _STATES
_HEADERS = (
"GreenPower accredited name",
"CER code",
"Fuel source",
"Capacity (MW)",
"Location",
"State",
"Generator owner",
"GreenPower accreditation date",
"CER accreditation date",
)
def _accreditation_date(value: Any, cutoff: date) -> str | None:
if value is None:
return None
if not isinstance(value, datetime) or not date(1997, 1, 1) <= value.date() <= cutoff:
raise ValueError("Unexpected GreenPower accreditation date")
return value.date().isoformat()
[docs]
def read_greenpower_workbook(
workbook: Path, *, sha256: str, release_date: str, minimum_mw: float = 1
) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
"""Read the Generators sheet as candidates for a reviewed existing PV crosswalk.
Solar is the publisher's fuel label, and capacity is a scheme observation
without an AC/DC definition. This reader does not infer PV technology,
publish the owner column, or make canonical identity decisions.
"""
from openpyxl import load_workbook
if not math.isfinite(minimum_mw) or minimum_mw <= 0:
raise ValueError("The GreenPower threshold must be positive and finite")
data = workbook.read_bytes()
if hashlib.sha256(data).hexdigest() != sha256:
raise ValueError("Unexpected GreenPower workbook checksum")
cutoff = date.fromisoformat(release_date)
book = load_workbook(BytesIO(data), read_only=True, data_only=True)
try:
rows = list(book["Generators"].values)
finally:
book.close()
if (
len(rows) < 4
or not isinstance(rows[0][3], datetime)
or rows[0][3].date() != cutoff
or rows[2] != _HEADERS
):
raise ValueError("Unexpected GreenPower workbook layout or release")
codes = Counter(row[1].strip() for row in rows[3:] if isinstance(row[1], str))
candidates = []
held = []
for number, row in enumerate(rows[3:], 4):
name, raw_code, fuel, power, locality, state, _, green_date, cer_date = row
if not isinstance(fuel, str) or fuel.strip() != "Solar" or type(power) not in (float, int):
continue
if not math.isfinite(power):
raise ValueError("Non-finite GreenPower capacity")
if power < minimum_mw:
continue
code = raw_code.strip() if isinstance(raw_code, str) else ""
if (
not re.fullmatch(r"SR[A-Z0-9]+", code)
or codes[code] != 1
or not isinstance(state, str)
or state.strip() not in _STATES
or not isinstance(name, str)
or not name.strip()
):
held.append(
{"worksheet_row": number, "reason": "invalid or non-solar registry identity"}
)
continue
candidates.append(
{
"worksheet_row": number,
"source_as_of": release_date,
"accredited_name": name.strip(),
"cer_code": code,
"state_code": state.strip(),
"locality_reported": locality.strip() if isinstance(locality, str) else None,
"scheme_capacity_mw_ac_dc_unspecified": power,
"greenpower_accreditation_date": _accreditation_date(green_date, cutoff),
"cer_accreditation_date": _accreditation_date(cer_date, cutoff),
}
)
return candidates, held