blesession 0.1.0__py3-none-any.whl

blesession/__init__.py

@@ -0,0 +1,62 @@
+"""One BLE session, instrumented.
+
+    from blesession import ble_session, Notifications, SessionTrace, stages
+
+    trace = SessionTrace(stage_map={"start": stages.AUTH})
+    async with ble_session(ble_device, trace=trace) as client:
+        async with Notifications(client, NOTIFY_UUID, settle=0.5) as replies:
+            with trace.timed("start"):
+                await client.write_gatt_char(WRITE_UUID, START, response=False)
+                await replies.next(timeout=5, step="start")
+            ...
+
+See docs/design.md for what belongs here and what does not.
+"""
+
+from . import stages
+from .attempts import Attempt, default_retry_if, run_attempts
+from .causes import generic_cause, placement
+from .errors import (
+    AttemptTimedOut,
+    BleSessionError,
+    ConnectFailed,
+    NotificationTimeout,
+    SessionDropped,
+    Unreachable,
+    error_text,
+)
+from .link import LinkInfo, connected_via, is_proxy, probe_link
+from .notifications import Notifications
+from .report import FACT_KEYS, build_report, report_attempt
+from .session import DISCONNECT_TIMEOUT_S, ble_session
+from .trace import SessionTrace, traced
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "DISCONNECT_TIMEOUT_S",
+    "FACT_KEYS",
+    "Attempt",
+    "AttemptTimedOut",
+    "BleSessionError",
+    "ConnectFailed",
+    "LinkInfo",
+    "NotificationTimeout",
+    "Notifications",
+    "SessionDropped",
+    "SessionTrace",
+    "Unreachable",
+    "ble_session",
+    "build_report",
+    "connected_via",
+    "default_retry_if",
+    "error_text",
+    "generic_cause",
+    "is_proxy",
+    "placement",
+    "probe_link",
+    "report_attempt",
+    "run_attempts",
+    "stages",
+    "traced",
+]

blesession/attempts.py

