Every public callable says what it is for

The 46 missing docstrings, written rather than generated.

Most of the test ones already carried the explanation — as a comment sitting on
the first line of the body. That prose is the docstring; it was only in the
wrong place, so the config editor's PIN and lane tests keep their own words and
lose the duplicate comment. The rest are new: the two `repo` fixtures, the
counting `FakeDevice` in `test_device_state` (each method now says what it
answers *and* that it counts the call), the PicoCalc chrome and 16-slot theme
tests, and three one-offs.

In the package: `PathLine` and `FastRenderer`'s constructors point at the class
docstring that already documents their arguments rather than repeating it,
`SelectItem.__post_init__` and `courier_screen`'s opener say what they cache and
why, and `emoji_width.create_content` explains the memo it wraps the line lookup
in. `flash.py` and `uart1-mux.py` get theirs too, and `tests/__init__.py`
finally says what the package is.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Jean-Pierre MartineauandClaude Opus 5 committed 2026-09-06 20:28:01 -04:00
1 parent b5006cc415
commit 4545173c65
17 files changed
+152 -26

No files matched your search

+5
View File
@@ -181,6 +181,11 @@ class CourierOutboxScreen(SelectScreen):
"""
def __init__(self, ctx: AppContext, *, default: Any = None) -> None:
"""Open the outbox on the store's current entries, remembering their shape.
The remembered shape is what :meth:`refresh` compares against, so a tick that
changed nothing leaves the highlight exactly where the reader put it.
"""
self._ctx = ctx
self._shape = self._fingerprint()
super().__init__(
+4
View File
@@ -415,6 +415,10 @@ class PathLine:
separator: str = _ARROW,
empty: str = "direct",
) -> None:
"""Hold the hops and the drawing choices; nothing is measured or drawn yet.
Every argument is described in the class docstring above.
"""
self._hops = list(hops)
self._mode = mode
self._separator = separator
+6
View File
@@ -617,6 +617,12 @@ class ClusterTextControl(FormattedTextControl):
"""
def create_content(self, width: int, height: int | None): # type: ignore[override]
"""The base class's content, with each line's ZWJ sequences joined into one glyph.
The joining is wrapped around the returned object's line lookup and memoised
behind it, because prompt_toolkit hands back the same content object paint after
paint — walking every line of every frame would cost far more than it saves.
"""
content = super().create_content(width, height)
# The base class caches its ``UIContent`` per (fragments, width, cursor), so the same
# object comes back paint after paint: wrap its line lookup once, and memoise the merge
+5
View File
@@ -69,6 +69,11 @@ class FastRenderer(Renderer):
"""
def __init__(self, *args, frame_source: Callable[[], str | None], **kwargs) -> None:
"""Wrap the stock renderer, starting with no remembered frame.
With nothing to compare against, the first paint is always a full one; the
``frame_source`` argument is described in the class docstring above.
"""
super().__init__(*args, **kwargs)
self._frame_source = frame_source
self._prev_rows: list[str] | None = None
+1
View File
@@ -83,6 +83,7 @@ class Choice:
hscroll_from: int = 0
def __post_init__(self) -> None:
"""Read the title callable's arity once, so no paint has to ask again."""
# The callable form's arity, read once — see _wants_width.
self._title_wants_width = callable(self.title) and _wants_width(self.title)
+6
View File
@@ -118,6 +118,12 @@ def check_drive_is_ours(drive, force=False):
def main():
"""Put the XIAO in its bootloader and copy the firmware onto the drive it exposes.
Takes the .uf2 to flash, defaulting to the one built beside this script, and
refuses to write to a drive that turns out to be some other board unless
``--force`` says otherwise.
"""
args = [a for a in sys.argv[1:] if a != "--force"]
force = "--force" in sys.argv[1:]
uf2 = args[0] if args else os.path.join(HERE, "meshcore-xiao-radio.uf2")
+10
View File
@@ -30,6 +30,11 @@ UART1_RX_SIG = 0x02
def poke(addr: int, value: int) -> None:
"""Write one 32-bit word to a physical address, through a one-page /dev/mem map.
Needs root, and the address must be a register: this maps the page it falls in and
writes straight to it.
"""
page = addr & ~0xFFF
off = addr - page
fd = os.open("/dev/mem", os.O_RDWR | os.O_SYNC)
@@ -44,6 +49,11 @@ def poke(addr: int, value: int) -> None:
def main() -> None:
"""Point the two pads at UART1 and switch them to matrix mode.
The four writes are the whole job, and re-running them changes nothing, so this is
safe to run on every boot. See the module docstring for the register layout.
"""
poke(RMIO + 0x80 + 0 * 4, (0x7F << 16) | UART1_TX_SIG) # gpio0-0 -> UART1 TX
poke(RMIO + 0x80 + 1 * 4, (0x7F << 16) | UART1_RX_SIG) # gpio0-1 -> UART1 RX
poke(PMU + 0x00, (0xFF << 16) | 0x77) # iomux pins 0,1 -> matrix mode (7)
+1
View File
@@ -0,0 +1 @@
"""The MeshTerm test suite."""
+1
View File
@@ -67,6 +67,7 @@ class _StubContext:
@pytest.fixture()
def repo(tmp_path: Path) -> Repository:
"""A Repository on a scratch database, closed when the test finishes."""
r = Repository(tmp_path / "chat.db")
yield r
r.close()
+63 -24
View File
@@ -103,21 +103,25 @@ def _table_lines(width: int, **kwargs: Any) -> list[str]:
def test_config_table_gives_the_description_lane_the_widest_share() -> None:
"""DESCRIPTION takes the widest lane, because it carries the widest content.
Sizing the other two lanes to their content and leaving DESCRIPTION the remainder
gave it 19 of the 72 cells, and every explanation wrapped three deep.
"""
lines = _table_lines(72)
header = next(line for line in lines if line.lstrip().startswith("SETTING"))
setting = header.index("CURRENT")
current = header.index("DESCRIPTION") - setting
description = 72 - header.index("DESCRIPTION")
# DESCRIPTION carries the systematically widest content, so it takes the widest lane
# — not what two lanes that sized themselves to their content left over. Its share
# used to be 19 of the 72 cells, and every explanation wrapped three deep.
assert description >= setting > current
assert description >= 26
def test_config_table_keeps_every_row_within_three_lines() -> None:
# The whole point of the reallocation: no setting's explanation sprawls further than
# three lines at the readability standard.
"""No setting's explanation sprawls further than three lines at the readable width.
That is the whole point of the reallocation.
"""
lines = _table_lines(72)
body = [line for line in lines if line.strip() and not line.startswith("──")]
runs, run = [], 0
@@ -132,8 +136,11 @@ def test_config_table_keeps_every_row_within_three_lines() -> None:
def test_config_table_drops_the_description_lane_where_it_cannot_fit() -> None:
# PicoCalc's 53 columns hold the setting and its value and nothing more; the labels
# keep their natural width there, nothing competing for the cells.
"""At 53 columns the description lane is dropped rather than squeezed.
The setting and its value are all that fit, and with nothing competing for the
cells the labels keep their natural width.
"""
set_platform(PICOCALC)
try:
lines = _table_lines(PICOCALC.readable_cols)
@@ -146,7 +153,7 @@ def test_config_table_drops_the_description_lane_where_it_cannot_fit() -> None:
def test_config_table_drops_the_description_lane_beside_a_staged_column() -> None:
# Three narrow lanes leave no room for prose, so the staged view is values alone.
"""A staged column costs the description lane too: three narrow lanes leave no room."""
lines = _table_lines(72, pending={"tx_power": 14})
header = next(line for line in lines if line.lstrip().startswith("SETTING"))
assert "STAGED" in header and "DESCRIPTION" not in header
@@ -180,7 +187,10 @@ def _info_screen(snapshot: dict) -> DeviceInfoScreen:
def test_the_pin_is_bullets_until_it_is_asked_for() -> None:
# One bullet per digit — the app's own mask glyph, the one a password prompt types in.
"""The PIN reads as bullets until something asks for it.
One bullet per digit, in the app's own mask glyph — the one a password prompt types.
"""
masked = _pin_row(_table_lines(72))
assert f"{MASK_MARK * 6}" in masked
assert "123456" not in masked
@@ -188,8 +198,11 @@ def test_the_pin_is_bullets_until_it_is_asked_for() -> None:
def test_the_mask_shows_the_field_not_the_pins_length() -> None:
# A stored secret draws its field: a one-digit PIN behind one bullet would have told
# you how many digits to guess (and read as a stray dot besides).
"""The mask draws the field's width, not the PIN's.
A one-digit PIN behind a single bullet would tell you how many digits to guess —
and would read as a stray dot besides.
"""
short = {**_SNAPSHOT, "ble_pin": 0}
console = Console(
width=72, file=io.StringIO(), theme=active_theme(), legacy_windows=False
@@ -200,7 +213,10 @@ def test_the_mask_shows_the_field_not_the_pins_length() -> None:
def test_a_device_with_no_pin_has_nothing_to_conceal() -> None:
# "?" is an absence, not a secret: masking it would claim there is something behind it.
"""A device with no PIN shows ``?`` unmasked.
An absence is not a secret, and masking it would claim there is something behind it.
"""
snapshot = {k: v for k, v in _SNAPSHOT.items() if k != "ble_pin"}
console = Console(
width=72, file=io.StringIO(), theme=active_theme(), legacy_windows=False
@@ -212,6 +228,7 @@ def test_a_device_with_no_pin_has_nothing_to_conceal() -> None:
def test_the_chord_uncovers_the_pin_and_puts_it_back() -> None:
"""The reveal chord uncovers the PIN, and the same key puts it away again."""
screen = _info_screen(_SNAPSHOT)
assert MASK_MARK in _pin_row(screen.render_body(72))
@@ -223,7 +240,10 @@ def test_the_chord_uncovers_the_pin_and_puts_it_back() -> None:
def test_the_lane_chip_and_the_key_are_one_behaviour() -> None:
# The PicoCalc's chip dispatches the action the letter does, not a second copy of it.
"""The PicoCalc's lane chip runs the action the letter runs, and relabels with it.
One behaviour reached two ways, not a second copy of it.
"""
screen = _info_screen(_SNAPSHOT)
assert screen.fkey_lane[2].label == "Reveal"
@@ -233,6 +253,7 @@ def test_the_lane_chip_and_the_key_are_one_behaviour() -> None:
def test_the_footer_names_what_the_press_would_do_now() -> None:
"""The footer says what the key would do now: show while hidden, hide while shown."""
screen = _info_screen(_SNAPSHOT)
assert f"{REVEAL_KEY} show PIN" in screen.footer_hint
screen.handle("reveal")
@@ -240,8 +261,11 @@ def test_the_footer_names_what_the_press_would_do_now() -> None:
def test_a_page_with_no_pin_advertises_no_key_for_it() -> None:
# The standing rule: a footer never names a key that would do nothing, and a lane slot
# for an action this screen doesn't have stays empty rather than dim.
"""A page with no PIN advertises no key for it, in the footer or on the lane.
The standing rule: a footer never names a key that would do nothing, and a lane
slot for an action this screen does not have stays empty rather than dim.
"""
screen = _info_screen({k: v for k, v in _SNAPSHOT.items() if k != "ble_pin"})
assert "PIN" not in screen.footer_hint
assert screen.fkey_lane[2] is None
@@ -250,7 +274,10 @@ def test_a_page_with_no_pin_advertises_no_key_for_it() -> None:
def test_uncovering_the_pin_keeps_the_reader_where_they_were() -> None:
# Nothing reflows — six cells become six cells — so the scroll must not jump.
"""Uncovering the PIN leaves the scroll where the reader put it.
Nothing reflows — six cells become six cells — so nothing should move.
"""
screen = _info_screen(_SNAPSHOT)
screen.note_viewport(10)
screen.render_body(72)
@@ -275,16 +302,21 @@ def _editor(snapshot: dict, pending: dict | None = None) -> _ConfigMenu:
def test_the_editor_masks_the_pin_row_too() -> None:
# The same value on the page next door: concealed on the same terms, or the reader
# only has to walk one menu over to undo it.
"""The editor conceals the same value on the same terms as the page next door.
Otherwise the reader only has to walk one menu over to undo it.
"""
menu = _editor(_SNAPSHOT)
assert MASK_MARK in _pin_row(menu.render_body(72))
assert "123456" not in _pin_row(menu.render_body(72))
def test_a_staged_pin_is_concealed_as_well_as_the_saved_one() -> None:
# A PIN typed a moment ago is still a PIN; a row that uncovered itself the instant it
# was edited would leave the secret up for the rest of the staging session.
"""A PIN typed a moment ago is concealed too, staged and saved alike.
A row that uncovered itself the instant it was edited would leave the secret up
for the rest of the staging session.
"""
menu = _editor(_SNAPSHOT, {"device_pin": 424242})
row = _pin_row(menu.render_body(72))
assert f"{MASK_MARK * 6} → {MASK_MARK * 6}" in row
@@ -293,8 +325,11 @@ def test_a_staged_pin_is_concealed_as_well_as_the_saved_one() -> None:
def test_the_editor_reveals_on_the_same_chord_as_the_info_page() -> None:
# One key for the concept, both places — the editor's letters are find-as-you-type,
# which is why it can't be a bare one.
"""The editor reveals on the same chord as the info page: one key for the concept.
It has to be a chord rather than a bare letter, because the editor's letters are
find-as-you-type.
"""
menu = _editor(_SNAPSHOT)
assert f"{REVEAL_KEY} show PIN" in menu.footer_hint
assert menu.fkey_lane[2].label == "Reveal"
@@ -306,8 +341,11 @@ def test_the_editor_reveals_on_the_same_chord_as_the_info_page() -> None:
def test_revealing_keeps_the_filter_and_the_row_the_reader_was_on() -> None:
# The rows are data, so the toggle refreshes them in place rather than rebuilding the
# screen under a reader who had narrowed it and picked a row.
"""Revealing keeps the typed filter and the row the reader had picked.
The rows are data, so the toggle refreshes them in place rather than rebuilding
the screen under a reader who had narrowed it.
"""
menu = _editor(_SNAPSHOT)
for ch in "telemetry":
menu.handle("text", ch)
@@ -320,6 +358,7 @@ def test_revealing_keeps_the_filter_and_the_row_the_reader_was_on() -> None:
def test_an_editor_over_a_device_with_no_pin_offers_no_reveal() -> None:
"""An editor over a device with no PIN offers no reveal either, footer or lane."""
menu = _editor({k: v for k, v in _SNAPSHOT.items() if k != "ble_pin"})
assert "PIN" not in menu.footer_hint
assert menu.fkey_lane[2] is None
+17 -2
View File
@@ -22,6 +22,7 @@ class FakeDevice:
"""A stand-in device that counts how often each cached read hits the wire."""
def __init__(self) -> None:
"""Start with every call count at zero and no fixed contact table."""
self.contacts_calls = 0
self.self_info_calls = 0
self.mode_calls = 0
@@ -30,6 +31,11 @@ class FakeDevice:
self.contact_rows: list[Contact] | None = None # fixed table, when a test needs one
async def get_contacts(self) -> list:
"""The contact list, counting the call.
Either the fixed table a test installed, or a single contact whose name carries
the call number — so a second read is visible in what comes back.
"""
self.contacts_calls += 1
if self.contact_rows is not None:
return list(self.contact_rows)
@@ -37,22 +43,31 @@ class FakeDevice:
return [Contact(name=f"contact-{self.contacts_calls}")]
async def get_self_info(self) -> dict:
"""A fixed self-description, counting the call."""
self.self_info_calls += 1
return {"name": "node", "tx_power": 20}
async def get_path_hash_mode(self) -> int:
"""A fixed path hash mode, counting the call."""
self.mode_calls += 1
return 2
async def get_channel(self, idx: int):
# One configured slot at index 0, then the firmware "rejects" index 1 to end the probe.
"""One configured slot at index 0, then a raised error, counting each call.
Refusing the next index is how the firmware answers a slot it does not have,
and it is what stops the caller walking past the last one.
"""
self.channel_calls += 1
if idx == 0:
return {"channel_name": "public", "channel_secret": b"\x00" * 16}
raise RuntimeError("out of range")
async def channel_capacity(self) -> int:
# A fixed hardware constant; the cache must read it exactly once for the session.
"""The slot count, counting the call.
A fixed hardware constant, so the cache must read it exactly once per session.
"""
self.capacity_calls += 1
return 8
+1
View File
@@ -76,6 +76,7 @@ def test_section_heading_wears_the_dashes_and_accent() -> None:
def test_changes_phrase_pluralizes() -> None:
"""One staged change is singular; any other count is plural."""
assert changes_phrase(1) == "1 staged change"
assert changes_phrase(2) == "2 staged changes"
+1
View File
@@ -11,6 +11,7 @@ def _reset() -> None:
def test_shift_down_reflects_the_raw_flag() -> None:
"""``shift_down()`` reports the flag the watcher last set, with nothing in between."""
_reset()
try:
assert modifier_watch.shift_down() is False
+1
View File
@@ -62,6 +62,7 @@ def _sgr(rgb: tuple[int, int, int]) -> str:
def test_no_layers_render_nothing() -> None:
"""Nothing to draw means no rows at all, not a blank canvas."""
assert render_path_graph(
[], 60, glyph_of=_glyph, label_of=lambda n: None, label_rgb_of=lambda n: WHITE
) == []
+17
View File
@@ -32,6 +32,11 @@ def _slot_style(row: Text, index: int) -> str:
def test_borderless_frame_swaps_the_panel_for_a_title_bar() -> None:
"""On the PicoCalc there is no Panel; a one-row title bar stands in for the whole border.
It carries the rule, the title, and the clip arrow. No border column is spent, so the
body starts at column 0 and owns all 53 cells.
"""
set_platform(PICOCALC)
composed = frame.compose_base(Text("hdr"), _screen(), "hint", 53, 26).split("\n")
assert len(composed) == 26
@@ -136,6 +141,7 @@ def test_the_esc_hint_gives_way_before_it_crowds_the_title() -> None:
def test_bordered_frame_is_unchanged_on_regular() -> None:
"""Regular keeps its Panel — the borderless frame is the console's shape, not the app's."""
set_platform(REGULAR)
composed = frame.compose_base(Text("hdr"), _screen(), "hint", 72, 24).split("\n")
plain = [_plain(line) for line in composed]
@@ -171,6 +177,11 @@ def test_picocalc_header_brands_the_app_not_the_device() -> None:
def test_fkey_lane_resolution_and_banks() -> None:
"""What the shared lane claims, and what it leaves alone.
The pager takes F4/F5, each jump rides the Shift half of the pager heading for it,
F1-F3 stay free for the screen's own verbs, and neither Enter nor Esc takes a slot.
"""
lane = DEFAULT_LANE
# F4/F5 (paging — no physical key at all) carry the pager, and each jump rides the
# Shift half of the very pager heading for it: Home behind Page ↑, End behind Page ↓.
@@ -185,6 +196,11 @@ def test_fkey_lane_resolution_and_banks() -> None:
def test_fkey_lane_text_fits_and_flips() -> None:
"""The lane fills exactly 53 cells in both banks, and a long label is clipped, not wrapped.
The directional pair rises toward its outer key, and a free slot draws as a bare
key number rather than an empty gap.
"""
primary = lane_text(DEFAULT_LANE)
shifted = lane_text(DEFAULT_LANE, shifted=True)
assert cell_len(primary.plain) == 53 and cell_len(shifted.plain) == 53
@@ -339,6 +355,7 @@ def test_host_battery_reads_the_sysfs_supply(tmp_path, monkeypatch) -> None:
def test_dialog_gate_shrinks_on_picocalc() -> None:
"""A dialog is allowed fewer cells on the PicoCalc, the screen being narrower."""
from meshterm.ui.surface import _dialog_max_cells
set_platform(PICOCALC)
+1
View File
@@ -13,6 +13,7 @@ from meshterm.persistence.repository import Repository
@pytest.fixture()
def repo(tmp_path: Path) -> Repository:
"""A Repository on a scratch database, closed when the test finishes."""
r = Repository(tmp_path / "test.db")
yield r
r.close()
+12
View File
@@ -155,6 +155,11 @@ def test_glyph_map_targets_never_widen_their_icon() -> None:
def test_glyph_is_identity_on_regular_and_compact_on_picocalc() -> None:
"""Emoji pass through on regular and become font-native marks on the console.
Node and status marks are in the console font already, so they cross unchanged on
both platforms.
"""
set_platform(REGULAR)
assert glyph("📡") == "📡"
set_platform(PICOCALC)
@@ -174,6 +179,11 @@ def test_fold_is_identity_on_regular_even_after_picocalc_used_it() -> None:
def test_fold_strips_accents_and_preserves_cell_widths() -> None:
"""The fold leaves only characters the console font has, without changing the width.
An accent drops to its base letter and an emoji becomes its mapped mark, each in
place, so nothing downstream has to measure the row again.
"""
set_platform(PICOCALC)
for text in ("café ⚠", "Ĉu vi paroläs", "📡 Advert", "🗑 Clear", "…", "npo Waymarker 🇨🇦"):
folded = fold_text(text)
@@ -190,6 +200,7 @@ def test_fold_replaces_the_unmappable_at_width() -> None:
def test_fold_keeps_ansi_sequences_intact() -> None:
"""The fold rewrites text only: colour escapes and newlines cross it untouched."""
set_platform(PICOCALC)
line = "\x1b[1;93mwarn é\x1b[0m\nnext"
folded = fold_text(line)
@@ -211,6 +222,7 @@ def test_fold_quantizes_embedded_truecolor_to_the_slots() -> None:
def test_fold_drops_zero_width_machinery() -> None:
"""Variation selectors and zero-width joiners are dropped — they have no cell to occupy."""
set_platform(PICOCALC)
assert fold_text("🕸️") == fold_text("🕸")
assert "‍" not in fold_text("a‍b")