src.bluetooth_sig.stream.pairing¶

Stream helpers for pairing dependent characteristic notifications.

This module provides a generic, backend-agnostic buffer that correlates dependent characteristic notifications based on caller-defined grouping keys. Useful for Bluetooth SIG profiles where characteristics must be paired by sequence numbers, timestamps, or other identifiers.

Classes¶

Name	Description
`BufferStats`	Snapshot of pairing buffer statistics.
`DependencyPairingBuffer`	Buffer and pair dependent characteristic notifications.

Module Contents¶

class src.bluetooth_sig.stream.pairing.BufferStats¶

Bases: msgspec.Struct

Snapshot of pairing buffer statistics.

pending¶: Number of incomplete groups currently buffered.

completed¶: Total number of groups successfully paired since creation.

evicted¶: Total number of groups evicted due to TTL expiry since creation.

completed: int¶

evicted: int¶

pending: int¶

class src.bluetooth_sig.stream.pairing.DependencyPairingBuffer(*, translator: src.bluetooth_sig.core.translator.BluetoothSIGTranslator, required_uuids: set[str], group_key: collections.abc.Callable[[str, Any], collections.abc.Hashable], on_pair: collections.abc.Callable[[dict[str, Any]], None], max_age_seconds: float | None = None, clock: collections.abc.Callable[[], float] = time.monotonic)¶

Buffer and pair dependent characteristic notifications.

Buffers incoming notifications until all required UUIDs for a grouping key are present, then batch-parses and invokes the callback. Order-independent.

Parameters:

translator – BluetoothSIGTranslator instance for parsing characteristics.
required_uuids – Set of UUID strings that must be present to form a complete pair.
group_key – Function that extracts a grouping key from each parsed notification. Called as group_key(uuid, parsed_result) and must return a hashable value.
on_pair – Callback invoked with complete parsed pairs as on_pair(results: dict[str, Any]).
max_age_seconds – Maximum age in seconds for buffered groups before eviction. None disables TTL eviction (default).
clock – Callable returning current time as a float (seconds). Defaults to time.monotonic. Override in tests for deterministic timing.

Note

Does not manage BLE subscriptions. Callers handle connection and notification setup.

ingest(uuid: str, data: bytes) → None¶

Ingest a single characteristic notification.

Evicts stale groups (if TTL is configured) before processing.

Parameters:

uuid – Characteristic UUID string (16-bit or 128-bit).
data – Raw bytes from the characteristic notification.

stats() → BufferStats¶

Return a snapshot of buffer statistics.

Returns:: BufferStats with current pending count and lifetime completed/evicted totals.