switch2 0.1.2__tar.gz → 0.2.0__tar.gz

{switch2-0.1.2 → switch2-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: switch2
-Version: 0.1.2
+Version: 0.2.0
 Summary: Async client library for the Switch2 energy portal
 Author-email: Jelmer Vernooij <jelmer@jelmer.uk>
 License-Expression: Apache-2.0
@@ -38,20 +38,39 @@ import asyncio
 from switch2 import Switch2ApiClient
 
 async def main():
-    client = Switch2ApiClient("you@example.com", "your-password")
-    try:
+    async with Switch2ApiClient("you@example.com", "your-password") as client:
         data = await client.fetch_data()
         print(f"Customer: {data.customer.name}")
+        if data.account_balance is not None:
+            print(f"Balance: £{data.account_balance.balance}")
         for reading in data.readings:
             print(f"  {reading.date}: {reading.amount} {reading.unit}")
         for bill in data.bills:
             print(f"  {bill.date}: £{bill.amount}")
-    finally:
-        await client.close()
+            detail = await client.fetch_bill_detail(bill)
+            print(f"    invoice {detail.invoice_number}, total £{detail.total}")
 
 asyncio.run(main())
 ```
 
+All exceptions derive from `Switch2Error`. `Switch2AuthError` means the
+portal rejected the credentials; `Switch2ParseError` means a page did not
+look the way the parser expects, which usually means the portal changed.
+
+`data.readings` holds the readings of the register the portal selects by
+default; `data.register_readings` maps each register in `data.registers`
+to its readings.
+
+## Command line
+
+```sh
+SWITCH2_PASSWORD=... python -m switch2 you@example.com
+```
+
+prints what the portal reports. With `--dump-html DIR` it also saves every
+page it fetches, which is the easiest way to capture a page the parser gets
+wrong.
+
 ## License
 
 Apache-2.0

switch2-0.2.0/README.md

@@ -0,0 +1,53 @@
+# python-switch2
+
+Async Python client library for the [Switch2](https://my.switch2.co.uk) energy portal.
+
+## Installation
+
+```sh
+pip install switch2
+```
+
+## Usage
+
+```python
+import asyncio
+from switch2 import Switch2ApiClient
+
+async def main():
+    async with Switch2ApiClient("you@example.com", "your-password") as client:
+        data = await client.fetch_data()
+        print(f"Customer: {data.customer.name}")
+        if data.account_balance is not None:
+            print(f"Balance: £{data.account_balance.balance}")
+        for reading in data.readings:
+            print(f"  {reading.date}: {reading.amount} {reading.unit}")
+        for bill in data.bills:
+            print(f"  {bill.date}: £{bill.amount}")
+            detail = await client.fetch_bill_detail(bill)
+            print(f"    invoice {detail.invoice_number}, total £{detail.total}")
+
+asyncio.run(main())
+```
+
+All exceptions derive from `Switch2Error`. `Switch2AuthError` means the
+portal rejected the credentials; `Switch2ParseError` means a page did not
+look the way the parser expects, which usually means the portal changed.
+
+`data.readings` holds the readings of the register the portal selects by
+default; `data.register_readings` maps each register in `data.registers`
+to its readings.
+
+## Command line
+
+```sh
+SWITCH2_PASSWORD=... python -m switch2 you@example.com
+```
+
+prints what the portal reports. With `--dump-html DIR` it also saves every
+page it fetches, which is the easiest way to capture a page the parser gets
+wrong.
+
+## License
+
+Apache-2.0

{switch2-0.1.2 → switch2-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "switch2"
-version = "0.1.2"
+version = "0.2.0"
 description = "Async client library for the Switch2 energy portal"
 readme = "README.md"
 license = "Apache-2.0"
@@ -33,6 +33,9 @@ Homepage = "https://github.com/jelmer/python-switch2"
 Repository = "https://github.com/jelmer/python-switch2"
 Issues = "https://github.com/jelmer/python-switch2/issues"
 
+[tool.setuptools.package-data]
+switch2 = ["py.typed"]
+
 [tool.mypy]
 packages = ["switch2"]
 strict = true

{switch2-0.1.2 → switch2-0.2.0}/switch2/__init__.py

@@ -11,6 +11,8 @@ from .api import (
     Switch2AuthError,
     Switch2ConnectionError,
     Switch2Data,
+    Switch2Error,
+    Switch2ParseError,
 )
 
 __all__ = [
@@ -24,4 +26,6 @@ __all__ = [
     "Switch2AuthError",
     "Switch2ConnectionError",
     "Switch2Data",
+    "Switch2Error",
+    "Switch2ParseError",
 ]

switch2-0.2.0/switch2/__main__.py

@@ -0,0 +1,75 @@
+"""Print what the Switch2 portal reports for an account.
+
+Usage: python -m switch2 [--dump-html DIR] EMAIL
+
+The password is read from $SWITCH2_PASSWORD, or prompted for.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import getpass
+import os
+from collections.abc import Callable
+from pathlib import Path
+from urllib.parse import urlparse
+
+from .api import Switch2ApiClient
+
+
+def _page_saver(directory: Path) -> Callable[[str, str], None]:
+    counts: dict[str, int] = {}
+
+    def save(url: str, html: str) -> None:
+        name = urlparse(url).path.strip("/").replace("/", "_") or "index"
+        counts[name] = counts.get(name, 0) + 1
+        path = directory / f"{name}-{counts[name]}.html"
+        path.write_text(html)
+        print(f"Saved {url} to {path}")
+
+    return save
+
+
+async def _run(email: str, password: str, dump_dir: Path | None) -> None:
+    on_page: Callable[[str, str], None] | None = None
+    if dump_dir is not None:
+        dump_dir.mkdir(parents=True, exist_ok=True)
+        on_page = _page_saver(dump_dir)
+
+    async with Switch2ApiClient(email, password, on_page=on_page) as client:
+        data = await client.fetch_data()
+        print(f"Customer: {data.customer}")
+        print(f"Account balance: {data.account_balance}")
+        for register_id, name in data.registers.items():
+            readings = data.register_readings.get(register_id, [])
+            print(f"Register {register_id} ({name}): {len(readings)} readings")
+            for reading in readings[:3]:
+                print(f"  {reading}")
+        print(f"Bills: {len(data.bills)}")
+        if data.bills:
+            print(f"Latest bill: {data.bills[0]}")
+            detail = await client.fetch_bill_detail(data.bills[0])
+            for charge in detail.consumption_charges:
+                print(f"  consumption: {charge}")
+            for charge in detail.other_charges:
+                print(f"  other: {charge}")
+            print(f"  total excl. VAT: {detail.total_excl_vat}, VAT: {detail.vat}")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="python -m switch2")
+    parser.add_argument("email")
+    parser.add_argument(
+        "--dump-html",
+        type=Path,
+        metavar="DIR",
+        help="save every page fetched to DIR",
+    )
+    args = parser.parse_args()
+    password = os.environ.get("SWITCH2_PASSWORD") or getpass.getpass()
+    asyncio.run(_run(args.email, password, args.dump_html))
+
+
+if __name__ == "__main__":
+    main()

{switch2-0.1.2 → switch2-0.2.0}/switch2/api.py

@@ -3,8 +3,10 @@
 from __future__ import annotations
 
 import logging
-from dataclasses import dataclass
+from collections.abc import Callable
+from dataclasses import dataclass, field
 from datetime import datetime
+from types import TracebackType
 
 import aiohttp
 from bs4 import BeautifulSoup, Tag
@@ -16,15 +18,25 @@ LOGIN_URL = f"{BASE_URL}/Login"
 METER_HISTORY_URL = f"{BASE_URL}/MeterReadings/History"
 BILL_HISTORY_URL = f"{BASE_URL}/Credit/BillHistory"
 
+DEFAULT_TIMEOUT = aiohttp.ClientTimeout(total=60)
 
-class Switch2AuthError(Exception):
-    """Raised when authentication fails."""
 
+class Switch2Error(Exception):
+    """Base class for errors raised by this library."""
 
-class Switch2ConnectionError(Exception):
+
+class Switch2AuthError(Switch2Error):
+    """Raised when the portal rejects the credentials."""
+
+
+class Switch2ConnectionError(Switch2Error):
     """Raised when a connection error occurs."""
 
 
+class Switch2ParseError(Switch2Error):
+    """Raised when a portal page does not have the expected structure."""
+
+
 @dataclass
 class CustomerInfo:
     """Customer information from the Switch2 portal."""
@@ -61,6 +73,20 @@ class BillCharge:
     units: str
     charge: float
 
+    @property
+    def quantity(self) -> float | None:
+        """The number of units charged for, e.g. 252.0 for "252 kWh"."""
+        try:
+            return float(self.units.split()[0].replace(",", ""))
+        except (IndexError, ValueError):
+            return None
+
+    @property
+    def unit(self) -> str:
+        """The unit charged for, e.g. "kWh" for "252 kWh"."""
+        parts = self.units.split(maxsplit=1)
+        return parts[1] if len(parts) > 1 else ""
+
 
 @dataclass
 class BillDetail:
@@ -94,10 +120,13 @@ class Switch2Data:
     """All data fetched from the Switch2 portal."""
 
     customer: CustomerInfo
+    # Readings for the register the portal selects by default.
     readings: list[MeterReading]
     registers: dict[str, str]  # register_id -> register_name
     bills: list[Bill]
     account_balance: AccountBalance | None
+    # register_id -> readings, newest first
+    register_readings: dict[str, list[MeterReading]] = field(default_factory=dict)
 
 
 def _get_attr(tag: Tag, attr: str, default: str = "") -> str:
@@ -111,14 +140,26 @@ def _get_attr(tag: Tag, attr: str, default: str = "") -> str:
 class Switch2ApiClient:
     """Client to interact with the Switch2 web portal."""
 
-    def __init__(self, email: str, password: str) -> None:
+    def __init__(
+        self,
+        email: str,
+        password: str,
+        on_page: Callable[[str, str], None] | None = None,
+    ) -> None:
+        """Create a client.
+
+        ``on_page`` is called with the URL and HTML of every page fetched,
+        which is useful for capturing pages when the parser falls behind
+        changes to the portal.
+        """
         self._email = email
         self._password = password
+        self._on_page = on_page
         self._session: aiohttp.ClientSession | None = None
 
     async def _ensure_session(self) -> aiohttp.ClientSession:
         if self._session is None or self._session.closed:
-            self._session = aiohttp.ClientSession()
+            self._session = aiohttp.ClientSession(timeout=DEFAULT_TIMEOUT)
         return self._session
 
     async def close(self) -> None:
@@ -126,51 +167,55 @@ class Switch2ApiClient:
         if self._session and not self._session.closed:
             await self._session.close()
 
-    async def authenticate(self) -> tuple[CustomerInfo, BeautifulSoup]:
-        """Log in to the Switch2 portal and return customer info and dashboard soup."""
+    async def __aenter__(self) -> "Switch2ApiClient":
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.close()
+
+    async def _fetch(
+        self, url: str, what: str, data: dict[str, str] | None = None
+    ) -> BeautifulSoup:
+        """GET (or with ``data``, POST to) a page and parse it."""
         session = await self._ensure_session()
-
         try:
-            # Step 1: GET the login page to get any CSRF tokens
-            async with session.get(LOGIN_URL) as resp:
-                if resp.status != 200:
-                    raise Switch2ConnectionError(
-                        f"Failed to load login page: HTTP {resp.status}"
-                    )
-                html = await resp.text()
-
-            soup = BeautifulSoup(html, "html.parser")
-            token_input = soup.select_one('input[name="__RequestVerificationToken"]')
-            form_data: dict[str, str] = {}
-            if token_input:
-                form_data["__RequestVerificationToken"] = _get_attr(
-                    token_input, "value"
-                )
-
-            # Step 2: POST login credentials
-            form_data["UserName"] = self._email
-            form_data["Password"] = self._password
-
-            async with session.post(
-                LOGIN_URL, data=form_data, allow_redirects=True
-            ) as resp:
+            if data is None:
+                request = session.get(url)
+            else:
+                request = session.post(url, data=data, allow_redirects=True)
+            async with request as resp:
                 if resp.status != 200:
                     raise Switch2ConnectionError(
-                        f"Login request failed: HTTP {resp.status}"
+                        f"Failed to load {what}: HTTP {resp.status}"
                     )
                 html = await resp.text()
-
-            soup = BeautifulSoup(html, "html.parser")
-            customer = _parse_customer_info(soup)
-            if not customer.name:
-                raise Switch2AuthError("Login failed: no customer info returned")
-
-            return customer, soup
-
         except aiohttp.ClientError as err:
             raise Switch2ConnectionError(
-                f"Connection error during login: {err}"
+                f"Connection error loading {what}: {err}"
             ) from err
+        if self._on_page is not None:
+            self._on_page(url, html)
+        return BeautifulSoup(html, "html.parser")
+
+    async def authenticate(self) -> tuple[CustomerInfo, BeautifulSoup]:
+        """Log in to the Switch2 portal and return customer info and dashboard soup."""
+        soup = await self._fetch(LOGIN_URL, "login page")
+        form_data = _form_token(soup)
+        form_data["UserName"] = self._email
+        form_data["Password"] = self._password
+
+        soup = await self._fetch(LOGIN_URL, "login response", form_data)
+        if soup.select_one('input[name="Password"]') is not None:
+            raise Switch2AuthError("Login rejected by the Switch2 portal")
+        customer = _parse_customer_info(soup)
+        if not customer.name:
+            raise Switch2ParseError("No customer info on the page after logging in")
+        return customer, soup
 
     async def fetch_bill_detail(self, bill: Bill) -> BillDetail:
         """Fetch and parse the detail page for a bill.
@@ -179,90 +224,72 @@ class Switch2ApiClient:
         """
         if not bill.detail_url:
             raise ValueError("Bill has no detail URL")
-        session = await self._ensure_session()
+        soup = await self._fetch(bill.detail_url, "bill detail")
         try:
-            async with session.get(bill.detail_url) as resp:
-                if resp.status != 200:
-                    raise Switch2ConnectionError(
-                        f"Failed to load bill detail: HTTP {resp.status}"
-                    )
-                html = await resp.text()
-        except aiohttp.ClientError as err:
-            raise Switch2ConnectionError(
-                f"Connection error fetching bill detail: {err}"
+            return _parse_bill_detail(soup)
+        except ValueError as err:
+            raise Switch2ParseError(
+                f"Unrecognised bill detail page {bill.detail_url}: {err}"
             ) from err
-        return _parse_bill_detail(BeautifulSoup(html, "html.parser"))
 
     async def fetch_data(self) -> Switch2Data:
         """Authenticate and fetch all meter data."""
         customer, dashboard_soup = await self.authenticate()
         account_balance = _parse_account_balance(dashboard_soup)
-        session = await self._ensure_session()
 
-        try:
-            # GET meter readings history page
-            async with session.get(METER_HISTORY_URL) as resp:
-                if resp.status != 200:
-                    raise Switch2ConnectionError(
-                        f"Failed to load meter history: HTTP {resp.status}"
-                    )
-                html = await resp.text()
-
-            soup = BeautifulSoup(html, "html.parser")
-
-            # Parse available registers
-            registers: dict[str, str] = {}
-            register_select = soup.select_one("#RegisterId")
-            if register_select:
-                for option in register_select.select("option"):
-                    reg_id = option.get("value", "")
-                    if reg_id:
-                        registers[str(reg_id)] = option.text.strip()
-
-            # Try to get all readings by POSTing with a large page size
-            token_input = soup.select_one('input[name="__RequestVerificationToken"]')
-            selected_register = soup.select_one("#RegisterId option[selected]")
-
-            if token_input and selected_register:
-                form_data = {
-                    "__RequestVerificationToken": _get_attr(token_input, "value"),
-                    "Page": "1",
-                    "TotalPages": "1",
-                    "RegisterId": _get_attr(selected_register, "value"),
-                    "PageSize": "1000000",
-                }
-
-                async with session.post(
-                    METER_HISTORY_URL, data=form_data, allow_redirects=True
-                ) as resp:
-                    if resp.status == 200:
-                        html = await resp.text()
-                        soup = BeautifulSoup(html, "html.parser")
+        soup = await self._fetch(METER_HISTORY_URL, "meter history")
+        registers: dict[str, str] = {}
+        register_select = soup.select_one("#RegisterId")
+        if register_select:
+            for option in register_select.select("option"):
+                reg_id = _get_attr(option, "value")
+                if reg_id:
+                    registers[reg_id] = option.text.strip()
+
+        selected = soup.select_one("#RegisterId option[selected]")
+        selected_id = _get_attr(selected, "value") if selected else ""
+        token = _form_token(soup)
+
+        register_readings: dict[str, list[MeterReading]] = {}
+        if token:
+            for register_id in registers:
+                # Ask for everything on a single page.
+                history = await self._fetch(
+                    METER_HISTORY_URL,
+                    f"meter history for register {register_id}",
+                    {
+                        **token,
+                        "Page": "1",
+                        "TotalPages": "1",
+                        "RegisterId": register_id,
+                        "PageSize": "1000000",
+                    },
+                )
+                register_readings[register_id] = _parse_readings(history)
 
+        if selected_id in register_readings:
+            readings = register_readings[selected_id]
+        else:
             readings = _parse_readings(soup)
 
-            # Fetch bill history
-            async with session.get(BILL_HISTORY_URL) as resp:
-                if resp.status != 200:
-                    raise Switch2ConnectionError(
-                        f"Failed to load bill history: HTTP {resp.status}"
-                    )
-                html = await resp.text()
+        bills = _parse_bills(await self._fetch(BILL_HISTORY_URL, "bill history"))
 
-            bills = _parse_bills(BeautifulSoup(html, "html.parser"))
+        return Switch2Data(
+            customer=customer,
+            readings=readings,
+            registers=registers,
+            bills=bills,
+            account_balance=account_balance,
+            register_readings=register_readings,
+        )
 
-            return Switch2Data(
-                customer=customer,
-                readings=readings,
-                registers=registers,
-                bills=bills,
-                account_balance=account_balance,
-            )
 
-        except aiohttp.ClientError as err:
-            raise Switch2ConnectionError(
-                f"Connection error fetching data: {err}"
-            ) from err
+def _form_token(soup: BeautifulSoup) -> dict[str, str]:
+    """Return the anti-forgery token of the form on a page, if it has one."""
+    token_input = soup.select_one('input[name="__RequestVerificationToken"]')
+    if token_input is None:
+        return {}
+    return {"__RequestVerificationToken": _get_attr(token_input, "value")}
 
 
 def _parse_date(text: str) -> datetime:
@@ -375,6 +402,30 @@ def _parse_account_balance(soup: BeautifulSoup) -> AccountBalance | None:
     return AccountBalance(balance=balance, last_updated=last_updated)
 
 
+def _has_class(tag: Tag, class_name: str) -> bool:
+    """Return True if the tag has the given CSS class."""
+    classes = tag.get("class")
+    if classes is None:
+        return False
+    if isinstance(classes, str):
+        return class_name in classes.split()
+    return class_name in classes
+
+
+def _parse_charge_row(row: Tag) -> BillCharge | None:
+    """Parse a single .bill-table-row into a BillCharge, or None if incomplete."""
+    desc_el = row.select_one(".bill-table-row-item-left")
+    units_el = row.select_one(".bill-table-row-item")
+    charge_el = row.select_one(".bill-table-row-item-right")
+    if not desc_el or not charge_el:
+        return None
+    return BillCharge(
+        description=desc_el.text.strip(),
+        units=units_el.text.strip() if units_el else "",
+        charge=_parse_currency(charge_el.text),
+    )
+
+
 def _parse_bill_charges(
     soup: BeautifulSoup, container_selector: str
 ) -> list[BillCharge]:
@@ -382,20 +433,51 @@ def _parse_bill_charges(
     charges: list[BillCharge] = []
     rows = soup.select(f"{container_selector} .bill-table-row-desktop .bill-table-row")
     for row in rows:
-        desc_el = row.select_one(".bill-table-row-item-left")
-        units_el = row.select_one(".bill-table-row-item")
-        charge_el = row.select_one(".bill-table-row-item-right")
-        if desc_el and charge_el:
-            charges.append(
-                BillCharge(
-                    description=desc_el.text.strip(),
-                    units=units_el.text.strip() if units_el else "",
-                    charge=_parse_currency(charge_el.text),
-                )
-            )
+        charge = _parse_charge_row(row)
+        if charge is not None:
+            charges.append(charge)
     return charges
 
 
+def _parse_keyed_currency_rows(
+    container: Tag | None,
+    fields: dict[str, Callable[[str], bool]],
+) -> dict[str, float]:
+    """Parse .bill-total-table-row rows, matching labels to keys via predicates.
+
+    Returns a mapping for each predicate that matched a row; missing keys are
+    logged at warning level so silent zeros don't hide upstream HTML changes.
+    """
+    found: dict[str, float] = {}
+    if container is None:
+        for key in fields:
+            _LOGGER.warning("Missing expected bill-total field: %s", key)
+        return found
+    for row in container.select(".bill-total-table-row"):
+        label_el = row.select_one(".bill-total-table-row-item-left")
+        value_el = row.select_one(".bill-total-table-row-item-right")
+        if not label_el or not value_el:
+            continue
+        label = label_el.text.strip()
+        for key, matches in fields.items():
+            if key not in found and matches(label):
+                found[key] = _parse_currency(value_el.text)
+                break
+    for key in fields:
+        if key not in found:
+            _LOGGER.warning("Missing expected bill-total field: %s", key)
+    return found
+
+
+def _parse_currency_header(soup: BeautifulSoup, selector: str, name: str) -> float:
+    """Parse a single currency value from a header selector, defaulting to 0.0."""
+    el = soup.select_one(selector)
+    if el is None:
+        _LOGGER.warning("Missing expected %s header", name)
+        return 0.0
+    return _parse_currency(el.text)
+
+
 def _parse_bill_detail(soup: BeautifulSoup) -> BillDetail:
     """Extract bill detail from the bill detail page."""
     # Header: invoice number and date of issue
@@ -437,110 +519,81 @@ def _parse_bill_detail(soup: BeautifulSoup) -> BillDetail:
         soup, "#BillItemsContainer > .bill-table-row:first-of-type"
     )
     # If the CSS child selector doesn't match, fall back to looking at
-    # desktop rows that come before .other-charges-table-row
+    # desktop rows that come before .other-charges-table-row.
     if not consumption_charges:
         items_container = soup.select_one("#BillItemsContainer")
         if items_container:
-            consumption_rows: list[Tag] = []
             for child in items_container.children:
                 if not isinstance(child, Tag):
                     continue
-                if "other-charges-table-row" in child.get("class", []):
+                if _has_class(child, "other-charges-table-row"):
                     break
-                desktop = child.select_one(".bill-table-row-desktop .bill-table-row")
-                if desktop:
-                    consumption_rows.append(desktop)
-                elif "bill-table-row-desktop" in child.get("class", []):
-                    inner = child.select_one(".bill-table-row")
-                    if inner:
-                        consumption_rows.append(inner)
-            for row in consumption_rows:
-                desc_el = row.select_one(".bill-table-row-item-left")
-                units_el = row.select_one(".bill-table-row-item")
-                charge_el = row.select_one(".bill-table-row-item-right")
-                if desc_el and charge_el:
-                    consumption_charges.append(
-                        BillCharge(
-                            description=desc_el.text.strip(),
-                            units=(units_el.text.strip() if units_el else ""),
-                            charge=_parse_currency(charge_el.text),
-                        )
-                    )
-
-    # Other charges
+                desktop_row = child.select_one(
+                    ".bill-table-row-desktop .bill-table-row"
+                )
+                if desktop_row is None and _has_class(child, "bill-table-row-desktop"):
+                    desktop_row = child.select_one(".bill-table-row")
+                if desktop_row is not None:
+                    charge = _parse_charge_row(desktop_row)
+                    if charge is not None:
+                        consumption_charges.append(charge)
+
+    # Other charges: desktop rows that follow the .other-charges-table-row header,
+    # stopping at the first sibling that isn't a desktop or narrow row.
     other_charges: list[BillCharge] = []
     other_header = soup.select_one(".other-charges-table-row")
     if other_header:
         sibling = other_header.next_sibling
         while sibling:
             if isinstance(sibling, Tag):
-                if "bill-table-row-desktop" in sibling.get("class", []):
+                if _has_class(sibling, "bill-table-row-desktop"):
                     charge_row = sibling.select_one(".bill-table-row")
-                    if charge_row:
-                        desc_el = charge_row.select_one(".bill-table-row-item-left")
-                        units_el = charge_row.select_one(".bill-table-row-item")
-                        charge_el = charge_row.select_one(".bill-table-row-item-right")
-                        if desc_el and charge_el:
-                            other_charges.append(
-                                BillCharge(
-                                    description=desc_el.text.strip(),
-                                    units=(units_el.text.strip() if units_el else ""),
-                                    charge=_parse_currency(charge_el.text),
-                                )
-                            )
-                elif "bill-table-row-narrow" not in sibling.get("class", []):
+                    if charge_row is not None:
+                        charge = _parse_charge_row(charge_row)
+                        if charge is not None:
+                            other_charges.append(charge)
+                elif not _has_class(sibling, "bill-table-row-narrow"):
                     break
             sibling = sibling.next_sibling
 
-    # Totals
-    totals_container = soup.select_one("#BillTotalsCollapsibleContent")
-    total_excl_vat = 0.0
-    vat = 0.0
-    total_rows = (
-        totals_container.select(".bill-total-table-row") if totals_container else []
+    # Totals. Defaults to 0.0 stay for backwards compatibility with callers, but
+    # log when an expected field is missing so problems aren't completely silent.
+    totals = _parse_keyed_currency_rows(
+        soup.select_one("#BillTotalsCollapsibleContent"),
+        {
+            "total_excl_vat": lambda label: label.startswith(
+                "Total charges excluding VAT"
+            ),
+            "vat": lambda label: label.startswith("VAT"),
+        },
     )
-    for row in total_rows:
-        label_el = row.select_one(".bill-total-table-row-item-left")
-        value_el = row.select_one(".bill-total-table-row-item-right")
-        if label_el and value_el:
-            label = label_el.text.strip()
-            if label.startswith("Total charges excluding VAT"):
-                total_excl_vat = _parse_currency(value_el.text)
-            elif label.startswith("VAT"):
-                vat = _parse_currency(value_el.text)
+    total_excl_vat = totals.get("total_excl_vat", 0.0)
+    vat = totals.get("vat", 0.0)
 
     # Bill total from the collapsible header
-    total = 0.0
-    total_header = soup.select_one(
-        "#BillTotalsContainer > .collapsible-header .bill-total-table-row-item-right"
+    total = _parse_currency_header(
+        soup,
+        "#BillTotalsContainer > .collapsible-header .bill-total-table-row-item-right",
+        "bill total",
     )
-    if total_header:
-        total = _parse_currency(total_header.text)
 
     # Account balance
-    balance_container = soup.select_one("#AccountBalanceCollapsibleContent")
-    previous_balance = 0.0
-    payments_received = 0.0
-    balance_rows = (
-        balance_container.select(".bill-total-table-row") if balance_container else []
+    balances = _parse_keyed_currency_rows(
+        soup.select_one("#AccountBalanceCollapsibleContent"),
+        {
+            "previous_balance": lambda label: label == "Previous account balance",
+            "payments_received": lambda label: label == "Payments received",
+        },
     )
-    for row in balance_rows:
-        label_el = row.select_one(".bill-total-table-row-item-left")
-        value_el = row.select_one(".bill-total-table-row-item-right")
-        if label_el and value_el:
-            label = label_el.text.strip()
-            if label == "Previous account balance":
-                previous_balance = _parse_currency(value_el.text)
-            elif label == "Payments received":
-                payments_received = _parse_currency(value_el.text)
-
-    balance = 0.0
-    balance_header = soup.select_one(
+    previous_balance = balances.get("previous_balance", 0.0)
+    payments_received = balances.get("payments_received", 0.0)
+
+    balance = _parse_currency_header(
+        soup,
         "#AccountBalanceContainer > .collapsible-header"
-        " .bill-total-table-row-item-right"
+        " .bill-total-table-row-item-right",
+        "account balance",
     )
-    if balance_header:
-        balance = _parse_currency(balance_header.text)
 
     # Download URL
     download_url = ""

{switch2-0.1.2 → switch2-0.2.0}/switch2.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: switch2
-Version: 0.1.2
+Version: 0.2.0
 Summary: Async client library for the Switch2 energy portal
 Author-email: Jelmer Vernooij <jelmer@jelmer.uk>
 License-Expression: Apache-2.0
@@ -38,20 +38,39 @@ import asyncio
 from switch2 import Switch2ApiClient
 
 async def main():
-    client = Switch2ApiClient("you@example.com", "your-password")
-    try:
+    async with Switch2ApiClient("you@example.com", "your-password") as client:
         data = await client.fetch_data()
         print(f"Customer: {data.customer.name}")
+        if data.account_balance is not None:
+            print(f"Balance: £{data.account_balance.balance}")
         for reading in data.readings:
             print(f"  {reading.date}: {reading.amount} {reading.unit}")
         for bill in data.bills:
             print(f"  {bill.date}: £{bill.amount}")
-    finally:
-        await client.close()
+            detail = await client.fetch_bill_detail(bill)
+            print(f"    invoice {detail.invoice_number}, total £{detail.total}")
 
 asyncio.run(main())
 ```
 
+All exceptions derive from `Switch2Error`. `Switch2AuthError` means the
+portal rejected the credentials; `Switch2ParseError` means a page did not
+look the way the parser expects, which usually means the portal changed.
+
+`data.readings` holds the readings of the register the portal selects by
+default; `data.register_readings` maps each register in `data.registers`
+to its readings.
+
+## Command line
+
+```sh
+SWITCH2_PASSWORD=... python -m switch2 you@example.com
+```
+
+prints what the portal reports. With `--dump-html DIR` it also saves every
+page it fetches, which is the easiest way to capture a page the parser gets
+wrong.
+
 ## License
 
 Apache-2.0

{switch2-0.1.2 → switch2-0.2.0}/switch2.egg-info/SOURCES.txt

@@ -1,7 +1,9 @@
 README.md
 pyproject.toml
 switch2/__init__.py
+switch2/__main__.py
 switch2/api.py
+switch2/py.typed
 switch2.egg-info/PKG-INFO
 switch2.egg-info/SOURCES.txt
 switch2.egg-info/dependency_links.txt

{switch2-0.1.2 → switch2-0.2.0}/tests/test_api.py

@@ -1,11 +1,17 @@
 """Tests for the Switch2 API client."""
 
+import asyncio
 import unittest
 from datetime import datetime
 
 from bs4 import BeautifulSoup
 
 from switch2.api import (
+    Bill,
+    BillCharge,
+    Switch2ApiClient,
+    Switch2AuthError,
+    Switch2ParseError,
     _parse_account_balance,
     _parse_bill_detail,
     _parse_bills,
@@ -353,6 +359,15 @@ class ParseBillDetailTests(unittest.TestCase):
         )
 
 
+class ClientContextManagerTests(unittest.TestCase):
+    def test_aclose_without_session(self) -> None:
+        async def run() -> None:
+            async with Switch2ApiClient("e", "p") as client:
+                self.assertIsNone(client._session)
+
+        asyncio.run(run())
+
+
 class ParseAccountBalanceTests(unittest.TestCase):
     def test_balance_from_dashboard(self) -> None:
         html = """
@@ -391,3 +406,145 @@ class ParseAccountBalanceTests(unittest.TestCase):
     def test_no_balance_element(self) -> None:
         soup = BeautifulSoup("<div></div>", "html.parser")
         self.assertIsNone(_parse_account_balance(soup))
+
+
+class BillChargeTests(unittest.TestCase):
+    def test_kwh(self) -> None:
+        charge = BillCharge("Heat", "252 kWh", 42.87)
+        self.assertEqual(charge.quantity, 252.0)
+        self.assertEqual(charge.unit, "kWh")
+
+    def test_days(self) -> None:
+        charge = BillCharge("Heat Standing Charge", "30.00 days", 22.46)
+        self.assertEqual(charge.quantity, 30.0)
+        self.assertEqual(charge.unit, "days")
+
+    def test_thousands(self) -> None:
+        self.assertEqual(BillCharge("Heat", "1,234 kWh", 1.0).quantity, 1234.0)
+
+    def test_no_units(self) -> None:
+        charge = BillCharge("Adjustment", "", -3.0)
+        self.assertIsNone(charge.quantity)
+        self.assertEqual(charge.unit, "")
+
+
+LOGIN_FORM = """
+<form>
+  <input name="__RequestVerificationToken" value="tok">
+  <input name="UserName"><input name="Password" type="password">
+</form>
+"""
+
+DASHBOARD = """
+<span class="customer-info-name">John Doe</span>
+<span class="customer-info-account-number">ACC-123</span>
+<span class="customer-info-address">42 Test Lane</span>
+"""
+
+METER_HISTORY = """
+<form>
+  <input name="__RequestVerificationToken" value="tok2">
+  <select id="RegisterId">
+    <option value="R1" selected>Heat Meter</option>
+    <option value="R2">Hot Water Meter</option>
+  </select>
+</form>
+"""
+
+
+def _reading_row(date: str, amount: str) -> str:
+    return f"""
+    <div class="meter-reading-history-table-data-row desktop-layout">
+      <div class="meter-reading-history-table-data-date-row-item">{date}</div>
+      <div class="meter-reading-history-table-data-amount-row-item">{amount}</div>
+      <div class="meter-reading-history-table-data-type-row-item">Actual</div>
+    </div>
+    """
+
+
+class FakePortal:
+    """Serves canned pages in place of Switch2ApiClient._fetch."""
+
+    def __init__(self, login_response: str) -> None:
+        self.login_response = login_response
+        self.posts: list[tuple[str, dict[str, str]]] = []
+
+    async def __call__(
+        self, url: str, what: str, data: dict[str, str] | None = None
+    ) -> BeautifulSoup:
+        if data is not None:
+            self.posts.append((url, data))
+        if url.endswith("/Login"):
+            html = LOGIN_FORM if data is None else self.login_response
+        elif url.endswith("/MeterReadings/History"):
+            if data is None:
+                html = METER_HISTORY
+            elif data["RegisterId"] == "R1":
+                html = _reading_row("26th October 2026", "9166 kWh")
+            else:
+                html = _reading_row("26th October 2026", "512 kWh")
+        elif url.endswith("/Credit/BillHistory"):
+            html = "<div></div>"
+        else:
+            raise AssertionError(f"unexpected fetch of {url}")
+        return BeautifulSoup(html, "html.parser")
+
+
+def _client(portal: FakePortal) -> Switch2ApiClient:
+    client = Switch2ApiClient("e@example.com", "pw")
+    client._fetch = portal  # type: ignore[method-assign]
+    return client
+
+
+class AuthenticateTests(unittest.TestCase):
+    def test_success(self) -> None:
+        portal = FakePortal(DASHBOARD)
+        customer, _ = asyncio.run(_client(portal).authenticate())
+        self.assertEqual(customer.account_number, "ACC-123")
+        self.assertEqual(
+            portal.posts,
+            [
+                (
+                    "https://my.switch2.co.uk/Login",
+                    {
+                        "__RequestVerificationToken": "tok",
+                        "UserName": "e@example.com",
+                        "Password": "pw",
+                    },
+                )
+            ],
+        )
+
+    def test_rejected(self) -> None:
+        portal = FakePortal(LOGIN_FORM + "<p>Invalid login attempt.</p>")
+        with self.assertRaises(Switch2AuthError):
+            asyncio.run(_client(portal).authenticate())
+
+    def test_unrecognised_page(self) -> None:
+        portal = FakePortal("<p>Down for maintenance</p>")
+        with self.assertRaises(Switch2ParseError):
+            asyncio.run(_client(portal).authenticate())
+
+
+class FetchBillDetailTests(unittest.TestCase):
+    def test_unrecognised_page(self) -> None:
+        client = Switch2ApiClient("e", "p")
+
+        async def fetch(url: str, what: str) -> BeautifulSoup:
+            return BeautifulSoup("<p>Something else</p>", "html.parser")
+
+        client._fetch = fetch  # type: ignore[method-assign,assignment]
+        bill = Bill(datetime(2026, 10, 27), 104.03, "https://example/bill/1")
+        with self.assertRaises(Switch2ParseError):
+            asyncio.run(client.fetch_bill_detail(bill))
+
+
+class FetchDataTests(unittest.TestCase):
+    def test_readings_per_register(self) -> None:
+        data = asyncio.run(_client(FakePortal(DASHBOARD)).fetch_data())
+        self.assertEqual(data.registers, {"R1": "Heat Meter", "R2": "Hot Water Meter"})
+        self.assertEqual(
+            {r: [x.amount for x in v] for r, v in data.register_readings.items()},
+            {"R1": [9166.0], "R2": [512.0]},
+        )
+        self.assertEqual([x.amount for x in data.readings], [9166.0])

switch2-0.1.2/README.md

@@ -1,34 +0,0 @@
-# python-switch2
-
-Async Python client library for the [Switch2](https://my.switch2.co.uk) energy portal.
-
-## Installation
-
-```sh
-pip install switch2
-```
-
-## Usage
-
-```python
-import asyncio
-from switch2 import Switch2ApiClient
-
-async def main():
-    client = Switch2ApiClient("you@example.com", "your-password")
-    try:
-        data = await client.fetch_data()
-        print(f"Customer: {data.customer.name}")
-        for reading in data.readings:
-            print(f"  {reading.date}: {reading.amount} {reading.unit}")
-        for bill in data.bills:
-            print(f"  {bill.date}: £{bill.amount}")
-    finally:
-        await client.close()
-
-asyncio.run(main())
-```
-
-## License
-
-Apache-2.0