aioabrp 0.1.0__py3-none-any.whl

aioabrp/__init__.py

@@ -0,0 +1,39 @@
+"""Async Python client for the A Better Routeplanner (ABRP) / Iternio telemetry API."""
+
+from .auth import AbstractAuth, StaticAuth
+from .client import AbrpClient
+from .exceptions import AbrpApiError, AbrpAuthError, AbrpError
+from .models import (
+    AbrpVehicle,
+    CatalogEntry,
+    ChargingState,
+    ConnectionEvent,
+    ConnectionState,
+    Location,
+    Metric,
+    MetricValue,
+    Telemetry,
+)
+from .stream import TelemetryStream
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AbrpApiError",
+    "AbrpAuthError",
+    "AbrpClient",
+    "AbrpError",
+    "AbrpVehicle",
+    "AbstractAuth",
+    "CatalogEntry",
+    "ChargingState",
+    "ConnectionEvent",
+    "ConnectionState",
+    "Location",
+    "Metric",
+    "MetricValue",
+    "StaticAuth",
+    "Telemetry",
+    "TelemetryStream",
+    "__version__",
+]

aioabrp/_clock.py

@@ -0,0 +1,44 @@
+"""Wall-clock seam and pure future-time clamp helpers.
+
+Shared by the stream gate, the one-shot getter, and seed validation so a
+future-dated wire ``time`` can never escape the library or poison the
+monotonicity gate. The clock is a single module-level seam (mirroring
+``stream._sleep``): tests monkeypatch ``aioabrp._clock._now`` once and it
+governs every clamp site. The clamp helpers are PURE — callers pass the
+``now`` snapshot in — so exactly one ``_now()`` read happens per SSE frame,
+per construction, and per one-shot call.
+"""
+
+from dataclasses import replace
+from datetime import UTC, datetime
+from typing import Any, overload
+
+from .models import Metric, MetricValue
+
+
+# Single monkeypatch target for all clock-dependent behaviour. Returns a
+# tz-aware UTC datetime to match the extractor's tz-aware wire times.
+def _now() -> datetime:
+    return datetime.now(UTC)
+
+
+@overload
+def _clamp_time(t: datetime, now: datetime) -> datetime: ...
+@overload
+def _clamp_time(t: None, now: datetime) -> None: ...
+def _clamp_time(t: datetime | None, now: datetime) -> datetime | None:
+    """Return ``min(t, now)``; ``None`` passes through (no ordering claim)."""
+    if t is None or t <= now:
+        return t
+    return now
+
+
+def clamp_future_times(
+    extracted: dict[Metric, MetricValue[Any]], now: datetime
+) -> dict[Metric, MetricValue[Any]]:
+    """Rewrite any future block ``time`` to ``now``; everything else untouched."""
+    out: dict[Metric, MetricValue[Any]] = {}
+    for metric, v in extracted.items():
+        clamped = _clamp_time(v.time, now)
+        out[metric] = v if clamped is v.time else replace(v, time=clamped)
+    return out

aioabrp/_extract.py