@@ -0,0 +1,147 @@
+"""Attempts, the lock, and the bound: the contract, with the policy left to you.
+
+What the loop fixes, each learnt from an integration that got it wrong first:
+
+- The lock is held for **one attempt**, not the whole retry sequence, so
+  between attempts (the pause, or after a timed-out attempt) other devices
+  go first.
+- Every attempt has a bound, connecting included. A GATT write has no
+  timeout of its own; a proxy that dies mid-transfer leaves the attempt
+  hanging, and while it holds the lock every other device hangs with it.
+- The checks that can change while waiting for the lock (a write lock, a
+  superseded job, a duplicate payload) run under the lock, before the
+  attempt, via `guard`.
+- A timed-out attempt is not retried by default: the transport is dead, not
+  the device unwilling, and a retry would only hang the lock again.
+
+What it leaves to the integration: the lock instance and its scope, how
+many attempts, the bound, the pause, and — via `retry_if` — which failures
+deserve another try.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+from asyncio import sleep
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from typing import Any
+
+from .errors import AttemptTimedOut
+from .stages import StageMap
+from .trace import SessionTrace
+
+_LOGGER = logging.getLogger(__name__)
+
+
+@dataclass
+class Attempt[T]:
+    """One try: its number, its trace, and how it ended."""
+
+    number: int
+    trace: SessionTrace
+    result: T | None = None
+    error: BaseException | None = None
+    timed_out: bool = False
+    skipped: Any = None
+    """What `guard` returned when it declined to run this attempt."""
+    state: dict[str, Any] = field(default_factory=dict)
+    """Scratch for `retry_if` / the attempt function across attempts (pacing
+    counters, ...). Copied forward from the previous attempt."""
+
+    @property
+    def ok(self) -> bool:
+        return self.error is None and self.skipped is None
+
+    @property
+    def failed_stage(self) -> str | None:
+        """The primary stage the failure hit (see SessionTrace.failure)."""
+        return self.trace.failure(self.error)[0]
+
+    @property
+    def failed_detail(self) -> str | None:
+        return self.trace.failure(self.error)[1]
+
+
+type AttemptFn[T] = Callable[[Attempt[T]], Awaitable[T]]
+type RetryIf[T] = Callable[[Attempt[T]], bool]
+type Guard = Callable[[], Awaitable[Any]]
+type OnAttempt[T] = Callable[[Attempt[T]], None]
+
+
+def default_retry_if(attempt: Attempt[Any]) -> bool:
+    """Retry anything but a timed-out attempt."""
+    return not attempt.timed_out
+
+
+async def run_attempts[T](
+    attempt_fn: AttemptFn[T],
+    *,
+    lock: asyncio.Lock | None = None,
+    max_attempts: int = 1,
+    attempt_timeout_s: float | None = None,
+    pause_s: float = 1.0,
+    retry_if: RetryIf[T] = default_retry_if,
+    guard: Guard | None = None,
+    on_attempt: OnAttempt[T] | None = None,
+    stage_map: StageMap | None = None,
+    name: str = "",
+) -> Attempt[T]:
+    """Run `attempt_fn` up to `max_attempts` times and return the last Attempt.
+
+    Never raises for a failed attempt: the returned Attempt carries the
+    error, the trace and the stage, and the integration decides what to
+    raise or publish. `on_attempt` sees every attempt as it finishes (for
+    logging, or recording each one on a sensor).
+
+    `attempt_fn` receives the Attempt (use `attempt.trace` for its stages
+    and `attempt.state` for anything carried between attempts) and returns
+    the result or raises.
+    """
+    if max_attempts < 1:
+        raise ValueError("max_attempts must be at least 1")
+    state: dict[str, Any] = {}
+    attempt: Attempt[T] | None = None
+    for number in range(1, max_attempts + 1):
+        attempt = Attempt(number=number, trace=SessionTrace(stage_map), state=dict(state))
+        async with lock if lock is not None else contextlib.nullcontext():
+            if guard is not None and (skipped := await guard()) is not None:
+                attempt.skipped = skipped
+                return attempt
+            bound = asyncio.timeout(attempt_timeout_s)
+            try:
+                async with bound:
+                    attempt.result = await attempt_fn(attempt)
+            except Exception as exc:  # noqa: BLE001 - every failure is an attempt outcome
+                attempt.error = exc
+                if bound.expired():
+                    attempt.timed_out = True
+                    assert attempt_timeout_s is not None
+                    timed_out = AttemptTimedOut(
+                        attempt_timeout_s,
+                        stage=attempt.trace.failed_primary,
+                        detail=attempt.trace.failed_detail,
+                    )
+                    timed_out.__cause__ = exc
+                    attempt.error = timed_out
+                _LOGGER.debug(
+                    "%s attempt %d/%d failed in %s: %s",
+                    name or "session",
+                    number,
+                    max_attempts,
+                    attempt.failed_stage or "?",
+                    attempt.error,
+                    exc_info=attempt.error,
+                )
+        state = attempt.state
+        if on_attempt is not None:
+            on_attempt(attempt)
+        if attempt.ok or number == max_attempts or not retry_if(attempt):
+            return attempt
+        # Lock released: other devices go first. Module-level `sleep` so an
+        # integration's tests can stub the pause.
+        await sleep(pause_s)
+    assert attempt is not None
+    return attempt

blesession/causes.py

@@ -0,0 +1,103 @@
+"""One sentence on what a failed session most likely means — the generic part.
+
+Read from where it died (the primary stage), the error text and the radio
+situation. Best effort: the report keeps the exact `error` beside it. A
+device's own sentences ("the tag rejected authentication: not a WOLINK
+tag", "the cuff was not showing -P-") come from the integration's cause
+callback, which build_report() consults first; these fill in when it has
+nothing to say.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from . import stages
+from .errors import AttemptTimedOut
+
+WEAK_RSSI_DBM = -85
+"""At or below this the placement advice is worth giving; above it the radio
+is not the first suspect."""
+
+
+def placement(facts: Mapping[str, Any], *, noun: str = "device") -> str:
+    """Placement advice when the signal is actually weak, else an empty string.
+
+    A single radio is the normal case and on its own says nothing about the
+    cause; it is mentioned only alongside a weak signal.
+    """
+    rssi = facts.get("rssi")
+    if not isinstance(rssi, int) or rssi > WEAK_RSSI_DBM:
+        return ""
+    text = f" The signal is weak ({rssi} dBm via {facts.get('via', 'unknown')})"
+    if facts.get("paths") == 1:
+        text += f" and no other radio reaches the {noun}"
+    return text + f" — move the {noun} or add a proxy."
+
+
+def generic_cause(
+    stage: str | None,
+    error: str,
+    facts: Mapping[str, Any],
+    *,
+    exc: BaseException | None = None,
+    noun: str = "device",
+) -> str | None:
+    """The generic sentence for a failure, or None when there is none.
+
+    Keyed on the primary stage and a few error-text markers that every
+    transport produces the same way.
+    """
+    err = error.lower()
+    where = placement(facts, noun=noun)
+    if isinstance(exc, AttemptTimedOut):
+        return (
+            "The BLE stack stopped answering mid-session and the attempt was cut at "
+            "its bound: usually a wedged adapter or a proxy that died. Restart the "
+            "adapter / proxy if it repeats."
+        )
+    if stage == stages.UNREACHABLE:
+        return (
+            f"No radio currently sees the {noun}: out of range, asleep, its battery "
+            "flat, or the adapter / proxy is down."
+        )
+    if stage == stages.CONNECT:
+        if "slot" in err:
+            return (
+                "The proxy has no free connection slot; add a proxy or reduce the "
+                "BLE devices it serves."
+            )
+        if "settle" in err:
+            return (
+                f"The {noun} accepted the link and dropped it before encryption "
+                "settled: on a multi-proxy setup usually a proxy that does not hold "
+                "the bond, otherwise a stale bond — pair again if it repeats."
+            )
+        return f"The BLE link could not be established.{where}"
+    if stage == stages.SESSION:
+        return (
+            f"Connected, but the {noun} dropped or refused the session before the "
+            "protocol started (service discovery / notifications); usually transient "
+            "— if it repeats, the protocol or model may not match."
+        )
+    if stage == stages.AUTH:
+        if "no response" in err:
+            return (
+                f"The {noun} did not answer the handshake: not ready, or the link dropped.{where}"
+            )
+        return None
+    if stage == stages.TRANSFER:
+        if "no response" in err:
+            return f"The {noun} stopped answering mid-transfer: link dropped or reset.{where}"
+        return None
+    if stage == stages.FINISH:
+        if "no response" in err:
+            return f"The {noun} took the data but did not report completion in time.{where}"
+        return None
+    if stage == stages.DISCONNECT:
+        return (
+            "The work was done; only the session close failed. "
+            "Harmless unless the next connection is refused."
+        )
+    return None

