Source code for energy_data_retrieval.bess_catalogue.pib

"""Offline staging of PIB's Indian BESS deployment table, never automatic imports.

The July 2026 table includes portfolio aggregates, ambiguous identities and
description/rating disagreements. Return reported columns separately from the
description; reviewed site identities and lifecycle evidence are still required.
"""

from __future__ import annotations

import math
import re
from html.parser import HTMLParser
from typing import Any


class _Tables(HTMLParser):
    def __init__(self) -> None:
        super().__init__(convert_charrefs=True)
        self.tables: list[list[list[str]]] = []
        self.stack: list[dict[str, Any]] = []

    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
        if tag == "table":
            self.stack.append({"rows": [], "row": None, "cell": None})
        elif self.stack:
            table = self.stack[-1]
            if tag == "tr":
                table["row"] = []
            elif tag in {"td", "th"}:
                table["cell"] = []
            elif tag in {"br", "p"} and table["cell"] is not None:
                table["cell"].append(" ")

    def handle_data(self, data: str) -> None:
        if self.stack and self.stack[-1]["cell"] is not None:
            self.stack[-1]["cell"].append(data)

    def handle_endtag(self, tag: str) -> None:
        if not self.stack:
            return
        table = self.stack[-1]
        if tag in {"td", "th"} and table["cell"] is not None:
            if table["row"] is not None:
                table["row"].append(" ".join("".join(table["cell"]).split()))
            table["cell"] = None
        elif tag == "tr" and table["row"] is not None:
            table["rows"].append(table["row"])
            table["row"] = None
        elif tag == "table":
            self.tables.append(table["rows"])
            self.stack.pop()


def _capacity(text: str) -> float:
    value = text.strip()
    if not re.fullmatch(r"(?:\d+|\d{1,3}(?:,\d{3})+)(?:\.\d+)?", value):
        raise ValueError(f"Invalid reported capacity: {text!r}")
    number = float(value.replace(",", ""))
    if not math.isfinite(number):
        raise ValueError("Non-finite capacity")
    return number


[docs] def parse_pib_bess_html(content: bytes) -> list[dict[str, Any]]: """Extract Table-II candidates, preserving MW/MWh and mixed project scopes. Supports identical mobile/desktop table copies without double counting. A changed header, conflicting duplicate, missing row or inconsistent total fails closed. No power is extracted from free text or hybrid solar ratings. """ parser = _Tables() parser.feed(content.decode("utf-8-sig")) header = ["Sl. No.", "Details of BESS Deployment", "State", "Capacity"] tables = [rows for rows in parser.tables if rows and rows[0] == header] if not tables: raise ValueError("PIB BESS table header not found; review source revision") accepted: list[dict[str, Any]] | None = None for table in tables: if len(table) < 4 or table[1] != ["MW", "MWh"]: raise ValueError("PIB capacity units changed") candidates: list[dict[str, Any]] = [] totals = None for cells in table[2:]: if "Total" in cells: if totals is not None: raise ValueError("Duplicate total") totals = [_capacity(v) for v in cells[-2:]] continue if len(cells) != 5 or not re.fullmatch(r"\d+\.", cells[0]): raise ValueError("Unexpected PIB row shape") row_number = int(cells[0][:-1]) if row_number != len(candidates) + 1 or not cells[1] or not cells[2]: raise ValueError("Missing/duplicate row number or identity text") candidates.append( { "source_row": row_number, "reported_description": cells[1], "reported_state": cells[2], "reported_power_mw": _capacity(cells[3]), "reported_energy_mwh": _capacity(cells[4]), "review_required": True, } ) if totals is None or any( not math.isclose(sum(r[key] for r in candidates), total, abs_tol=0.005) for key, total in zip(("reported_power_mw", "reported_energy_mwh"), totals, strict=True) ): raise ValueError("Missing or inconsistent PIB table totals") if accepted is not None and candidates != accepted: raise ValueError("Conflicting desktop/mobile PIB table copies") accepted = candidates assert accepted is not None return accepted