@@ -0,0 +1,295 @@
+"""Wire frame -> typed metric extraction. Internal module.
+
+Converts one telemetry wire frame (a one-shot ``GET /2/tlm/{id}`` payload
+or an SSE frame body — see :mod:`aioabrp._wire_types`) into the library's
+typed event shape ``dict[Metric, MetricValue]`` (internal; the public
+``on_update`` / ``async_get_current_telemetry`` boundary packs this into a
+:class:`~aioabrp.models.Telemetry`).
+
+Tolerance matrix shared by every metric: the extractors tolerate every
+shape the server might emit for an unavailable metric — missing key,
+``null`` block, empty dict, ``null`` leaf, non-numeric leaf, and
+bool-as-number (bool is a subclass of ``int`` in Python) — by omitting
+the metric. Extraction never raises on frame content. Display rounding
+is the consumer's concern.
+
+Per-metric load-bearing notes (ported with the extractors):
+
+* soc / soh — ``frac`` arrives as a 0.0-1.0 fraction; surfaced x100 on
+  the familiar 0-100 % scale. soh is intentionally NOT clamped at 100 —
+  a post-recalibration overshoot (``frac > 1.0``) is meaningful drift
+  downstream statistics are meant to capture, so flattening it would
+  lose signal.
+* battery_temperature — °C with NO lower-bound filter: winter operation
+  (sub-zero pack temps) is a real wire shape, not a degenerate one.
+  Distinct from any cabin or external temperature ABRP might surface in
+  future fields.
+* odometer / range — native meters: a canonical, unit-flip-safe scale;
+  km rendering is display policy, not extraction policy.
+"""
+
+import logging
+import math
+from collections.abc import Mapping
+from datetime import datetime
+from typing import Any
+
+from .models import ChargingState, Location, Metric, MetricValue
+
+_LOGGER = logging.getLogger(__name__)
+
+# Wire key for each metric. Most metrics are named identically on the
+# wire, but a handful of fields camelCase on the wire while the Metric
+# enum stays snake_case. Pinned by tests/test_extract.py against the
+# keep-set in _wire_types.py so the column cannot drift from the wire.
+WIRE_KEYS: dict[Metric, str] = {
+    Metric.SOC: "soc",
+    Metric.POWER: "power",
+    Metric.VOLTAGE: "voltage",
+    Metric.SOE: "soe",
+    Metric.ODOMETER: "odometer",
+    Metric.CALIBRATED_REF_CONS: "calibratedRefCons",
+    Metric.BATTERY_CAPACITY: "batteryCapacity",
+    Metric.SOH: "soh",
+    Metric.RANGE: "estimatedBatteryRange",
+    Metric.BATTERY_TEMPERATURE: "batteryTemperature",
+    Metric.CHARGING_STATE: "chargingState",
+    Metric.LOCATION: "location",
+}
+
+# Numeric leaf key under each metric's wire block (units in the module
+# docstring: percent-after-x100, W, V, Wh, m, Wh/km, °C).
+_NUMERIC_LEAF_KEYS: dict[Metric, str] = {
+    Metric.SOC: "frac",
+    Metric.POWER: "w",
+    Metric.VOLTAGE: "v",
+    Metric.SOE: "wh",
+    Metric.ODOMETER: "m",
+    Metric.CALIBRATED_REF_CONS: "wh_per_km",
+    Metric.BATTERY_CAPACITY: "wh",
+    Metric.SOH: "frac",
+    Metric.RANGE: "m",
+    Metric.BATTERY_TEMPERATURE: "c",
+}
+
+# Metrics whose wire leaf is a 0.0-1.0 fraction surfaced x100 (soh
+# deliberately unclamped — see the module docstring).
+_FRACTION_METRICS = frozenset({Metric.SOC, Metric.SOH})
+
+# Wire enum member -> ChargingState for the categorical ``chargingState``
+# field. Closed-enum: every member ABRP's v2 spec emits has an entry
+# (mirrors the ``ChargingStateValue`` Literal in _wire_types.py). An
+# unrecognized/future member maps to None — the metric is omitted, never
+# surfaced as a raw string (see :func:`_charging_state`).
+_CHARGING_STATES: dict[str, ChargingState] = {
+    "CHARGING_AC": ChargingState.CHARGING_AC,
+    "CHARGING_DC": ChargingState.CHARGING_DC,
+    "CHARGING_UNKNOWN": ChargingState.CHARGING_UNKNOWN,
+    "NOT_CHARGING": ChargingState.NOT_CHARGING,
+    "PLUGGED_IN": ChargingState.PLUGGED_IN,
+}
+
+
+def parse_block_time(block: Mapping[str, Any]) -> datetime | None:
+    """Return the block's ``time`` as a tz-aware datetime, or ``None``.
+
+    Returns ``None`` whenever:
+
+    * the block has no ``time`` key — defense; every keep-set block
+      carries one in production but absence MUST NOT crash extraction;
+    * ``time`` is not a string (e.g. an opaque ``int`` marker);
+    * the string is malformed, or structurally well-formed but invalid
+      (e.g. ``2026-13-01T00:00:00Z``, ``2026-02-30T...``) —
+      :meth:`datetime.fromisoformat` raises :class:`ValueError` for
+      both shapes; caught here to keep call sites branch-free;
+    * the parsed datetime is naive (no tz suffix in the string) — naive
+      vs. aware comparison would raise :class:`TypeError` at the
+      monotonicity-gate comparison site. ABRP's wire format always
+      carries a ``Z`` suffix per the captured rollup sample
+      (2026-05-25), so rejecting naive strings filters wire-shape
+      regressions only.
+
+    Defensive return-``None`` (rather than fail-loud) is load-bearing:
+    callers rely on ``None`` to bypass the monotonicity gate and fall
+    through to "adopt incoming" — today's contract.
+    """
+    raw = block.get("time")
+    if not isinstance(raw, str):
+        return None
+    try:
+        parsed = datetime.fromisoformat(raw)
+    except ValueError:
+        return None
+    if parsed.tzinfo is None:
+        return None
+    return parsed
+
+
+def is_clean_provider_str(value: object) -> bool:
+    r"""Return True iff ``value`` is a non-empty, unpadded string.
+
+    Single REJECT-ONLY contract for the provider-rejection guard, shared
+    by :func:`extract_metrics`'s per-block provider gate and any
+    consumer-side restore/persistence guard that needs the symmetric
+    semantics. An upstream that pads its enum strings is a wire-shape
+    regression we want loud, not silently normalised — so the guard
+    rejects padding rather than stripping.
+
+    **ASCII-whitespace contract.** The
+    ``value == value.strip()`` check uses :meth:`str.strip` with no
+    argument, which only strips characters for which
+    ``str.isspace()`` returns True. Several Unicode characters
+    commonly used as padding — ``U+200B`` (ZWS), ``U+200C`` (ZWNJ),
+    ``U+200D`` (ZWJ), ``U+FEFF`` (BOM) — return False from
+    ``isspace()`` and therefore survive both this guard and
+    ``.strip()``: a ``"\u200bDERIVED"`` value would slip through as
+    "clean". That gap is intentional. ABRP's ``Provider`` enum is
+    closed and ASCII-only (see the spec at
+    https://api.iternio.com/swagger-ui/spec/prod/IternioPlanning.out.yaml);
+    a Unicode-whitespace-padded provider value would be an upstream
+    regression we want surfaced as a downstream mismatch / loud
+    failure of the matching ``Provider`` literal, not silently
+    sanitised at the boundary. ``NBSP`` (``U+00A0``) and other
+    in-``isspace`` Unicode whitespace at edges behave differently:
+    ``.strip()`` removes them, so ``value != value.strip()`` and the
+    guard REJECTS them. That asymmetry vs. ZWS-family codepoints is
+    also acceptable given the closed-ASCII contract — both shapes
+    (slip-through-then-mismatch-downstream for ZWS-family, loud-
+    rejection-at-boundary for NBSP-family) surface upstream regressions.
+    """
+    return isinstance(value, str) and bool(value) and value == value.strip()
+
+
+def _clean_provider(block: Mapping[str, Any]) -> str | None:
+    """Return the block's upstream provider string, or ``None``.
+
+    Symmetric-reject boundary: every non-string AND the empty string AND
+    any whitespace-only or leading-/trailing-padded string map to
+    ``None`` via :func:`is_clean_provider_str`. Per-metric ``provider``
+    is a ``NotRequired`` claim on each ``WithTimeAndProvider`` block
+    (see :mod:`aioabrp._wire_types`); absent / null / non-string /
+    empty / whitespace-padded are all treated as "no usable provider on
+    this block". Consumers that stamp providers may keep their prior
+    value on ``None`` (sticky-on-omission — providers don't flip
+    mid-stream in normal operation).
+    """
+    provider = block.get("provider")
+    if is_clean_provider_str(provider):
+        return provider
+    return None
+
+
+def _float_leaf(block: Mapping[str, Any], leaf_key: str) -> float | None:
+    """Return the numeric leaf ``block[leaf_key]`` as a float, or ``None``.
+
+    Shared numeric tolerance matrix: missing leaf, ``null`` leaf,
+    non-numeric leaf, bool (a subclass of ``int`` in Python — the
+    explicit check matters), and non-finite values (``json.loads``
+    accepts the non-standard ``NaN``/``Infinity`` tokens; neither is a
+    usable metric value) all map to ``None``. Never raises. Accepted
+    leaves are coerced so :class:`MetricValue.value` is always a runtime
+    ``float`` regardless of wire int/float spelling.
+    """
+    value = block.get(leaf_key)
+    if (
+        not isinstance(value, int | float)
+        or isinstance(value, bool)
+        or not math.isfinite(value)
+    ):
+        return None
+    return float(value)
+
+
+def _charging_state(
+    block: Mapping[str, Any],
+    unknown_charging_states_seen: set[str],
+    log_name: str | None,
+) -> ChargingState | None:
+    """Map the categorical ``chargingState`` block to a :class:`ChargingState`.
+
+    Tolerates every degenerate leaf shape (missing / null / non-string
+    ``state``) by returning ``None`` — consistent with the
+    absent/malformed -> omitted contract the numeric extractors share
+    (non-dict blocks are already rejected by :func:`extract_metrics`).
+    An unrecognized non-empty member also maps to ``None`` (the enum is
+    closed; a raw string must never leak into the typed event) and logs
+    a WARNING once per ``unknown_charging_states_seen`` set so upstream
+    enum drift leaves a runtime breadcrumb. The dedup set is
+    caller-owned — one per client/stream instance, never module-global —
+    so warning state cannot leak across accounts.
+    """
+    state = block.get("state")
+    if not isinstance(state, str):
+        return None
+    member = _CHARGING_STATES.get(state)
+    if member is None and state and state not in unknown_charging_states_seen:
+        unknown_charging_states_seen.add(state)
+        _LOGGER.warning(
+            "%sUnrecognized ABRP chargingState %r; the charging_state metric "
+            "will be omitted for this state until aioabrp adds it",
+            f"{log_name}: " if log_name else "",
+            state,
+        )
+    return member
+
+
+def _location(block: Mapping[str, Any]) -> Location | None:
+    """Extract a GPS coordinate pair, or ``None`` when unavailable.
+
+    The wire spells longitude ``long`` (spec ``Location`` block — see
+    :mod:`aioabrp._wire_types`); the model field is ``lon``. Tolerance
+    mirrors the numeric matrix: either leaf missing / null / non-numeric
+    / bool omits the whole metric (a half-coordinate is meaningless).
+    """
+    lat = _float_leaf(block, "lat")
+    long = _float_leaf(block, "long")
+    if lat is None or long is None:
+        return None
+    return Location(lat=lat, lon=long)
+
+
+def extract_metrics(
+    frame: Mapping[str, Any],
+    *,
+    unknown_charging_states_seen: set[str],
+    log_name: str | None = None,
+) -> dict[Metric, MetricValue[Any]]:
+    """Extract every present, well-formed metric from one wire frame.
+
+    Iterates :data:`WIRE_KEYS`; a metric appears in the result only when
+    its wire block is a dict and its value survives the tolerance matrix
+    (module docstring). Each emitted :class:`MetricValue` carries the
+    block's tz-aware ``time`` (or ``None`` — see
+    :func:`parse_block_time`) and clean ``provider`` (or ``None`` — see
+    :func:`is_clean_provider_str`).
+
+    ``unknown_charging_states_seen`` is the caller-owned dedup set for
+    the unrecognized-chargingState warning: one warning per state per
+    set. Keep one set per client/stream instance so multi-account
+    consumers do not share dedup state. ``log_name`` prefixes that
+    warning when given; the warning contains nothing from the frame but
+    the state string itself.
+    """
+    result: dict[Metric, MetricValue[Any]] = {}
+    for metric, wire_key in WIRE_KEYS.items():
+        block = frame.get(wire_key)
+        if not isinstance(block, dict):
+            # Missing key / null block / non-dict block: metric absent.
+            continue
+        value: float | ChargingState | Location | None
+        if metric is Metric.CHARGING_STATE:
+            value = _charging_state(block, unknown_charging_states_seen, log_name)
+        elif metric is Metric.LOCATION:
+            value = _location(block)
+        else:
+            value = _float_leaf(block, _NUMERIC_LEAF_KEYS[metric])
+            if value is not None and metric in _FRACTION_METRICS:
+                value = value * 100
+        if value is None:
+            continue
+        result[metric] = MetricValue(
+            value=value,
+            time=parse_block_time(block),
+            provider=_clean_provider(block),
+        )
+    return result

