Add full type annotations and black formatting across all modules

Annotated all functions with mypy --strict-compatible types (-> None, dict[str,
Any], Generator types, etc.), added # type: ignore for untyped third-party libs
(lxml), and reformatted with black. All 18 source files now pass mypy --strict
with zero errors.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

scraper/realtime_trains.py

@@ -7,9 +7,12 @@ Two fetches:
   PAD/from/BRI → arrival times at Paddington (div.time.plan.a)
 Matched by train ID (div.tid).
 """
+
 import re
+from typing import Any
+
 import httpx
-import lxml.html
+import lxml.html  # type: ignore[import-untyped]
 
 _TO_PAD_TMPL = (
     "https://www.realtimetrains.co.uk/search/detailed/"
@@ -38,7 +41,7 @@ DEFAULT_UA = (
 )
 
 
-def _browser_headers(user_agent: str) -> dict:
+def _browser_headers(user_agent: str) -> dict[str, str]:
     return {
         "User-Agent": user_agent,
         "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8",
@@ -55,7 +58,7 @@ def _browser_headers(user_agent: str) -> dict:
 
 def _fmt(hhmm: str) -> str:
     """Convert '0830' → '08:30'."""
-    hhmm = re.sub(r'[^0-9]', '', hhmm)
+    hhmm = re.sub(r"[^0-9]", "", hhmm)
     if len(hhmm) == 4:
         return f"{hhmm[:2]}:{hhmm[2:]}"
     return hhmm
@@ -64,12 +67,12 @@ def _fmt(hhmm: str) -> str:
 def _parse_services(html: str, time_selector: str) -> dict[str, str]:
     """Return {train_id: time_string} from a servicelist page."""
     root = lxml.html.fromstring(html)
-    sl = root.cssselect('div.servicelist')
+    sl = root.cssselect("div.servicelist")
     if not sl:
         return {}
     result = {}
-    for svc in sl[0].cssselect('a.service'):
-        tid_els  = svc.cssselect('div.tid')
+    for svc in sl[0].cssselect("a.service"):
+        tid_els = svc.cssselect("div.tid")
         time_els = svc.cssselect(time_selector)
         if tid_els and time_els:
             tid = tid_els[0].text_content().strip()
@@ -79,56 +82,58 @@ def _parse_services(html: str, time_selector: str) -> dict[str, str]:
     return result
 
 
-def _parse_arrivals(html: str) -> dict[str, dict]:
+def _parse_arrivals(html: str) -> dict[str, dict[str, str]]:
     """Return {train_id: {'time': ..., 'platform': ...}} from an arrivals page."""
     root = lxml.html.fromstring(html)
-    sl = root.cssselect('div.servicelist')
+    sl = root.cssselect("div.servicelist")
     if not sl:
         return {}
     result = {}
-    for svc in sl[0].cssselect('a.service'):
-        tid_els  = svc.cssselect('div.tid')
-        time_els = svc.cssselect('div.time.plan.a')
+    for svc in sl[0].cssselect("a.service"):
+        tid_els = svc.cssselect("div.tid")
+        time_els = svc.cssselect("div.time.plan.a")
         if not (tid_els and time_els):
             continue
         time_text = time_els[0].text_content().strip()
         if not time_text:
             continue
-        plat_els = svc.cssselect('div.platform')
-        platform = plat_els[0].text_content().strip() if plat_els else ''
+        plat_els = svc.cssselect("div.platform")
+        platform = plat_els[0].text_content().strip() if plat_els else ""
         result[tid_els[0].text_content().strip()] = {
-            'time': _fmt(time_text),
-            'platform': platform,
+            "time": _fmt(time_text),
+            "platform": platform,
         }
     return result
 
 
-def fetch(date: str, user_agent: str = DEFAULT_UA, station_crs: str = 'BRI') -> list[dict]:
+def fetch(
+    date: str, user_agent: str = DEFAULT_UA, station_crs: str = "BRI"
+) -> list[dict[str, Any]]:
     """Fetch trains from station_crs to PAD."""
     headers = _browser_headers(user_agent)
     with httpx.Client(headers=headers, follow_redirects=True, timeout=30) as client:
         r_bri = client.get(_TO_PAD_TMPL.format(crs=station_crs, date=date))
         r_pad = client.get(_PAD_FROM_TMPL.format(crs=station_crs, date=date))
 
-    departures = _parse_services(r_bri.text, 'div.time.plan.d')
-    arrivals   = _parse_arrivals(r_pad.text)
+    departures = _parse_services(r_bri.text, "div.time.plan.d")
+    arrivals = _parse_arrivals(r_pad.text)
 
     trains = [
         {
-            'depart_bristol': dep,
-            'arrive_paddington': arrivals[tid]['time'],
-            'arrive_platform': arrivals[tid]['platform'],
-            'headcode': tid,
+            "depart_bristol": dep,
+            "arrive_paddington": arrivals[tid]["time"],
+            "arrive_platform": arrivals[tid]["platform"],
+            "headcode": tid,
         }
         for tid, dep in departures.items()
         if tid in arrivals
     ]
-    return sorted(trains, key=lambda t: t['depart_bristol'])
+    return sorted(trains, key=lambda t: t["depart_bristol"])
 
 
 def fetch_to_paddington(
-    date: str, user_agent: str = DEFAULT_UA, station_crs: str = 'BRI'
-) -> list[dict]:
+    date: str, user_agent: str = DEFAULT_UA, station_crs: str = "BRI"
+) -> list[dict[str, Any]]:
     """Fetch trains from station_crs to PAD using generic field names."""
     return [
         {
@@ -143,15 +148,15 @@ def fetch_to_paddington(
 
 
 def fetch_from_paddington(
-    date: str, user_agent: str = DEFAULT_UA, station_crs: str = 'BRI'
-) -> list[dict]:
+    date: str, user_agent: str = DEFAULT_UA, station_crs: str = "BRI"
+) -> list[dict[str, Any]]:
     """Fetch trains from PAD to station_crs."""
     headers = _browser_headers(user_agent)
     with httpx.Client(headers=headers, follow_redirects=True, timeout=30) as client:
         r_pad = client.get(_PAD_TO_TMPL.format(crs=station_crs, date=date))
         r_station = client.get(_FROM_PAD_TMPL.format(crs=station_crs, date=date))
 
-    departures = _parse_services(r_pad.text, 'div.time.plan.d')
+    departures = _parse_services(r_pad.text, "div.time.plan.d")
     arrivals = _parse_arrivals(r_station.text)
 
     trains = [