Source code for energy_data_retrieval.bess_oem_catalogue.rolls

"""Stage exact Rolls flooded-battery specifications from downloaded HTML.

Offline, bounded factual extraction only. No crawling, inferred energy/power,
canonical IDs, warranty adjudication or automatic family/variant merging.
"""

from __future__ import annotations

import hashlib
import re
from html.parser import HTMLParser
from typing import Any
from urllib.parse import urlsplit


class _Tables(HTMLParser):
    def __init__(self) -> None:
        super().__init__(convert_charrefs=True)
        self.rows: list[list[str]] = []
        self.row: list[str] | None = None
        self.cell: list[str] | None = None
        self.text: list[str] = []
        self.models: list[str] = []
        self.model_cell = False

    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
        if tag == "tr":
            self.row = []
        elif tag in {"th", "td"} and self.row is not None:
            self.cell = []
            self.model_cell = "battery-title-model" in (dict(attrs).get("class") or "").split()
        elif tag == "br" and self.cell is not None:
            self.cell.append(" ")

    def handle_data(self, data: str) -> None:
        self.text.append(data)
        if self.cell is not None:
            self.cell.append(data)

    def handle_endtag(self, tag: str) -> None:
        if tag in {"th", "td"} and self.cell is not None and self.row is not None:
            value = " ".join("".join(self.cell).split())
            self.row.append(value)
            if self.model_cell:
                self.models.append(value)
            self.cell = None
            self.model_cell = False
        elif tag == "tr" and self.row is not None:
            self.rows.append(self.row)
            self.row = None


def _number(text: str, unit: str) -> float:
    match = re.fullmatch(r"([0-9]+(?:[.][0-9]+)?)\s*" + re.escape(unit), text)
    if not match or float(match[1]) <= 0:
        raise ValueError(f"Expected positive {unit!r} value, got {text!r}")
    return float(match[1])


[docs] def parse_rolls_flooded_html( content: bytes, *, source_url: str, expected_model: str ) -> dict[str, Any]: """Stage one reviewed model, preserving rate-dependent Ah and charge units. The caller must choose a renewable-energy model from the OEM index and review identity, revision and conditions. Fail on renamed models, duplicate labels, absent core rows or changed units; never repair units from magnitude. """ url = urlsplit(source_url) if ( url.scheme != "https" or url.hostname not in {"rollsbattery.com", "www.rollsbattery.com"} or not url.path.startswith("/battery/") ): raise ValueError("Expected an official Rolls battery product URL") parser = _Tables() parser.feed(content.decode("utf-8-sig")) if parser.models != [expected_model]: raise ValueError("Exact model identity changed or duplicated") text = " ".join(" ".join(parser.text).split()) if "FLOODED DEEP CYCLE BATTERY" not in text: raise ValueError("Unsupported battery technology") labels = { "Series", "Warranty", "Volts", "Cells", "Plates/Cell", "Design", "Terminal Type", "Size & Thread", "Charge Voltage Range", "Float Voltage Range", "Recommended Charge Current", "Maximum Charge Current", "Self-Discharge Rate", "Weight", "Length", "Width", "Height Incl. Term.", "Container", "Cover", "Electrolyte Reserve", } values: dict[str, str] = {} rates = [] seen_rates = set() for row_number, row in enumerate(parser.rows, 1): for i, cell in enumerate(row[:-1]): if cell in labels: if cell in values: raise ValueError(f"Duplicate label: {cell}") values[cell] = row[i + 1] if row and row[0].startswith("@ "): match = re.fullmatch(r"@ ([0-9]+) Hour Rate", row[0]) if not match or len(row) != 3: raise ValueError("Changed hour-rate row") hours = int(match[1]) if hours in seen_rates or hours <= 0: raise ValueError("Duplicate or invalid hour rate") seen_rates.add(hours) rates.append( { "hours": hours, "capacity_ah": _number(row[1], "AH"), "current_a": _number(row[2], "A"), "table_row": row_number, } ) required = { "Series", "Volts", "Cells", "Charge Voltage Range", "Weight", "Length", "Width", "Height Incl. Term.", } if not required <= values.keys() or not {20, 100} <= seen_rates: raise ValueError("Missing required technical facts or rate conditions") revision = re.search(r"Rev\.#\d+\s*\|\s*[A-Za-z]+ \d{4}", text) if not revision: raise ValueError("Missing printed revision") return { "model": expected_model, "source_url": source_url, "source_sha256": hashlib.sha256(content).hexdigest(), "document_revision": revision[0], "reported_fields": values, "voltage_v": _number(values["Volts"], ""), "cells": _number(values["Cells"], ""), "length_mm": _number(values["Length"], "mm"), "width_mm": _number(values["Width"], "mm"), "height_including_terminals_mm": _number(values["Height Incl. Term."], "mm"), "sample_mass_kg": _number(values["Weight"], "kg"), "recommended_charge_current_a": ( _number(values["Recommended Charge Current"], "A") if "Recommended Charge Current" in values else None ), "maximum_charge_current_a": ( _number(values["Maximum Charge Current"], "A") if "Maximum Charge Current" in values else None ), "discharge_rates": rates, "review_required": True, }