blesession 0.1.0__tar.gz

blesession-0.1.0/CHANGELOG.md

@@ -0,0 +1,59 @@
+# Changelog
+
+All notable changes to blesession. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); the project uses
+[Semantic Versioning](https://semver.org/) — until 1.0, a minor bump may carry
+a behaviour change, and every such change is listed under **Changed** with the
+old and new behaviour.
+
+Report keys (`failed_stage`, `likely_cause`, `via`, `<stage>_s`, …) and the
+primary stage names are part of the contract: troubleshooting docs quote
+them, so any change to them is at least a minor bump and is listed here.
+
+## [0.1.0] — 2026-09-22
+
+First release. Same code as 0.1.0a2, verified on device with `hass-ble-esl`
+0.10.0b1 over a Bluetooth proxy: `via` / `via_type` / `advertised_via`,
+`failed_stage` / `failed_detail` / `likely_cause` as designed.
+
+## [0.1.0a2] — 2026-09-22
+
+### Fixed
+
+- `build_report()` dropped an error's `detail` whenever the trace had a
+  failed stage, so a `ConnectFailed(detail="settle")` inside `connect` lost
+  it on the direct path while `report_attempt()` kept it. Both now use one
+  rule, `SessionTrace.failure(exc)`: the trace names the stage; the error's
+  detail applies when it is about that same stage or the trace has none.
+
+## [0.1.0a1] — 2026-09-22
+
+Pre-release for on-device testing with `hass-ble-esl`. The API is what the
+ESL integration shaped; `hass-omron` is next and may still move it.
+
+### Added
+
+- `ble_session()`: connect inside the block, bounded disconnect in `finally`,
+  `settle_s`, `keep`, `close_stale`; the client class is resolved at connect
+  time so Home Assistant's proxy-aware wrapper is picked up regardless of
+  import order.
+- `Notifications`: queued replies from one characteristic; every wait names
+  its `step`, and `NotificationTimeout` carries it.
+- `SessionTrace` / `traced()`: nested stage timings, the innermost stage a
+  failure escaped from, `note()` facts, `stage_map` to the primary vocabulary.
+- Primary stage vocabulary: `unreachable`, `connect`, `session`, `auth`,
+  `transfer`, `finish`, `disconnect`.
+- `run_attempts()`: lock held per attempt, attempt bound with `timed_out`,
+  `guard` under the lock, `retry_if`, `on_attempt`, `state` carried between
+  attempts.
+- `build_report()` / `report_attempt()`: fixed attribute key order, device
+  cause callback first, generic sentences as fallback.
+- Errors: `BleSessionError(ConnectionError)` with `Unreachable`,
+  `ConnectFailed`, `SessionDropped`, `NotificationTimeout`, `AttemptTimedOut`.
+- `link.py`: the one place that probes bleak / habluetooth internals for the
+  radio a link took; `is_proxy()`.
+- `blesession.hass.radio_facts()`: `via`, `via_type`, `rssi`, `paths`,
+  `advertised_via` as scanner names (imports Home Assistant lazily).
+- `blesession.testing`: `FakeClient`, `FakeDevice`, `fake_connect()`.
+- `SessionTrace.record()` for a stage measured elsewhere; `NotificationTimeout(message=)`
+  for protocols that word their own probe timeouts.

blesession-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 eigger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

blesession-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include LICENSE README.md CHANGELOG.md
+recursive-include tests *.py
+recursive-include docs *.md

blesession-0.1.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: blesession
+Version: 0.1.0
+Summary: One BLE session, instrumented: connect, notifications, stage timings, where it failed and why — for Home Assistant BLE integrations.
+Author: eigger
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/eigger/blesession
+Project-URL: Repository, https://github.com/eigger/blesession
+Keywords: ble,bluetooth,bleak,home-assistant,session,diagnostics
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Framework :: AsyncIO
+Classifier: Topic :: System :: Hardware
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: bleak>=0.22
+Requires-Dist: bleak-retry-connector>=3.6
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: mypy>=1.14; extra == "dev"
+Dynamic: license-file
+
+# blesession
+
+One BLE session, instrumented — for Home Assistant BLE integrations built on
+[bleak](https://github.com/hbldh/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
+
+**0.1.0 — first release.** `hass-ble-esl` 0.10.0 runs on it, verified on
+device over a Bluetooth proxy; `hass-omron` is next. The library is tested
+without Home Assistant (`pytest`).
+Read [`docs/design.md`](docs/design.md) for what belongs here, what
+deliberately does not, how a Bluetooth-proxy route works without importing
+Home Assistant, and the rollout plan.
+
+The design is extracted from two integrations that already carry this
+instrumentation and have drifted apart:
+
+- [`hass-ble-esl`](https://github.com/eigger/hass-ble-esl) — e-paper shelf
+  labels (write an image, wait for the panel)
+- [`hass-omron`](https://github.com/eigger/hass-omron) — blood pressure
+  monitors (bonded, unlock, read record memory)
+
+and is meant to be adopted by the rest of the family (`hass-catprinter`,
+`hass-niimbot`, `hass-gicisky`, `hass-zhsunyco`, `hass-lywsd02`,
+`hass-marklife`, `hass-minibig`, `hass-vson`, …), which today each hand-roll
+the same notification wait and have no failure attribution at all.
+
+## What it provides
+
+| piece | one line |
+|---|---|
+| `ble_session()` | connect inside the block, bounded disconnect in `finally`, never masks the real error |
+| `Notifications` | queued replies from one characteristic; every wait names its `step` |
+| `SessionTrace` | nested stage timings; the innermost stage an exception escaped from |
+| stage vocabulary | `unreachable · connect · session · auth · transfer · finish · disconnect`, plus a device `detail` |
+| `run_attempts()` | the lock-per-attempt / fresh-handle-per-attempt contract; policy stays yours |
+| `blesession.hass.radio_facts()` | `via`, `via_type`, `rssi`, `paths`, `advertised_via` as scanner names |
+| `link.py` | the *one* place that probes bleak / habluetooth internals for the radio a link took |
+| `blesession.testing` | `FakeClient` / `fake_connect()` so every integration's tests fake bleak the same way |
+| `build_report()` | fixed attribute key order; generic likely-cause sentences, your device sentences first |
+| errors | `ConnectionError` subclasses so an off device never becomes a traceback |
+
+## 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/design.md          the design
+```
+
+```python
+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="tag")
+    # {'operation': 'write', 'success': False, 'error': ..., 'failed_stage': 'auth',
+    #  'failed_detail': 'start', 'likely_cause': ..., 'via': ..., 'connect_s': ..., ...}
+```
+
+## License
+
+MIT

blesession-0.1.0/README.md

@@ -0,0 +1,84 @@
+# blesession
+
+One BLE session, instrumented — for Home Assistant BLE integrations built on
+[bleak](https://github.com/hbldh/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
+
+**0.1.0 — first release.** `hass-ble-esl` 0.10.0 runs on it, verified on
+device over a Bluetooth proxy; `hass-omron` is next. The library is tested
+without Home Assistant (`pytest`).
+Read [`docs/design.md`](docs/design.md) for what belongs here, what
+deliberately does not, how a Bluetooth-proxy route works without importing
+Home Assistant, and the rollout plan.
+
+The design is extracted from two integrations that already carry this
+instrumentation and have drifted apart:
+
+- [`hass-ble-esl`](https://github.com/eigger/hass-ble-esl) — e-paper shelf
+  labels (write an image, wait for the panel)
+- [`hass-omron`](https://github.com/eigger/hass-omron) — blood pressure
+  monitors (bonded, unlock, read record memory)
+
+and is meant to be adopted by the rest of the family (`hass-catprinter`,
+`hass-niimbot`, `hass-gicisky`, `hass-zhsunyco`, `hass-lywsd02`,
+`hass-marklife`, `hass-minibig`, `hass-vson`, …), which today each hand-roll
+the same notification wait and have no failure attribution at all.
+
+## What it provides
+
+| piece | one line |
+|---|---|
+| `ble_session()` | connect inside the block, bounded disconnect in `finally`, never masks the real error |
+| `Notifications` | queued replies from one characteristic; every wait names its `step` |
+| `SessionTrace` | nested stage timings; the innermost stage an exception escaped from |
+| stage vocabulary | `unreachable · connect · session · auth · transfer · finish · disconnect`, plus a device `detail` |
+| `run_attempts()` | the lock-per-attempt / fresh-handle-per-attempt contract; policy stays yours |
+| `blesession.hass.radio_facts()` | `via`, `via_type`, `rssi`, `paths`, `advertised_via` as scanner names |
+| `link.py` | the *one* place that probes bleak / habluetooth internals for the radio a link took |
+| `blesession.testing` | `FakeClient` / `fake_connect()` so every integration's tests fake bleak the same way |
+| `build_report()` | fixed attribute key order; generic likely-cause sentences, your device sentences first |
+| errors | `ConnectionError` subclasses so an off device never becomes a traceback |
+
+## 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/design.md          the design
+```
+
+```python
+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="tag")
+    # {'operation': 'write', 'success': False, 'error': ..., 'failed_stage': 'auth',
+    #  'failed_detail': 'start', 'likely_cause': ..., 'via': ..., 'connect_s': ..., ...}
+```
+
+## License
+
+MIT