blesession/const.py

@@ -0,0 +1,14 @@
+"""Option keys and defaults shared across integrations.
+
+Exported so config flows and options can use the same names; the library
+never reads configuration itself.
+"""
+
+CONF_RETRY_COUNT = "retry_count"
+CONF_KEEP_CONNECTION = "keep_connection"
+CONF_SCAN_INTERVAL = "scan_interval"
+CONF_ATTEMPT_TIMEOUT = "attempt_timeout"
+
+DEFAULT_RETRY_COUNT = 3
+DEFAULT_KEEP_CONNECTION = False
+DEFAULT_RETRY_PAUSE_S = 1.0

blesession/errors.py

@@ -0,0 +1,86 @@
+"""Session errors: every one a ConnectionError, every one naming its stage.
+
+A device that is off, out of range, asleep or unwilling is the ordinary case
+for a BLE integration, and must reach Home Assistant as an expected failure
+(`UpdateFailed`, `HomeAssistantError`) rather than a traceback that renders
+as "this error originated from a custom integration". Deriving from
+ConnectionError lets an integration make that mapping in one `except`.
+"""
+
+from __future__ import annotations
+
+from . import stages
+
+
+class BleSessionError(ConnectionError):
+    """A session failed in `stage` (a primary stage) with optional `detail`."""
+
+    stage: str | None = None
+    detail: str | None = None
+
+    def __init__(self, message: str = "", *, stage: str | None = None, detail: str | None = None):
+        super().__init__(message)
+        if stage is not None:
+            self.stage = stage
+        if detail is not None:
+            self.detail = detail
+
+
+class Unreachable(BleSessionError):
+    """No connectable radio currently sees the device."""
+
+    stage = stages.UNREACHABLE
+
+    def __init__(self, address: str) -> None:
+        super().__init__(
+            f"No connectable radio sees {address} "
+            "(out of range, asleep, or the adapter / proxy is down)"
+        )
+
+
+class ConnectFailed(BleSessionError):
+    """establish_connection raised, or the link dropped during the settle."""
+
+    stage = stages.CONNECT
+
+
+class SessionDropped(BleSessionError):
+    """The link went away mid-session."""
+
+    stage = stages.SESSION
+
+
+class NotificationTimeout(BleSessionError, TimeoutError):
+    """No notification arrived in time. Carries the `step` that was waiting.
+
+    Also a TimeoutError so protocol code that already catches one keeps
+    working; unlike asyncio's it always carries a message.
+    """
+
+    def __init__(self, timeout: float, *, step: str, message: str | None = None) -> None:
+        super().__init__(
+            message or f"No response from device within {timeout:g}s after {step}", detail=step
+        )
+        self.step = step
+        self.timeout = timeout
+
+
+class AttemptTimedOut(BleSessionError, TimeoutError):
+    """The attempt bound fired: the transport is dead, not the device unwilling.
+
+    `stage` is the stage that was running when the bound hit, taken from
+    the trace by run_attempts().
+    """
+
+    def __init__(self, timeout: float, *, stage: str | None = None, detail: str | None = None):
+        super().__init__(
+            f"Attempt timed out after {timeout:g}s; the BLE stack stopped answering",
+            stage=stage,
+            detail=detail,
+        )
+        self.timeout = timeout
+
+
+def error_text(exc: BaseException) -> str:
+    """The message, or the type name for exceptions that carry none."""
+    return str(exc) or type(exc).__name__