aioabrp/_sse.py

@@ -0,0 +1,97 @@
+"""SSE byte-stream parsing internals.
+
+Internal module: converts the raw ``text/event-stream`` bytes of the ABRP
+v2 telemetry endpoint into raw SSE event blocks (:func:`iter_sse_events`)
+and one event block into a JSON frame dict (:func:`parse_sse_event`).
+
+PII contract: nothing in this module ever logs a frame body, header value,
+or token — frame key names only.
+"""
+
+import json
+import logging
+from codecs import getincrementaldecoder
+from collections.abc import AsyncIterator
+from typing import Any
+
+from aiohttp import StreamReader
+
+from .exceptions import AbrpApiError
+
+_LOGGER = logging.getLogger(__name__)
+
+
+async def iter_sse_events(content: StreamReader) -> AsyncIterator[str]:
+    r"""Yield raw ``\n\n``-terminated SSE event blocks from a byte stream.
+
+    An incremental UTF-8 decoder preserves multi-byte sequences that span
+    chunk boundaries — naive per-chunk decode would mojibake on Unicode
+    vehicle names / location strings and the JSON parser would then reject
+    the otherwise-valid frame.
+    """
+    decoder = getincrementaldecoder("utf-8")(errors="replace")
+    buffer = ""
+    async for chunk in content.iter_any():
+        buffer += decoder.decode(chunk)
+        # SSE spec accepts ``\n``, ``\r\n`` and ``\r`` as line
+        # terminators. Normalize before splitting on ``\n\n``.
+        # A trailing lone ``\r`` may be the first half of a ``\r\n``
+        # pair that arrives in the next chunk — hold it back so the
+        # pair-rewrite below sees the whole sequence and we don't
+        # mistake a CR for an extra blank line. The re-appended ``\r``
+        # stays un-normalized in the buffer until the next chunk's pass
+        # — or the final flush — normalizes it, which is why the
+        # flush-path normalization below is not redundant.
+        if buffer.endswith("\r"):
+            buffer, held_cr = buffer[:-1], "\r"
+        else:
+            held_cr = ""
+        buffer = buffer.replace("\r\n", "\n").replace("\r", "\n")
+        buffer += held_cr
+        while "\n\n" in buffer:
+            event, _, buffer = buffer.partition("\n\n")
+            yield event
+    # Flush the incremental decoder and any residual buffer in case the
+    # server closed the stream gracefully without a trailing blank line.
+    # Rare but observed on cold reconnects.
+    buffer += decoder.decode(b"", final=True)
+    buffer = buffer.replace("\r\n", "\n").replace("\r", "\n")
+    if buffer.strip():
+        yield buffer
+
+
+def parse_sse_event(event: str) -> dict[str, Any] | None:
+    r"""Parse one ``\n\n``-terminated SSE event block into a JSON frame dict.
+
+    Returns ``None`` for events that carry only comments / keepalives, or
+    for frames missing the required ``vehicleId`` key (probable upstream
+    drift — drop quietly with a keys-only debug log rather than killing
+    the SSE consumer). Raises :exc:`AbrpApiError` on malformed JSON or a
+    decoded payload that is not a JSON object.
+    """
+    data_parts: list[str] = []
+    for line in event.split("\n"):
+        if not line or line.startswith(":"):
+            # blank line (intra-event whitespace) or SSE comment (``: heartbeat``)
+            continue
+        if line.startswith("data:"):
+            data_parts.append(line[5:].removeprefix(" "))
+    if not data_parts:
+        return None
+    payload = "\n".join(data_parts)
+    try:
+        decoded = json.loads(payload)
+    except json.JSONDecodeError as err:
+        raise AbrpApiError(f"malformed SSE frame: {err}") from err
+    if not isinstance(decoded, dict):
+        raise AbrpApiError(f"unexpected SSE frame shape: {type(decoded).__name__}")
+    if "vehicleId" not in decoded:
+        # PII contract: key names only — never the frame body.
+        _LOGGER.debug(
+            "Dropping SSE frame missing 'vehicleId': keys=%s",
+            sorted(decoded.keys()),
+        )
+        return None
+    # Per-metric shape validation lives at the consumer (the extraction
+    # layer) which tolerates missing/null keys.
+    return decoded