Source code for energy_data_retrieval.pv_catalogue.greenpower

"""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