blesession/hass.py

@@ -0,0 +1,73 @@
+"""What only Home Assistant knows about a session: the radios.
+
+Imported only from inside a running integration; `homeassistant` is not a
+dependency of this package.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from .link import LinkInfo
+
+if TYPE_CHECKING:
+    from homeassistant.core import HomeAssistant
+
+
+def radio_facts(hass: HomeAssistant, address: str, link: LinkInfo | None = None) -> dict[str, Any]:
+    """Which radio the session went through, its RSSI and how many reach the device.
+
+        via             the radio the link took (scanner name), when knowable;
+                        else the scanner holding the strongest advertisement,
+                        which is the one the client wrapper tries first
+        via_type        "proxy" | "adapter"
+        rssi            as seen by that radio
+        paths           connectable radios that currently see the device;
+                        1 means no failover is possible
+        advertised_via  the scanner whose advertisement was strongest, only
+                        when it is not the radio the link took (a failover, or
+                        on a bonded device the one proxy that holds the bond)
+
+    `link` is what ble_session() recorded on the trace; None (a session that
+    never connected) falls back to the advertising scanner.
+    """
+    from homeassistant.components.bluetooth import (
+        BaseHaRemoteScanner,
+        BaseHaScanner,
+        async_last_service_info,
+        async_scanner_by_source,
+        async_scanner_devices_by_address,
+    )
+
+    def scanner_for(value: Any) -> Any:
+        if isinstance(value, BaseHaScanner):
+            return value
+        if isinstance(value, str) and value:
+            return async_scanner_by_source(hass, value)
+        return None
+
+    advertised = scanner_for(link.source if link else None)
+    if advertised is None:
+        info = async_last_service_info(hass, address, connectable=True)
+        advertised = async_scanner_by_source(hass, info.source) if info else None
+    connected = scanner_for(link.via if link else None) or advertised
+
+    facts: dict[str, Any] = {}
+    if connected is not None:
+        facts["via"] = connected.name
+        facts["via_type"] = "proxy" if isinstance(connected, BaseHaRemoteScanner) else "adapter"
+    elif link is not None and link.via:
+        # A BlueZ D-Bus path or an id habluetooth does not know: still worth showing.
+        facts["via"] = str(link.via)
+    rssi_scanner = connected or advertised
+    if rssi_scanner is not None:
+        try:
+            seen = rssi_scanner.get_discovered_device_advertisement_data(address)
+        except Exception:  # noqa: BLE001 - a scanner without the method
+            seen = None
+        if seen is not None:
+            facts["rssi"] = seen[1].rssi
+    facts["paths"] = len(async_scanner_devices_by_address(hass, address, connectable=True))
+    if advertised is not None and connected is not None and advertised is not connected:
+        facts["advertised_via"] = advertised.name
+    return facts

blesession/link.py

@@ -0,0 +1,96 @@
+"""Which radio a link went over — the one place that probes bleak internals.
+
+Home Assistant may reach a device through the local adapter or any of
+several Bluetooth proxies, and the scanner whose advertisement was
+strongest is not always the radio the connection took (a failover, or on a
+bonded device the only proxy that holds the bond). The real answer lives
+only on the client wrapper / backend, in private attributes whose shapes
+change between habluetooth and bleak-esphome releases. When they do, this
+is the one function to fix.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from bleak import BleakClient
+from bleak.backends.device import BLEDevice
+
+
+@dataclass(frozen=True)
+class LinkInfo:
+    """What was learnt about the link at connect time.
+
+    `via` is the radio the connection actually took: a scanner object
+    (habluetooth's client wrapper records one), a habluetooth source id, a
+    BlueZ D-Bus path, or None when unknowable. `source` is the scanner that
+    advertised the device (habluetooth source id) — always a string on a
+    proxy route, None on a plain local adapter.
+
+    Both are opaque here; `blesession.hass.radio_facts()` turns them into
+    scanner names.
+    """
+
+    via: Any = None
+    source: str | None = None
+    proxy: bool | None = None
+    """Whether the advertising route was a remote scanner, when knowable."""
+
+
+def advertising_source(ble_device: BLEDevice) -> str | None:
+    """The habluetooth source id the advertisement came from, if recorded.
+
+    Remote (ESPHome) scanners publish a plain dict with the proxy's source
+    address; local adapters carry backend-specific details (a BlueZ object
+    path, a WinRT / CoreBluetooth handle).
+    """
+    details = getattr(ble_device, "details", None)
+    if isinstance(details, dict):
+        for key in ("source", "scanner"):
+            if value := details.get(key):
+                return str(value)
+    return None
+
+
+def is_proxy(ble_device: BLEDevice) -> bool:
+    """True when Home Assistant reached this device through a remote scanner.
+
+    Integrations that adapt pacing to the transport (a longer packet
+    interval over a proxy) read this; the report reads `via_type` instead,
+    which reflects the radio the link actually took.
+    """
+    details = getattr(ble_device, "details", None)
+    return isinstance(details, dict) and "source" in details
+
+
+def connected_via(client: BleakClient) -> Any:
+    """The radio the connection took, from the client, or None.
+
+    Tried in order:
+      client._connected_scanner   habluetooth's wrapper, newer versions
+                                  (a BaseHaScanner object)
+      client._backend._source     bleak-esphome (a source id string)
+      client._backend.source
+      client._backend._device_path  BlueZ (a D-Bus path)
+    """
+    if (scanner := getattr(client, "_connected_scanner", None)) is not None:
+        return scanner
+    backend = getattr(client, "_backend", None)
+    if backend is None:
+        return None
+    for attr in ("_source", "source"):
+        if value := getattr(backend, attr, None):
+            return str(value)
+    if path := getattr(backend, "_device_path", None):
+        return str(path)
+    return None
+
+
+def probe_link(client: BleakClient, ble_device: BLEDevice) -> LinkInfo:
+    """Everything knowable about the link right after connecting."""
+    return LinkInfo(
+        via=connected_via(client),
+        source=advertising_source(ble_device),
+        proxy=is_proxy(ble_device),
+    )

