switch2 0.1.3__tar.gz → 0.2.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: switch2
-Version: 0.1.3
+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
@@ -53,6 +53,24 @@ async def main():
 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.3 → switch2-0.2.0}/README.md

@@ -30,6 +30,24 @@ async def main():
 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.3 → switch2-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "switch2"
-version = "0.1.3"
+version = "0.2.0"
 description = "Async client library for the Switch2 energy portal"
 readme = "README.md"
 license = "Apache-2.0"

{switch2-0.1.3 → 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.3 → switch2-0.2.0}/switch2/api.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import logging
 from collections.abc import Callable
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from datetime import datetime
 from types import TracebackType
 
@@ -21,14 +21,22 @@ 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."""
@@ -65,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:
@@ -98,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:
@@ -115,9 +140,21 @@ 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:
@@ -141,51 +178,44 @@ class Switch2ApiClient:
     ) -> None:
         await self.close()
 
-    async def authenticate(self) -> tuple[CustomerInfo, BeautifulSoup]:
-        """Log in to the Switch2 portal and return customer info and dashboard soup."""
+    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 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"Failed to load login page: HTTP {resp.status}"
+                        f"Failed to load {what}: 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 resp.status != 200:
-                    raise Switch2ConnectionError(
-                        f"Login request failed: 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.
@@ -194,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:

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: switch2
-Version: 0.1.3
+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
@@ -53,6 +53,24 @@ async def main():
 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.3 → switch2-0.2.0}/switch2.egg-info/SOURCES.txt

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

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

@@ -7,7 +7,11 @@ 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,
@@ -402,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])