Repository navigation
docs: elke27 0.6.0 release cut - #146
Conversation
Co-authored-by: Mitch Mitchell <mitchmitchell1616@msn.com>
Codex Review Summary: ✅ CompletedThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
Co-authored-by: Mitch Mitchell <mitchmitchell1616@msn.com>
Claude (hourly) — tip verdict @
|
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 0cc4d2fd07
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| that need a fresh snapshot should call `get_snapshot()` after the command | ||
| returns or subscribe to status events. |
There was a problem hiding this comment.
Correct the fresh-snapshot advice after publication timeout
When the publication deadline expires, calling get_snapshot() immediately after the command returns does not ensure fresh status: get_snapshot() only returns self._snapshot (src/elke27_lib/client.py:2527–2529) and neither waits for publication nor refreshes it. An integration following this upgrade advice can therefore consume the stale area or zone state that the publication wait was intended to avoid. Clarify that the snapshot may still be stale after a timeout and that callers requiring confirmed fresh state must wait for publication rather than merely read it again.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Addressed in bf37c9b follow-up (latest push):
-
Publication timeout (P2): Removed the advice that
get_snapshot()after a timeout yields fresh state. The release notes now state the snapshot may stay stale until dispatch publishes the status, and point integrators atsubscribe()/events()forElke27EventwithEventType.AREAorEventType.ZONE, or a later status read. -
Disconnect messages: Split the two
Elke27DisconnectedErrortexts—Connection lost during the command.(reply still pending) vsConnection lost while waiting for snapshot publication.(after reply, before publication)—perclient.py_disconnected_from_connection_lostand_fail_all_reply_publication_waiters.
mitchmitchell
left a comment
There was a problem hiding this comment.
Verdict: Changes needed @ f4d6c06
Docs-only release cut for 0.6.0 (minor, per the D57 ruling). I checked the notes against src/ at this head. The firmware gate (0.0.5.37, required/actual), the hierarchy of every error class in the table, Elke27PanelError.panel_error_code/reason, the route=("area", "set_arm_state") outcome-unknown paths, the WARNING-and-ok on an expired wait budget, and the disconnect message all match the code. Two blockers:
B1: the status-read wait list leaves out zone_get_status. REPLY_PUBLICATION_COMMAND_KEYS (client.py ~494) is area_set_arm_state, area_get_status, zone_set_status, zone_get_status, zone_get_all_zones_status. _command_needs_reply_publication_wait returns True unconditionally for zone_get_status. It is also the follow-up read after an ack-only zone_set_status (client.py ~1665). Both CHANGES ("Status reads (#144)") and v0.6.0.md ("Behavior" and "Area and zone status reads") name only area_get_status and zone_get_all_zones_status. Add zone_get_status to both lists. Also state that the ack-only arm/bypass paths wait on their follow-up reads.
B2: the notes say "raises" for status-read failures, but async_execute returns them. At client.py ~3576, Elke27DisconnectedError and Elke27SnapshotPublicationError from the publication wait are caught and returned as _err(...). That is Result(ok=False, error=...), and nothing is raised from async_execute. CHANGES says link loss or close "raises Elke27DisconnectedError" and that a replace failure "raises Elke27SnapshotPublicationError". v0.6.0.md says waiters "fail with" and the command "returns" the error. An integration that wraps async_execute in try/except would never see these errors. Say plainly that for async_execute they arrive as Result.error with ok=False. They are raised only by the typed helpers that go through _raise_v2_command_error (for example async_arm_area and zone bypass). Fix both files so they say the same thing.
Should-fix items (not blocking; tracked on elke27#50):
- The release date reads 2026-11-17 in both files. Match it to the actual tag day, since the tag still needs Mitch's OK.
- README still doesn't name
Elke27PanelApplicationFirmwareUnknownError,Elke27NightArmFirmwareTooOldErrororElke27SnapshotPublicationError. This is #142 S1, carried on elke27#50.
There is no code in this diff, so the Bugbot gate doesn't apply. CI was still pending at review time.
…830) Co-authored-by: Mitch Mitchell <mitchmitchell1616@msn.com>
mitchmitchell
left a comment
There was a problem hiding this comment.
Decision 55 Not approved (offline only) @ f4d6c06
I ran these checks independently at this exact head. The merge base is 774011385769ce67aa22ef33aede781e874571ee, which is current main. No hardware was used; this is offline only.
Diff scope: docs only. git diff origin/main...HEAD touches just two files: docs/CHANGES.md (+31/−20) and the new docs/release-notes/v0.6.0.md (+95). Nothing changed under src/, test/, pyproject.toml, uv.lock, CI or examples. No code changed, so I ran no mutants.
Version consistency. pyproject.toml has dynamic = ["version"] (uv-dynamic-versioning), and there is no __version__ in src/. The package version comes only from the git tag, and this head builds as 0.5.2.dev6+f4d6c06. CHANGES (0.6.0, 2026-11-17), the release-notes title and the compare/v0.5.1...v0.6.0 link all agree on 0.6.0. I found no stale version strings in README or the other docs. The published version is 0.6.0 only if the v0.6.0 tag goes on the merge commit.
Offline gates (fresh Python 3.14.8 venv, uv cache clean elke27 first), compared with main 7740113:
| Gate | f4d6c06 | 7740113 |
|---|---|---|
pytest -k "not test_live_e27_" |
1449 passed / 9 skipped / 33 deselected | 1449 / 9 / 33 |
| basedpyright | 0 errors, 0 warnings | 0 errors |
| devtools/lint.py | passed | passed |
| ruff check --no-fix (src, test) / format --check | clean / 251 files formatted | same |
| ruff repo-wide | 6 findings, all in examples/ | same 6 |
| test_review_guards.py and private-access ceilings | 10 passed | 10 passed |
The gates pass and match main exactly, which is expected for a docs-only change. The verdict depends only on whether the docs are accurate.
Doc claims I verified against src/ at this head:
- Every row of the error-class table is correct, and every class is exported.
DelayStateexists, and so do theasync_arm_area(area_id, *, mode: ArmMode, ...)signature,PanelInfo.application_firmware,AreaState.night_arm_supported,delay_state, and thearming/entry_delayproperties.- An expired wait budget does give ok plus a WARNING.
Blockers (the fix in each case is to make the docs match the code, not the other way round):
zone_get_statusis missing from the status-read wait list.REPLY_PUBLICATION_COMMAND_KEYSisarea_set_arm_state,area_get_status,zone_set_status,zone_get_status,zone_get_all_zones_status.zone_get_statusalways waits, and it is also the follow-up read after an ack-onlyzone_set_status. CHANGES ("Status reads (#144)") and v0.6.0.md ("Behavior" and the bullets under "Area and zone status reads") list onlyarea_get_statusandzone_get_all_zones_status. Fix: addzone_get_statusto both files.- CHANGES says "raises" for something
async_executereturns. Link loss, client close and snapshot-replace failure during the publication wait are caught insideasync_executeand returned asResult(ok=False, error=Elke27DisconnectedError | Elke27SnapshotPublicationError). That is the #143 contract, and nothing is raised. CHANGES says each "raises". The release notes are closer ("fail with", "returns") but never say that the error arrives asResult.error. An integration that wrapsasync_executeintry/exceptbecause it read the changelog would never see these failures. Fix: say in both files that forasync_executethese arrive asResult.errorwithok=False, and that they are raised only by the typed helpers that go through_raise_v2_command_error(async_arm_area, zone bypass).
Should-fix (non-blocking):
- v0.6.0.md, publication-timeout bullet: the advice to call
get_snapshot()after the command returns does not get fresh state.get_snapshot()only returns the current snapshot. This agrees with the existing P2 inline comment. Fix: say the snapshot may still be stale after a timeout, and that callers who need confirmed state should subscribe to status events or re-issue the read. - v0.6.0.md quotes the disconnect message "Connection lost while waiting for snapshot publication." That text is used only for waiters failed by the disconnect event. If the link drops while the reply itself is still pending,
async_executereturnsElke27DisconnectedError("Connection lost during the command.")(client.py ~1059). Fix: drop the exact quote, or name both messages. - The release date says 2026-11-17 in both files. It should match the actual tag day.
Re-review scope: docs only. After a follow-up commit, I'll re-check the diff scope, rerun the gates once, and re-verify the corrected wording against src/.
Claude (hourly) — tip verdict @
|
|
re-review @ bf37c9b — addresses Architect 5933463830 B1 (zone_get_status and ack-only follow-up reads listed, matching REPLY_PUBLICATION_COMMAND_KEYS) and B2 (async_execute returns Result(ok=False, error=...); only _raise_v2_command_error helpers raise), plus README names the three new errors. |
mitchmitchell
left a comment
There was a problem hiding this comment.
Verdict: Approved (code) @ bf37c9b
Re-review of bf37c9b (docs only). B1 fixed: CHANGES, v0.6.0.md and README now list zone_get_status and the ack-only follow-up reads, matching REPLY_PUBLICATION_COMMAND_KEYS and _command_needs_reply_publication_wait. B2 fixed: all three files say async_execute returns Result(ok=False, error=...) and only the typed helpers raise. README now names the three new errors. One new should-fix is on elke27#50: the public notes name the private _raise_v2_command_error; name the public helpers instead (for example async_arm_area and zone bypass). The release-date should-fix still applies. Bugbot gate n/a (no code). CI was pending at review time.
…ews) Co-authored-by: Mitch Mitchell <mitchmitchell1616@msn.com>
Claude (hourly) — tip verdict @
|
|
re-review @ 4469e9d — adds Tester 5933494702 should-fixes (no fresh-snapshot claim after publication timeout, per P2 4595731644; both disconnect messages named) and Architect elke27#50 6939690184 (public helpers named instead of the private raise helper; the six named helpers match the six call sites in client.py). |
mitchmitchell
left a comment
There was a problem hiding this comment.
Verdict: Approved (code) @ 4469e9d
Docs-only follow-up checked against src/ at this head: the six named helpers match the six _raise_v2_command_error call sites in client.py, both disconnect messages match client.py (1059 and 2010), subscribe()/events()/EventType.AREA/ZONE exist, and no private helper name is left in README or docs. This closes the elke27#50 item from comment 6939690184 and Tester's 5933494702 should-fixes.
mitchmitchell
left a comment
There was a problem hiding this comment.
Decision 55 Approved (offline only) @ 4469e9d
I checked this head myself, offline only (no hardware). The merge base is 774011385769ce67aa22ef33aede781e874571ee, which is current main.
Release note: the package version comes from the git tag (dynamic = ["version"], no __version__), and this head builds as 0.5.2.dev8+4469e9d. The v0.6.0 tag must go on the merge commit. I accept 2026-11-17 in CHANGES and v0.6.0.md as the planned tag day, but the date must match the day the tag is actually created.
Scope: docs and README only. git diff origin/main...HEAD changes README.md (+20/−6), docs/CHANGES.md and docs/release-notes/v0.6.0.md (new). Nothing changed in src/, test/, pyproject.toml, uv.lock, CI or examples, so I ran no mutants. Since bf37c9b only the same three docs files changed (+21/−15).
Offline gates (fresh Python 3.14.8 venv, uv cache clean elke27 first), compared with main 7740113:
| Gate | 4469e9d | 7740113 |
|---|---|---|
pytest -k "not test_live_e27_" |
1449 passed / 9 skipped / 33 deselected | 1449 / 9 / 33 |
| basedpyright | 0 errors, 0 warnings | 0 errors |
| devtools/lint.py | passed | passed |
| ruff check --no-fix (src, test) / format --check | clean / 251 files | same |
| ruff repo-wide | 6 findings, all in examples/ | same 6 |
| test_review_guards.py and private-access ceilings | 10 passed | 10 passed |
Developer's claims, each checked against src/:
- B1 fixed.
zone_get_statusis listed in CHANGES, v0.6.0.md and README. The code matches:REPLY_PUBLICATION_COMMAND_KEYSincludes it, and_command_needs_reply_publication_waitreturns True for it. The new wording on ack-only writes versus confirmed-status writes also matches. When anarea_set_arm_state/zone_set_statusreply carries confirmed status, that write waits on its own reply. Otherwise the follow-uparea_get_status/zone_get_status(itself anasync_execute) does the waiting. - B2 fixed.
async_executecatchesElke27DisconnectedError/Elke27SnapshotPublicationErrorfrom the publication wait and returns_err(...), which isResult(ok=False, error=...). All three files now say "returns … does not raise". - No fresh-snapshot claim after a timeout. The timeout bullet now says
get_snapshot()may still be stale and points tosubscribe()/events()or another read. I checked that both work the way the docs say:Elke27Client.subscribe(callback: Callable[[Elke27Event], None], *, kinds=None) -> Callable[[], bool]andevents() -> AsyncIterator[Elke27Event]both exist.Elke27EventandEventType(withAREA/ZONE) are exported fromelke27_lib.- Status events are handled on the loop thread (
call_soon_threadsafe(_handle_kernel_event)). Subscriber callbacks run after_replace_snapshot_for_reply_publication.events()consumers resume only after the handler returns. So in both casesget_snapshot()already shows the update when the AREA/ZONE event is delivered.
- Both disconnect messages are named, and both strings match the source exactly.
- Reply still pending:
_disconnected_from_connection_lostgives "Connection lost during the command." (client.py:1059). This is reached from_await_kernel_command_responseonConnectionLost. - Reply in, publication pending:
_fail_all_reply_publication_waiterson disconnect gives "Connection lost while waiting for snapshot publication." (client.py:2010).
- Reply still pending:
- Private helper name replaced.
_raise_v2_command_errorno longer appears in the changed text. The docs name helpers but show no signatures.async_arm_area,async_disarm_area,async_set_zone_bypass,async_set_output,async_set_barrierandasync_refresh_barrierare all publicElke27Clientmethods (Elke27Clientis exported). Each one raises whenasync_executereturns a failedResult.
README matches the code. It names Elke27PanelApplicationFirmwareUnknownError and Elke27NightArmFirmwareTooOldError, which closes #142 S1, and both are exported from elke27_lib. The PanelInfo.application_firmware and 0.0.5.37/app 1317 gate claims match.
Should-fix (non-blocking, docs only):
- README ("Status reads … and ack-only arm or bypass follow-up status reads …
async_executereturnsResult(ok=False, …)when that wait fails") and the matching v0.6.0.md sentence go too far for the ack-only write path. When the follow-up read's publication wait fails,_status_refresh_after_successful_writeswallows it. The outerarea_set_arm_state/zone_set_statusasync_executereturnsResult(ok=True, status_refresh_ok=False), logs a WARNING and marks the area or zone stale. That is the existing contract, already in CHANGES under the status-refresh entry. Fix: say that a failed follow-up read shows up asstatus_refresh_ok=Falseon a successful write Result.ok=Falseapplies only to direct status reads and to writes whose own reply carried confirmed status.
…3568227) Co-authored-by: Mitch Mitchell <mitchmitchell1616@msn.com>
Claude (hourly) — tip verdict @
|
|
re-review @ 2b45917 — Tester 5933568227 should-fix: failed follow-up read after ack-only arm/bypass is documented as Result(ok=True, status_refresh_ok=False) + WARNING + stale; ok=False kept only for publication-wait failures; typed helpers described per client.py (only ARMED_NIGHT arm raises Elke27CommandOutcomeUnknownError; disarm/bypass/other arm modes return, with status_refresh_ok on CommandResult). |
mitchmitchell
left a comment
There was a problem hiding this comment.
Verdict: Changes needed @ 2b45917
Re-review of 4469e9d..2b45917 (README.md, docs/CHANGES.md, docs/release-notes/v0.6.0.md). Checked against src/elke27_lib/client.py at this head.
What's now correct: an ack-only area_set_arm_state / zone_set_status whose follow-up read fails returns Result(ok=True, status_refresh_ok=False), logs a WARNING and marks the area/zone stale (_status_refresh_after_successful_write). async_disarm_area and async_set_zone_bypass return in that case. Only async_arm_area(ArmMode.ARMED_NIGHT) raises Elke27CommandOutcomeUnknownError.
B1 (new in this commit): the scope of the new "ok=False only when the publication wait fails" wording is wrong for ack-only writes.
README.md (around line 258) says that status reads and ack-only arm or bypass follow-up status reads wait for publication, then says async_execute returns Result(ok=False, error=Elke27DisconnectedError | Elke27SnapshotPublicationError) "only when that publication wait fails". docs/CHANGES.md (Status reads #144 bullet) and the error-class paragraph in v0.6.0.md say the same thing without limits. In the code, an ack-only write never returns ok=False for a failed follow-up publication wait. _refresh_snapshot_from_panel_status calls async_execute("area_get_status" | "zone_get_status"). If that nested call's publication wait fails, it comes back as a failed refresh_result, so the write returns ok=True, status_refresh_ok=False (plus WARNING and stale). The outer _await_reply_snapshot_publication / return _err(publication_failed) only runs when _command_needs_reply_publication_wait is true, which for these two commands means the write reply already carried confirmed status. An integrator who reads these docs would expect Elke27SnapshotPublicationError from an ack-only arm or bypass. They will never get it.
Fix: state the two cases in all three files. (a) Direct status reads (area_get_status, zone_get_status, zone_get_all_zones_status), and arm/bypass writes whose reply includes confirmed status, return ok=False with Elke27DisconnectedError or Elke27SnapshotPublicationError when the publication wait fails. (b) For an ack-only arm or bypass, any failure of the follow-up read, including its publication wait, is reported as ok=True, status_refresh_ok=False.
No other findings. Should-fix items stay on #50.
mitchmitchell
left a comment
There was a problem hiding this comment.
Decision 55 Approved (offline only) @ 2b45917
I checked this head myself, offline only (no hardware). The merge base is 774011385769ce67aa22ef33aede781e874571ee, which is current main.
Release sequencing: the RC runs at the untagged merge SHA, which builds as a 0.5.2.devN+<sha> version. The package version comes from the git tag (dynamic = ["version"], no __version__). The v0.6.0 tag goes on that same merge commit after RC PASS. The 2026-11-17 date in CHANGES and v0.6.0.md must match the tag day.
Scope: docs and README only. 4469e9d..2b45917 changes only README.md (+8/−4), docs/CHANGES.md (+14/−10) and docs/release-notes/v0.6.0.md (+16/−8). Against main, origin/main...HEAD changes only those three files. Nothing changed in src/, test/, pyproject.toml, uv.lock, CI or examples, so I ran no mutants.
Offline gates (fresh Python 3.14.8 venv, uv cache clean elke27 first), compared with main 7740113:
| Gate | 2b45917 | 7740113 |
|---|---|---|
pytest -k "not test_live_e27_" |
1449 passed / 9 skipped / 33 deselected | 1449 / 9 / 33 |
| basedpyright | 0 errors, 0 warnings | 0 errors |
| devtools/lint.py | passed | passed |
| ruff check --no-fix (src, test) / format --check | clean / 251 files | same |
| ruff repo-wide | 6 findings, all in examples/ | same 6 |
| test_review_guards.py and private-access ceilings | 10 passed | 10 passed |
New status_refresh_ok wording, checked against client.py. It is correct:
async_executeline 3584 returns_ok(response_payload, status_refresh_ok=status_refresh_ok)._status_refresh_after_successful_writereturnsFalsewhen the follow-uparea_get_status/zone_get_statusfails, including a publication-wait failure inside that read. It also logs a WARNING ("Panel accepted %s but follow-up status read failed") and calls_mark_area_stale/_mark_zone_stale. The write's Result staysok=True. This closes my 4469e9d should-fix.async_disarm_areaandasync_set_zone_bypassdo not raise onstatus_refresh_ok=False. Withreturn_result=Truethey returnCommandResult(status_refresh_ok=...).CommandResultis exported fromelke27_lib.async_arm_area(mode=ArmMode.ARMED_NIGHT)raisesElke27CommandOutcomeUnknownError(("area", "set_arm_state"), ...)whenstatus_refresh_ok is False(client.py ~2888). This is inside theif mode is ArmMode.ARMED_NIGHTbranch only.ok=FalsewithElke27DisconnectedError/Elke27SnapshotPublicationErrorhappens only when the command's own publication wait fails (client.py ~3574–3583). That covers direct status reads and writes whose reply carried confirmed status. It matches the docs.
Is ARMED_NIGHT really the "only" path for Elke27CommandOutcomeUnknownError? I grepped every raise site in src/:
- client.py ~2890,
async_arm_area: raised whenstatus_refresh_ok is False. ARMED_NIGHT only. - client.py ~2777,
_raise_if_night_arm_ignored(#142): the panel acked, but the area is missing from the snapshot after refresh. The only caller is the ARMED_NIGHT branch (~2895). ARMED_NIGHT only. - client.py ~974–1042,
_outcome_unknownin_await_kernel_command_response: the frame was confirmed sent, but no reply came (deadline, reply timeout or caller cancel) on any non-read-only route. It comes back asResult(ok=False, error=Elke27CommandOutcomeUnknownError)._raise_v2_command_errorre-raises it as-is (it is anElke27Error) from every typed write helper: arm Away/Stay/Night, disarm, bypass,async_set_output,async_set_barrier. On caller cancel, theCancelledErroris chained from it. Theasync_set_barrierdocstring says so explicitly.
So "only ARMED_NIGHT" is true for the status_refresh_ok=False case, which is how the new text scopes it. It is not true for Elke27CommandOutcomeUnknownError overall. The docs as written don't claim the general "only": the no-reply case is already in CHANGES (#35, and the 0.5.x entries at lines ~345/~474), and "other helpers raise when async_execute returns ok=False" covers it. Nothing is wrong enough to block.
Should-fix (non-blocking, docs only):
- The ARMED_NIGHT trigger is incomplete. CHANGES (line ~30) and v0.6.0.md "Upgrade notes" name only
status_refresh_ok=False. Site 2 also raises the same error on ARMED_NIGHT when the refresh succeeded but the area is missing from the snapshot. Fix: add "or the area is missing from the snapshot after the refresh". - Arm Away/Stay is missing from the non-raising list. With
status_refresh_ok=False,async_arm_areainARMED_AWAY/ARMED_STAYalso returns without raising, the same as disarm and bypass. The three files list onlyasync_disarm_areaandasync_set_zone_bypass. Fix: name "async_arm_areain Away/Stay" alongside them. - The error-table row is labelled "(failed night refresh)". Fix: relabel it "(night refresh failed or missing; or no reply after send on any write)" so the label isn't read as "only".
- Scope of "ok=False only when the publication wait fails". This is the same issue as the Codex review at this SHA. I count it as an ambiguity rather than a blocker, because all three files also say outright that an ack-only arm or bypass whose follow-up read fails returns
Result(ok=True, status_refresh_ok=False). The README also adds "(not when the write succeeded but the follow-up read failed)". Still, "that publication wait" in README, and the unqualified sentence in CHANGES and in the v0.6.0.md error paragraph, could be read as covering the follow-up read's wait. That nestedasync_executedoes fail withok=False, but_status_refresh_after_successful_writeturns it intostatus_refresh_ok=Falseon the write'sok=TrueResult. Fix: split the two cases.ok=Falseapplies to direct status reads and to writes whose reply carried confirmed status. For an ack-only write, every follow-up failure, publication wait included, shows up asok=True, status_refresh_ok=False.
…33614663, 5933633496) Co-authored-by: Mitch Mitchell <mitchmitchell1616@msn.com>
Claude (hourly) — tip verdict @
|
|
re-review @ c29f1cb — Architect 5933614663 B1 (two cases: direct reads and confirmed-status writes return ok=False on publication failure; ack-only follow-up failures, including the nested publication wait, give ok=True/status_refresh_ok=False) in README, CHANGES, v0.6.0.md; Tester 5933633496 should-fixes (ARMED_NIGHT missing-area trigger, Away/Stay return without raising, table label, refresh-failed scope vs no-reply path). |
mitchmitchell
left a comment
There was a problem hiding this comment.
Verdict: Approved (code) @ c29f1cb
B1 from 5933614663 is fixed: README, CHANGES and v0.6.0.md now split (a) direct reads and confirmed-status writes (ok=False on publication failure) from (b) ack-only follow-ups (ok=True, status_refresh_ok=False). This matches client.py. Tester's should-fixes match the code too: the ARMED_NIGHT missing-area raise, Away/Stay returning without raising, and the no-reply path through result.ok. One wording should-fix is on elke27#50; it doesn't block.
mitchmitchell
left a comment
There was a problem hiding this comment.
Decision 55 Approved (offline only) @ c29f1cb
I checked this head myself, offline only (no hardware). The merge base is 774011385769ce67aa22ef33aede781e874571ee, which is current main.
Release sequencing: the RC runs at the untagged merge SHA, which builds as a 0.5.2.devN+<sha> version. The package version comes from the git tag (dynamic = ["version"], no __version__). The v0.6.0 tag goes on that same merge commit after RC PASS. The 2026-11-17 date in CHANGES and v0.6.0.md must match the tag day.
Scope: docs and README only. 2b45917..c29f1cb changes only README.md (+18/−14), docs/CHANGES.md (+20/−19) and docs/release-notes/v0.6.0.md (+57/−36). origin/main...HEAD changes only those three files. Nothing changed in src/, test/, pyproject.toml, uv.lock, CI or examples, so I ran no mutants.
Offline gates (fresh Python 3.14.8 venv, uv cache clean elke27 first), compared with main 7740113:
| Gate | c29f1cb | 7740113 |
|---|---|---|
pytest -k "not test_live_e27_" |
1449 passed / 9 skipped / 33 deselected | 1449 / 9 / 33 |
| basedpyright | 0 errors, 0 warnings | 0 errors |
| devtools/lint.py | passed | passed |
| ruff check --no-fix (src, test) / format --check | clean / 251 files | same |
| ruff repo-wide | 6 findings, all in examples/ | same 6 |
| test_review_guards.py and private-access ceilings | 10 passed | 10 passed |
Should-fixes from 5933633496, each checked against client.py:
- #142 missing-area trigger: fixed. README, CHANGES and v0.6.0.md "Upgrade notes" now say ARMED_NIGHT also raises
Elke27CommandOutcomeUnknownErrorwhen the area is missing from the snapshot after refresh. That matches_raise_if_night_arm_ignored(~2774–2780). Its only caller is theArmMode.ARMED_NIGHTbranch ofasync_arm_area(~2895). - Away/Stay don't raise: fixed and correct. In
async_arm_area, thestatus_refresh_ok is Falseraise (~2888) and the missing-area check both sit insideif mode is ArmMode.ARMED_NIGHT. Away and Stay fall through toreturn_result/None. All three files now list Away/Stay with disarm and bypass as not raising. - Table label: fixed. It now reads "(ARMED_NIGHT: failed refresh or area missing after refresh; also no-reply on write helpers)". That covers all three raise sites.
- Two-case
ok=Falsesplit (Codex B1, 5933614663): fixed and correct in all three files.- (a)
_command_needs_reply_publication_waitis True for directarea_get_status/zone_get_status/zone_get_all_zones_status. Forarea_set_arm_state/zone_set_statusit is True only when_command_reply_includes_confirmed_status. A failure in that wait returns_err(...), which isok=FalsewithElke27DisconnectedError/Elke27SnapshotPublicationError(~3574–3583). - (b) For ack-only writes, the outer wait is skipped.
_status_refresh_after_successful_writeruns the nestedasync_execute("area_get_status" | "zone_get_status")through_refresh_snapshot_from_panel_status. Any non-ok nested Result is turned intostatus_refresh_ok=False, including a nested publication-wait_err, a transport error, or a hit on the write deadline. It also logs a WARNING and marks the entity stale, and the outer call returns_ok(response_payload, status_refresh_ok=...)(~3584).
- (a)
No-reply caveat (~974–1042): accurate. _outcome_unknown builds Elke27CommandOutcomeUnknownError(route, ...) only when a route is passed and kernel.was_request_sent(seq) holds.
- The single-response
async_executepath (~3517) passesroute=NoneforREAD_ONLY_ROUTESand passes(domain, command)for writes. So it applies to the write helpers (arm, disarm, bypass,async_set_output,async_set_barrier) and not to reads. - On deadline or reply timeout it comes back as
ok=False._raise_v2_command_errorre-raises it unchanged because it is anElke27Error, so "write helpers raise via theresult.okcheck" is correct.
Optional nits (non-blocking):
- Caller cancellation after a confirmed send raises
asyncio.CancelledErrorchained fromElke27CommandOutcomeUnknownError(~1021–1025, ~1032–1039). It is not returned asok=False. The new text describes only theok=Falsecase. That is fine for this release, but a half-sentence would make it complete. - In case (b), if the nested follow-up read's own publication wait times out without failing, the nested Result is
ok=True. The write then reportsstatus_refresh_ok=Trueeven thoughget_snapshot()may still lag. That is the case (a) timeout rule applied to the nested read. The (a) timeout bullet ("may still show stale state … usesubscribe()/events()") could say it applies to ack-only follow-up reads too.
mitchmitchell
left a comment
There was a problem hiding this comment.
Docs-only release cut; checked the error hierarchy table and the new exports against errors.py / __init__.py at this head and they match.
- The status-publication (a)/(b) text now lives almost verbatim in README, CHANGES and the release notes. Can the README keep a two-line summary and link to
docs/release-notes/v0.6.0.md? Three copies will drift the next time this behavior changes.
No blocking findings.
Verdict: APPROVED @ c29f1cb
joostlek-style review via Claude
Generated by Claude Code
| `reason`, and a warning log) when the panel answers with a non-zero | ||
| `error_code`, including single and paged responses. Helpers that already | ||
| mapped panel errors via `_raise_v2_command_error` are unchanged. | ||
| mapped panel errors; public typed command helpers are unchanged. |
There was a problem hiding this comment.
This sentence reads broken after the semicolon, and it rewrites a 0.5.0-era entry. Maybe just:
| mapped panel errors; public typed command helpers are unchanged. | |
| mapped panel errors (the public typed command helpers) are unchanged. |
Generated by Claude Code
|
@cursor review |
There was a problem hiding this comment.
✅ Bugbot reviewed your changes and found no new issues!
Comment @cursor review or bugbot run to trigger another review on this PR
Reviewed by Cursor Bugbot for commit c29f1cb. Configure here.
Docs-only 0.6.0 release cut. No version bumps, tags, or GitHub release.
Changes
docs/CHANGES.md: rename Unreleased to Area Delay, Arm Night Stay Instant, Status Read Publication (0.6.0, 2026-11-17) with entries for Area DelayState for entry/exit delay (#92) #141 (delay state), Map arm night to Stay Instant (ARMED_STAY_INST), firmware 0.5.37+ #140/Arm night follow-ups from #140 (Stay Instant deferred items) #142 (arm night Stay Instant + new errors), and Wait for snapshot publication on area/zone status reads #144 (status-read snapshot publication).docs/release-notes/v0.6.0.md: minor-release notes with upgrade section (Stay Instant firmware 0.0.5.37+, error class bases fromsrc/elke27_lib/errors.py, status-read publication behavior fromclient.py), new public fields, and compare link.Verification (branch)
Note
Low Risk
Documentation-only PR with no runtime or API implementation changes in the diff.
Reviewed by Cursor Bugbot for commit c29f1cb. Bugbot is set up for automated code reviews on this repo. Configure here.