blesession/notifications.py

@@ -0,0 +1,90 @@
+"""Notifications from one characteristic, queued for the session's duration.
+
+Every protocol needs the same thing around its exchange: subscribe,
+optionally let the link settle, read replies with a timeout, and
+unsubscribe in `finally` even when the link has dropped. Only the
+interpretation of the replies is protocol-specific.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+from collections.abc import Callable
+from typing import Any
+
+from bleak import BleakClient
+
+from .errors import NotificationTimeout
+
+
+class Notifications:
+    """Queued notifications from one characteristic.
+
+        async with Notifications(client, NOTIFY_UUID, settle=0.5) as replies:
+            await client.write_gatt_char(WRITE_UUID, cmd, response=False)
+            reply = await replies.next(timeout=5, step="start")
+            done = await replies.wait_for(is_done, timeout=120, step="finish")
+
+    A queue rather than an event: a reply that lands between two waits is
+    kept, not lost. Every wait names its `step`, so the NotificationTimeout
+    it raises already says which stage of the protocol went unanswered.
+    """
+
+    def __init__(self, client: BleakClient, characteristic: Any, *, settle: float = 0.0) -> None:
+        self._client = client
+        self._characteristic = characteristic
+        self._settle = settle
+        self._queue: asyncio.Queue[bytes] = asyncio.Queue()
+
+    async def __aenter__(self) -> Notifications:
+        await self._client.start_notify(self._characteristic, self._on_notify)
+        if self._settle:
+            # Some adapters/proxies drop a write issued right after the CCCD write.
+            await asyncio.sleep(self._settle)
+        return self
+
+    async def __aexit__(self, *exc_info: Any) -> None:
+        # Never let an unsubscribe failure on a dropped link mask the
+        # original error; ble_session() still disconnects.
+        with contextlib.suppress(Exception):
+            if self._client.is_connected:
+                await self._client.stop_notify(self._characteristic)
+
+    def _on_notify(self, _sender: Any, data: bytearray) -> None:
+        self._queue.put_nowait(bytes(data))
+
+    @property
+    def pending(self) -> int:
+        """Notifications received and not yet read."""
+        return self._queue.qsize()
+
+    def clear(self) -> list[bytes]:
+        """Drop (and return) notifications received so far."""
+        dropped = []
+        while not self._queue.empty():
+            dropped.append(self._queue.get_nowait())
+        return dropped
+
+    async def next(self, timeout: float, *, step: str) -> bytes:
+        """The next notification, or NotificationTimeout naming `step`."""
+        try:
+            return await asyncio.wait_for(self._queue.get(), timeout)
+        except TimeoutError as exc:
+            raise NotificationTimeout(timeout, step=step) from exc
+
+    async def wait_for(
+        self, accept: Callable[[bytes], bool], timeout: float, *, step: str
+    ) -> bytes:
+        """The first notification `accept` returns True for, within `timeout` overall.
+
+        `accept` may raise to turn an error frame into the session's failure.
+        """
+        try:
+            async with asyncio.timeout(timeout):
+                while True:
+                    data = await self._queue.get()
+                    if accept(data):
+                        return data
+        except TimeoutError as exc:
+            raise NotificationTimeout(timeout, step=step) from exc