Cut the updater session's comments back to what they have to say #71
Loading…
Reference in a new issue
No description provided.
Delete branch "docs/updater-session-comments"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
A comment pass over
updater/session.py,updater/link.py,updater/bus.pyand their two test files. No behaviour change.Narration, restatement and the essays around the spec citations are gone; every spec section number is kept, as a bare citation. Where a comment only existed because the code was unclear, the code moved instead: the build-of-zero rule that was written out three times in two files is now
session.announced_build, whichlink.pyimports.Tests and lint are unchanged in what they cover. Lint keeps
Dselected under thepep257convention, so every module, class and public function still needs a docstring — the shortened ones are cut, not deleted.announced_buildis exactly equivalent at all three sites (x or Nonethenor buildcollapses tox or build), no other behaviour change in the five files, nothing touched outside them, tabs and British English clean, ruff/mypy/pytest green.Two small things, both inline.
@ -5,3 +3,1 @@thread throughout, because a request arrives on one and the session it startsruns on the loop. A test that deadlocked the two would hang rather than fail,so every one of them is waited on with a deadline.No van and no CAN interface; the bus is the session tests' own fake. The API isThe
spec section 11citation that was on this line is gone — the only one dropped in the branch, and the PR body says every one is kept. It still survives onFakeNodeintests/test_updater_session.py, so either put it back here or fix the claim in the description.@ -921,7 +863,6 @@ async def test_credentials_a_node_has_no_room_for_reach_no_node("""Section 8.9 gives 32 bytes to the name and 64 to the key, and they are separate.A node answers result 4, which says only that some node refused something.This paragraph is now a fact with no conclusion: it says result 4 is unspecific and stops, having lost the clause that tied it to
assert named in result.detail. Either drop the paragraph or end it with why the check is local ("so this says which half was wrong").Both earlier findings are fixed. One thing left, and it is prose accuracy rather than code.
@ -1009,3 +948,1 @@Both ends of the range reach it by accident: a deadline under a minuterounds to nothing, and the codec keeps the low byte of one past 255. Eitherwould leave a node's radio up until something else took it down.Both ends reach it by accident: under a minute rounds to nothing, and the"Both ends reach it" is not true of the
past-a-bytecase. The parameter is 9 hours = 540 minutes, and the codec keeps the low byte: 0x1C, 28 minutes, not 0. Only exact multiples of 256 reach 0. The sentence this replaced didn't claim that — it ended "Either would leave a node's radio up until something else took it down", which generalised the harm. Say the truncation gives an arbitrary timeout rather than the one meant, or drop the second half.@ -65,2 +60,2 @@(spec section 8.1), and never past the byte, whose low half is all thecodec keeps. Both are how a deadline meant to be short becomes no deadline.Never 0, which spec section 8.1 reads as the idle timeout never firing, andnever past the byte the codec keeps. Either leaves a node's radio up.Same overclaim, carried over from before this branch rather than introduced by it: "Either leaves a node's radio up" only holds for the wrap-to-zero case; past 255 the truncation usually gives a shorter timeout. Worth fixing while the sentence is being rewritten anyway.
Both
radio_minutesdocstrings now read true against the clamp and againstcodec.encode, which masks a one-byte field withraw & 0xFF. One thing left.@ -404,3 +375,2 @@"sequence": sequence,# The length is what stops the last frame where the# content stops rather than padding it out.# Declared short, so the padding below is not content.Declared short, so the padding below is not content.reads as though the padding goes on the wire and is excluded by the declared length. It doesn't:lengthis the counted field, soMessage.length_forshortens the frame and the zero bytes are never sent. That distinction is the point of the surrounding tests, since padding that did go out would land under the CRC. Say that the length stops the frame where the chunk stops.Round three's point is settled and nothing else is left. The new wording matches
Message.length_forandcodec.encode: passinglengthshortens the frame to2 + len(chunk), and theljustzeros only exist to left-align the six-byte integer, so they are truncated before the frame goes out.