blesession

One BLE session, instrumented — for Home Assistant BLE integrations built on bleak.

Connect, subscribe to notifications, exchange frames with per-step timeouts, disconnect — and come out the other side with where the time went, where it failed, which radio it went over, and one sentence on what that most likely means, ready to publish as sensor attributes so a failed session at 3 am can be read off the entity without debug logging.

Status

Verified on device over a Bluetooth proxy. The library is tested without Home Assistant (pytest). Adopting it? docs/adopting.md is a whole integration end to end: what to write, what the library writes for you, every report key, and how to test it without bleak or Home Assistant. docs/design.md is the why — what belongs here, what deliberately does not, and how a Bluetooth-proxy route works without importing Home Assistant. See CHANGELOG.md for releases.

The design is extracted from integrations that already carry this instrumentation (and had drifted apart), and is meant to be adopted by others that today each hand-roll the same notification wait and have no failure attribution at all.

Install

pip install blesession

Requires Python 3.13+. The core depends only on bleak / bleak-retry-connector; blesession.hass imports Home Assistant lazily and is not needed outside HA.

What it provides

What it does not provide

Retry counts, backoff, packet pacing, lock scope, bonding and pairing, cooldowns, advertisement parsing, protocol frames. Those are the parts each integration learned from its own device and keeps.

Layout

src/blesession/         pure Python + bleak, tested without Home Assistant
src/blesession/hass.py  imports homeassistant lazily; only used inside HA
docs/adopting.md        how to use it, with a whole integration
docs/design.md          why it is shaped this way

from blesession import Notifications, SessionTrace, ble_session, build_report, stages

trace = SessionTrace(stage_map={"start": stages.AUTH})
try:
    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")
            with trace.timed("transfer"):
                ...
except ConnectionError as exc:          # every session error is one
    report = build_report(operation="write", trace=trace, exc=exc,
                          facts=radio_facts(hass, address, trace.link), noun="device")
    # {'operation': 'write', 'success': False, 'error': ..., 'failed_stage': 'auth',
    #  'failed_detail': 'start', 'likely_cause': ..., 'via': ..., 'connect_s': ..., ...}

Development & testing

pip install -e ".[dev]"
pytest                 # unit tests; FakeClient fakes bleak the same way for adopters
ruff check . && ruff format --check .
mypy                   # type-check src/ (the package ships py.typed)
python -m build

CI runs on every push/PR (.github/workflows/ci.yml): ruff lint+format, mypy, the test suite on Python 3.13/3.14 (plus a lowest-pinned-dependencies job), and a build that asserts py.typed and the licence are in the wheel.

Releasing: add a version section to CHANGELOG.md (behaviour changes go under Changed with before/after), bump version in pyproject.toml, merge, then tag: pushing a v* tag triggers .github/workflows/release.yml to build and publish to PyPI (trusted publishing).

License

MIT