From 6b90e0505b6f91f9f8a4e0582e9bcb6d834cdec6 Mon Sep 17 00:00:00 2001 From: Jean-Pierre Martineau Date: Tue, 6 Oct 2026 03:48:44 -0400 Subject: [PATCH] Docstrings and comments of meshterm/tools are in ASD-STE100 The same rewrite as for the core package. No help= string, epilog, or other UX text changed. Co-Authored-By: Claude Opus 5.5 (1M context) --- meshterm/tools/__init__.py | 14 +- meshterm/tools/about.py | 124 +++--- meshterm/tools/advert.py | 44 +- meshterm/tools/base.py | 215 +++++----- meshterm/tools/channels.py | 153 +++---- meshterm/tools/chat.py | 705 ++++++++++++++++--------------- meshterm/tools/config.py | 301 ++++++------- meshterm/tools/contacts.py | 91 ++-- meshterm/tools/courier.py | 142 ++++--- meshterm/tools/dashboard.py | 45 +- meshterm/tools/devices.py | 122 +++--- meshterm/tools/diagnostics.py | 270 ++++++------ meshterm/tools/info.py | 112 ++--- meshterm/tools/livefeed.py | 44 +- meshterm/tools/map.py | 73 ++-- meshterm/tools/monitor.py | 138 +++--- meshterm/tools/preferences.py | 130 +++--- meshterm/tools/records.py | 122 +++--- meshterm/tools/regions.py | 55 +-- meshterm/tools/repeater_admin.py | 72 ++-- meshterm/tools/rooms.py | 76 ++-- meshterm/tools/timemachine.py | 42 +- meshterm/tools/trace.py | 340 ++++++++------- meshterm/tools/tx_optimize.py | 287 +++++++------ meshterm/tools/walk.py | 54 +-- meshterm/tools/watchtower.py | 49 ++- 26 files changed, 2001 insertions(+), 1819 deletions(-) diff --git a/meshterm/tools/__init__.py b/meshterm/tools/__init__.py index ff7c644..271899d 100644 --- a/meshterm/tools/__init__.py +++ b/meshterm/tools/__init__.py @@ -1,8 +1,9 @@ # SPDX-License-Identifier: Apache-2.0 -"""Pluggable tools (menu options / CLI subcommands). +"""Tools that plug in: the menu items and the CLI subcommands. -Importing this package eagerly imports every tool module so that each one's ``@register`` -decorator populates the shared registry. New features only need to add a module here. +When this package is imported, it imports each tool module immediately. Thus the +``@register`` decorator of each module adds its tools to the shared registry. A new feature +must only add a module here. """ from __future__ import annotations @@ -16,9 +17,10 @@ __all__ = ["Tool", "all_tools", "get_tool", "register", "load_all_tools"] def load_all_tools() -> None: - """Import every sibling module so its tools self-register. + """Import each sibling module, so that its tools add themselves to the registry. - Modules whose names start with an underscore (and ``base``) are skipped. + This function does not import the modules whose names start with an underscore, or + ``base``. """ package = __name__ for mod in pkgutil.iter_modules(__path__): @@ -27,5 +29,5 @@ def load_all_tools() -> None: importlib.import_module(f"{package}.{mod.name}") -# Populate the registry on import so the CLI and menu see every tool. +# Fill the registry when the package is imported, so that the CLI and the menu get each tool. load_all_tools() diff --git a/meshterm/tools/about.py b/meshterm/tools/about.py index 2e5e7e0..ea525e5 100644 --- a/meshterm/tools/about.py +++ b/meshterm/tools/about.py @@ -1,21 +1,21 @@ # SPDX-License-Identifier: Apache-2.0 -"""The About MeshTerm tools: the four written pages in the menu's last section. +"""The About MeshTerm tools: the four written pages in the last section of the menu. -*About MeshTerm*, *About the author*, *Join Discord*, *Support MeshTerm* — in that -order, which is the order a stranger asks the questions in: what is this, who made it, -where is everyone, how do I help. They share the *This app* section with Preferences, -which leads it: the section is the app's own, and the one row that *changes* -MeshTerm sits above the four that describe it. -Each is a page rather than a feature: it reads nothing, transmits nothing, and needs no -device, so it opens straight to its screen (see :mod:`meshterm.ui.about`) instead of -prompting for anything first. +The pages are "About MeshTerm", "About the author", "Join Discord", and "Support +MeshTerm", in that order. A new user asks the questions in the same order: what is this, +who made it, where are the other users, and how can I help. The pages share the "This +app" section with Preferences, which is first in it. The section belongs to the app +itself, and the only row that changes MeshTerm is above the four rows that describe it. +Each item is a page, not a feature. It reads nothing, it transmits nothing, and it does +not use a device. Thus it opens directly to its screen (refer to :mod:`meshterm.ui.about`), +and it does not ask for anything first. -Each also keeps a CLI face — ``meshterm about``, ``meshterm about-author``, -``meshterm discord``, ``meshterm support`` — printing the same page to the terminal, so -the answers are reachable from a shell without launching the full-screen session. +Each page also has a CLI face (``meshterm about``, ``meshterm about-author``, +``meshterm discord``, ``meshterm support``) that prints the same page to the terminal. +Thus a user can get the answers from a shell without the full-screen session. -The pages themselves are written in markdown under ``meshterm/assets/pages`` (see -:mod:`meshterm.ui.about`); nothing here knows what any of them say. +The pages are written in markdown in ``meshterm/assets/pages`` (refer to +:mod:`meshterm.ui.about`). Nothing in this module knows the content of a page. """ from __future__ import annotations @@ -31,34 +31,34 @@ if TYPE_CHECKING: class _AboutTool(Tool): - """Shared behaviour for the four About pages: open the screen, or print the page. + """The shared behaviour of the four About pages: open the screen, or print the page. - The pages differ only in their title, icon, and content, so everything else — the - menu-only screen open, the printing CLI face, the run row — lives here once. A - subclass supplies :meth:`page`, and nothing more. + The pages are different only in their title, icon, and content. Thus all the other + parts (the screen that opens only in the menu, the CLI face that prints, the run row) + are in this class, one time. A subclass gives :meth:`page`, and nothing more. """ category = "This app" @staticmethod def page() -> MarkdownDoc: - """Build this page's content. + """Build the content of this page. - Overridden by each page. Subclasses import their builder *inside* the override - rather than at module scope: the registry imports every tool module at startup - (see :func:`~meshterm.tools.load_all_tools`), and a page's content is only ever - wanted once someone actually opens it. + Each page overrides this method. A subclass imports its builder in the override, + not at module scope. The reason is that the registry imports each tool module at + startup (refer to :func:`~meshterm.tools.load_all_tools`), but the content of a + page is necessary only when a user opens it. """ raise NotImplementedError async def prompt_params(self, ctx: AppContext) -> dict[str, Any] | None: - """Open the page; returning ``None`` completes the invocation with no run row. + """Open the page. The return value ``None`` completes the run with no run row. - The page transmits nothing and stores nothing, so — like the Trophy case and the - mesh walk — it lives here rather than in :meth:`run`, and logs no run of its own. + The page transmits nothing and stores nothing. Thus, as with the Trophy case and + the mesh walk, it opens here, not in :meth:`run`, and it logs no run of its own. Args: - ctx: Shared application context. + ctx: The shared application context. Returns: Always ``None``. @@ -69,18 +69,18 @@ class _AboutTool(Tool): return None async def run(self, ctx: AppContext, params: dict[str, Any]) -> ToolResult: - """State the page — only reachable from the CLI (the menu opens the screen). + """Give the page. Only the CLI comes to this method (the menu opens the screen). - Without its scannable codes: a QR is a second rendering of a link the page already - prints, drawn for a phone pointed at a screen, and redirected into a file it is a - block of block characters around nothing new. + The page has no QR codes here. A QR code is a second rendering of a link that the + page already prints. It is drawn for a phone that points at a screen. In a + redirected file, it is only a mass of block characters, with no new information. Args: - ctx: Shared application context. - params: Unused beyond the injected ``_run_id``. + ctx: The shared application context. + params: Not used, except for the injected ``_run_id``. Returns: - A :class:`ToolResult` naming the page that was shown. + A :class:`ToolResult` that names the page that was shown. """ return ToolResult( summary={"page": self.name}, @@ -90,13 +90,13 @@ class _AboutTool(Tool): @register class AboutMeshTermTool(_AboutTool): - """What MeshTerm is, where it came from, and the terms it ships under.""" + """What MeshTerm is, where it came from, and the terms under which it is distributed.""" name = "about" title = "About MeshTerm" icon = "📖" help = "What this is, and the terms it ships under" - order = 10 # the question a stranger asks first + order = 10 # the first question of a new user @staticmethod def page() -> MarkdownDoc: @@ -108,13 +108,13 @@ class AboutMeshTermTool(_AboutTool): @register class AboutAuthorTool(_AboutTool): - """The person behind MeshTerm, on the mesh and off it.""" + """The person who made MeshTerm, on the mesh and off the mesh.""" name = "about-author" title = "About the author" icon = "👤" help = "The person behind MeshTerm, on and off the mesh" - order = 20 # who made the thing you just read about + order = 20 # who made the app that the previous page describes @staticmethod def page() -> MarkdownDoc: @@ -126,13 +126,13 @@ class AboutAuthorTool(_AboutTool): @register class JoinDiscordTool(_AboutTool): - """The community server: one invite link, and a QR of it for a phone to read.""" + """The community server: one invite link, and its QR code for a phone to read.""" name = "discord" title = "Join Discord" icon = "🔗" help = "The invite link to the MeshTerm community server" - order = 25 # where everyone else is, once you know what this is and who made it + order = 25 # where the other users are, after the user knows what this is and who made it @staticmethod def page() -> MarkdownDoc: @@ -144,13 +144,13 @@ class JoinDiscordTool(_AboutTool): @register class SupportProjectTool(_AboutTool): - """What keeps MeshTerm going, and the ways — paid and unpaid — to help it along.""" + """What MeshTerm needs to continue, and the paid and unpaid ways to help it.""" name = "support" title = "Support MeshTerm" icon = "💰" help = "What keeps MeshTerm going, and how to help" - order = 30 # the ask, and only once the pages before it have earned it + order = 30 # the request for help, only after the pages before it earned it @staticmethod def page() -> MarkdownDoc: @@ -161,20 +161,21 @@ class SupportProjectTool(_AboutTool): def _written_page(name: str, title: str, doc: MarkdownDoc) -> Facts: - """One prose page, stated once for both faces. + """One prose page, given one time for both faces. - **Wrapped**, and that is the one deliberate exception to "no line wrapping". The rule - exists so a *record* is never split across two lines with its fields landing under the - wrong headings; a paragraph has no records and no headings, and left unwrapped these - four pages print as single six-hundred-cell lines no terminal can read. So the page is - drawn on a console :data:`~meshterm.ui.script.PAGE_WIDTH` cells wide — a fixed width, - not the terminal's, so the same paragraph reads the same piped, redirected, or shipped - as the document's ``text``. + The page is **wrapped**. This is the only exception, on purpose, to the "no line + wrapping" rule. The rule makes sure that a record is never divided across two lines, + with its fields under the wrong headings. A paragraph has no records and no headings. + Without a wrap, these four pages print as lines of six hundred cells, and in a + terminal, nobody can read such a line. Thus the page is drawn on a console that is + :data:`~meshterm.ui.script.PAGE_WIDTH` cells wide. This is a fixed width, not the width + of the terminal. Thus the same paragraph looks the same in a pipe, in a redirected + file, or in the ``text`` of the document. - ``links`` is the one machine-actionable thing on a page of prose, and the one thing the - menu bothers to draw a QR of. ``text`` is the page's plain rendering rather than a fold - of the markdown into nested JSON: a structured markdown tree would be a second - rendering, not data, and nothing would consume it. + ``links`` is the only part of a prose page that a program can use, and the only part + that the menu draws as a QR code. ``text`` is the plain rendering of the page, not the + markdown changed into nested JSON. A structured markdown tree is a second rendering, + not data, and no program uses one. """ from .. import __version__ from ..ui import fields @@ -193,8 +194,8 @@ def _written_page(name: str, title: str, doc: MarkdownDoc) -> Facts: values={ "page": name, "title": title, - # Duplicated from the package on purpose: a page's own facts are part of its - # content, and this is the version its `{version}` placeholder resolved to. + # A copy of the package value, on purpose. The facts of a page are part of its + # content, and this is the version that its `{version}` placeholder became. "version": __version__, "text": text, "links": _links(text), @@ -205,7 +206,7 @@ def _written_page(name: str, title: str, doc: MarkdownDoc) -> Facts: def _rendered_page(doc: MarkdownDoc) -> str: - """The page as plain text, folded to the fixed page width.""" + """The page as plain text, wrapped at the fixed page width.""" import io from rich.console import Console @@ -225,11 +226,12 @@ def _rendered_page(doc: MarkdownDoc) -> str: def _links(text: str) -> list[str]: - """Every URL the page carries, in document order, de-duplicated. + """All the URLs on the page, in document order, and each URL one time. - Read off the rendered page rather than the markdown source, so a link written as a - reference and a link written inline both count once and both read as what the reader - sees. Trailing punctuation is not part of a URL and is trimmed. + The function reads the URLs from the rendered page, not from the markdown source. + Thus a reference link and an inline link both count one time, and both are the text + that the user sees. Punctuation at the end is not part of a URL, so the function + removes it. """ import re diff --git a/meshterm/tools/advert.py b/meshterm/tools/advert.py index e7bfef2..23ef42a 100644 --- a/meshterm/tools/advert.py +++ b/meshterm/tools/advert.py @@ -1,14 +1,14 @@ # SPDX-License-Identifier: Apache-2.0 -"""The ``advert`` tool: announce this node to the mesh, straight from the main menu. +"""The ``advert`` tool: announce this node to the mesh, directly from the main menu. -Opens the Send advert flow (see :func:`meshterm.ui.config_editor.send_advert`) — a -zero-hop or flood advertisement, or this node's shareable contact card as a QR code. -A ``popup`` tool: the flow's prompts and result float over the still-pushed main menu -as modal dialogs (the quit-dialog pattern), so the everyday action stays a quick -in-place popup rather than a screen change. +The tool opens the Send advert flow (refer to :func:`meshterm.ui.config_editor.send_advert`): +a zero-hop or flood advert, or the contact card of this node as a QR code to share. It is +a ``popup`` tool. The prompts and the result of the flow float as modal dialogs over the +main menu, which stays pushed (the pattern of the quit dialog). Thus this everyday action +stays a quick dialog in place, not a change of screen. -Menu-only: the scripted equivalents are ``config advert`` and ``config share``, so no -duplicate subcommand is registered here. +Menu only: the scripted equivalents are ``config advert`` and ``config share``, so this +module registers no duplicate subcommand. """ from __future__ import annotations @@ -30,19 +30,19 @@ class SendAdvertTool(Tool): icon = "📡" help = "Announce this node — zero-hop, flood, or QR" category = "This node" - order = 40 # your own node announcing itself: a device action, not a view - popup = True # dialog-sized: float over the menu instead of replacing it + order = 40 # our node announces itself: a device action, not a screen + popup = True # dialog-sized: float over the menu, and do not replace it async def prompt_params(self, ctx: AppContext) -> dict[str, Any] | None: - """Run the interactive advert flow; there are never parameters to collect. + """Run the interactive advert flow. It has no parameters to collect. - The flow presents its own result (the sent-advert note or the contact-card - view) before returning, so by the time the user backs out there is nothing - left for :meth:`run` to do — returning ``None`` tells the menu the invocation - is complete (the same pattern as the Device config page). + The flow shows its own result (the note about the sent advert, or the contact + card) before it returns. Thus, when the user leaves, :meth:`run` has nothing more + to do. The return value ``None`` tells the menu that the run is complete (the + same pattern as the Device config page). Args: - ctx: Shared application context. + ctx: The shared application context. Returns: Always ``None``. @@ -53,20 +53,20 @@ class SendAdvertTool(Tool): return None async def run(self, ctx: AppContext, params: dict[str, Any]) -> ToolResult: - """Nothing runs here: the advert is sent inside :meth:`prompt_params`. + """Nothing runs here: the advert is sent in :meth:`prompt_params`. Args: - ctx: Shared application context. - params: Unused. + ctx: The shared application context. + params: Not used. Returns: - An empty :class:`ToolResult` (only reachable from a scripted call). + An empty :class:`ToolResult` (only a scripted call comes here). """ return ToolResult(summary={}) def register_cli(self, app: typer.Typer) -> None: - """Register no CLI command — ``config advert`` / ``config share`` cover scripting. + """Register no CLI command: ``config advert`` and ``config share`` are for scripts. Args: - app: The Typer application (untouched). + app: The Typer application (not changed). """ diff --git a/meshterm/tools/base.py b/meshterm/tools/base.py index 30676f0..5432270 100644 --- a/meshterm/tools/base.py +++ b/meshterm/tools/base.py @@ -1,10 +1,11 @@ # SPDX-License-Identifier: Apache-2.0 -"""The tool plugin contract and registry. +"""The contract and the registry of the tool plugins. -A *tool* is one menu option / CLI subcommand. Subclass :class:`Tool`, decorate it with -:func:`register`, and implement :meth:`Tool.run`. The same registry drives both the -interactive menu and the Typer CLI, and :meth:`Tool.execute` wraps every invocation in a -logged ``runs`` row, so new tools get persistence and logging for free. +A *tool* is one menu item and one CLI subcommand. To make a tool, subclass :class:`Tool`, +decorate it with :func:`register`, and implement :meth:`Tool.run`. The same registry +controls the interactive menu and the Typer CLI. :meth:`Tool.execute` puts each run of a +tool in a logged ``runs`` row. Thus a new tool gets storage and logging with no more +work. """ from __future__ import annotations @@ -15,7 +16,7 @@ from typing import TYPE_CHECKING, Any from ..core import exitcodes -if TYPE_CHECKING: # avoid importing typer/context at module load for fast startup +if TYPE_CHECKING: # do not import typer or the context at module load, for a fast start import typer from ..context import AppContext @@ -24,34 +25,36 @@ if TYPE_CHECKING: # avoid importing typer/context at module load for fast start @dataclass(slots=True) class ToolResult: - """The outcome of a tool execution. + """The result of a run of a tool. Attributes: - summary: JSON-serializable summary persisted to the run record. - message: Optional human-readable closing message. The *menu's* closing line — a - scripted run does not print it (see + summary: A summary that can be serialized to JSON. It is stored in the record of + the run. + message: An optional closing message for a person. It is the closing line of the + *menu*. A scripted run does not print it (refer to :func:`~meshterm.cli._execute_and_render`), because on the command line it - restates the output above it and the exit status below it. - artifacts: Paths to any files produced (e.g. generated visualizations). - exit_code: The status a scripted run should exit with — see - :mod:`meshterm.core.exitcodes`. Left at ``OK`` by everything that worked; - set to ``NO_RESULT`` by a tool that ran fine and found nothing to report, so - a caller can tell an empty mesh from a full one without counting lines. A - *failure* is raised, not returned, so this never carries one. - report: **The answer**, as data (see :mod:`meshterm.ui.report`). A scripted run - states it here and the CLI boundary hands it to a renderer, exactly as it - already does with ``exit_code`` — the tool says what happened, and something - else turns that into bytes or into a process status. It used to be printed - instead, which meant the answer was gone by the time anything could ask for it - in another format, which is why ``--json`` reached two commands and stopped. + repeats the output above it and the exit status below it. + artifacts: The paths of the files that the tool made (for example, generated + visualizations). + exit_code: The status with which a scripted run must exit. Refer to + :mod:`meshterm.core.exitcodes`. A tool that worked keeps ``OK``. A tool that + ran correctly and found nothing to report sets ``NO_RESULT``. Thus a caller + can tell an empty mesh from a full one, and does not have to count lines. A + *failure* is raised, not returned, so this value never holds one. + report: **The answer**, as data (refer to :mod:`meshterm.ui.report`). A scripted + run puts it here, and the CLI boundary gives it to a renderer. The boundary + does the same with ``exit_code``: the tool says what occurred, and other code + changes that into bytes or into a process status. Before, the tool printed + the answer instead. Then the answer was gone before anything could ask for it + in another format. That is why ``--json`` got to two commands and stopped. - ``None`` for the menu path and for a feature with no scripted face at all (the - map, the dashboard), which keep working unchanged. + ``None`` for the menu path, and for a feature that has no scripted face (the + map, the dashboard). These continue to work with no change. - Not folded into ``summary``: that is the *run log's* record of what this - invocation did, written to the ``runs`` table on every execution including a - menu run. Putting a five-hour ``monitor`` capture in SQLite would be the price - of one field fewer. + It is not part of ``summary``. ``summary`` is the record in the *run log* of + what this run did, and each run writes it to the ``runs`` table, also a menu + run. If ``report`` is part of it, a five-hour ``monitor`` capture goes into + SQLite. That is the cost of one field fewer. """ summary: dict[str, Any] = field(default_factory=dict) @@ -62,27 +65,31 @@ class ToolResult: class Tool(ABC): - """Base class for all MeshTerm features. + """The base class for all MeshTerm features. Class Attributes: - name: CLI identifier (kebab-case), unique across tools. - title: Display name shown as the interactive menu item and on the tool's result - window. Capitalized, and kept identical to the screen the item opens so the - menu never promises one name and delivers another. Falls back to ``name``. - help: One-line description shown in the menu and ``--help`` (no trailing period). - icon: Emoji drawn before the title in the interactive menu (and only there — the - result window keeps the plain title). Single-codepoint, emoji-presentation - glyphs only, so the two-cell width holds across terminals (see - :mod:`meshterm.ui.tui.emoji_width`). - category: Grouping label used to organize the interactive menu. - order: Sort key within a category (lower sorts first). - menu_visible: Whether the tool appears in the interactive menu. Set ``False`` for - CLI-only tools (e.g. startup-time diagnostics with no place in a connected - session); such tools still register a CLI subcommand as usual. - popup: Whether the menu stays pushed while this tool runs, so the tool's prompts - and result float over it as modal popups (the quit-dialog pattern) instead of - replacing the screen. For quick dialog-sized tools; a tool that pushes its - own full screen keeps the default. + name: The CLI identifier (kebab-case). It is unique among the tools. + title: The name that the interactive menu item and the result screen of the tool + show. It starts with a capital letter. It is the same as the name of the + screen that the item opens, so that the menu never shows one name and opens + another. If it is empty, ``name`` is used. + help: The one-line description in the menu and in ``--help`` (with no period at + the end). + icon: The emoji that the interactive menu draws before the title (only there: + the result screen keeps the plain title). Use only glyphs of one code point + with emoji presentation, so that the width of two cells is the same on all + terminals (refer to :mod:`meshterm.ui.tui.emoji_width`). + category: The group label that organizes the interactive menu. + order: The sort key in a category (a lower value comes first). + menu_visible: Whether the tool is in the interactive menu. Set ``False`` for a + tool that is only for the CLI (for example, diagnostics at startup, which + have no place in a connected session). Such a tool registers a CLI + subcommand as usual. + popup: Whether the menu stays pushed while this tool runs. Then the prompts and + the result of the tool float over the menu as modal dialogs (the pattern of + the quit dialog), and do not replace the screen. This is for quick tools of + the size of a dialog. A tool that pushes its own full screen keeps the + default. """ name: str = "" @@ -96,39 +103,40 @@ class Tool(ABC): @abstractmethod async def run(self, ctx: AppContext, params: dict[str, Any]) -> ToolResult: - """Execute the tool's work. + """Do the work of the tool. Args: - ctx: Shared application context (console, device, repository, ...). - params: Validated parameters for this invocation. + ctx: The shared application context (console, device, repository, and other + items). + params: The validated parameters for this run. Returns: - A :class:`ToolResult` describing the outcome. + A :class:`ToolResult` that describes the result. """ async def prompt_params(self, ctx: AppContext) -> dict[str, Any]: - """Interactively gather parameters for the menu. + """Ask the user for the parameters of a menu run. - The default implementation requires no parameters. Tools override this to ask - the user through :attr:`AppContext.ui` — a dialog or a select list in the menu, and - nothing at all on the CLI, where the arguments came off the command line. + The default implementation has no parameters. A tool overrides this method to ask + the user through :attr:`AppContext.ui`: a dialog or a select list in the menu. + On the CLI, it asks nothing, because the arguments came from the command line. Args: - ctx: Shared application context. + ctx: The shared application context. Returns: - A parameter dict compatible with :meth:`run`. + A dict of parameters that :meth:`run` accepts. """ return {} def register_cli(self, app: typer.Typer) -> None: """Register this tool as a Typer subcommand. - The default registers a no-argument command. Tools with parameters override this - to declare typed options, then delegate to :meth:`execute`. + The default registers a command with no arguments. A tool with parameters + overrides this method to declare typed options, and then calls :meth:`execute`. Args: - app: The Typer application to add the command to. + app: The Typer application that gets the command. """ from ..cli import run_tool_command @@ -137,20 +145,20 @@ class Tool(ABC): run_tool_command(self, {}) async def execute(self, ctx: AppContext, params: dict[str, Any]) -> ToolResult: - """Run the tool wrapped in run-logging and error capture. + """Run the tool, with a log of the run and a capture of its errors. - Opens a ``runs`` row before execution and closes it with the final status and - summary afterward, regardless of success. + This method opens a ``runs`` row before the run. After the run, it closes the row + with the final status and the summary, also when the run failed. Args: - ctx: Shared application context. - params: Parameters for this invocation. + ctx: The shared application context. + params: The parameters for this run. Returns: The :class:`ToolResult` from :meth:`run`. Raises: - Exception: Re-raises any error from :meth:`run` after recording it. + Exception: Each error from :meth:`run`, raised again after it is stored. """ import typer @@ -168,24 +176,27 @@ class Tool(ABC): DeviceConfigError, DeviceCommandError, PreferenceError, - # A tool rejecting one of its own arguments (an unresolvable `--to`) raises - # what the parser would have. It is a usage error, not a fault. + # When a tool refuses one of its own arguments (a `--to` that it cannot + # resolve), it raises the same error as the parser. It is a usage error, not a + # fault. typer.BadParameter, typer.Abort, typer.Exit, ) as exc: - # Expected user-facing condition (no/ambiguous device, a bad config or - # preference value, a bad argument, or a transient command failure): record it - # but don't dump a traceback; callers print the message cleanly. + # An expected condition for the user (no device or an ambiguous device, a bad + # config or preference value, a bad argument, or a temporary failure of a + # command). Store it, but do not write a traceback. The callers print the + # message cleanly. ctx.repo.finish_run(run_id, "error", {"error": str(exc)}) ctx.log.debug("run %s aborted: %s", run_id, exc) raise - except Exception as exc: # noqa: BLE001 - we record then re-raise + except Exception as exc: # noqa: BLE001 - we store it, then raise it again ctx.repo.finish_run(run_id, "error", {"error": str(exc)}) if is_connection_lost(exc): - # The radio was unplugged or powered off mid-command. Every layer above - # already knows how to say that in one line; a stack of serial internals - # describes how the driver found out, which is not the same question. + # The device was disconnected or switched off during a command. Each + # layer above knows how to say that in one line. A stack of serial + # internals tells how the driver found the problem, and that is a + # different question. ctx.log.warning("run %s lost the device connection: %s", run_id, exc) else: ctx.log.exception("run %s failed: %s", run_id, exc) @@ -197,20 +208,22 @@ class Tool(ABC): _REGISTRY: dict[str, Tool] = {} -#: Explicit menu ordering for tool categories. The menu asks "What would you like to -#: do?", so its sections answer that: each names a *doing*, not a subject, and holds -#: everything that shares it. Message leads (the everyday features, plus the book you -#: pick a recipient from), then Watch (what the mesh is doing, what it did, what to be -#: told about), Explore (where the nodes are, how they reach each other, and the boards -#: that score the walking), then the two owners a setting can belong to — This node, the -#: radio in your hand, and Other nodes, someone else's over the mesh. +#: The explicit order of the tool categories in the menu. The menu asks "What would you +#: like to do?", so its sections answer that question. Each section names an *activity*, +#: not a subject, and holds all the items for that activity. Message is first (the +#: features for each day, and the list from which you select a recipient). Then come Watch +#: (what the mesh does, what it did, and what to get notifications about) and Explore +#: (where the nodes are, how they get to each other, and the boards that score the walks). +#: Then come the two owners of a setting: This node (the radio in your hand) and Other +#: nodes (the radio of another person, over the mesh). #: -#: This app closes the list as the third and last *owner*, after the radio in your hand and -#: someone else's over the mesh: the program in front of you. It holds the one thing that -#: changes how MeshTerm behaves (Preferences) and the four pages that say what MeshTerm is -#: — questions none of the doings above can hold, and which nothing on the mesh can answer. -#: It sits last because a reader who has run out of things to do is who goes looking for it. -#: Categories not listed here sort last, alphabetically, so a new category still appears. +#: This app ends the list as the third and last *owner*, after the radio in your hand and +#: the radio of another person over the mesh: it is the program in front of you. It holds +#: the one item that changes how MeshTerm behaves (Preferences), and the four pages that +#: say what MeshTerm is. These are questions that no activity above can hold, and that +#: nothing on the mesh can answer. This app is last because the user who has nothing more +#: to do is the user who looks for it. Categories that are not in this list come last, in +#: alphabetical order. Thus a new category is always in the menu. _CATEGORY_ORDER = [ "Message", "Watch", @@ -222,7 +235,7 @@ _CATEGORY_ORDER = [ def _category_rank(category: str) -> int: - """Return a category's sort rank (its position in ``_CATEGORY_ORDER``, else last).""" + """Return the sort rank of a category (its position in ``_CATEGORY_ORDER``, or last).""" try: return _CATEGORY_ORDER.index(category) except ValueError: @@ -230,16 +243,16 @@ def _category_rank(category: str) -> int: def register(cls: type[Tool]) -> type[Tool]: - """Class decorator that instantiates a tool and adds it to the registry. + """A class decorator that makes an instance of a tool and adds it to the registry. Args: cls: The :class:`Tool` subclass to register. Returns: - The unchanged class (so the decorator is transparent). + The class with no change (thus the decorator is transparent). Raises: - ValueError: If the tool has no ``name`` or the name is already registered. + ValueError: If the tool has no ``name``, or if the name is already registered. """ instance = cls() if not instance.name: @@ -251,14 +264,14 @@ def register(cls: type[Tool]) -> type[Tool]: def all_tools() -> list[Tool]: - """Return all registered tools sorted by category rank, then order, then name. + """Return all the registered tools, sorted by category rank, then order, then name. - Categories are ordered by :data:`_CATEGORY_ORDER` (Mesh first), so the first-class - Chat and Channels tools lead the menu; within a category, ``order`` then ``name`` break - ties. + :data:`_CATEGORY_ORDER` sets the order of the categories (Mesh first). Thus the main + tools, Chat and Channels, come first in the menu. In a category, ``order`` and then + ``name`` decide a tie. Returns: - The registered tool instances in stable menu order. + The registered tool instances, in a stable menu order. """ return sorted( _REGISTRY.values(), @@ -267,12 +280,12 @@ def all_tools() -> list[Tool]: def get_tool(name: str) -> Tool | None: - """Look up a registered tool by name. + """Find a registered tool by its name. Args: - name: The tool's ``name``. + name: The ``name`` of the tool. Returns: - The tool instance, or ``None`` if not registered. + The tool instance, or ``None`` if no tool has that name. """ return _REGISTRY.get(name) diff --git a/meshterm/tools/channels.py b/meshterm/tools/channels.py index 332e938..8fd79f0 100644 --- a/meshterm/tools/channels.py +++ b/meshterm/tools/channels.py @@ -1,14 +1,15 @@ # SPDX-License-Identifier: Apache-2.0 """The ``channels`` tool: create, join, and manage mesh channels. -Interactively it opens a full-screen channel manager (see :mod:`meshterm.ui.channels`) — a -first-class, phone-app-style experience for creating private channels, adding public ``#`` -channels, joining with a key, importing a scanned ``meshcore://`` link, and sharing any -channel as a QR code. On the CLI it exposes ``list``, ``add``, ``join``, ``import``, -``share``, ``clear`` and ``scope`` subcommands for scripted use. +In the menu, the tool opens a full-screen channel manager (refer to +:mod:`meshterm.ui.channels`). The manager is a complete feature, similar to a phone app. +With it, the user can create a private channel, add a public ``#`` channel, join a channel +with a key, import a scanned ``meshcore://`` link, and share any channel as a QR code. On +the CLI, the tool gives the ``list``, ``add``, ``join``, ``import``, ``share``, ``clear``, +and ``scope`` subcommands for use in scripts. -Channels are also *listed* by the ``chat`` tool for picking a conversation; this tool owns -everything to do with configuring the slots themselves. +The ``chat`` tool also lists the channels, so that the user can select a conversation. But +this tool owns all the configuration of the slots. """ from __future__ import annotations @@ -49,11 +50,11 @@ class ChannelsTool(Tool): """Open the channel manager (menu) or run a scripted action (CLI). Args: - ctx: Shared application context. - params: A ``cli_action`` with its arguments (CLI), or empty for the menu. + ctx: The shared application context. + params: A ``cli_action`` and its arguments (CLI), or empty for the menu. Returns: - A :class:`ToolResult` recording what happened (the menu path shows nothing). + A :class:`ToolResult` that holds what occurred. The menu path shows nothing. """ action = params.get("cli_action") if action is not None: @@ -61,16 +62,16 @@ class ChannelsTool(Tool): from ..ui.channels import manage_channels - # No message: the manager acknowledged its work on the way out, which meant telling - # the reader that changes they had just watched land were applied. The count still - # goes to the run log through ``summary``, which is the record of what an invocation - # did rather than anything shown. + # No message. The manager once acknowledged its work when the user left it. That + # told the user that the changes were applied, but the user saw them occur already. + # The count still goes to the run log through ``summary``. ``summary`` is the + # record of what a run did, not a thing that the screen shows. return ToolResult(summary={"changes": await manage_channels(ctx)}) # -- CLI -------------------------------------------------------------------- async def _run_cli(self, ctx: AppContext, action: str, params: dict[str, Any]) -> ToolResult: - """Dispatch a scripted CLI action.""" + """Run the handler for a scripted CLI action.""" if action == "add": return await self._cli_add(ctx, params) if action == "join": @@ -98,13 +99,13 @@ class ChannelsTool(Tool): ) async def _cli_add(self, ctx: AppContext, params: dict[str, Any]) -> ToolResult: - """Add a public, private-random, or explicitly-keyed channel on a slot.""" + """Add a channel on a slot: public, private with a random key, or with a given key.""" from ..ui.channels import write_channel device = await ctx.device() idx = int(params["index"]) name = str(params["name"]) - if name.startswith("#"): # public: firmware derives the key from the name + if name.startswith("#"): # public: the firmware derives the key from the name await write_channel(ctx, device, idx, name, None) secret = derive_secret(name) else: @@ -117,7 +118,7 @@ class ChannelsTool(Tool): ) async def _cli_join(self, ctx: AppContext, params: dict[str, Any]) -> ToolResult: - """Join a channel from a name and an explicit key.""" + """Join a channel with a name and a given key.""" from ..ui.channels import write_channel device = await ctx.device() @@ -147,11 +148,11 @@ class ChannelsTool(Tool): ) async def _cli_share(self, ctx: AppContext, params: dict[str, Any]) -> ToolResult: - """Print a channel's share link, with its QR code in the menu. + """Print the share link of a channel. In the menu, also show its QR code. - The one command that names a channel's key deliberately, so it is the one place - the secret and the share URL leave the app at all — every other channel document - carries the identity and stops there. + This is the only command that shows the key of a channel on purpose. Thus it is + the only place where the secret and the share URL go out of the app. Each other + channel document holds the identity of the channel and nothing more. """ from ..core.channel_probe import read_channel_slots @@ -171,12 +172,13 @@ class ChannelsTool(Tool): ) async def _cli_clear(self, ctx: AppContext, params: dict[str, Any]) -> ToolResult: - """Clear a channel slot, removing the channel from the device. + """Clear a channel slot. This removes the channel from the device. - The scriptable face of the channel manager's *Clear this slot*: an empty name - makes the firmware read the slot as unused. The ``--yes`` gate lives on the CLI - command (a private channel's key is lost with the slot unless it's saved - elsewhere), mirroring the interactive flow's danger confirmation. + This is the script form of "Clear this slot" in the channel manager. An empty + name makes the firmware read the slot as unused. The ``--yes`` gate is on the CLI + command, because the key of a private channel is lost with the slot if it is not + saved in a different place. The gate is the same as the danger confirmation of + the interactive flow. """ from ..core.channel_probe import read_channel_slots from ..ui.channels import write_channel @@ -190,27 +192,28 @@ class ChannelsTool(Tool): report=(_cleared(idx, False),), exit_code=exitcodes.NO_RESULT, ) - await write_channel(ctx, device, idx, "", None) # empty name => the slot reads as unused + await write_channel(ctx, device, idx, "", None) # an empty name marks the slot as unused return ToolResult( summary={"index": idx, "cleared": True}, report=(_cleared(idx, True),), ) async def _cli_scope(self, ctx: AppContext, params: dict[str, Any]) -> ToolResult: - """Read, set or clear the region a channel's messages are sent under. + """Read, set, or clear the scope of a channel: the region its messages are sent in. - The scriptable face of the detail page's *Send scope…*. The scope is MeshTerm's to - keep (the firmware has none per channel; the send sets the companion's session - scope around each message), so setting one writes nothing to the radio — the slot - is read only to learn which channel is in it, since the scope is keyed by the - channel's identity and follows it to any slot. + This is the script form of "Send scope…" on the detail page. MeshTerm keeps the + scope, because the firmware has no scope for each channel. When MeshTerm sends a + message, it sets the session scope of the companion around that message. Thus, + when this command sets a scope, it writes nothing to the device. It reads the slot + only to find which channel is in it, because the scope is keyed by the identity of + the channel. The scope follows the channel to any slot. - With no region, the plain face prints the scope alone, the way ``config get`` prints - one value — and a channel with none prints ``-`` and exits 0: "no scope, so the - device default" is an answer about a channel that is there, not an empty result. A - set or a clear prints nothing, and the document always carries the channel and its - scope (``null`` for none). Only an empty slot, with no channel to answer about, - exits 5. + With no region, the plain face prints only the scope, as ``config get`` prints one + value. A channel with no scope prints ``-`` and exits 0, because "no scope, so the + device default" is an answer about a channel that exists. It is not an empty + result. A set or a clear prints nothing. The document always holds the channel and + its scope (``null`` for no scope). Only an empty slot exits 5, because it has no + channel to answer about. """ from ..core.channel_probe import read_channel_slots @@ -220,8 +223,9 @@ class ChannelsTool(Tool): region = params.get("region") if slot is None: if region is not None or params.get("clear"): - # A write names a channel that isn't there: a bad argument, not an empty - # answer — exit 5 would tell a script the scope was set and read back empty. + # A write names a channel that does not exist. That is a bad argument, not an + # empty answer. Exit 5 tells a script that the scope was set and then read + # back as empty, which is false. import typer raise typer.BadParameter(f"slot {idx} is empty; there is no channel to scope") @@ -244,12 +248,12 @@ class ChannelsTool(Tool): @staticmethod async def _show_qr(ctx: AppContext, name: str, url: str) -> None: - """Draw a channel's share link as a QR code — in the menu, and only there. + """Draw the share link of a channel as a QR code, only in the menu. - The QR is for a phone pointed at the screen, and there it takes the whole screen - (:func:`~meshterm.ui.qr.share_screen`). Piped into a file it is a block of block - characters wrapped around the one thing that is actually the answer, so a scripted - run states the link and nothing else. + The QR code is for a phone that points at the screen. There, the code fills the + whole screen (:func:`~meshterm.ui.qr.share_screen`). In a file (through a pipe), + the code is only a mass of block characters around the link, and the link is the + real answer. Thus a scripted run prints the link and nothing else. """ from ..ui.qr import share_screen from ..ui.surface import TuiUi @@ -314,8 +318,9 @@ class ChannelsTool(Tool): ), ) -> None: if not yes: - # A usage error, in the parser's own words and under its own status — not a - # red line printed onto whatever is reading this command's output. + # A usage error, in the words of the parser and with its exit status. It is + # not a red line printed into the program that reads the output of this + # command. raise typer.BadParameter( "clearing a slot removes the channel (a private channel's key is lost " "unless you have it saved). Re-run with --yes to confirm." @@ -349,14 +354,16 @@ class ChannelsTool(Tool): def _channel_listing(slots: list, store: object | None = None) -> Listing: - """The configured slots, one record each. + """The configured slots, one record for each slot. - The one listing whose record *is* a shared shape rather than carrying one: a row that - nested its only field under a ``channel`` key would make ``jq '.[].channel.name'`` - out of a listing whose every column is already the channel. + This is the only listing whose record is a shared shape itself, instead of a record + that holds one. Each column of this listing is already the channel. If each row put + its only field under a ``channel`` key, a query must be ``jq '.[].channel.name'`` + for no reason. - ``SCOPE`` is the region the channel's messages are sent under (``-`` and ``null`` for - the device default), read from the region store the send path reads. + ``SCOPE`` is the region that the messages of the channel are sent in (``-`` and + ``null`` for the device default). The value comes from the region store, which the + send path also reads. """ from ..ui import fields from ..ui.report import Listing @@ -389,15 +396,15 @@ def _channel_listing(slots: list, store: object | None = None) -> Listing: def _scoped( idx: int, name: str | None, secret: bytes | None, scope: str | None, *, changed: bool ) -> Facts: - """What ``channels scope`` read or set: the channel and the region it sends into. + """What ``channels scope`` read or set: the channel and the region that it sends into. Args: idx: The slot index. - name: The channel name, or ``None`` for a slot that turned out to be empty. + name: The channel name, or ``None`` if the slot is empty. secret: The 16-byte key, or ``None`` for an empty slot. - scope: The channel's scope now, or ``None`` for the device default. - changed: Whether this run set or cleared it — then the plain face is silent, the - way every write's is; a read prints the scope alone. + scope: The current scope of the channel, or ``None`` for the device default. + changed: Whether this run set or cleared the scope. If it did, the plain face + prints nothing, as for each write. A read prints only the scope. Returns: The facts block. @@ -410,10 +417,11 @@ def _scoped( if name is not None and secret is not None: public = is_public_channel(name, secret) channel = ChannelRef(slot=idx, name=name, public=public, hash=channel_hash(secret)) - # A channel with no scope answers `-` plain (and `null` in the document): "the device - # default" is an answer about a channel that is there, where the bare form's usual - # silence for an absent value would leave only the exit status to say it. An empty - # slot has no channel to answer about, so it keeps that silence (and its exit 5). + # A channel with no scope prints `-` on the plain face (and `null` in the document). + # "The device default" is an answer about a channel that exists. Usually the bare form + # prints nothing for an absent value, and then only the exit status can give this + # answer. An empty slot has no channel to answer about, so it keeps that silence (and + # its exit 5). value = Rendered(scope, scope or script.NONE) if channel is not None else None return Facts( key="channel", @@ -425,17 +433,18 @@ def _scoped( def _written(idx: int, name: str | None, secret: bytes | None, *, shown: bool = True) -> Facts: - """What a slot now holds, after ``add``, ``join``, ``import`` or ``share``. + """What a slot holds now, after ``add``, ``join``, ``import``, or ``share``. - All four write or read the same thing and all four know the key they wrote, so all - four state the same shape. The plain face prints the share URL alone where the caller - asked to be given something to pass on (``add``, ``share``) and nothing at all where - it did not (``join``, ``import``): those two were handed the key, and reading it back - to them is not an answer. + All four commands write or read the same thing, and all four know the key that they + wrote. Thus all four give the same shape. The plain face prints only the share URL + when the caller asked for something to give to other persons (``add``, ``share``). It + prints nothing when the caller did not ask for it (``join``, ``import``). The caller + gave the key to these two commands, and to read the key back to the caller is not an + answer. Args: idx: The slot index. - name: The channel name, or ``None`` for a slot that turned out to be empty. + name: The channel name, or ``None`` if the slot is empty. secret: The 16-byte key, or ``None`` for an empty slot. shown: Whether the plain face prints the URL. @@ -468,7 +477,7 @@ def _written(idx: int, name: str | None, secret: bytes | None, *, shown: bool = def _cleared(idx: int, cleared: bool) -> Facts: - """What ``channels clear`` did — nothing plain, since the status already said it.""" + """What ``channels clear`` did. The plain face prints nothing, because the status said it.""" from ..ui import fields from ..ui.report import SILENT, Facts diff --git a/meshterm/tools/chat.py b/meshterm/tools/chat.py index 1f74d01..0a3d611 100644 --- a/meshterm/tools/chat.py +++ b/meshterm/tools/chat.py @@ -1,16 +1,17 @@ # SPDX-License-Identifier: Apache-2.0 -"""The ``chat`` tool: channel and direct messaging over the mesh. +"""The ``chat`` tool: channel messages and direct messages over the mesh. -Interactively it opens a conversation picker and then a live, full-screen chat (see -:mod:`meshterm.ui.chat`) where sent and received messages stream together — or, for a room -server, its board (:mod:`meshterm.ui.room`). On the CLI it exposes ``send``, ``history``, -``list`` and ``listen`` subcommands for scripted use; a room is addressed by ``--to`` like a -contact. Channels and rooms are only *listed* here for picking: configuring channel slots is -the ``channels`` tool's, and joining a room is the ``rooms`` tool's. +In the menu, it opens a conversation picker, and then a live chat on the full screen +(refer to :mod:`meshterm.ui.chat`). There, the sent messages and the received messages +stream together. For a room server, it opens the board of the room instead +(:mod:`meshterm.ui.room`). On the CLI, it has the ``send``, ``history``, ``list``, and +``listen`` subcommands for scripts. You address a room with ``--to``, the same as a +contact. This tool only *lists* channels and rooms, so that you can select one. The +``channels`` tool configures the channel slots, and the ``rooms`` tool joins a room. -Every inbound message is recorded to history by the always-on -:class:`~meshterm.services.chat_service.ChatService`, and outbound messages are recorded on -send, so ``history`` reflects the full transcript regardless of which path produced it. +The :class:`~meshterm.services.chat_service.ChatService` always runs and stores each +received message in the history. Each sent message is stored when it is sent. Thus +``history`` shows the full transcript, whichever path made each message. """ from __future__ import annotations @@ -66,7 +67,7 @@ if TYPE_CHECKING: from ..core.channel_probe import ChannelSlot from ..ui.report import Facts, Listing -#: How many recent messages ``chat history`` prints by default. +#: The number of recent messages that ``chat history`` prints by default. _HISTORY_LIMIT = 50 @@ -82,29 +83,30 @@ class ChatTool(Tool): order = 10 async def prompt_params(self, ctx: AppContext) -> dict[str, Any] | None: - """Nothing to gather here — the conversation picker lives inside :meth:`run`. + """Nothing to collect here. The conversation picker is in :meth:`run`. - The picker has to *stay pushed* while a chat runs, so backing out of a thread lands - on the very list it was opened from — same cursor, same typed filter. A prompt - gathered here would resolve, and pop, before the tool ran. + The picker must *stay pushed* while a chat runs. Thus, when the user leaves a + thread, the user goes back to the same list that opened it, with the same + highlight and the same typed filter. A prompt here resolves, and pops, before the + tool runs. Args: - ctx: Shared application context. + ctx: The shared application context. Returns: - ``{"live": True}`` — the menu's marker for the interactive path. + ``{"live": True}``: the marker of the menu for the interactive path. """ return {"live": True} async def run(self, ctx: AppContext, params: dict[str, Any]) -> ToolResult: - """Open a live chat (menu) or perform a scripted messaging action (CLI). + """Open a live chat (menu), or do a scripted message action (CLI). Args: - ctx: Shared application context. - params: Either ``conversation`` (menu) or a ``cli_action`` with its arguments. + ctx: The shared application context. + params: ``conversation`` (menu), or a ``cli_action`` with its arguments. Returns: - A :class:`ToolResult` summarizing what happened. + A :class:`ToolResult` with a summary of what occurred. """ action = params.get("cli_action") if action is not None: @@ -114,24 +116,25 @@ class ChatTool(Tool): # -- interactive picker ----------------------------------------------------- async def _run_live(self, ctx: AppContext) -> ToolResult: - """Keep the conversation picker pushed and open chats above it until it is left. + """Keep the conversation picker pushed, and open chats above it until the user leaves. - One screen for the whole visit, so backing out of a thread lands on the row it was - opened from with the typed filter still narrowing the list. The picker used to be - rebuilt from scratch each round and the cursor put back by a ``default=`` restore, - which recovers the cursor alone — and only while the row it names still exists. + One screen stays for the full visit. Thus, when the user leaves a thread, the user + goes back to the row that opened it, and the typed filter still narrows the list. + Before, each round made the picker again from nothing, and a ``default=`` restore + put the highlight back. That restored only the highlight, and only while its row + was still there. - The rows *are* data: an exchange moves its thread up the recency order, and deleting - a history hollows its dot and demotes the row to the alphabetical tail. So they are - re-read and swapped in place after each chat and each delete, which follows the - highlighted thread wherever it moved to. + The rows *are* data. An exchange moves its thread up in the order of recency. A + delete of a history makes its dot hollow and moves the row down to the alphabetical + end of the list. Thus, after each chat and each delete, the rows are read again and + replaced in place. The highlight follows its thread to its new position. Args: - ctx: Shared application context. + ctx: The shared application context. Returns: - A :class:`ToolResult` counting the conversations opened and the messages the - last one showed. + A :class:`ToolResult` that counts the opened conversations and the messages that + the last one showed. """ from ..ui.chat import open_chat from ..ui.tui import SelectScreen @@ -140,14 +143,14 @@ class ChatTool(Tool): picker = SelectScreen( "Chat — pick a conversation", await self._picker_items(ctx), - # Enter pushes the chat screen, so the committing verb is `open`. Neither the - # scroll nor the erase atom is written into the base: the select list splices - # each in exactly when its key would act — ←→ only while the highlighted row - # overflows, Del only on a thread that has history to lose — and the three of - # them together are what has to stay inside 72 cells (the archive preview's list - # is the same arithmetic). `Del erase` is that budget's doing: the row already - # names the conversation, so the atom spends its cells on the verb, and `erase` - # is the word the app uses elsewhere for taking data away. + # Enter pushes the chat screen, so the committing verb is `open`. The base hint + # does not contain the scroll atom or the erase atom. The select list adds each + # one only when its key does something: ←→ only while the highlighted row is + # too long, and Del only on a thread that has history to lose. The three + # together must fit in 72 cells (the list of the archive preview has the same + # calculation). That limit is the reason for `Del erase`. The row already names + # the conversation, so the atom uses its cells for the verb. Also, `erase` is + # the word that the app uses in other places when it removes data. footer_hint="↑↓ move · type to filter · Enter open · Esc back", delete_hint="Del erase", ) @@ -158,7 +161,7 @@ class ChatTool(Tool): choice = await visit.result() if isinstance(choice, DeleteRequest): await self._delete_history(ctx, choice.value) - elif choice is CANCEL or choice is None: # Esc — out to the menu + elif choice is CANCEL or choice is None: # Esc: back to the menu return ToolResult(summary={"conversations": opened, "messages": shown}) else: shown = await open_chat(ctx, choice) @@ -166,66 +169,72 @@ class ChatTool(Tool): picker.replace_items(await self._picker_items(ctx)) async def _picker_items(self, ctx: AppContext) -> list: - """Build the picker's rows: the pinned lane names, then Channels, Rooms and Direct. + """Make the rows of the picker: the pinned lane names, then Channels, Rooms, and Direct. - Read fresh every time the list is built or swapped, so a thread that just gained - messages sits where its recency puts it. Cheap enough to redo after each chat: the - two device reads go through the session cache and the rest is stored history. + The rows are read again each time that the list is made or replaced. Thus a thread + that got new messages is at the position that its recency gives it. It costs + little to do this after each chat: the two device reads go through the session + cache, and the rest is stored history. Args: - ctx: Shared application context. + ctx: The shared application context. Returns: - The :class:`~meshterm.ui.tui.select.Choice` / ``Separator`` rows, in display - order. + The :class:`~meshterm.ui.tui.select.Choice` and ``Separator`` rows, in the + order on the screen. """ - # Through the session cache: this picker runs on every Chat open, and its two - # reads — the channel-slot probe and the contacts table — are the two slowest - # round-trips on a companion. Reading them from the device each time is what made - # opening Chat stall for seconds (the cached chat screen behind it never got the - # chance to help). The cache holds channels until the channel editor writes a - # slot and refreshes contacts in the background (see + # Read through the session cache. This picker runs each time that Chat opens. Its + # two reads (the channel slot probe and the contacts table) are the two slowest + # round trips on a companion. When MeshTerm read them from the device each time, + # Chat stopped for seconds when it opened (the cached chat screen behind it had no + # chance to help). The cache keeps the channels until the channel editor writes a + # slot, and reads the contacts again in the background (refer to # :class:`~meshterm.services.device_state.DeviceState`). channels = _channels_from_slots(await ctx.devstate.channel_slots()) contacts = await ctx.devstate.contacts() - # Only companion nodes are listed under Direct — we don't DM repeaters, rooms, or - # sensors; a contact whose type was never advertised gets the benefit of the doubt - # (the app-wide DM rule, see is_direct_messageable). Room servers have their own - # section: somewhere you join and post, not someone you message. + # Direct lists only companion nodes. We do not send direct messages to repeaters, + # rooms, or sensors. A contact that never advertised its type is accepted (the + # app-wide DM rule, refer to is_direct_messageable). Room servers have their + # own section: a room is a place that you join and post to, not a person to whom + # you send a message. companions = [c for c in contacts if is_direct_messageable(c.node_type)] - # Only rooms we have joined — as only channels on a slot are listed. Joining is the - # Rooms page's (see meshterm.ui.rooms). + # Only the rooms that we joined, in the same way as only the channels on a slot are + # listed. The Rooms page joins rooms (refer to meshterm.ui.rooms). rooms = [ Conversation(label=c.name, is_channel=False, contact=c) for c in contacts if is_room(c.node_type) and ctx.rooms.joined(c) ] room_peers = [conv.peer for conv in rooms if conv.peer] - # A stable snapshot orders the rows (so the list doesn't reshuffle under the - # cursor), while a self-refreshing view feeds each row's live preview - # (see _LiveLasts). A room's latest is its latest *post*. + # A stable snapshot sets the order of the rows (so that the list does not change its + # order under the highlight). A lookup that reads itself again gives the live preview + # of each row (refer to _LiveLasts). The latest message of a room is its latest + # *post*. lasts = ctx.repo.last_chat_messages(rooms=room_peers) live = _LiveLasts(ctx, seed=lasts, rooms=room_peers) - # Names in previews/mentions resolve back to keys for their hue (the app-wide - # colour rule); a name no contact or stored advert carries stays muted. A room - # post names its author by key, which resolves the other way. + # The names in previews and mentions resolve back to keys for their hue (the + # app-wide colour rule). A name that no contact and no stored advert has stays + # muted. A room post names its author by key, which resolves in the other + # direction. stored_names = ctx.repo.node_names() key_of = make_name_key_resolver(contacts, stored_names) name_of = make_node_resolver(contacts, stored_names) - # List contacts by recency — those with messages first, newest exchange at the top — - # then the never-contacted ones alphabetically (see _recency_key). Rooms the same. + # List the contacts by recency: first the contacts with messages, with the newest + # exchange at the top. Then the contacts with no messages, in alphabetical order + # (refer to _recency_key). The same for rooms. direct = [Conversation(label=c.name, is_channel=False, contact=c) for c in companions] direct.sort(key=lambda conv: _recency_key(conv, lasts)) rooms.sort(key=lambda conv: _recency_key(conv, lasts)) - # One measurement for the whole list, headings and rows alike, taken before either is - # built: the name lane is only as wide as the names actually in it, and every cell it - # gives back goes to the message preview (see _lanes). + # One measurement for the full list, the headings and the rows, done before they are + # made. The name lane is only as wide as the names in it, and each cell that it does + # not use goes to the message preview (refer to _lanes). lanes = _lanes(channels + rooms + direct) - # The lane names pin for the whole picker (they mean the same in both groups), - # so scrolling into Direct keeps them overhead with that group's heading under - # them, instead of the header vanishing one row in — see Screen.sticky_rows. + # The lane names pin for the full picker (they have the same meaning in the two + # groups). Thus, when the list scrolls into Direct, they stay at the top, with the + # heading of that group under them. Otherwise the header goes away after one row. + # Refer to Screen.sticky_rows. items: list = [ Separator(lambda w: _picker_header(lanes, w), pinned=True), section_heading("📡 Channels"), @@ -235,7 +244,7 @@ class ChatTool(Tool): Choice( title=_row_title(ctx, conversation, live, key_of, lanes), value=conversation, - # ←→ slide the message alone; the lanes in front of it hold (_Lanes.head). + # ←→ move only the message. The lanes before it stay (_Lanes.head). hscroll_from=lanes.head, ) ) @@ -251,8 +260,8 @@ class ChatTool(Tool): ) ) if not rooms: - # Said, not left out: "how do I get on a room?" is a question people bring here, - # and an empty section answers where to go. + # Show this, do not omit it. Users come here with the question "how do I get on + # a room?", and an empty section tells them where to go. items.append(Separator(" no rooms joined — join one on the Rooms page")) items.append(section_heading("👤 Direct")) @@ -262,8 +271,8 @@ class ChatTool(Tool): Choice( title=_row_title(ctx, conversation, live, key_of, lanes), value=conversation, - # Del offers to delete this thread's stored history — - # only where there is history to delete. + # Del offers to delete the stored history of this thread, only + # where there is history to delete. deletable=lasts.get(conversation.key) is not None, hscroll_from=lanes.head, ) @@ -275,14 +284,15 @@ class ChatTool(Tool): @staticmethod async def _delete_history(ctx: AppContext, conversation: Conversation) -> None: - """Confirm and delete one direct conversation's — or room's — stored history. + """Confirm, then delete the stored history of one direct conversation or one room. - Deleting history is irreversible data loss, so the confirm wears the reserved - red (``destructive``): Cancel on the left, the committing Delete on the right. - On confirm the peer's messages are removed from the database and the thread's - unread count is cleared; the contact itself (a device-side record) is untouched. - A room's posts go from this machine only. The room keeps its own, and won't send - them again: it has seen them acknowledged. + A delete of history is a data loss that cannot be undone. Thus the confirm has the + reserved red (``destructive``): Cancel on the left, and the committing Delete on + the right. When the user confirms, MeshTerm deletes the messages of the peer from + the database and clears the unread count of the thread. The contact itself (a + record on the device) does not change. The posts of a room go only from this + machine. The room keeps its own posts, and does not send them again, because it + got the acknowledgements for them. """ prompt = ( f"Delete the posts stored from {conversation.label}? They are removed from " @@ -308,9 +318,9 @@ class ChatTool(Tool): """Dispatch a scripted CLI action. Args: - ctx: Shared application context. + ctx: The shared application context. action: One of ``send``, ``history``, ``listen``, ``list``. - params: The action's arguments. + params: The arguments of the action. Returns: A :class:`ToolResult` for the action. @@ -324,22 +334,24 @@ class ChatTool(Tool): return await self._cli_list(ctx) async def _cli_send(self, ctx: AppContext, params: dict[str, Any]) -> ToolResult: - """Send a channel or direct message and report whether it was acknowledged. + """Send a channel message or a direct message, and report whether it was acknowledged. - A channel broadcast has nothing to report — there is no acknowledgement on a - channel — so it prints nothing and lets the exit status say it went out. A direct - message prints its ``acked`` state, which is the one thing the send does not - already tell the caller: the radio accepted it either way, and whether the peer - answered is a separate fact. + A channel broadcast has nothing to report, because a channel has no + acknowledgement. Thus it prints nothing, and the exit status says that the message + went out. A direct message prints its ``acked`` state. That is the one thing that + the send does not already tell the caller: the radio accepted the message in the + two cases, and the answer of the peer is a separate fact. - A channel message goes out under the channel's send scope, or under ``scope`` for - this one message (a region name, or ``*`` for unscoped); the document says which it - went under. A radio that can't send under the scope refuses before anything is - transmitted, and that is a failure (exit 1), never a quiet unscoped send. + A channel message goes out under the send scope of the channel, or under ``scope`` + for this one message (a region name, or ``*`` for unscoped). The document says + which scope it went out under. If the radio cannot send under the scope, it + refuses before it transmits anything. That is a failure (exit 1), never a silent + unscoped send. - ``--to`` a room server posts to it. The room acknowledges a post once it has stored - it, so ``acked`` reads the same way; a room that no longer knows us (it restarted, - or we never joined) drops the post unacknowledged — ``rooms join`` first. + ``--to`` a room server posts to the room. The room acknowledges a post after it + stores it, so ``acked`` has the same meaning. A room that no longer knows us (it + restarted, or we never joined) discards the post with no acknowledgement. Use + ``rooms join`` first. """ device = await ctx.device() text = str(params["text"]) @@ -364,13 +376,13 @@ class ChatTool(Tool): ) async def _cli_history(self, ctx: AppContext, params: dict[str, Any]) -> ToolResult: - """Print a conversation's stored transcript — for a room, its board by author. + """Print the stored transcript of a conversation. For a room, print its board by author. - A room's transcript is its posts (its command replies are left out, as on its - board in the menu), and it names each post's author where a direct transcript - names the peer: the room is the conversation the caller already named, and every - post in it has a different writer. Our own posts name our node, as every hop of - ours does on this face. + The transcript of a room is its posts. Its command replies are not in it, the same + as on its board in the menu. Where a direct transcript names the peer, the + transcript of a room names the author of each post. The reason: the room is the + conversation that the caller already named, and the posts in it have different + writers. Our own posts name our node, as each of our hops does on this face. """ limit = int(params.get("limit") or _HISTORY_LIMIT) channel = params.get("channel") @@ -407,27 +419,28 @@ class ChatTool(Tool): ) async def _cli_listen(self, ctx: AppContext, params: dict[str, Any]) -> ToolResult: - """Tail inbound messages live in the console (and record them to history). + """Show the received messages live in the console (and store them in the history). - A plain-console receiver, outside the full-screen menu: it starts the always-on - listener and prints each message as it arrives. Doubles as a diagnostic — with the - pump's debug logging enabled (``--debug`` on the CLI) it shows whether messages are - being pulled from the companion at all. + A receiver on the plain console, outside the full-screen menu. It starts the + listener that always runs, and prints each message when it arrives. It is also a + diagnostic: with the debug logging of the pump on (``--debug`` on the CLI), it + shows whether MeshTerm gets messages from the companion. Args: - ctx: Shared application context. - params: ``seconds`` — how long to listen (``0``/``None`` = until interrupted). + ctx: The shared application context. + params: ``seconds``: how long to listen (``0`` or ``None`` means until an + interrupt). Returns: - A :class:`ToolResult` with how many messages were seen. + A :class:`ToolResult` with the number of heard messages. """ from ..ui import script seconds = params.get("seconds") or 0 await ctx.device() - await ctx.chat.start() # begins recording inbound to history too - # About the run, not part of its answer: stderr, so a redirected stdout holds - # nothing but messages. + await ctx.chat.start() # also starts to store the received messages in the history + # This line is about the run, and is not part of its answer. Thus it goes to stderr, + # so that a redirected stdout holds only messages. script.stderr_console().print( "listening for messages" + (f" for {seconds}s" if seconds else " — press Ctrl-C to stop"), @@ -467,7 +480,7 @@ class ChatTool(Tool): if seconds: await asyncio.sleep(seconds) else: - await asyncio.Event().wait() # until Ctrl-C / cancellation + await asyncio.Event().wait() # until Ctrl-C or a cancellation except (KeyboardInterrupt, asyncio.CancelledError): # pragma: no cover - interactive pass finally: @@ -479,7 +492,7 @@ class ChatTool(Tool): ) async def _cli_list(self, ctx: AppContext) -> ToolResult: - """List channels, contacts, and their most recent message.""" + """List the channels, the contacts, and the most recent message of each.""" device = await ctx.device() channels = await _read_channels(device) contacts = await device.get_contacts() @@ -549,14 +562,15 @@ class ChatTool(Tool): def _cli_scope(scope: str, channel: int | None) -> str: - """Check ``--scope`` before anything is sent: a region the firmware could hold, or ``*``. + """Check ``--scope`` before anything is sent: a region that the firmware can hold, or ``*``. - A usage error (exit 2), not a device failure: nothing has been transmitted yet. A - direct message has no scope to give it here — the firmware floods a DM under the - session scope like anything else, but only a channel send sets one for itself. + A bad value is a usage error (exit 2), not a device failure, because nothing was + transmitted yet. Here, a direct message has no scope to get. The firmware floods a + DM under the session scope, the same as all other packets, but only a channel send + sets a scope for itself. Raises: - typer.BadParameter: For a direct send, or a name the firmware would refuse. + typer.BadParameter: For a direct send, or for a name that the firmware refuses. """ from ..core.regions import WILDCARD, RegionNameError, normalize, validate @@ -571,11 +585,11 @@ def _cli_scope(scope: str, channel: int | None) -> str: def _enable_receive_debug() -> None: - """Route the message-pull and library debug logs to the console for diagnosis. + """Send the debug logs of the message pull and of the library to the console. - Raises the ``meshcore`` and connection-layer loggers to DEBUG and attaches a stderr - handler, so ``chat listen --debug`` shows whether inbound messages are being pulled - from the companion (the receive path) at all. + This function sets the ``meshcore`` logger and the logger of the connection layer to + DEBUG, and attaches a stderr handler. Thus ``chat listen --debug`` shows whether + MeshTerm pulls received messages from the companion (the receive path) at all. """ import logging import sys @@ -589,22 +603,23 @@ def _enable_receive_debug() -> None: def _channels_from_slots(slots: list[ChannelSlot]) -> list[Conversation]: - """Turn cached channel slots into channel conversations, always offering Public (slot 0). + """Change cached channel slots into channel conversations, and always offer Public (slot 0). The picker reads its channels through the session cache - (:meth:`~meshterm.services.device_state.DeviceState.channel_slots`) so it reuses the one - slow slot probe instead of re-walking every slot on each Chat open; this maps that cached - :class:`~meshterm.core.channel_probe.ChannelSlot` list onto the picker's - :class:`~meshterm.core.models.Conversation` rows. Channel 0 (the default public channel) is - synthesised when the firmware reports no slot for it, so there is always somewhere to chat — - the same guarantee :func:`_read_channels` (the CLI path) makes. + (:meth:`~meshterm.services.device_state.DeviceState.channel_slots`). Thus it uses the one + slow slot probe again, and does not read each slot again each time that Chat opens. + This function maps that cached :class:`~meshterm.core.channel_probe.ChannelSlot` list + onto the :class:`~meshterm.core.models.Conversation` rows of the picker. When the + firmware reports no slot for channel 0 (the default public channel), this function + makes one. Thus there is always a place to chat. :func:`_read_channels` (the CLI path) + gives the same guarantee. Args: slots: The configured channel slots, from the session cache. Returns: - One :class:`~meshterm.core.models.Conversation` per slot, with Public prepended when - slot 0 is absent. + One :class:`~meshterm.core.models.Conversation` for each slot, with Public at the + start when slot 0 is absent. """ conversations = [ Conversation( @@ -631,23 +646,23 @@ def _channels_from_slots(slots: list[ChannelSlot]) -> list[Conversation]: async def _read_channels(device: Device) -> list[Conversation]: - """Probe channel slots and return them as channel conversations. + """Probe the channel slots, and return them as channel conversations. - Channel 0 (the default public channel) is always offered even when the firmware reports - no configured slots, so there is always somewhere to chat. + This function always offers channel 0 (the default public channel), also when the + firmware reports no configured slots. Thus there is always a place to chat. Args: device: The connected device to probe. Returns: - One :class:`~meshterm.core.models.Conversation` per configured channel (at least - channel 0). + One :class:`~meshterm.core.models.Conversation` for each configured channel (at + least channel 0). """ conversations: list[Conversation] = [] for idx in range(CHANNEL_SLOT_PROBE_CAP): try: channel = await device.get_channel(idx) - except Exception: # noqa: BLE001 - firmware may not support channel reads + except Exception: # noqa: BLE001 - the firmware may not support channel reads break if channel: name = str(channel.get("channel_name") or idx) @@ -676,11 +691,11 @@ async def _read_channels(device: Device) -> list[Conversation]: def _resolve_contact(contacts: list[Contact], needle: str) -> Contact: - """Find a contact by exact name (case-insensitive) or key-prefix match. + """Find a contact by its exact name (case-insensitive), or by a key prefix that matches. Args: contacts: The known contacts. - needle: A contact name or public-key prefix. + needle: A contact name, or a prefix of a public key. Returns: The matching contact. @@ -697,18 +712,19 @@ def _resolve_contact(contacts: list[Contact], needle: str) -> Contact: def _recency_key(conversation: Conversation, lasts: dict) -> tuple: - """Sort key ordering conversations by recency, then name. + """A sort key that puts the conversations in order of recency, then of name. - Conversations that have been chatted with sort first, most-recent exchange at the top; - those never chatted with sort after them, alphabetically by label. The leading ``0``/``1`` - keeps the two groups apart so their differently-typed tie-breakers never compare. + The conversations that have messages come first, with the most recent exchange at the + top. The conversations with no messages come after them, in alphabetical order of + label. The ``0`` or ``1`` at the start keeps the two groups apart. Thus their + tie-breakers, which have different types, are never compared. Args: conversation: The conversation to rank. - lasts: Map of conversation key to its most recent message. + lasts: A map from the conversation key to its most recent message. Returns: - A tuple usable as a ``sorted`` key. + A tuple that ``sorted`` can use as a key. """ last: ChatMessage | None = lasts.get(conversation.key) if last is not None: @@ -717,22 +733,25 @@ def _recency_key(conversation: Conversation, lasts: dict) -> tuple: class _LiveLasts: - """A self-refreshing view of each conversation's most recent message. + """A lookup of the most recent message of each conversation, which reads itself again. - The picker snapshots :meth:`~meshterm.persistence.repository.Repository.last_chat_messages` - once to *order* the rows (so the list never reshuffles under the cursor), but the row - previews read through this so a message arriving while the list is open updates the - sender/text preview on the next repaint. It re-queries the repository at most a few times a - second (bounded by ``ttl``) rather than once per row per repaint, so a wide list stays cheap. + The picker takes one snapshot of + :meth:`~meshterm.persistence.repository.Repository.last_chat_messages` to set the *order* + of the rows (so that the list never changes its order under the highlight). But the row + previews read through this lookup. Thus, when a message arrives while the list is open, + the next paint shows the new sender and text in the preview. The lookup queries the + repository again a few times each second at most (``ttl`` sets the limit), not one time + for each row on each paint. Thus a wide list stays fast. """ def __init__( self, ctx: AppContext, *, seed: dict, ttl: float = 0.5, rooms: list[str] | None = None ) -> None: - """Bind to a context, seeding the cache with the snapshot already loaded at open. + """Bind to a context, and start the cache with the snapshot that was read at open. - ``rooms`` are the room servers' peers among the conversations, so a refresh reads - a room's latest *post* just as the seed did (see ``Repository.last_chat_messages``). + ``rooms`` are the peers of the room servers in the conversations. Thus a new read + gets the latest *post* of a room, the same as the first snapshot did (refer to + ``Repository.last_chat_messages``). """ self._ctx = ctx self._ttl = ttl @@ -741,48 +760,50 @@ class _LiveLasts: self._at = time.monotonic() def get(self, key: str) -> ChatMessage | None: - """Return the latest message for ``key``, refreshing the cache once its TTL lapses.""" + """Return the latest message for ``key``. Read the cache again when its TTL ends.""" now = time.monotonic() if now - self._at >= self._ttl: try: self._cache = self._ctx.repo.last_chat_messages(rooms=self._rooms) - except Exception: # noqa: BLE001 - keep the last good snapshot on a read error + except Exception: # noqa: BLE001 - if a read error occurs, keep the last snapshot pass self._at = now return self._cache.get(key) -#: Width of the unread-badge lane between the label and the age (fits ``● 999``). +#: The width of the unread badge lane, between the label and the age (``● 999`` fits). _BADGE_WIDTH = 5 -#: Width of the relative-age lane between the badge and the preview (right-aligned; fits ``now`` -#: and two-digit spans like ``59m`` / ``23h``), so every row's message text starts in one column. +#: The width of the relative age lane, between the badge and the preview. It is right-aligned. +#: ``now`` and two-digit spans such as ``59m`` and ``23h`` fit. Thus the message text of each +#: row starts in the same column. _AGE_WIDTH = 3 -#: Floor for the conversation lane. The header word is ``CONVERSATION`` (12 cells) and the -#: lane carries a two-cell gap after it, so anything narrower than this runs the heading -#: straight into ``NEW`` on a mesh whose every name is ``Bob``. +#: The minimum width of the conversation lane. The header word is ``CONVERSATION`` (12 cells) +#: and the lane has a gap of two cells after it. If the lane is narrower, the heading touches +#: ``NEW`` on a mesh where each name is ``Bob``. _LABEL_MIN = 12 -#: Ceiling for it. The lane is sized to the longest name it actually holds (see -#: :func:`_lanes`), and this is where that stops paying: one very long name would otherwise -#: buy padding in front of every *short* one. It holds the long-but-ordinary shape of a -#: repeater-style name (``YUL-Cartierville``), a name past it ellipsizes — the row is a way -#: in to the conversation, whose own screen is titled with the whole name — and every cell -#: the ceiling saves goes to the preview. +#: The maximum width of the lane. The lane width is the length of the longest name in it +#: (refer to :func:`_lanes`), and at this width that rule is no longer useful. Without this +#: limit, one very long name puts padding before each *short* name. This width holds the +#: long but usual shape of a repeater name (``YUL-Cartierville``). A longer name ends with +#: an ellipsis. The row only opens the conversation, and the title of its screen has the +#: full name. Each cell that this limit saves goes to the preview. _LABEL_MAX = 16 @dataclass(frozen=True) class _Lanes: - """The picker's fixed lane widths, measured once per list build. + """The fixed lane widths of the picker, measured one time each time the list is made. - Both the column header and every row are laid out from one of these, so the headings - cannot drift off the columns they name. Only the first two vary: the marker is the - platform's own glyph width (a channel glyph is double-cell on regular and single on the - PicoCalc console) and the label lane is sized to the longest name the list actually - holds, within :data:`_LABEL_MIN` / :data:`_LABEL_MAX`. + The column header and each row get their layout from one of these objects. Thus the + headings cannot move away from the columns that they name. Only the first two widths + change. The marker has the glyph width of the platform (a channel glyph is two cells + on regular, and one cell on the PicoCalc console). The label lane has the width of the + longest name in the list, between :data:`_LABEL_MIN` and :data:`_LABEL_MAX`. Attributes: - marker: The leading glyph lane — a channel glyph or contact dot plus its space. - label: Cells the conversation name is padded/ellipsized to. + marker: The first glyph lane: a channel glyph or a contact dot, and its space. + label: The number of cells to which the conversation name is padded or cut with an + ellipsis. """ marker: int @@ -790,57 +811,58 @@ class _Lanes: @property def head(self) -> int: - """Cells before the preview: everything ←→ leave pinned (:attr:`Choice.hscroll_from`). + """The cells before the preview: all that ←→ do not move (:attr:`Choice.hscroll_from`). - Marker, name, unread badge and age, with the two-cell gap that follows each — the - columns that say *which conversation this row is*. The preview is the only run that - slides, which is the point: the lanes are the reader's place in the list and they - already fit. + The marker, the name, the unread badge, and the age, each with the gap of two cells + after it. These columns say *which conversation this row is*. The preview is the + only part that moves, and that is the purpose. The lanes show the user where the + user is in the list, and they already fit. """ return self.marker + self.label + 2 + _BADGE_WIDTH + 2 + _AGE_WIDTH + 2 def _lanes(conversations: list[Conversation]) -> _Lanes: - """Measure the picker's lanes against the conversations it is about to draw. + """Measure the lanes of the picker for the conversations that it will draw. - The name lane used to be a flat 22 cells, which is a wide claim on a 72-column terminal - and a very wide one on the PicoCalc's 53: every cell it holds past the longest name in - the list is padding taken straight out of the last-message preview. Sized to the content - instead, a mesh of ``Alice`` and ``Bob`` keeps its names inside the header word's own - lane and gives everything else to the messages. + Before, the name lane was always 22 cells. That is wide on a terminal of 72 cells, and + very wide on the 53 cells of the PicoCalc. Each cell after the longest name in the list + is padding that the preview of the last message loses. When the width comes from the + content, a mesh of ``Alice`` and ``Bob`` keeps its names in the lane of the header word, + and gives all the other cells to the messages. Args: - conversations: Every row the list will hold, channels and direct alike. + conversations: All the rows that the list will hold, channels and direct. Returns: - The lane widths for both the header and the rows. + The lane widths for the header and for the rows. """ longest = max((cell_len(c.label) for c in conversations), default=0) return _Lanes( - # The marker is "glyph + space", and the glyph is the platform's: double-cell on - # regular, single on the console font. Read from the widget rather than assumed, so - # the two groups' lanes line up on both platforms — a contact's dot is padded to - # whatever a channel's glyph measures here (see _append_marker). + # The marker is "glyph + space", and the glyph comes from the platform: two cells on + # regular, one cell on the console font. The width is read from the widget, not + # assumed. Thus the lanes of the two groups align on the two platforms: the dot of + # a contact is padded to the width of a channel glyph here (refer to + # _append_marker). marker=cell_len(channel_glyph("Public", None)) + 1, label=max(_LABEL_MIN, min(_LABEL_MAX, longest)), ) def _picker_header(lanes: _Lanes, width: int) -> str: - """Column headers over the picker's fixed lanes (see :func:`_title` for the layout). + """Column headers above the fixed lanes of the picker (the layout is in :func:`_title`). - The indent covers the select screen's pointer column (2 cells, drawn on choice rows but - not separators) plus the marker lane, so each header lands exactly over its column. - ``NEW`` counts the unread messages, ``LAST`` is the last message's age, and ``MESSAGE`` - is that message — short words, because the lanes under the first two are a badge and an - age, and a heading longer than its lane runs into the next one's. ``LAST`` still borrows - its lane's trailing gap (the age lane is three cells), which leaves a space before the - preview. + The indent covers the pointer column of the select screen (2 cells, drawn on choice + rows but not on separators) and the marker lane. Thus each header is exactly above its + column. ``NEW`` counts the unread messages, ``LAST`` is the age of the last message, + and ``MESSAGE`` is that message. The words are short, because the lanes under the + first two are a badge and an age, and a heading that is longer than its lane touches + the next heading. ``LAST`` also uses the gap after its lane (the age lane is three + cells), and that leaves a space before the preview. - Resolved against the render width (the header row is pinned, so it must stay one row): - on a terminal too narrow for the whole line, ``MESSAGE`` gives its cells back as ``MSG`` - rather than the line wrapping or losing the label (see - :func:`~meshterm.ui.menus.column_header`). + The header is resolved for the render width (the header row is pinned, so it must + stay one row). On a terminal that is too narrow for the full line, ``MESSAGE`` becomes + ``MSG`` and gives back its cells. Thus the line does not wrap and does not lose the + label (refer to :func:`~meshterm.ui.menus.column_header`). """ return column_header( [ @@ -863,22 +885,24 @@ def _row_title( *, name_of: NodeResolver | None = None, ) -> Callable[[], str | Text]: - """Return a picker-row title *callable* the select screen re-renders on each repaint. + """Return the row title as a *callable* that the select screen renders on each paint. - Both the unread badge and the last-message preview are read live, so a message arriving - while the picker sits open updates that row's ``●`` count *and* its sender/text preview on - the next repaint (the session already repaints ~1×/s for the header). + The unread badge and the preview of the last message are both read live. Thus, when a + message arrives while the picker is open, the next paint changes the ``●`` count of + that row *and* its preview of the sender and text (the session already paints + approximately one time each second, for the header). Args: - ctx: Shared application context (for the live unread count). - conversation: The conversation the row represents. - lasts: The self-refreshing latest-message view feeding the preview. - key_of: Maps a sender name back to its node's key, for the preview hues. - lanes: The list's measured lane widths. - name_of: Maps a room post's author key to a name (rooms only). + ctx: The shared application context (for the live unread count). + conversation: The conversation of the row. + lasts: The lookup of the latest messages, which reads itself again and gives the + preview. + key_of: Maps a sender name back to the key of its node, for the hues of the preview. + lanes: The measured lane widths of the list. + name_of: Maps the author key of a room post to a name (only for rooms). Returns: - A zero-argument callable producing the current row title. + A callable with no arguments, which makes the current row title. """ return lambda: _title(ctx, conversation, lasts, key_of, lanes, name_of=name_of) @@ -892,24 +916,30 @@ def _title( *, name_of: NodeResolver | None = None, ) -> str | Text: - """Build a picker row as fixed-width, colour-coded lanes. + """Make a picker row from lanes of fixed width, with colour codes. - Alignment carries the readability — marker, label, unread badge, relative age, and preview - each sit in their own lane, so every row's message text starts in the same column. Colour is - purposeful: a direct contact's name takes its key-derived palette hue (a channel label stays - base), the leading dot is the standard companion pink with its shape marking history, the - unread ``●`` badge is red, the age is muted, and the preview mutes its body while lighting - sender names and ``@mentions`` in their key-derived hue — the same colours the live - transcript uses. The row is always a Rich :class:`~rich.text.Text` so those spans survive - under the select screen's row highlight. + The alignment makes the row easy to read. The marker, the label, the unread badge, the + relative age, and the preview each have their own lane. Thus the message text of each + row starts in the same column. Each colour has a purpose: + + - The name of a direct contact gets the palette hue that comes from its key (a channel + label keeps the base style). + - The first dot is the standard companion pink, and its shape shows the history. + - The unread ``●`` badge is red, and the age is muted. + - The preview mutes its body, and lights the sender names and the ``@mentions`` in the + hues that come from their keys. These are the same colours as in the live transcript. + + The row is always a Rich :class:`~rich.text.Text`, so that those spans stay under the + row highlight of the select screen. Args: - ctx: Shared application context (for the live unread count). - conversation: The conversation the row represents. - lasts: The self-refreshing latest-message view. - key_of: Maps a preview sender/mention name back to its node's key. - lanes: The list's measured lane widths. - name_of: Maps a room post's author key to a name (rooms only). + ctx: The shared application context (for the live unread count). + conversation: The conversation of the row. + lasts: The lookup of the latest messages, which reads itself again. + key_of: Maps a sender name or a mention name in the preview back to the key of its + node. + lanes: The measured lane widths of the list. + name_of: Maps the author key of a room post to a name (only for rooms). Returns: The row title as a styled :class:`~rich.text.Text`. @@ -924,15 +954,15 @@ def _title( label_style = name_style(conversation.label, contact.public_key or contact.key_prefix) text.append(fit_cells(conversation.label, lanes.label), style=label_style or None) text.append(" ") - # Unread badge lane (_BADGE_WIDTH cells): a red ● with the count in warn, or blank filler so - # the following lanes still line up on rows with nothing unread. + # The unread badge lane (_BADGE_WIDTH cells): a red ● with the count in warn, or blank + # spaces. Thus the lanes after it still align on rows with nothing unread. if unread: text.append("●", style="err") text.append(f" {unread}".ljust(_BADGE_WIDTH - 1), style="warn") else: text.append(" " * _BADGE_WIDTH) - # Relative-age lane (right-aligned) sits between the badge and the message text, so the ages - # stack in one tidy column and the previews all start at the same place. + # The relative age lane (right-aligned) is between the badge and the message text. Thus + # the ages are in one neat column, and all the previews start at the same position. age = _ago(last.created_at) if last is not None else "" text.append(" ") text.append(f"{age:>{_AGE_WIDTH}}", style="muted") @@ -942,31 +972,33 @@ def _title( return text -#: The standard companion pink — the shared plain-node ``●`` colour — the contact dot's -#: hue: the shape (filled/hollow) marks history, the colour marks "a companion", and the -#: name beside it carries the person's own key-derived hue. +#: The standard companion pink (the shared colour of the plain node ``●``) is the hue of the +#: contact dot. The shape (filled or hollow) shows the history, the colour shows "a +#: companion", and the name next to it has the hue that comes from the key of the person. _COMPANION_DOT_STYLE = NODE_GLYPHS[NODE_TYPE_CHAT][1] -#: A room's marker: the room server's own ``■``, in its type colour — the mark the map and -#: the contact list give a room. The console font has no hollow square, so it carries no -#: history state; the preview lane says whether there is anything to read, or to join. +#: The marker of a room: the ``■`` of the room server, in the colour of its type. The map +#: and the contact list give a room the same mark. The console font has no hollow square, +#: so the marker shows no history state. The preview lane says whether there is something +#: to read, or a room to join. _ROOM_MARK = NODE_GLYPHS[NODE_TYPE_ROOM] def _append_marker( text: Text, conversation: Conversation, last: ChatMessage | None, lanes: _Lanes ) -> None: - """Prepend the row's leading marker — a channel glyph or a contact dot — in its own lane. + """Add the first marker of the row (a channel glyph or a contact dot) in its own lane. - A channel keeps its openness marker (# / 🌐 / 🔒). A contact gets a small circle in the - standard companion pink — filled (``●``) once we've exchanged messages, a hollow ring - (``○``) before any — so the hollow-vs-filled shape marks whether there's history while the - name itself carries the person's key-derived hue. + A channel keeps its marker for open or private (# / 🌐 / 🔒). A contact gets a small + circle in the standard companion pink. It is filled (``●``) after we exchanged + messages, and a hollow ring (``○``) before that. Thus the shape (hollow or filled) + shows whether there is history, and the name itself has the hue that comes from the + key of the person. - The dot is padded out to :attr:`_Lanes.marker`, which is measured from the channel glyph - itself rather than assumed: that glyph is double-cell on regular and single-cell on the - PicoCalc console font, so a hard-coded pad lined the two sections up on one platform and - left every channel row a cell to the left of every direct row on the other. + The dot is padded to :attr:`_Lanes.marker`, which is measured from the channel glyph + itself, not assumed. That glyph is two cells on regular and one cell on the PicoCalc + console font. A fixed pad aligned the two sections on one platform. On the other + platform, it put each channel row one cell to the left of each direct row. """ if conversation.is_channel: glyph = channel_glyph(conversation.label, conversation.secret) @@ -984,19 +1016,23 @@ def _append_marker( def _preview_text( last: ChatMessage, key_of: NameKeyResolver, name_of: NodeResolver | None = None ) -> Text: - """A muted last-message preview with sender names and ``@mentions`` lit in their hue. + """A muted preview of the last message, with sender names and ``@mentions`` lit in their hue. - Mirrors the live transcript: our own messages get a ``you:`` prefix, an inbound channel - message's inline ``Name:`` sender is coloured in its key-derived hue (muted when no known - node carries the name), a room post leads with its author — named by key the way the room - view names them (:func:`~meshterm.ui.room.author_label`) — and every ``@[Name]`` mention - reads as a bare ``@Name`` the same way, so the list and the chat speak the same colour - language. + It is the same as the live transcript: - The preview is built *whole*, however long the message ran. It used to be clipped to a - fixed 40 cells, which is a cut nothing could undo: the row is what ←→ scroll now, and a - preview pre-truncated to roughly the visible lane would have had nothing left to reveal. - The list cuts it at the right edge like any other row; the scroll walks past that. + - Our own messages get a ``you:`` prefix. + - In a received channel message, the inline ``Name:`` sender gets the hue that comes from + its key (muted when no known node has the name). + - A room post starts with its author, named by key in the same way as the room screen + names authors (:func:`~meshterm.ui.room.author_label`). + - Each ``@[Name]`` mention shows as a bare ``@Name``, in the same way. + + Thus the list and the chat use the same colour language. + + The preview is made *in full*, however long the message is. Before, it was cut to a + fixed 40 cells, and nothing could undo that cut. Now ←→ scroll the row. A preview that + was cut before to approximately the visible lane has nothing more to show. The list + cuts it at the right edge, the same as any other row, and the scroll goes past that. """ body_raw = last.text.replace("\n", " ") text = Text() @@ -1024,10 +1060,10 @@ def _preview_text( def _append_body(text: Text, body: str, key_of: NameKeyResolver) -> None: - """Append ``body`` to ``text``, muted, lighting up the names it mentions. + """Append ``body`` to ``text``, muted, and light the names that it mentions. - Each ``@[Name]`` is drawn in that node's key-derived hue, or left muted when the - name resolves to no node we know. + Each ``@[Name]`` is drawn in the hue that comes from the key of that node. It stays + muted when the name resolves to no node that we know. """ pos = 0 for match in MENTION.finditer(body): @@ -1041,11 +1077,11 @@ def _append_body(text: Text, body: str, key_of: NameKeyResolver) -> None: def _ago(when: Any) -> str: - """The column age for a message time, through THE grammar (``format_age``). + """The column age for a message time, through the only grammar (``format_age``). - One deliberate difference from the widget: a missing or naive timestamp (a stray one - from the wire) reads as a *blank* lane rather than ``never`` — the picker wants an - empty cell there, not a word. + There is one difference from the widget, on purpose. A missing or naive timestamp (a + bad value from the wire) shows as a *blank* lane, not as ``never``. The picker must + have an empty cell there, not a word. """ if getattr(when, "tzinfo", None) is None: return "" @@ -1053,11 +1089,12 @@ def _ago(when: Any) -> str: def _channel_ref(idx: int | None, label: str, secret: bytes | None) -> ChannelRef: - """One channel as the shared shape, from whatever the surface knows about it. + """One channel in the shared shape, from what the surface knows about it. - A transcript row and a live message know a slot and a label but not the key, so - ``public`` is read off the name where the secret is not in hand — which is what the - leading ``#`` means and how a public channel is written everywhere else in the app. + A transcript row and a live message know a slot and a label, but not the key. Thus, + when the secret is not available, ``public`` comes from the name. A ``#`` at the start + of the name means a public channel, and the app writes a public channel that way in + all other places. """ return ChannelRef( slot=int(idx or 0), @@ -1068,21 +1105,22 @@ def _channel_ref(idx: int | None, label: str, secret: bytes | None) -> ChannelRe def _message_columns(*, author_lane: bool = False) -> tuple: - """One transcript row's columns, shared by ``history`` and the ``listen`` stream. + """The columns of one transcript row, shared by ``history`` and the ``listen`` stream. - ``DIR`` carries what the menu's transcript writes into its sender lane as the word - "you": which way a message went is a fact of its own, and spending the name lane on it - made our own name a value that lane could not otherwise hold. ``PEER`` is therefore + ``DIR`` holds what the transcript of the menu writes into its sender lane as the word + "you". The direction of a message is a separate fact. When the name lane held it, our + own name became a value that the lane could not hold in other cases. Thus ``PEER`` is always the *other* party. - ``TEXT`` is last and escaped: it is the rest of the line, and "the rest of the line" - stops being true the moment a body holds a newline — after which the remainder reads - as a second record with an empty time. The document carries the body raw, a JSON string - holding a newline natively. + ``TEXT`` is last and escaped. It is the rest of the line, and "the rest of the line" + is not true when a body holds a newline. After the newline, the rest looks like a + second record with an empty time. The document holds the raw body, because a JSON + string can hold a newline. - ``author`` is a room post's writer, in every document (``null`` off a room) so one - command answers in one shape; ``author_lane`` draws it as ``AUTHOR`` too, for a room's - transcript, where it is the column a reader is there for. + ``author`` is the writer of a room post. It is in each document (``null`` when the + conversation is not a room), so that one command answers in one shape. For the + transcript of a room, ``author_lane`` also draws it as ``AUTHOR``, because there it is + the column that the user wants to see. """ from dataclasses import replace @@ -1092,9 +1130,10 @@ def _message_columns(*, author_lane: bool = False) -> tuple: return ( fields.when("created_at", "TIME"), fields.word("direction", "DIR"), - # One column for whichever end the conversation had; the document keeps the two - # apart, because a parser cannot tell a channel from a contact by its label. A - # room's transcript names the room on every row, so there AUTHOR stands instead. + # One column for the other end of the conversation, whichever type it is. The + # document keeps the two types apart, because a parser cannot tell a channel from a + # contact by its label. The transcript of a room names the room on each row, so + # there AUTHOR is in its place. replace(peer, lanes=()) if author_lane else peer, fields.node("node", lanes=()), fields.channel("channel", lanes=()), @@ -1106,11 +1145,11 @@ def _message_columns(*, author_lane: bool = False) -> tuple: def _author_column(*, lane: bool) -> Any: - """A room post's author: the shared node object, drawn as one hop — ``Name (hash)``. + """The author of a room post: the shared node object, drawn as one hop (``Name (hash)``). - The hop's grammar (:func:`~meshterm.ui.script.route`), because that is the plain - face's one way of naming a node by name *and* key: an author nothing names is its hash - alone, never an empty ``()``. + It uses the grammar of a hop (:func:`~meshterm.ui.script.route`), because that is the + one way in which the plain face names a node by name *and* key. When nothing names an + author, the author is only its hash, never an empty ``()``. """ from dataclasses import replace @@ -1128,7 +1167,7 @@ def _author_column(*, lane: bool) -> Any: def _self_ref(info: dict) -> NodeRef: - """Our own node, from the companion's self info — how a post of ours names its author.""" + """Our node, from the self info of the companion: how one of our posts names its author.""" key = str(info.get("public_key") or "").lower() return NodeRef( name=str(info.get("name") or "") or None, @@ -1140,7 +1179,7 @@ def _self_ref(info: dict) -> NodeRef: def _author_ref(author: str, name_of: NodeResolver | None) -> NodeRef: - """A post's author as a node: its hash always, its name where something names it.""" + """The author of a post as a node: always its hash, and its name if something names it.""" from ..ui.room import author_label label, key = author_label(author, name_of) if name_of is not None else (author, None) @@ -1154,15 +1193,15 @@ def _transcript( name_of: NodeResolver | None = None, me: NodeRef | None = None, ) -> Listing: - """A conversation's stored messages, oldest first, one record each. + """The stored messages of a conversation, oldest first, one record for each. Args: messages: The transcript. - room: Whether it is a room's board: each row then names its author, in an - ``AUTHOR`` lane standing where ``PEER`` would (the peer being the room on - every row). - name_of: Names an author's key, for a room. - me: Our own node, the author of our own posts in a room. + room: Whether it is the board of a room. Then each row names its author, in an + ``AUTHOR`` lane in the place of ``PEER`` (because the peer is the room on + each row). + name_of: Names the key of an author, for a room. + me: Our node, the author of our own posts in a room. """ from ..ui.report import Listing @@ -1201,12 +1240,12 @@ def _transcript( def _live_messages() -> Listing: - """The shape ``chat listen`` streams: what arrived, as it arrived. + """The shape that ``chat listen`` streams: what arrived, when it arrived. - ``TIME`` is absolute here where the transcript's is an age, and for the reason the - whole time rule turns on: every row of a live tail would read ``now``, which is no - information at all. There is no ``DIR`` lane — everything a tail hears came in — and - the body goes last, so the one field with no width can never push a lane. + Here ``TIME`` is absolute, but in the transcript it is an age. The reason is the base + of the full time rule: with ages, each row of a live tail shows ``now``, which gives no + information. There is no ``DIR`` lane, because all that a tail hears came in. The + body goes last, so that the one field with no width can never push a lane. """ from dataclasses import replace @@ -1223,8 +1262,8 @@ def _live_messages() -> Listing: pin(fields.plain_only(fields.name("conversation", "PEER")), 16), fields.node("node", lanes=()), fields.channel("channel", lanes=()), - # A room post's writer rides in the document; the tail itself names the room, - # which is the node that sent it. + # The writer of a room post is in the document. The tail itself names the room, + # which is the node that sent the post. _author_column(lane=False), pin(fields.snr("snr_db", "SNR_DB"), 6), fields.free("text", "TEXT"), @@ -1236,11 +1275,11 @@ def _live_messages() -> Listing: def _conversations(ctx: AppContext, rows: list, lasts: dict) -> Listing: - """Every channel and contact, with the last thing said in each. + """Each channel and contact, with the last message in each. - ``LAST`` is an age rather than an instant: a conversation list is scanned for what is - warm, and ``never`` is a real answer — the conversation exists and nothing has been - said in it. + ``LAST`` is an age, not an instant. A user looks through a conversation list for the + conversations that are active. ``never`` is a real answer: the conversation exists, + and it has no messages. """ from ..ui import fields from ..ui.report import Listing @@ -1275,9 +1314,9 @@ def _conversations(ctx: AppContext, rows: list, lasts: dict) -> Listing: ), "unread": ctx.chat.unread(conversation.key), "last_message_at": last.created_at if last is not None else None, - # Not truncated to 40 cells the way the picker's preview is: nothing here - # wraps, so there is no reason to cut a message short — but a body that - # holds a newline would still end the record, so it is folded flat. + # Not cut to 40 cells, as the preview of the picker is. Nothing here wraps, + # so there is no reason to make a message shorter. But a body that holds a + # newline still ends the record, so it is folded flat. "last_text": last.text if last is not None else None, } ) @@ -1306,16 +1345,16 @@ def _sent( ) -> Facts: """What one ``chat send`` did. - A direct message prints its ``acked`` state, which is the one thing the send does not - already tell the caller: the radio accepted it either way, and whether the peer - answered is a separate fact. A channel broadcast prints nothing, because there *is* no - acknowledgement on a channel — and the document says that in the one way the plain - face never could, with ``null`` rather than ``false``. + A direct message prints its ``acked`` state. That is the one thing that the send does + not already tell the caller: the radio accepted the message in the two cases, and the + answer of the peer is a separate fact. A channel broadcast prints nothing, because a + channel *has* no acknowledgement. The document says that in the one way that the plain + face cannot: with ``null``, not ``false``. - The document also carries the ``scope`` a channel message went out under, in the same - shape a received frame's scope takes (:func:`~meshterm.ui.fields.scope`): the region, - ``unscoped``, or ``null`` where it isn't known (a direct message, or a default scope - that couldn't be read). + The document also holds the ``scope`` under which a channel message went out, in the + same shape as the scope of a received packet (:func:`~meshterm.ui.fields.scope`): the + region, ``unscoped``, or ``null`` when it is not known (a direct message, or a default + scope that MeshTerm could not read). """ from dataclasses import replace @@ -1342,16 +1381,16 @@ def _sent( return Facts( key="sent", fields=( - # `acked` is the only lane: the caller named the recipient and the radio - # accepting the message is what a zero exit already says, so the one fact + # `acked` is the only lane. The caller named the recipient, and a zero exit + # already says that the radio accepted the message. Thus the one fact that is # left to report is whether the peer answered. fields.hidden("kind"), fields.node("node", lanes=()), fields.channel("channel", lanes=()), fields.hidden("sent"), fields.flag("acked", "acked"), - # Document only: a direct message has no scope of its own to print, and a - # channel send prints nothing at all. + # Only in the document. A direct message has no scope of its own to print, and a + # channel send prints nothing. replace(fields.scope("scope", "scope"), lanes=()), ), values={ diff --git a/meshterm/tools/config.py b/meshterm/tools/config.py index 7e0d40d..a23b64e 100644 --- a/meshterm/tools/config.py +++ b/meshterm/tools/config.py @@ -1,13 +1,14 @@ # SPDX-License-Identifier: Apache-2.0 -"""The ``config`` tool: every device setting, and the operations on the box itself. +"""The ``config`` tool: each device setting, and the operations on the device itself. -Interactively it opens the Device config page (see :mod:`meshterm.ui.config_editor`) — -settings staged and applied in place, with the clock, backup/restore, the identity key, -reboot and factory reset as actions below them. On the CLI it exposes generic key/value -subcommands plus backup/restore, channels, custom vars, and a ``--yes``-gated set of -destructive operations. Everything funnels through :func:`apply_ops`: the page's Apply and -its actions, :meth:`ConfigTool.run` for the scripted commands, and the standalone ``advert`` -tool's sends all run through the one executor. +In the menu, it opens the Device config page (refer to :mod:`meshterm.ui.config_editor`). +There, the settings are staged and applied in place, and the clock, backup and restore, +the identity key, reboot, and factory reset are actions below them. On the CLI, it has +generic key and value subcommands, and also backup and restore, channels, custom +variables, and a set of destructive operations that must have ``--yes``. All of these go +through :func:`apply_ops`. The Apply and the actions of the page, :meth:`ConfigTool.run` +for the scripted commands, and the sends of the standalone ``advert`` tool all run +through the one executor. """ from __future__ import annotations @@ -38,7 +39,7 @@ if TYPE_CHECKING: # pragma: no cover - typing only @register class ConfigTool(Tool): - """View and edit the connected device's full configuration.""" + """Show and edit all the settings of the connected device.""" name = "config" title = "Device config" @@ -48,14 +49,14 @@ class ConfigTool(Tool): order = 20 async def prompt_params(self, ctx: AppContext) -> dict[str, Any] | None: - """Run the Device config page; there are never parameters to collect. + """Run the Device config page. There are never parameters to collect. - The page applies what is staged and runs its actions itself, logging a ``runs`` row - for each Apply (the same pattern as ``repeater-admin``), so by the time the reader - backs out there is nothing left for :meth:`run` to do. + The page itself applies the staged values and runs its actions, and logs a ``runs`` + row for each Apply (the same pattern as ``repeater-admin``). Thus, when the user + leaves, :meth:`run` has nothing more to do. Args: - ctx: Shared application context. + ctx: The shared application context. Returns: Always ``None``. @@ -66,14 +67,14 @@ class ConfigTool(Tool): return None async def run(self, ctx: AppContext, params: dict[str, Any]) -> ToolResult: - """Execute a list of configuration operations against the device. + """Do a list of setting operations on the device. Args: - ctx: Shared application context. - params: ``ops`` — a list of operation tuples (see module docstring). + ctx: The shared application context. + params: ``ops``: a list of operation tuples (refer to the module docstring). Returns: - A :class:`ToolResult` summarizing how many values changed. + A :class:`ToolResult` with a summary of how many values changed. """ device = await ctx.device() ops: list[tuple] = list(params.get("ops") or []) @@ -104,7 +105,7 @@ class ConfigTool(Tool): @config_app.callback(invoke_without_command=True) def _root(ctx: typer.Context) -> None: - """Show the configuration when no subcommand is given.""" + """Show all the current settings when no subcommand is given.""" if ctx.invoked_subcommand is None: run_tool_command(self, {"ops": [("show",)]}) @@ -196,30 +197,30 @@ class ConfigTool(Tool): app.add_typer(config_app, name=self.name) -# -- op execution (shared by the tool and the interactive editor) ------------- +# -- op execution (the tool and the interactive editor share it) -------------- async def apply_ops( ctx: AppContext, device: Device, snapshot: dict, ops: list[tuple] ) -> tuple[int, list[str], Report]: - """Execute a list of configuration operation tuples against ``device``. + """Do a list of setting operation tuples on ``device``. - This is the single executor for every config operation, used by :meth:`ConfigTool.run` - (the scripted commands) and by the Device config page — its Apply, one staged value at a - time, and its actions (reboot, backup/restore, key management, factory reset), which run - immediately rather than staging. + This is the only executor for all the setting operations. :meth:`ConfigTool.run` (the + scripted commands) uses it, and the Device config page uses it too: for its Apply, one + staged value at a time, and for its actions (reboot, backup and restore, key + management, factory reset). The actions run immediately, and are not staged. Args: - ctx: Shared application context (for console output). - device: The connected device to act on. - snapshot: The current device snapshot; updated in place as settings change so - coupled commands rebuild from current values. - ops: Operation tuples (see the module docstring). + ctx: The shared application context (for console output). + device: The connected device on which to do the operations. + snapshot: The current device snapshot. It is changed in place when settings + change, so that coupled commands are made again from the current values. + ops: The operation tuples (refer to the module docstring). Returns: - A ``(changes, artifacts, report)`` triple: the number of value changes applied, - any file paths produced, and the blocks stating what happened (empty for the - menu, which shows its own acknowledgements). + A ``(changes, artifacts, report)`` triple: the number of applied value changes, + the paths of the files that were made, and the blocks that state what occurred + (empty for the menu, which shows its own acknowledgements). """ changes = 0 artifacts: list[str] = [] @@ -232,10 +233,10 @@ async def apply_ops( if block is not None: report.append(block) elif kind == "get": - # The bare value, nothing else: the caller named the key, so repeating it back - # is one more thing for `$(meshterm config get name)` to strip off. The same - # shape `sysctl -n` and `git config --get` print. The document keeps the key, - # the type and an enum's label, none of which the bare form has room for. + # Only the bare value. The caller named the key, so if the output repeats it, + # `$(meshterm config get name)` must remove one more thing. `sysctl -n` and + # `git config --get` print the same shape. The document keeps the key, the type, + # and the label of an enum, and the bare form has space for none of them. spec = get_spec(op[1]) report.append(_one_setting(spec, spec.getter(snapshot))) elif kind == "set": @@ -265,9 +266,10 @@ async def apply_ops( elif kind == "advert": flood = len(op) > 1 and bool(op[1]) await device.send_advert(flood) - # A flood advert, however it was asked for, restarts this device's week: the - # weekly one only ever goes out a full week after the last (see - # AdvertScheduler). A zero-hop reaches only the neighbours, and resets nothing. + # A flood advert, however it was requested, starts the week of this device again. + # The weekly advert goes out only a full week after the last one (refer to + # AdvertScheduler). A zero-hop advert gets only to the neighbours, and resets + # nothing. public_key = str(snapshot.get("public_key") or "") if flood and public_key: ctx.advert_store.mark_flood(public_key) @@ -277,8 +279,8 @@ async def apply_ops( elif kind == "share": report.append(await _share_contact(ctx, snapshot)) elif kind == "sync_clock": - # The same step the on-connect service runs in the background - # (:mod:`meshterm.services.clock_sync`); here it is acknowledged and reported. + # The same step that the on-connect service runs in the background + # (:mod:`meshterm.services.clock_sync`). Here, it is acknowledged and reported. done = await set_clock(device) if done.written: ctx.ui.ack(f"[ok]✓[/ok] device clock set to [brand]{done.stamp}[/brand]") @@ -293,8 +295,8 @@ async def apply_ops( "clock", changes=int(done.written), set_at=done.set_at, - # What the clock was off by *before* the set: the fact worth logging, - # and the one this command destroys by succeeding. + # The clock error *before* the set. That is the fact to log, and when + # this command succeeds, it removes that fact. drift_s=done.drift_s, ) ) @@ -303,8 +305,9 @@ async def apply_ops( ctx.ui.ack("[warn]device rebooting[/warn]") report.append(_acted("reboot", rebooted=True)) if ctx.active_transport is not None: - # Run from the menu's command line, this hands off to the reconnect dialog - # as the config editor's reboot does; a scripted run has no watcher to wake. + # When this runs from the command line of the menu, it gives control to the + # reconnect dialog, as the reboot of the config editor does. A scripted run + # has no watcher to wake. ctx.announce_reboot() elif kind == "export_key": report.append(await _export_key(ctx, device, op[1] if len(op) > 1 else None, artifacts)) @@ -317,20 +320,21 @@ async def apply_ops( await device.factory_reset() ctx.ui.ack("[err]device factory-reset[/err]") report.append(_acted("factory_reset", factory_reset=True)) - else: # pragma: no cover - guarded by the call sites that build ops + else: # pragma: no cover - the call sites that make ops prevent this raise DeviceCommandError(f"unknown config operation: {kind}") if applied: report.append(_applied(applied)) - # Drop any session-cached facts these ops may have changed, so the next screen re-reads - # the truth rather than a stale copy (see meshterm.services.device_state.DeviceState). A - # reboot/reconnect resets the whole cache on its own; these cover the in-place edits. + # Remove the facts in the session cache that these ops can have changed. Thus the next + # screen reads the true values again, not an old copy (refer to + # meshterm.services.device_state.DeviceState). A reboot or a reconnect resets the full + # cache itself. These lines are for the edits in place. kinds = {op[0] for op in ops} _WHOLESALE = {"restore", "import_key", "factory_reset"} if kinds & _WHOLESALE: ctx.devstate.reset() else: if "set" in kinds: - ctx.devstate.invalidate_config() # self-info fields + path-hash mode + ctx.devstate.invalidate_config() # the self-info fields and the path hash mode if "set_channel" in kinds: ctx.devstate.invalidate_channels() return changes, artifacts, tuple(report) @@ -339,24 +343,25 @@ async def apply_ops( async def _apply_setting( ctx: AppContext, device: Device, key: str, raw: Any, snapshot: dict ) -> dict[str, Any]: - """Parse, apply and record one setting; keep ``snapshot`` consistent. + """Parse, apply, and store one setting, and keep ``snapshot`` consistent. - The local snapshot is updated with the new value so a later coupled change in the - same batch (e.g. another radio field) is rebuilt from current values. + The local snapshot gets the new value. Thus a later coupled change in the same batch + (for example, another radio field) is made again from the current values. Returns: - The change, as ``{"key", "previous", "value"}``. The *previous* value is read off - the snapshot before it is overwritten: a caller managing a machine's configuration - wants to know what moved, and it is gone the moment this returns. + The change, as ``{"key", "previous", "value"}``. The *previous* value is read from + the snapshot before it is overwritten. A caller that manages the settings of a + machine wants to know what changed, and the old value is gone when this function + returns. """ spec = get_spec(key) value = parse_value(spec, raw, snapshot) previous = spec.getter(snapshot) await spec.apply(device, value, snapshot) snapshot[key] = value - # Remember what we set, keyed by the device's own public key, so a forgetful device (a - # firmware-less radio bridge) can be offered its settings back on the next connect (see - # meshterm.core.settings_store). Provenance-gated: only values changed through MeshTerm. + # Keep what we set, keyed by the public key of the device. Thus a device that forgets + # (a radio bridge with no firmware) can get its settings back at the next connect (refer + # to meshterm.core.settings_store). Only the values that MeshTerm changed are kept. if ctx.settings_store is not None: ctx.settings_store.remember(str(snapshot.get("public_key") or ""), key, value) if key == "flood_scope": @@ -366,21 +371,21 @@ async def _apply_setting( def learn_default_scope(ctx: AppContext, snapshot: dict) -> None: - """Take in the default flood scope a config read or write has just seen. + """Keep the default flood scope that a settings read or a settings write got. - Two things want it. The region store learns the name (source ``default``): it is the - region this station's own plain floods carry, so it is the first name any of them will - be resolved against. And the session cache holds it (``devstate``), since a channel with - no scope of its own records its messages as sent under the default, and this saves that - record a round trip. + Two parts of MeshTerm use it. The region store learns the name (source ``default``). + It is the region that the plain floods of our node have, so it is the first name + against which any of them is resolved. The session cache (``devstate``) also keeps + it, because a channel with no scope of its own stores its messages as sent under the + default. Thus that store does not have to do a round trip. - A snapshot whose read of the default failed (firmware before 1.15) carries no - ``flood_scope`` key at all, and teaches nothing. + A snapshot whose read of the default failed (firmware before 1.15) has no + ``flood_scope`` key, and gives nothing to learn. Args: - ctx: Shared application context. - snapshot: A :func:`~meshterm.core.device_config.build_snapshot` result, or one an - apply has just updated. + ctx: The shared application context. + snapshot: A :func:`~meshterm.core.device_config.build_snapshot` result, or a + snapshot that an apply has changed. """ if "flood_scope" not in snapshot: return @@ -396,17 +401,17 @@ def learn_default_scope(ctx: AppContext, snapshot: dict) -> None: async def _show(ctx: AppContext, device: Device, snapshot: dict) -> Listing | None: - """Print every current setting, plus any custom variables. + """Print each current setting, and the custom variables, if there are any. - The menu shows the annotated table; a scripted run gets one ``key value`` line per - setting, keyed exactly as ``config get`` and ``config set`` name them, so a line read - out of ``show`` can be typed straight back in. The labels and descriptions the table - carries are for a reader choosing a setting, and this reader has already chosen. + The menu shows the table with notes. A scripted run gets one ``key value`` line for + each setting, with the key exactly as ``config get`` and ``config set`` name it. Thus + a line from ``show`` can be typed back in directly. The labels and descriptions in the + table help a user who selects a setting, but this user already selected. - The pairing PIN stays concealed here, as it is in the table: this is the whole-device - dump, the thing that gets redirected into a file and pasted into a bug report, and the - PIN is the one value on it that lets someone else's phone onto the radio. - ``config get device_pin`` names it deliberately. + The pairing PIN stays hidden here, as it is in the table. This is the dump of the full + device: a person redirects it into a file and pastes it into a bug report. The PIN is + the one value in it that lets the phone of another person connect to the radio. + ``config get device_pin`` names it on purpose. """ from ..ui import fields, script from ..ui.config_editor import PIN_KEY, conceal, config_table @@ -428,17 +433,17 @@ async def _show(ctx: AppContext, device: Device, snapshot: dict) -> Listing | No rows.append( { "key": spec.key, - # A masked PIN is *withheld*, which is not a value: the document says - # so with `redacted` and writes `null`, rather than shipping six - # bullets a consumer would have to recognise as a mask. + # A masked PIN is *withheld*, and that is not a value. The document says + # so with `redacted` and writes `null`. It does not send six bullets + # that a consumer must recognize as a mask. "value": fields.Rendered(None if redacted else value, masked), "type": spec.value_type, "label": (spec.choices or {}).get(value) if spec.value_type == "enum" else None, "redacted": redacted, } ) - # Custom variables are experimental firmware fields with no spec, so they are namespaced - # rather than mixed in — a reader can tell which lines `config set` will take. + # Custom variables are experimental firmware fields with no spec. Thus they have their + # own namespace, and are not mixed in. A user can tell which lines `config set` accepts. rows.extend( { "key": f"custom.{key}", @@ -453,26 +458,27 @@ async def _show(ctx: AppContext, device: Device, snapshot: dict) -> Listing | No key="settings", columns=_setting_columns(), rows=rows, - # An array to a parser and a `sysctl -a` block to a reader: a header line over two - # columns whose keys *are* the answer would be furniture. + # An array for a parser, and a `sysctl -a` block for a person. A header line above + # two columns whose keys *are* the answer adds nothing. headed=False, ) def _script_value(spec: SettingSpec, value: Any) -> str: - """A setting's value in the form ``config set`` accepts back. + """The value of a setting, in the form that ``config set`` accepts back. - :func:`~meshterm.core.device_config.format_value` writes for a reader choosing a - setting: an enum reads ``0 (off)``, an unset string reads ``(not set)``, an unreported - one reads ``?``. None of those three survive a round trip — - :func:`~meshterm.core.device_config.parse_value` wants a bare integer for an enum, and - would take the words ``(not set)`` as the literal value of a string. So the scripted - dump prints what can be typed back: the enum's number, the empty string as ``""``, and - :data:`~meshterm.ui.script.NONE` for a value the firmware never reported (which is an - absence, not a value, and is the one line ``config set`` should not be handed back). + :func:`~meshterm.core.device_config.format_value` writes for a user who selects a + setting. An enum shows as ``0 (off)``, a string with no value shows as ``(not set)``, + and a value that the device did not report shows as ``?``. None of those three can go + in and come back out unchanged. :func:`~meshterm.core.device_config.parse_value` must + have a bare integer for an enum, and takes the words ``(not set)`` as the literal value + of a string. Thus the scripted dump prints what can be typed back: the number of the + enum, the empty string as ``""``, and :data:`~meshterm.ui.script.NONE` for a value + that the firmware never reported. That last one is an absence, not a value, and it is + the one line that must not go back to ``config set``. Args: - spec: The setting the value belongs to. + spec: The setting of the value. value: Its current value, or ``None`` when the device did not report it. Returns: @@ -490,13 +496,13 @@ def _script_value(spec: SettingSpec, value: Any) -> str: async def _share_contact(ctx: AppContext, snapshot: dict) -> Facts: - """State this node's contact card — with the QR code drawn in the menu, full-frame. + """State the contact card of this node, with the QR code drawn on the full frame in the menu. - The QR is for a phone pointed at the screen, and there it takes the whole screen - (:func:`~meshterm.ui.qr.share_screen`). Redirected into a file it is a block of - block characters around the one thing that is the answer, so a scripted run states the - link by itself. There is no machine face for the code either, and never will be: it is - a second rendering of ``url``. + The QR code is for a phone that points at the screen, and there it fills the screen + (:func:`~meshterm.ui.qr.share_screen`). In a redirected file, it is a block of block + characters around the one thing that is the answer. Thus a scripted run states only + the link. There is also no machine face for the code, and there never will be one, + because it is a second rendering of ``url``. """ from ..ui import fields from ..ui.config_editor import contact_share_url @@ -527,11 +533,12 @@ async def _share_contact(ctx: AppContext, snapshot: dict) -> Facts: async def _backup(device: Device, snapshot: dict, path: Path) -> tuple[Path, dict[str, int]]: - """Write a TOML backup of the current configuration. + """Write a TOML backup of the current settings. Returns: - The path written and how much went into it, counted the way the file counts — - a setting the firmware never reported is not in the backup and is not in the tally. + The path of the written file, and how much went into it, counted in the same way + as the file counts. A setting that the firmware never reported is not in the + backup, and is not in the count. """ from ..core.device_config import DEVICE_SETTINGS @@ -549,15 +556,16 @@ async def _backup(device: Device, snapshot: dict, path: Path) -> tuple[Path, dic async def _restore( ctx: AppContext, device: Device, snapshot: dict, path: Path, dry_run: bool ) -> tuple[int, list[Block]]: - """Apply (or preview) a backup file against the current configuration. + """Apply (or preview) a backup file over the current settings. - The plan is the answer on a dry run and a record on a real one, so the same listing - serves both — drawn for a reader only when nothing was changed, since a run that *did* - change things already said so, setting by setting, on stderr. + On a dry run, the plan is the answer. On a real run, it is a record. Thus the same + listing is for the two runs. It is drawn for a person only when nothing changed, + because a run that *did* change settings already said so on stderr, one setting at a + time. Returns: - The number of changes applied (always ``0`` for a dry run), and the blocks stating - what was planned or done. + The number of applied changes (always ``0`` for a dry run), and the blocks that + state what was planned or done. """ from ..ui import fields from ..ui.report import SILENT, Facts, Listing @@ -617,16 +625,16 @@ async def _restore( async def _export_key( ctx: AppContext, device: Device, out: Path | None, artifacts: list[str] ) -> Facts: - """Export the private key, to a file if ``out`` is given, else as the answer itself. + """Export the private key: to a file if ``out`` is given, or else as the answer itself. - Either way the plain face prints **one bare line** — the key, or the path it was - written to — because ``config export-key > key.hex`` is expected to hold the key and - nothing else, and a caller that asked for a file wants the name of it. The warning - that comes with either belongs beside it on screen, not in the file, so it goes to - stderr with every other acknowledgement. + In the two cases, the plain face prints **one bare line**: the key, or the path of the + file that holds it. The reason: ``config export-key > key.hex`` must hold the key and + nothing else, and a caller that asked for a file wants its name. The warning that + comes with each of them must be next to it on the screen, not in the file. Thus it + goes to stderr with all the other acknowledgements. - This document carries a private key when one was asked for. That is what the command - is, exactly as on the plain face, and no extra gate is introduced here. + This document holds a private key when the caller asked for one. That is the purpose + of the command, the same as on the plain face, and this function adds no more gate. """ from ..ui import fields from ..ui.report import BARE, Facts @@ -654,12 +662,12 @@ async def _export_key( async def _read_channels(device: Device) -> list[dict]: - """Probe channel slots and return the configured ones.""" + """Probe the channel slots, and return the configured slots.""" channels: list[dict] = [] for idx in range(CHANNEL_SLOT_PROBE_CAP): try: ch = await device.get_channel(idx) - except Exception: # noqa: BLE001 - firmware may not support channel reads + except Exception: # noqa: BLE001 - the firmware may not support channel reads break if ch: channels.append(ch) @@ -667,27 +675,27 @@ async def _read_channels(device: Device) -> list[dict]: def _require_yes(yes: bool, what: str) -> None: - """Abort a destructive CLI command unless ``--yes`` was passed. + """Stop a destructive CLI command, unless the user gave ``--yes``. - Raised as a :class:`typer.BadParameter` rather than printed and exited: a missing - confirmation *is* a usage error, so it belongs on stderr in the parser's own words and - under the parser's own status (see :mod:`meshterm.core.exitcodes`). Printing it in red - on stdout put a colour, and a sentence that is not the command's answer, into whatever - was reading the command's answer. + This function raises a :class:`typer.BadParameter`, and does not print and exit. A + missing confirmation *is* a usage error. Thus it must go to stderr, in the words of the + parser, and with the status of the parser (refer to :mod:`meshterm.core.exitcodes`). + Before, the function printed it in red on stdout. That put a colour, and a sentence + that is not the answer of the command, into the program that read the answer. Args: - yes: Whether the user passed ``--yes``. - what: Human-readable description of the consequence. + yes: Whether the user gave ``--yes``. + what: A description of the result, for a person. Raises: - typer.BadParameter: If confirmation was not given. + typer.BadParameter: If the user did not confirm. """ if not yes: raise typer.BadParameter(f"{what}. Re-run with --yes to confirm.") def _setting_columns() -> tuple: - """One setting row's columns, shared by ``config show`` and ``config get``.""" + """The columns of one setting row, shared by ``config show`` and ``config get``.""" from ..ui import fields return ( @@ -700,11 +708,11 @@ def _setting_columns() -> tuple: def _one_setting(spec: SettingSpec, value: Any) -> Facts: - """One setting: the bare value plain, the whole object in the document. + """One setting: the bare value on the plain face, and the full object in the document. - ``config get device_pin`` is the one place the PIN is named deliberately, so it is - **not** redacted here — the caller asked for that key by name, which is a different - act from dumping every setting into a file. + ``config get device_pin`` is the one place where the caller names the PIN on purpose. + Thus it is **not** redacted here. The caller asked for that key by name, and that is a + different act from a dump of all the settings into a file. """ from ..ui import fields from ..ui.report import BARE, Facts @@ -725,10 +733,10 @@ def _one_setting(spec: SettingSpec, value: Any) -> Facts: def _applied(applied: list[dict[str, Any]]) -> Facts: - """What a ``set`` changed — nothing plain, a record for whoever is logging it. + """What a ``set`` changed: nothing on the plain face, and a record for a program that logs it. - The exit status is the plain answer and the acknowledgement on stderr is the reassurance; - neither is something a script can read back later to find out *what moved*. + The exit status is the plain answer, and the acknowledgement on stderr tells the user + that all is well. A script cannot read either of them later to find *what changed*. """ from ..ui import fields from ..ui.report import SILENT, Column, Facts @@ -766,10 +774,10 @@ def _channel_written(idx: int, name: str, secret: bytes | None) -> Facts: def _backed_up(written: Path, counts: dict[str, int]) -> Facts: - """What ``config backup`` wrote, and how much of it. + """What ``config backup`` wrote, and how much. - The plain face prints the path bare — it is what the caller keeps, and what the thing - that ran the command reads next. + The plain face prints only the path. The caller keeps the path, and the program that + ran the command reads it next. """ from ..ui import fields from ..ui.report import BARE, Facts @@ -789,11 +797,12 @@ def _backed_up(written: Path, counts: dict[str, int]) -> Facts: def _acted(key: str, **facts: Any) -> Facts: - """An action, stated as data: nothing plain, a document for whoever wanted a record. + """An action, stated as data: nothing on the plain face, and a document for a record. - Every one of these prints nothing on the plain face today and should keep doing so — - ``config advert`` says all it has to say in its exit status. But "prints nothing" is an - answer a person can act on and a program cannot, so the machine face gets the fact. + Each of these actions prints nothing on the plain face now, and must continue to print + nothing. ``config advert`` says all that it has to say in its exit status. But "prints + nothing" is an answer on which a person can act, and a program cannot. Thus the + machine face gets the fact. """ from ..ui import fields from ..ui.report import SILENT, Column, Facts diff --git a/meshterm/tools/contacts.py b/meshterm/tools/contacts.py index 95d6bd3..cdda614 100644 --- a/meshterm/tools/contacts.py +++ b/meshterm/tools/contacts.py @@ -1,9 +1,9 @@ # SPDX-License-Identifier: Apache-2.0 -"""The ``contacts`` tool: list the contacts this node knows about. +"""The ``contacts`` tool: list the contacts that this node knows. -The menu opens the sortable Contacts screen, which leads with our own node; the CLI -prints the contact list alone, because our own node is not a contact — ``meshterm info`` -reports it, in far more detail than a row could hold. +The menu opens the Contacts screen, which you can sort and which starts with our node. +The CLI prints only the contact list, because our node is not a contact. +``meshterm info`` reports our node, with much more detail than a row can hold. """ from __future__ import annotations @@ -24,58 +24,61 @@ if TYPE_CHECKING: # pragma: no cover - typing only @register class ContactsTool(Tool): - """List this node and its known contacts, each with its path-hash prefix.""" + """List this node and its known contacts, each with its hash.""" name = "contacts" title = "Contacts" icon = "👥" help = "Known contacts — last heard, packets, type" category = "Message" - order = 40 # the address book the three above pick their recipient from + order = 40 # the address book from which the three tools above select a recipient async def run(self, ctx: AppContext, params: dict[str, Any]) -> ToolResult: - """Query the device and render the contacts list. + """Query the device and render the contact list. Args: - ctx: Shared application context. - params: Unused. + ctx: The shared application context. + params: Not used. Returns: - A :class:`ToolResult` summarizing the number of known contacts. + A :class:`ToolResult` with a summary of the number of known contacts. """ from ..ui.surface import TuiUi from ..ui.widgets import ContactsSort, ordered_contacts - # Read through the session cache: on a busy node the contacts table is a slow - # round-trip, and re-fetching it (plus self-info) on every menu visit is a chief cause - # of sluggish navigation. The cache holds them for the session and refreshes contacts - # in the background (see :class:`~meshterm.services.device_state.DeviceState`). + # Read through the session cache. On a busy node, the contacts table is a slow + # round trip. If MeshTerm reads it again (and the self info) at each visit to the + # menu, that is a main cause of slow navigation. The cache keeps them for the session + # and reads the contacts again in the background (refer to + # :class:`~meshterm.services.device_state.DeviceState`). info = await ctx.devstate.self_info() contacts = await ctx.devstate.contacts() - # The path-hash prefix — the leading slice of a key a forced path addresses — is - # ``mode + 1`` bytes wide; highlight it in every key. The mode is an optional read, - # so fall back to no highlighting when the firmware doesn't report it. + # The hash (the first part of a key, which a forced path uses as the address) is + # ``mode + 1`` bytes wide. Light it in each key. The mode is an optional read. Thus + # if the firmware does not report it, light nothing. try: mode = await ctx.devstate.path_hash_mode() - except Exception: # noqa: BLE001 - optional read; absence just skips highlighting + except Exception: # noqa: BLE001 - an optional read. If it is absent, nothing is lit. mode = None prefix_bytes = (mode + 1) if isinstance(mode, int) and 0 <= mode <= 3 else 0 - # Overheard-packet tallies from background monitoring, keyed by node hash; a - # contact we've never passively overheard simply has no entry. + # The counts of overheard packets from the background monitor, keyed by node hash. + # A contact that we never overheard passively has no entry. counts = {n.node: n.count for n in ctx.repo.heard_nodes() if n.node} self_name = str(info.get("name") or "this node") self_key = str(info.get("public_key") or "") - # Opens most-recently-heard first: the list's job is "who's out there right now", - # and a freshest-first order answers that on sight — an A→Z roll call doesn't. The - # Ctrl+arrows re-sort from there (and ``--sort`` picks the CLI's order). + # The list opens with the most recently heard node first. The list must answer "who + # is out there now", and an order with the newest first answers that immediately. + # A list from A to Z does not. Then the Ctrl+arrows sort the list again (and + # ``--sort`` sets the order of the CLI). sort_name = str(params.get("sort") or "heard") - # In the menu, hand the list to the interactive screen so the Ctrl+arrows re-sort it - # live — its ring spans the shared contact list's four columns (hash included); on the - # scripted CLI, print the plain listing once in the requested order. + # In the menu, give the list to the interactive screen, so that the Ctrl+arrows sort + # it again while it is open. Their ring goes through the four columns of the shared + # contact list (also the hash). On the scripted CLI, print the plain listing one + # time, in the requested order. if isinstance(ctx.ui, TuiUi): from ..ui.contactlist import SORT_COLUMNS, SORT_OPENS_ASCENDING from ..ui.contacts_screen import open_contacts @@ -107,10 +110,10 @@ class ContactsTool(Tool): "heard", "--sort", "-s", help="Order contacts by: heard, name, packets" ), ) -> None: - # `ContactsSort.from_name` falls back to the first column for an unknown name, - # deliberately, so a saved preference written by an older build cannot wedge - # the menu's list. On the command line the same silence hides a typo: the - # caller asked for one order and got another, with nothing said. + # For an unknown name, `ContactsSort.from_name` uses the first column. This is + # on purpose, so that a saved preference from an older build cannot block the + # list of the menu. On the command line, the same silence hides a typing error: + # the caller asked for one order and got another, and nothing said so. if sort not in ContactsSort.names(): choices = ", ".join(ContactsSort.names()) raise typer.BadParameter(f"--sort must be one of: {choices} (got {sort!r})") @@ -118,21 +121,23 @@ class ContactsTool(Tool): def _listing(contacts: list[Contact], counts: dict[str, int], prefix_bytes: int) -> Listing: - """The contact list, stated once for both faces. + """The contact list, stated one time for the two faces. - ``TYPE`` is the node's advertised role in words, where the menu draws a coloured glyph: - a monochrome ``▲`` would need a legend and the CLI has no legends. ``HEARD`` is a - relative age, because "recently?" is the question this listing is opened to answer. - ``HASH`` is the token ``--path`` and ``--to`` take — it used to have to be sliced out - of ``KEY`` by hand — and ``LOCATION`` is a fact the model has always carried and no - column had room for. ``KEY`` stays full and last, so it runs off the right harmlessly - and is never elided: a truncated key is not something a caller can hand back. + ``TYPE`` is the advertised role of the node, in words. The menu draws a coloured glyph + there, but a monochrome ``▲`` must have a legend, and the CLI has no legends. + ``HEARD`` is a relative age, because the user opens this listing to ask "recently?". + ``HASH`` is the token that ``--path`` and ``--to`` accept. Before, the user had to cut + it out of ``KEY`` by hand. ``LOCATION`` is a fact that the model always had, but no + column had space for it. ``KEY`` stays full and last. Thus it goes off the right side + with no harm and is never cut: a caller cannot give a truncated key back to a command. Args: contacts: The contacts, already in the requested order. - counts: Overheard-packet tallies keyed by node id (from passive monitoring). - prefix_bytes: The device's path-hash width, which is what makes ``HASH`` the - token a forced path addresses this node by rather than an arbitrary slice. + counts: The counts of overheard packets, keyed by node id (from the passive + monitor). + prefix_bytes: The path hash width of the device. Because of it, ``HASH`` is the + token by which a forced path addresses this node, not a random part of the + key. Returns: The listing. @@ -171,7 +176,7 @@ def _listing(contacts: list[Contact], counts: dict[str, int], prefix_bytes: int) fields.position(), ), rows=rows, - # The node's four lanes are not contiguous: what a reader scans for — who, what, - # how recently, how much — comes first, and the two long hex fields go right. + # The four lanes of the node are not together. What the user looks for (who, what, + # how recently, how much) comes first, and the two long hex fields go to the right. order=("NAME", "TYPE", "HEARD", "PKTS", "HASH", "LOCATION", "KEY"), ) diff --git a/meshterm/tools/courier.py b/meshterm/tools/courier.py index 69111d6..9633ea9 100644 --- a/meshterm/tools/courier.py +++ b/meshterm/tools/courier.py @@ -1,19 +1,24 @@ # SPDX-License-Identifier: Apache-2.0 -"""The ``courier`` tool: store-and-forward messaging for contacts that aren't there yet. +"""The ``courier`` tool: store-and-forward messages for contacts that MeshTerm cannot reach yet. -Interactively it opens the outbox screen (see :mod:`meshterm.ui.courier_screen`): -queued messages with their live state, the queueing flow (recipient → message → -when), forced sends, and the delivered/given-up history. Delivery runs in the -background for the whole session (see :mod:`meshterm.services.courier`): a queued -message goes out when its contact is next heard — or at its scheduled time — as a normal -direct message with acknowledgement tracking and polite exponential backoff, and the -outcome lights the header's Watchtower badge. +In the menu, the tool opens the outbox screen (refer to :mod:`meshterm.ui.courier_screen`). +The screen shows the queued messages with their live state, the flow to queue a message +(recipient → message → when), forced sends, and the history of the messages that were +delivered or that the courier gave up. Delivery runs in the background for the whole +session (refer to :mod:`meshterm.services.courier`). A queued message goes out when +MeshTerm next hears its contact, or at its scheduled time. It goes as a normal direct +message, with acknowledgement tracking and a polite exponential backoff. The result lights +the Watchtower badge in the header. -On the CLI the same outbox is scriptable through subcommands: ``queue`` adds a message -(reading the contact list to address it — nothing is transmitted) for the next -interactive session's courier to deliver, ``send`` forces one delivery attempt right now, -and ``list`` / ``cancel`` / ``clear`` inspect and prune the outbox — the scriptable face -of the outbox screen's own Send-now, Cancel, and Clear-finished actions. +On the CLI, subcommands give script access to the same outbox: + +- ``queue`` adds a message for the courier of the next interactive session to deliver. It + reads the contact list to address the message, but it transmits nothing. +- ``send`` forces one delivery try now. +- ``list``, ``cancel``, and ``clear`` examine the outbox and remove entries from it. + +These subcommands are the script form of the Send-now, Cancel, and Clear-finished actions +of the outbox screen. """ from __future__ import annotations @@ -33,24 +38,24 @@ if TYPE_CHECKING: # pragma: no cover - typing only @register class CourierTool(Tool): - """Queue messages for offline contacts; they go out when the contact is next heard.""" + """Queue messages for offline contacts. A message goes out when its contact is next heard.""" name = "courier" title = "Courier" icon = "📨" help = "Outbox that delivers when a contact is heard" category = "Message" - order = 30 # after Chat and Channels: the same conversations, minus the waiting around + order = 30 # after Chat and Channels: the same conversations, but without the wait async def prompt_params(self, ctx: AppContext) -> dict[str, Any] | None: - """Run the outbox screen; there are never parameters to collect. + """Run the outbox screen. It has no parameters to collect. - The screen presents everything itself and returns when dismissed, so - returning ``None`` tells the menu the invocation is complete (the same + The screen shows all its content itself, and it returns when the user leaves it. + Thus the return value ``None`` tells the menu that the run is complete (the same pattern as the ``dashboard`` tool). Args: - ctx: Shared application context. + ctx: The shared application context. Returns: Always ``None``. @@ -61,14 +66,14 @@ class CourierTool(Tool): return None async def run(self, ctx: AppContext, params: dict[str, Any]) -> ToolResult: - """Dispatch a scripted CLI action (the menu path lives in :meth:`prompt_params`). + """Run the handler for a scripted CLI action (the menu path is :meth:`prompt_params`). Args: - ctx: Shared application context. - params: A ``cli_action`` naming the outbox action, plus its arguments. + ctx: The shared application context. + params: A ``cli_action`` that names the outbox action, and its arguments. Returns: - A :class:`ToolResult` describing the action's outcome. + A :class:`ToolResult` that gives the result of the action. """ action = params.get("cli_action", "queue") if action == "list": @@ -84,15 +89,15 @@ class CourierTool(Tool): # -- CLI -------------------------------------------------------------------- async def _cli_queue(self, ctx: AppContext, params: dict[str, Any]) -> ToolResult: - """Queue one message from the CLI (transmits nothing). + """Queue one message from the CLI. This transmits nothing. Args: - ctx: Shared application context. - params: ``contact`` (contact name), ``text`` (the message body), and an - optional local ``at`` clock time (``HH:MM``, next occurrence). + ctx: The shared application context. + params: ``contact`` (the contact name), ``text`` (the message body), and an + optional local clock time ``at`` (``HH:MM``, the next occurrence). Returns: - A :class:`ToolResult` describing the queued entry. + A :class:`ToolResult` that describes the queued entry. """ from ..ui.courier_screen import parse_clock from ..ui.watchtower_screen import contact_watch_key @@ -102,8 +107,8 @@ class CourierTool(Tool): name = str(params["contact"]) needle = name.casefold() contact = next((c for c in contacts if c.name.casefold() == needle), None) - # The named contact, not the radio: nothing is queued and nothing is sent, so - # these are bad arguments (2) rather than device failures (4). + # The problem is the named contact, not the device. Nothing is queued and nothing + # is sent, so these are bad arguments (2) instead of device failures (4). if contact is None: raise typer.BadParameter(f"unknown contact: {name!r}") key = contact_watch_key(contact) @@ -135,10 +140,11 @@ class CourierTool(Tool): ) async def _cli_list(self, ctx: AppContext) -> ToolResult: - """State the outbox — waiting entries then finished ones. + """Give the outbox: first the waiting entries, then the finished entries. - A read-only view over the stored outbox: it needs no device, so it works the same - whether or not a radio is attached (the scriptable face of the outbox screen). + This is a read-only listing of the stored outbox. It does not use the device, so it + works the same when a device is connected and when it is not. It is the script + form of the outbox screen. """ entries = ctx.courier_store.entries() return ToolResult( @@ -148,16 +154,17 @@ class CourierTool(Tool): ) async def _cli_send(self, ctx: AppContext, params: dict[str, Any]) -> ToolResult: - """Force one delivery attempt for a waiting entry, right now. + """Try one forced delivery of a waiting entry, now. - The scriptable ``Send now`` — one forced attempt through the same courier the - outbox screen uses, skipping the "wait until the contact is heard" eligibility check. + This is the script form of ``Send now``. It tries one forced delivery through the + same courier that the outbox screen uses. It does not do the eligibility check + ("wait until the contact is heard"). """ ident = int(params["id"]) if ctx.courier_store.get(ident) is None: - # A bad argument, not a device failure: the outbox is a local file, nothing was - # transmitted, and no retry will make an id exist. Exit 4 told a caller to try - # again; exit 2 tells it to fix the command, which is the truth. + # A bad argument, not a device failure. The outbox is a local file, nothing was + # transmitted, and no retry can make an id exist. Exit 4 told a caller to try + # again. Exit 2 tells it to correct the command, and that is the true answer. raise typer.BadParameter(f"no outbox entry #{ident} (see `courier list`)") outcome = await ctx.courier.attempt_now(ident) notes = { @@ -177,7 +184,7 @@ class CourierTool(Tool): ) async def _cli_cancel(self, ctx: AppContext, params: dict[str, Any]) -> ToolResult: - """Remove a waiting entry from the outbox (finished ones use ``clear``).""" + """Remove a waiting entry from the outbox (for a finished entry, use ``clear``).""" ident = int(params["id"]) if ctx.courier_store.cancel(ident): ctx.ui.ack(f"[warn]cancelled outbox entry #{ident}[/warn]") @@ -193,7 +200,7 @@ class CourierTool(Tool): ) async def _cli_clear(self, ctx: AppContext) -> ToolResult: - """Drop every finished (delivered / given-up) entry, leaving the queue untouched.""" + """Remove each finished entry (delivered or given up), and keep the queue as it is.""" before = len(ctx.courier_store.entries()) ctx.courier_store.clear_done() cleared = before - len(ctx.courier_store.entries()) @@ -260,12 +267,13 @@ class CourierTool(Tool): def _recipient(name: str | None, node_key: str | None) -> object: - """The outbox's addressee as the shared node shape. + """The addressee of the outbox entry, as the shared node shape. - The outbox stores a name and the 12-hex id it addresses, so three of the five fields - are honestly ``null`` — and the id goes in ``hash`` rather than ``key``, because that - is what it is. A key is the full value and is never truncated by this app's choosing; - calling a six-byte prefix one would hand a caller something ``--to`` cannot take. + The outbox stores a name and the key prefix (12 hex digits) that it addresses. Thus + three of the five fields are correctly ``null``. The key prefix goes in ``hash`` + instead of ``key``, because it is a short id, not a full key. A key is the full value, + and MeshTerm never truncates a key by its own choice. If MeshTerm calls a six-byte + prefix a key, it gives a caller a value that ``--to`` cannot accept. """ from ..ui.fields import NodeRef @@ -275,10 +283,10 @@ def _recipient(name: str | None, node_key: str | None) -> object: def _queued(message: QueuedMessage, name: str, not_before: object) -> Facts: """What ``courier queue`` put in the outbox. - The plain face prints the **id and nothing else**, because the id is the one fact a - caller has to keep — it is what ``send`` and ``cancel`` take — and everything else on - the line is what they just typed. The document carries the rest, because a caller - logging the queue has no other record of it. + The plain face prints **only the id**, because the id is the only fact that a caller + must keep: ``send`` and ``cancel`` take it. All the other data on the line is what the + caller typed. The document holds the rest, because a caller that logs the queue has no + other record of it. """ from ..ui import fields from ..ui.report import Facts @@ -301,13 +309,13 @@ def _queued(message: QueuedMessage, name: str, not_before: object) -> Facts: def _outbox(entries: list) -> Listing: - """The outbox, waiting entries then finished ones. + """The outbox: first the waiting entries, then the finished entries. - The deliberate asymmetry between the two time columns: ``SCHEDULED`` is an - *appointment* the caller set with ``--at``, so it stays a wall-clock instant, and - ``FINISHED`` is an age, because "how long ago did it go" is what anyone reading a - delivered row wants. The mixed widths are the price of both columns being right, and - ``--absolute`` makes them uniform for anyone who dislikes it. + The two time columns are different on purpose. ``SCHEDULED`` is an appointment that + the caller set with ``--at``, so it stays a wall-clock instant. ``FINISHED`` is an + age, because a person who reads a delivered row wants to know how long ago it went. + Thus the two columns have different widths, but both columns are correct. + ``--absolute`` makes them the same for a person who does not like the difference. """ from ..core.courier_store import DELIVERED, QUEUED from ..ui import fields @@ -326,11 +334,11 @@ def _outbox(entries: list) -> Listing: "id": m.ident, "state": state, "node": _recipient(m.node_name, m.node_key), - # An entry with no scheduled time goes as soon as the contact is heard, - # which is not a time and so is not one here either. + # An entry with no scheduled time goes when the contact is next heard. That + # is not a time, so this field has no time either. "scheduled_at": m.not_before, "finished_at": m.finished, - # Not shortened the way the outbox screen shortens it: nothing wraps here. + # Not shortened as the outbox screen shortens it, because nothing wraps here. "text": m.text, } ) @@ -349,11 +357,11 @@ def _outbox(entries: list) -> Listing: def _attempted(ident: int, outcome: str) -> Facts: - """What one forced delivery attempt came to. + """The result of one forced delivery try. - ``outcome`` is one of the closed set the help lists, kept verbatim — spaces and all — - so both faces say the same word and a script matching ``no ack`` matches what a person - reads. + ``outcome`` is one value of the closed set that the help gives. It is kept exactly, + with its spaces. Thus both faces show the same word, and a script that matches + ``no ack`` matches the text that a person reads. """ from ..ui import fields from ..ui.report import Facts @@ -366,11 +374,11 @@ def _attempted(ident: int, outcome: str) -> Facts: def _did(*facts: tuple[str, object]) -> Facts: - """An acknowledgement as data: nothing plain, a document for whoever is logging. + """An acknowledgement as data: nothing on the plain face, and a document for a log. - ``cancel`` and ``clear`` say everything they have to say in their exit status, which - is the right plain answer — but a caller that wants to record *what* was cancelled has - nowhere to read it, and that is what the document is for. + ``cancel`` and ``clear`` give all their information in their exit status, and that is + the correct plain answer. But a caller that wants to store what was cancelled has no + other place to read it. The document is for that caller. """ from ..ui import fields from ..ui.report import SILENT, Facts diff --git a/meshterm/tools/dashboard.py b/meshterm/tools/dashboard.py index e10873b..9837ee0 100644 --- a/meshterm/tools/dashboard.py +++ b/meshterm/tools/dashboard.py @@ -1,16 +1,17 @@ # SPDX-License-Identifier: Apache-2.0 -"""The ``dashboard`` tool: the live mesh overview, at the top of the Watch section. +"""The ``dashboard`` tool: the live overview of the mesh, at the top of the Watch section. -Opens the full-screen dashboard (see :mod:`meshterm.ui.dashboard_screen`): the two-hour -all-packet activity chart with its pulse line, the session's traffic tallies by packet -class, and the window's RF health beside the radio's own live numbers. (The per-packet -stream is the Live feed tool, right below.) It leads the Watch section because it answers -the section's first question — *what's going on out there?* — before any specific tool -is reached for. +The tool opens the full-screen dashboard (refer to :mod:`meshterm.ui.dashboard_screen`). +It shows the activity chart of all packets for two hours with its pulse line, the traffic +counts of the session for each packet class, and the RF health of the window next to the +live numbers of the radio itself. (The stream of each packet is the Live feed tool, +directly below.) The dashboard is first in the Watch section, because it answers the +first question of the section (what occurs on the mesh now?) before the user goes to a +specific tool. -Menu-only: the dashboard is inherently live (it rides the event hub and repaints every -second), so there is no scripted one-shot to register — the ``monitor`` and ``contacts`` -subcommands cover scripted inspection. +Menu only: the dashboard is always live (it uses the event hub and paints again each +second). Thus there is no scripted one-shot command to register. The ``monitor`` and +``contacts`` subcommands are the script commands to examine the mesh. """ from __future__ import annotations @@ -25,24 +26,24 @@ from .base import Tool, ToolResult, register @register class DashboardTool(Tool): - """Watch everything going on on the mesh: activity, traffic, RF health.""" + """Watch all that occurs on the mesh: activity, traffic, RF health.""" name = "dashboard" title = "Dashboard" icon = "📊" help = "The mesh live — activity, traffic, RF health" category = "Watch" - order = 10 # the section's overview, above the tools it summarizes + order = 10 # the overview of the section, above the tools that it summarizes async def prompt_params(self, ctx: AppContext) -> dict[str, Any] | None: - """Run the live dashboard; there are never parameters to collect. + """Run the live dashboard. It has no parameters to collect. - The screen presents everything itself and returns when dismissed, so - returning ``None`` tells the menu the invocation is complete (the same + The screen shows all its content itself, and it returns when the user leaves it. + Thus the return value ``None`` tells the menu that the run is complete (the same pattern as the ``advert`` tool). Args: - ctx: Shared application context. + ctx: The shared application context. Returns: Always ``None``. @@ -53,20 +54,20 @@ class DashboardTool(Tool): return None async def run(self, ctx: AppContext, params: dict[str, Any]) -> ToolResult: - """Nothing runs here: the dashboard lives inside :meth:`prompt_params`. + """Nothing runs here: the dashboard is in :meth:`prompt_params`. Args: - ctx: Shared application context. - params: Unused. + ctx: The shared application context. + params: Not used. Returns: - An empty :class:`ToolResult` (only reachable from a scripted call). + An empty :class:`ToolResult` (only a scripted call comes here). """ return ToolResult(summary={}) def register_cli(self, app: typer.Typer) -> None: - """Register no CLI command — the dashboard is a live, menu-only screen. + """Register no CLI command, because the dashboard is a live screen for the menu only. Args: - app: The Typer application (untouched). + app: The Typer application (not changed). """ diff --git a/meshterm/tools/devices.py b/meshterm/tools/devices.py index 84b4f8a..7e11d97 100644 --- a/meshterm/tools/devices.py +++ b/meshterm/tools/devices.py @@ -1,13 +1,15 @@ # SPDX-License-Identifier: Apache-2.0 -"""The ``devices`` tool: enumerate attached serial, SPI, and in-range Bluetooth companions. +"""The ``devices`` tool: list the connected serial, SPI, and in-range Bluetooth companions. -Discovery never opens the radio — it only lists what is attached or advertising. This is a -CLI-only, read-only inventory (``menu_visible = False``): by the time the interactive menu is -up a device is already selected, so the listing has no job there — it belongs on the command -line as a startup-time "which port/address is my radio?" diagnostic. It marks devices already -confirmed as MeshCore companions (and the active one). Selecting a companion is a startup-only -concern: pass ``--port`` or ``--ble`` on the CLI (remembered after it connects), or pick from -the prompt shown when the menu launches (which smoke-tests the choice before confirming it). +Discovery never opens the device. It only lists the devices that are connected or that +send a BLE advertisement. This tool is a read-only inventory, for the CLI only +(``menu_visible = False``). When the interactive menu opens, a device is already selected, +so the listing has no purpose there. It is a diagnostic on the command line at startup, +for the question "which port/address is my radio?". It marks the devices that MeshTerm +already confirmed as MeshCore companions, and it marks the active device. The user selects +a companion only at startup. Give ``--port`` or ``--ble`` on the CLI (MeshTerm remembers +it after it connects), or select from the prompt that shows when the menu starts. That +prompt does a smoke test of the selection before it confirms it. """ from __future__ import annotations @@ -32,16 +34,16 @@ from .base import Tool, ToolResult, register if TYPE_CHECKING: # pragma: no cover - typing only from ..ui.report import Listing -#: The ``MESHCORE`` verdict per discovery confidence tier, for devices we have *not* yet -#: confirmed. The USB vendor ID is only a hint — a native-USB board or a bare bridge chip -#: is a "maybe", never a "yes" — so nothing is billed as MeshCore until a connection proves -#: it. +#: The ``MESHCORE`` verdict for each discovery confidence tier, for the devices that +#: MeshTerm did not confirm yet. The USB vendor ID is only a hint: a native-USB board or a +#: bare bridge chip is a "maybe", never a "yes". Thus no device is called MeshCore until a +#: connection proves it. _MAYBE: dict[str, str] = {"board": "maybe", "bridge": "maybe", "unknown": "no"} @register class DevicesTool(Tool): - """List attached serial, SPI, and in-range Bluetooth companions; mark likely and active.""" + """List the serial, SPI, and in-range Bluetooth companions, and mark likely and active ones.""" name = "devices" title = "Devices" @@ -51,21 +53,22 @@ class DevicesTool(Tool): menu_visible = False # CLI-only: a startup diagnostic with no place in a connected session async def run(self, ctx: AppContext, params: dict[str, Any]) -> ToolResult: - """Enumerate attached and advertising devices, and state them as a listing. + """Find the connected devices and the devices that send BLE advertisements, as a listing. Args: - ctx: Shared application context. - params: Unused beyond the menu's selection bookkeeping. + ctx: The shared application context. + params: Not used, except for the selection bookkeeping of the menu. Returns: - A :class:`ToolResult` summarizing how many devices were found. + A :class:`ToolResult` with the number of devices found. """ if ctx.mock: - # `--mock` promises a session with no real hardware, and a scan is the one - # thing this tool does — it walked the serial ports and switched the Bluetooth - # radio on regardless, which is a promise broken on the first command a - # stranger without a radio would try. So under --mock the simulator *is* the - # inventory: one row, and nothing on the machine touched. + # `--mock` promises a session with no real hardware, and a scan is the only + # thing that this tool does. Before, the tool examined the serial ports and + # switched the Bluetooth radio on, also with `--mock`. Thus a new user without + # a companion saw that promise broken on the first command that they tried. + # Now, with --mock, the simulator is the inventory: one row, and the tool does + # not touch the machine. devices = [ DiscoveredDevice( transport=TRANSPORT_MOCK, @@ -76,9 +79,10 @@ class DevicesTool(Tool): else: scan_ble = params.get("ble", True) devices = await discover_all(ble=scan_ble) if scan_ble else discover_devices() - # A radio on the SPI bus is attached the way a serial port is, but nothing - # enumerates it: it is listed from its device node, as the device screen lists it - # — and the port its board's GPS answers on is listed as part of it, not beside it. + # A radio on the SPI bus is connected as a serial port is, but nothing lists it + # automatically. Thus the tool lists it from its device file, as the device + # screen lists it. The port on which the GPS of its board answers is listed as + # part of the radio, not next to it. devices = without_radio_ports(devices, ctx.settings.profiles) devices += spi_radios(ctx.settings.profiles, devices) known = ctx.device_store.load_all() @@ -91,7 +95,7 @@ class DevicesTool(Tool): else None ) except DeviceSelectionError: - spi = None # an ambiguous --spi: the listing is how the reader finds out which + spi = None # an ambiguous --spi: the listing shows the user which one active_target = ( ctx.ble_override @@ -100,10 +104,11 @@ class DevicesTool(Tool): or (active.target if active else None) ) - # A refused Bluetooth scan is not the same as a quiet one, and the difference is - # invisible in the listing — both simply lack BLE rows. Say so whether or not - # anything else was found: a serial board being present does not make a companion - # the reader expected over Bluetooth any less missing. + # A refused Bluetooth scan is not the same as a scan that found nothing. The + # listing does not show the difference, because both have no BLE rows. Thus tell + # the user, also if the scan found other devices. A serial board that is present + # does not change the fact that a companion that the user expected over Bluetooth + # is missing. blocked = ble_unavailable_reason() if blocked: from ..ui import script @@ -113,11 +118,12 @@ class DevicesTool(Tool): ) if not devices: - # Not an error: the scan ran and found nothing. Said on stderr so a caller - # redirecting stdout still hears it, and reported as NO_RESULT so a script can - # branch on it without matching prose. The empty listing still reaches the - # machine face as `[]`, which is a document a consumer can read — where an - # empty stdout is a parse error it would have to tell apart from a real one. + # Not an error: the scan ran and found nothing. The message goes to stderr, so + # that a caller that redirects stdout still gets it. The exit status is + # NO_RESULT, so that a script can branch on it without a match on the text. + # The empty listing still goes to the machine face as `[]`, which is a document + # that a consumer can read. An empty stdout is a parse error, and the consumer + # must then tell it apart from a real parse error. from ..ui import script script.stderr_console().print( @@ -127,13 +133,13 @@ class DevicesTool(Tool): return ToolResult( summary={"count": len(devices)}, report=(_listing(devices, known, remembered, active_target),), - # Changed from the 0 this used to return under --json: a rendering flag has no - # business changing the report, and the plain path has always said 5 here. + # Before, this returned 0 with --json. We changed it, because a rendering flag + # must not change the report, and the plain path always gave 5 here. exit_code=exitcodes.OK if devices else exitcodes.NO_RESULT, ) def register_cli(self, app: typer.Typer) -> None: - """Register the ``devices`` subcommand (inventory only; no connection). + """Register the ``devices`` subcommand (only an inventory, with no connection). Args: app: The Typer application. @@ -143,8 +149,8 @@ class DevicesTool(Tool): @app.command( name=self.name, help=self.help, - # The listing used to close with a line explaining its own markers and how to - # act on a row. That is help, and this is where help goes. + # Before, the listing ended with a line that explained its markers and how to + # use a row. That text is help, and help goes here. epilog="Select a device with --port TARGET or --ble TARGET, using the " "TARGET column verbatim; an SPI radio with --spi, or -p and its profile.", ) @@ -157,24 +163,28 @@ class DevicesTool(Tool): def _listing(devices: list, known: dict, remembered: object, active_target: str | None) -> Listing: - """The device inventory, stated once for both faces. + """The device inventory, given one time for both faces. - ``TARGET`` leads because it is the field a caller acts on — it is what ``--port`` and - ``--ble`` take, verbatim. The menu's two markers become columns of their own - (``ACTIVE``, and ``MESHCORE`` for the confirmed star), because a glyph in a margin is - something to look at rather than something to test. + ``TARGET`` is first, because a caller uses that field: ``--port`` and ``--ble`` take it + exactly as it is. The two markers of the menu become columns (``ACTIVE``, and + ``MESHCORE`` for the confirmed star), because a person can look at a glyph in a + margin, but a program cannot test it. - ``MESHCORE`` is three-valued and stays that way: ``yes`` only once a connection has - proved the device speaks the protocol, ``maybe`` for a USB vendor ID that suggests a - LoRa board or a bridge chip, ``no`` for anything else. A vendor ID is a hint, and the - column would be lying if it rounded one up — which is why the machine face carries the - same three words rather than the boolean it used to. + ``MESHCORE`` has three values, and it keeps them: + + - ``yes`` only after a connection proved that the device uses the protocol. + - ``maybe`` for a USB vendor ID that suggests a LoRa board or a bridge chip. + - ``no`` for all other devices. + + A vendor ID is a hint. If the column changes a hint to ``yes``, the column gives false + information. For this reason, the machine face has the same three words, and not + the boolean that it had before. Args: devices: The discovered devices. - known: Remembered device records, keyed by stable id. + known: The remembered device records, keyed by stable id. remembered: The remembered default device, if there is one. - active_target: The target this invocation is (or would be) using. + active_target: The target that this run uses (or would use). Returns: The listing. @@ -207,15 +217,15 @@ def _listing(devices: list, known: dict, remembered: object, active_target: str columns=( fields.word("target", "TARGET"), fields.word("transport", "TRANSPORT"), - # The two halves `target` is one of, kept apart for a caller that has to know - # which transport it is holding without parsing the target for a colon. + # The two possible forms of `target`, kept separate. Thus a caller knows which + # transport it has, and it does not have to parse the target for a colon. fields.hidden("port"), fields.hidden("address"), fields.name("label", "NAME"), fields.name("hardware", "HARDWARE"), fields.word("meshcore", "MESHCORE"), - # What the "maybe" was derived from. A person reading the column has the - # vendor label beside it and can see for themselves; a program cannot. + # The source of the "maybe". A person who reads the column sees the vendor + # label next to it, but a program cannot. fields.hidden("confidence"), fields.word("serial_number", "SERIAL"), fields.hidden("stable_id"), diff --git a/meshterm/tools/diagnostics.py b/meshterm/tools/diagnostics.py index 4c848ca..6b7bb3c 100644 --- a/meshterm/tools/diagnostics.py +++ b/meshterm/tools/diagnostics.py @@ -1,31 +1,33 @@ # SPDX-License-Identifier: Apache-2.0 -"""The ``diagnostics`` tool: everything a bug report needs, in one block worth pasting. +"""The ``diagnostics`` tool: all that is necessary for a bug report, in one block to paste. -A report that opens with "it crashed" costs two or three round trips before anyone knows -which MeshTerm, which OS, which terminal, which radio — and the person who hit the bug is -usually the one least able to answer, because half of it is resolved at boot and never -shown. This states all of it at once. +If a report starts with "it crashed", two or three questions and answers are necessary +before anyone knows which MeshTerm, which OS, which terminal, and which radio. The person +who found the bug is usually the person who can answer least, because MeshTerm finds half +of these facts at boot and never shows them. This tool states all of them at one time. -**What it deliberately does not say.** The block is designed to be pasted in public by -somebody who has not read it, so nothing that identifies a person or unlocks anything may -be in it: no pairing PIN, no admin password, no channel secret, no private key, no -position, and no contact's name or key. The mesh is described in **aggregate** — how many -rows of each kind, and the span of time they cover — which is the half that explains a bug -(a database with four observations and one with four hundred thousand fail differently) -without naming anyone the reporter talks to. :func:`~meshterm.core.hostinfo.host` and -:meth:`~meshterm.persistence.repository.Repository.table_counts` hold that line on their -own side, so it cannot be crossed here by accident. +**What it does not say, on purpose.** The block is made for a person who pastes it in +public and did not read it. Thus it must not contain anything that identifies a person or +unlocks anything: no pairing PIN, no admin password, no channel secret, no private key, no +position, and no name or key of a contact. The block describes the mesh only in +**totals**: how many rows of each type, and the span of time that they cover. That half +explains a bug (a database with four observations and one with four hundred thousand fail +in different ways), and it names nobody that the reporter talks to. +:func:`~meshterm.core.hostinfo.host` and +:meth:`~meshterm.persistence.repository.Repository.table_counts` keep that limit on their +own side. Thus this module cannot go past it by accident. -**One report, three faces**, which is the whole reason this is a report and not a -``print``: the menu draws it as a written page (see :mod:`meshterm.ui.diagnostics`) and -saves it as markdown, ``meshterm diagnostics`` prints the same facts as aligned records for -anyone who would rather redirect than read, and ``--json`` hands them to whatever files the -issue. The document face is the one that leaves this machine, so it is the one written in -the format an issue tracker already renders. +**One report, three faces.** That is the only reason why this is a report and not a +``print``. The menu draws it as a written page (refer to :mod:`meshterm.ui.diagnostics`) +and saves it as markdown. ``meshterm diagnostics`` prints the same facts as aligned +records, for a person who wants to redirect them and not read them. ``--json`` gives +them to the program that files the issue. The document face is the face that leaves this +machine. Thus it is written in a format that an issue tracker already renders. -The device is asked but never required. A report about a radio that will not connect is -exactly the report that most needs to be filed, so a failure to reach it becomes a fact in -the block (``connected``/``error``) rather than an error that replaces it. +The tool asks the device, but the device is not necessary. A report about a radio that +does not connect is the report that it is most necessary to file. Thus, when the tool +cannot get to the device, that failure becomes a fact in the block (``connected`` and +``error``), and not an error that replaces the block. """ from __future__ import annotations @@ -41,32 +43,33 @@ from .base import Tool, ToolResult, register if TYPE_CHECKING: # pragma: no cover - typing only from ..ui.report import Report -#: What the saved file is called, in the config directory beside the log it sits next to -#: in a bug report. Named for the app rather than just ``diagnostics.md`` because the one -#: thing that happens to this file is being moved somewhere else and attached, and by then -#: the directory it came from is no longer saying what it is. +#: The name of the saved file, in the config directory, next to the log that it goes with +#: in a bug report. The name includes the app name, and is not only ``diagnostics.md``. +#: The reason: the only thing that occurs to this file is that a person moves it to a +#: different place and attaches it. Then the directory that it came from no longer tells +#: what it is. DIAGNOSTICS_FILENAME = "meshterm-diagnostics.md" @register class DiagnosticsTool(Tool): - """What MeshTerm, this machine, this terminal and this radio actually are.""" + """What MeshTerm, this machine, this terminal, and this radio are.""" name = "diagnostics" title = "Diagnostics" icon = "🩺" help = "Version, host, terminal, and device facts for a bug report" category = "This app" - order = 7 # after Preferences (the row that changes MeshTerm), before the pages + order = 7 # after Preferences (the row that changes MeshTerm), and before the pages def register_cli(self, app: Any) -> None: - """Register the command, with the one option that turns the answer into a file. + """Register the command, with the one option that changes the answer into a file. - ``--out`` is spelled the way ``config export-key --out`` already spells it, rather - than inventing a second word for writing an answer to a path. Plain redirection - still works and is not replaced by it — what the option adds is a file whose - columns are laid out at full width instead of at whatever the terminal happened to - be, which is the difference between a readable attachment and a folded one. + ``--out`` has the same spelling as ``config export-key --out``. We did not make a + second word to write an answer to a path. Plain redirection continues to work, and + the option does not replace it. The option adds a file whose columns have the full + width, and not the width that the terminal had at that time. That is the + difference between an attachment that a person can read and a folded one. """ import typer @@ -81,18 +84,18 @@ class DiagnosticsTool(Tool): run_tool_command(self, {"out": out}) async def prompt_params(self, ctx: AppContext) -> dict[str, Any] | None: - """Open the page in the menu; returning ``None`` completes with no run row. + """Open the page in the menu. The return value ``None`` ends with no run row. - The same shape the About pages use — and the same screen, since the page *is* one: - the menu's whole interaction is the reading of it, and a run row recording that - somebody looked at their own version number would be a line in the log for every - glance. Saving from the page is likewise not a run. + The About pages use the same shape, and the same screen, because this page is a + written page too. In the menu, the user only reads it. If a run row stores that a + person looked at their own version number, the log gets a line for each look. A + save from the page is also not a run. Args: - ctx: Shared application context. + ctx: The shared application context. Returns: - Always ``None`` in the menu; the CLI never reaches this. + Always ``None`` in the menu. The CLI never gets to this method. """ from ..ui.diagnostics import open_diagnostics_page @@ -101,18 +104,18 @@ class DiagnosticsTool(Tool): return None async def run(self, ctx: AppContext, params: dict[str, Any]) -> ToolResult: - """State the diagnostics, or write them to a file — only reachable from the CLI. + """State the diagnostics, or write them to a file. Only the CLI gets to this method. - With ``--out`` the answer *becomes the path*, the same trade ``config export-key`` - makes: a caller who asked for a file wants to be told where it is, not handed the - contents they just redirected into it. + With ``--out``, the answer *is the path*. ``config export-key`` makes the same + choice. A caller who asked for a file wants to know where it is. The caller does + not want to get again the contents that it sent into that file. Args: - ctx: Shared application context. - params: ``out`` — a destination path, or ``None`` to print the block. + ctx: The shared application context. + params: ``out``: a destination path, or ``None`` to print the block. Returns: - A :class:`ToolResult` carrying the block, or the path it was written to. + A :class:`ToolResult` that holds the block, or the path of the written file. """ report = await build_report(ctx) out = params.get("out") @@ -129,23 +132,24 @@ class DiagnosticsTool(Tool): async def build_report(ctx: AppContext) -> Report: - """Gather every diagnostic fact, as the report both faces render. + """Collect all the diagnostic facts, as the report that the two faces render. - Seven blocks in the order a reader needs them: what this program is, what it is running - on, what it is drawing into, what radio it found, how much history it has, what that - history is made of, and what has been changed from the defaults. Each carries a - ``caption``, which is what the markdown face turns into the page's ``##`` landmarks. + Seven blocks, in the order that is most useful to the user: what this program is, the + machine it runs on, the terminal it draws into, the radio it found, how much history it + has, what that history contains, and what is changed from the defaults. Each block has + a ``caption``. The markdown face changes the captions into the ``##`` landmarks of the + page. - The five :class:`~meshterm.ui.report.Facts` blocks merge into one flat JSON object and - the two :class:`~meshterm.ui.report.Listing` blocks keep a key of their own — which is - also why the table counts are a listing, since a table named after a fact would - otherwise be able to collide with it. + The five :class:`~meshterm.ui.report.Facts` blocks merge into one flat JSON object. + The two :class:`~meshterm.ui.report.Listing` blocks each keep their own key. That is + also why the table counts are a listing: if they were facts, a table with the same name + as a fact could collide with it. Args: - ctx: Shared application context. + ctx: The shared application context. Returns: - The seven-block report. + The report of seven blocks. """ return ( _app_facts(), @@ -159,36 +163,41 @@ async def build_report(ctx: AppContext) -> Report: def markdown_source(report: Report, *, when: datetime | None = None) -> str: - """The whole block as a markdown document — the page's source, and the file's contents. + """The full block as a markdown document: the source of the page, and the file contents. - Markdown because both places this goes already speak it: the menu draws it through - :func:`~meshterm.ui.markdown.render_markdown`, the same renderer behind the About - pages, so the page gets real ``##`` landmarks that pin as it scrolls and that its - section jumps step by; and an issue tracker renders it as written, with no fence and - no apology. The command line keeps its aligned records — that face is a stream a - person greps, and headings are furniture on it. + It is markdown because the two places where this text goes already use markdown. The + menu draws it through :func:`~meshterm.ui.markdown.render_markdown`, the same renderer + as the About pages. Thus the page gets real ``##`` landmarks, which pin while the page + scrolls and which the section jumps go to. An issue tracker renders it as it is + written, with no fence and no apology. The command line keeps its aligned records, + because that face is a stream that a person searches with grep, and headings only add + clutter to it. Args: - report: The blocks to write out. - when: The moment to stamp in the colophon (defaults to now, local). Injectable so - the same report can be rendered twice and compared. + report: The blocks to write. + when: The time to put in the colophon (the default is now, in local time). A + caller can give it, so that the same report can be rendered two times and + compared. Returns: - Markdown source, ready for :func:`~meshterm.ui.markdown.render_markdown` or a file. + The markdown source, ready for :func:`~meshterm.ui.markdown.render_markdown` or + for a file. """ from .. import __version__ from ..ui.renderers import markdown_blocks stamp = (when or datetime.now().astimezone()).strftime("%Y-%m-%d %H:%M") return ( - # The `#` title carries what the frame around it cannot — which is the same reason - # `about.md` has one and the other three written pages do not. The screen is already - # headed "Diagnostics"; repeating that would spend the page's first line saying - # nothing, while the version belongs at the top of a file somebody will open later. - # Emphasis makes it the muted qualifier beside the name. + # The `#` title holds what the frame around it cannot hold. For the same reason, + # `about.md` has one and the other three written pages do not. The screen already + # has the heading "Diagnostics". If the title repeats it, the first line of the + # page says nothing. But the version must be at the top of a file that a + # person will open later. The emphasis makes the version the muted qualifier next + # to the name. f"# MeshTerm diagnostics *v{__version__}*\n\n" - # The standfirst sits flush and muted under the title, and says the one thing a - # reader needs before reading any of it: this is safe to hand over. + # The standfirst is flush and muted under the title. It says the one thing that the + # user must know before the user reads the rest: it is safe to give this text to + # other persons. "Everything a bug report opens with. Nothing here is private.\n\n" f"{markdown_blocks(report)}\n\n" "---\n\n" @@ -197,21 +206,22 @@ def markdown_source(report: Report, *, when: datetime | None = None) -> str: def default_path(ctx: AppContext) -> Path: - """Where the page saves when nobody named a place: beside the log, in the config dir. + """Where the page saves when no place is given: next to the log, in the config directory. - The config directory rather than the working directory, which in the menu is wherever - the reader happened to launch from and is not somewhere they can be told to look. It - is also where the log already lives, so "send me both" names one folder. + It is the config directory, not the working directory. In the menu, the working + directory is the directory from which the user started MeshTerm, and nobody can tell + the user where that is. The log is also in the config directory, so "send me both" + names one folder. """ return ctx.settings.config_dir / DIAGNOSTICS_FILENAME def write_markdown(source: str, path: Path | str) -> Path: - """Write a markdown document to ``path``, creating its directory. + """Write a markdown document to ``path``, and make its directory. - **Always markdown**, whatever face the run was printing. This file exists to be - attached to an issue and read there, and an issue tracker renders markdown; anyone who - wants the machine face can redirect ``--json`` and already has a better name for that + **Always markdown**, whatever face the run printed. This file is for an attachment to + an issue, where people read it, and an issue tracker renders markdown. A person who + wants the machine face can redirect ``--json``, and already has a better name for that file than this one. Args: @@ -219,10 +229,10 @@ def write_markdown(source: str, path: Path | str) -> Path: path: The destination. Returns: - The path written. + The path of the written file. Raises: - OSError: If the directory cannot be made or the file cannot be written. + OSError: If the directory cannot be made, or if the file cannot be written. """ written = Path(path) written.parent.mkdir(parents=True, exist_ok=True) @@ -231,7 +241,7 @@ def write_markdown(source: str, path: Path | str) -> Path: def _written_to(written: Path) -> Any: - """The answer a ``--out`` run gives: the path, alone on the plain face.""" + """The answer of a ``--out`` run: only the path, on the plain face.""" from ..ui import fields from ..ui.report import BARE, Facts @@ -245,7 +255,7 @@ def _written_to(written: Path) -> Any: def _app_facts() -> Any: - """What this program is: version, how it was installed, and where it keeps things.""" + """What this program is: the version, how it was installed, and where it keeps data.""" from .. import __version__ from ..core import hostinfo from ..ui import fields @@ -263,7 +273,7 @@ def _app_facts() -> Any: def _host_facts() -> Any: - """The machine underneath: which OS, which build, which processor, which Python.""" + """The machine below MeshTerm: which OS, which build, which processor, which Python.""" from ..core import hostinfo from ..ui import fields from ..ui.report import Facts @@ -288,13 +298,14 @@ def _host_facts() -> Any: def _terminal_facts() -> Any: - """The terminal, and every verdict about it resolved once at boot. + """The terminal, and each decision about it that MeshTerm made one time at boot. - Its own section rather than more host facts, because these are what a "it looks wrong" - report is actually about, and a reader skimming for them should not have to pass the - processor architecture on the way. Whether icons draw, whether the path widget's - separators draw, which platform flavour resolved and *why* — each is decided from the - environment before the first frame and none of it is visible on any screen. + These facts have their own section, and are not more host facts. The reason: a report + of "it looks wrong" is about these facts. A user who looks quickly for them must not + have to read the processor architecture first. Whether icons draw, whether the + separators of the path widget draw, which platform flavour resolved, and *why*: + MeshTerm decides each of these from the environment before the first frame, and no + screen shows them. """ from ..core import hostinfo from ..platforms import get_platform @@ -330,24 +341,25 @@ def _terminal_facts() -> Any: "platform": get_platform().name, "icons": emoji.supported, "icons_source": emoji.source, - # The face, and which terminal it was read from — an unidentified terminal - # (or an ssh session, where the font lives on the far client) has no answer, - # and saying so is worth more than naming a font nobody here can see. + # The font face, and the terminal from which it was read. A terminal that is not + # identified (or an ssh session, where the font is on the far client) has no + # answer. To say so is better than to name a font that nobody here can see. "font": f"{font.face} ({font.source})" if font else None, - # Level and source together: `none (font:windows-terminal)` is a measurement - # and `unknown (ssh)` is an admission, and they lead somewhere different. + # The level and the source together. `none (font:windows-terminal)` is a + # measurement and `unknown (ssh)` says that MeshTerm does not know. They lead + # to different places. "powerline": f"{powerline.level} ({powerline.source})", }, ) async def _device_facts(ctx: AppContext) -> Any: - """The radio: what it is, how it is attached, and what its link is set to. + """The radio: what it is, how it is connected, and the settings of its link. - Best-effort by design. Every value here is ``None`` on a machine whose radio is - unplugged, asleep, or refusing to pair — and ``connected: false`` with the failure's - own words in ``error`` is a better first line for that bug report than a command that - refused to produce one. + This function does what it can, on purpose. Each value here is ``None`` on a machine + whose radio is disconnected, asleep, or does not pair. For that bug report, + ``connected: false`` with the words of the failure in ``error`` is a better first line + than a command that did not make a report. """ from ..ui import fields from ..ui.report import Facts @@ -387,7 +399,7 @@ async def _device_facts(ctx: AppContext) -> Any: radio_cr=snapshot.get("radio_cr"), tx_power_dbm=snapshot.get("tx_power"), ) - except Exception as exc: # noqa: BLE001 - any failure to reach the radio is the fact + except Exception as exc: # noqa: BLE001 - each failure to get to the radio is the fact values["error"] = str(exc) or exc.__class__.__name__ return Facts( @@ -412,11 +424,11 @@ async def _device_facts(ctx: AppContext) -> Any: def _mesh_facts(ctx: AppContext) -> Any: - """How much history this install holds, and where it holds it. + """How much history this installation holds, and where it holds it. - Counts and a span, never a row. The span is the fact that sizes every other number - here: a thousand observations over two years and a thousand in an afternoon describe - two different installs, and only one of them has a radio worth suspecting. + Counts and a span, never a row. The span gives the scale of each other number here. + A thousand observations in two years and a thousand in an afternoon describe two + different installations, and only one of them has a radio that is possibly faulty. """ from ..core.preferences import current from ..persistence.logging import log_path @@ -442,8 +454,8 @@ def _mesh_facts(ctx: AppContext) -> Any: "config_dir": ctx.settings.config_dir, "db_size_kb": _size_kb(db_path), "log_level": preferences.log_level, - # How much the log holds, so a maintainer asking for it knows what they are - # asking for — and so a file still at zero says the level never let it write. + # How much the log holds. Thus a maintainer who asks for it knows what to expect. + # Also, a file that is still at zero shows that the level never let it write. "log_size_kb": _size_kb(log_path(ctx.settings.config_dir)), "runs_failed": ctx.repo.failed_run_count(), "first_heard": first, @@ -453,12 +465,12 @@ def _mesh_facts(ctx: AppContext) -> Any: def _table_listing(ctx: AppContext) -> Any: - """Every table in the database and how many rows it holds. + """Each table in the database, and how many rows it holds. - A listing rather than more facts, for two reasons. The keys are discovered from the - schema rather than declared, so a table named after a fact could otherwise collide - with it in the merged JSON object; and this genuinely is a set of records — one per - table — which is the shape a reader and a parser both already know. + A listing, and not more facts, for two reasons. First, the keys come from the schema, + and are not declared. Thus, if they were facts, a table with the same name as a fact + could collide with it in the merged JSON object. Second, this is in fact a set of + records (one for each table), and a person and a parser both already know that shape. """ from ..ui import fields from ..ui.report import Column, Listing @@ -473,11 +485,11 @@ def _table_listing(ctx: AppContext) -> Any: def _preference_listing(ctx: AppContext) -> Any: - """The preferences that differ from their defaults — the whole list, and only those. + """The preferences that are not at their defaults: all of them, and only those. - An override is the only part of the preference set that can explain anything: the - defaults are in the source, the same for everyone, and dumping all forty would bury - the two the reporter actually changed. + An override is the only part of the preferences that can explain something. The + defaults are in the source, and they are the same for all users. If the list shows + all forty preferences, the two that the reporter changed are hard to find. """ from ..core.preferences import current from ..ui import fields @@ -496,14 +508,14 @@ def _preference_listing(ctx: AppContext) -> Any: def _rows_lane() -> Any: - """The row-count lane: right-aligned, because a column of magnitudes only compares aligned.""" + """The lane of row counts: right-aligned, because only aligned numbers are easy to compare.""" from ..ui.report import Lane return Lane(header="ROWS", render=lambda v: str(v if v is not None else 0), align="right") def _size_kb(path: Any) -> int | None: - """A file's size in whole kilobytes, or ``None`` when it is not there to measure.""" + """The size of a file in whole kilobytes, or ``None`` when there is no file to measure.""" if path is None: return None try: @@ -513,18 +525,18 @@ def _size_kb(path: Any) -> int | None: async def _snapshot(ctx: AppContext, device: Any) -> dict: - """The device's settings snapshot, or an empty one when the read fails.""" + """The snapshot of the device settings, or an empty snapshot when the read fails.""" from ..ui.config_editor import cached_snapshot try: return await cached_snapshot(ctx, device) - except Exception: # noqa: BLE001 - a settings read that fails leaves the radio facts blank + except Exception: # noqa: BLE001 - if the settings read fails, the radio facts stay blank return {} async def _device_info(device: Any) -> dict: - """The device's self-description, or an empty one when the firmware does not answer.""" + """The self-description of the device, or an empty one when the firmware does not answer.""" try: return await device.get_device_info() or {} - except Exception: # noqa: BLE001 - firmware predating the query contributes nothing + except Exception: # noqa: BLE001 - firmware older than the query gives nothing return {} diff --git a/meshterm/tools/info.py b/meshterm/tools/info.py index 6ec4461..6393ae1 100644 --- a/meshterm/tools/info.py +++ b/meshterm/tools/info.py @@ -1,5 +1,5 @@ # SPDX-License-Identifier: Apache-2.0 -"""The ``info`` tool: show the connected companion device's identity and radio config.""" +"""The ``info`` tool: show the identity and the radio settings of the connected device.""" from __future__ import annotations @@ -23,9 +23,9 @@ if TYPE_CHECKING: # pragma: no cover - typing only @register class InfoTool(Tool): - """Display device identity and radio configuration. + """Show the identity and the radio settings of the device. - The known-contacts list lives in the separate ``nodes`` tool. + The list of known contacts is in the separate ``nodes`` tool. """ name = "info" @@ -33,17 +33,17 @@ class InfoTool(Tool): icon = "📋" help = "Show device status, identity, and radio config" category = "This node" - order = 10 # what it is, before anything that changes it + order = 10 # what it is, before the tools that change it async def run(self, ctx: AppContext, params: dict[str, Any]) -> ToolResult: - """Query the device and render its live status plus its full configuration. + """Query the device, and render its live status and all its settings. Args: - ctx: Shared application context. - params: Unused. + ctx: The shared application context. + params: Not used. Returns: - A :class:`ToolResult` summarizing the device name. + A :class:`ToolResult` with the device name in its summary. """ from rich.console import Group @@ -52,10 +52,10 @@ class InfoTool(Tool): device = await ctx.device() snapshot = await cached_snapshot(ctx, device) - # On the CLI this is the *status* report and nothing else: how the radio is doing - # right now, one fact per line. What it is set to is `config show`'s answer, in - # the very keys `config get`/`config set` take, so printing the settings here as - # well would be the same table twice under two different spellings. + # On the CLI, this is only the status report: the current condition of the device, + # one fact on each line. The settings are the answer of `config show`, with the + # same keys that `config get` and `config set` take. If this command also prints + # the settings, the same table shows two times, with two different spellings. session = getattr(ctx.ui, "session", None) if session is None: return ToolResult( @@ -66,16 +66,17 @@ class InfoTool(Tool): from ..ui.device_info_screen import DeviceInfoScreen custom = await device.get_custom_vars() - # A live status panel (role, firmware, battery, clock, radio/packet statistics) - # above every current setting with a short explanation of each. The panel is read - # once; only the table differs between the two states, and it is cheap to rebuild. + # A live status panel (role, firmware, battery, clock, radio and packet statistics) + # above all the current settings, each with a short explanation. The panel is read + # one time. Only the table is different between the two states, and it is fast to + # build again. panel = await _status_panel(device, snapshot) def page(reveal_pin: bool) -> Group: return Group(panel, Text(""), config_table(snapshot, custom, reveal_pin=reveal_pin)) - # The page is its own screen because it has a key of its own: the pairing PIN is - # masked until ``p`` uncovers it. + # The page is a separate screen, because it has its own keyboard key: the pairing + # PIN is masked until ``p`` shows it. await session.run_screen( DeviceInfoScreen(session, page, title=self.title, conceals=has_pin(snapshot)) ) @@ -98,18 +99,19 @@ class InfoTool(Tool): async def _read_status(device: Device) -> dict[str, Any]: - """Read every live status value the firmware will answer for, best-effort. + """Read each live status value that the firmware gives, as a best effort. - The one place the device is asked. Both faces build from what it returns: the menu's - panel composes prose rows out of these values, the CLI prints them one fact per line - (see :func:`_status_panel` and :func:`status_facts`). Every read is optional — - firmware predating a query simply contributes nothing — so this works on any device. + This is the only place that asks the device. Both faces use what it returns: the panel + of the menu makes prose rows from these values, and the CLI prints them one fact on + each line (refer to :func:`_status_panel` and :func:`status_facts`). Each read is + optional, because firmware that is older than a query gives nothing for it. Thus this + function works on any device. Args: device: The connected device to query. Returns: - The merged raw readings: ``info``, ``battery``, ``stats`` and ``clock``. + The merged raw readings: ``info``, ``battery``, ``stats``, and ``clock``. """ return { "info": await _try(device.get_device_info) or {}, @@ -122,16 +124,17 @@ async def _read_status(device: Device) -> dict[str, Any]: async def _status_panel(device: Device, snapshot: dict) -> Panel: """Build the live status panel: role, firmware, battery, clock, and statistics. - The menu's face of :func:`_read_status` — each row a short phrase rather than an + This is the menu face of :func:`_read_status`. Each row is a short phrase, not an atomic value, because a person reads "-110 dBm noise floor · last RSSI -62 dBm" in one - go where a script wants the three numbers apart. + step. A script wants the three numbers separately. Args: device: The connected device to query. - snapshot: The already-built settings snapshot (for role and identity fields). + snapshot: The settings snapshot that is already built (for the role and identity + fields). Returns: - A Rich :class:`Panel` of label/value status rows. + A Rich :class:`Panel` of status rows, each with a label and a value. """ rows: list[tuple[str, Text]] = [] readings = await _read_status(device) @@ -191,34 +194,35 @@ async def _status_panel(device: Device, snapshot: dict) -> Panel: def _firmware(info: dict) -> str: - """The firmware version and build joined, or ``""`` when neither was reported.""" + """The firmware version and build, joined, or ``""`` if the device reported neither.""" return " ".join(str(info[k]) for k in ("ver", "fw_build") if info.get(k)) async def status_facts(device: Device, snapshot: dict) -> Facts: - """The device's live status as one set of facts. + """The live status of the device, as one set of facts. - The CLI's face of :func:`_read_status`. Where the panel writes a phrase per row, this - writes one value per key and puts the unit *in the key* — ``battery_v``, ``uptime_s``, - ``noise_floor_dbm`` — so nothing has to be pulled back out of prose. A number never - carries a unit in its value, on either face. + This is the CLI face of :func:`_read_status`. The panel writes a phrase in each row, + but this function writes one value for each key. It puts the unit in the key + (``battery_v``, ``uptime_s``, ``noise_floor_dbm``), so that no program must get the + number out of prose. On both faces, a number never has a unit in its value. - The three second-valued readings and the clock drift carry a **gloss** beside the - figure: ``uptime_s 93784 (1d 2h)``. This is the one key/value block that may, and - the reason is that it is the one with no ``get`` and no ``set`` behind it — there is no - round trip to protect, the key still says what the number counts, and ``93784`` is a - reading nobody can hold in their head. The document carries the number alone, having - nowhere useful to put a phrase. + The three readings in seconds and the clock drift have a **gloss** next to the number: + ``uptime_s 93784 (1d 2h)``. This is the only key/value block that can have a gloss. + The reason is that it is the only block with no ``get`` and no ``set`` behind it. Thus + there is no round trip to protect, the key still tells what the number counts, and + ``93784`` is a value that no person can easily understand. The document holds only the + number, because it has no useful place for a phrase. - A reading the firmware did not answer for is **left out** of the plain block rather - than dashed: these are optional queries, and a missing key says "this device does not - report it" where a dash would claim it reported nothing. The document keeps the key and - writes ``null`` — see :attr:`~meshterm.ui.report.Facts.omit_absent` for why the two - faces disagree here on purpose. + If the firmware gave no answer for a reading, the plain block **leaves out** that + reading, and it does not show a dash. These are optional queries. A missing key says + "this device does not report it", but a dash says that it reported nothing. The + document keeps the key and writes ``null``. Refer to + :attr:`~meshterm.ui.report.Facts.omit_absent` for the reason why the two faces are + different here on purpose. Args: device: The connected device to query. - snapshot: The already-built settings snapshot (for role and identity). + snapshot: The settings snapshot that is already built (for the role and identity). Returns: The facts block. @@ -233,8 +237,8 @@ async def status_facts(device: Device, snapshot: dict) -> Facts: adv_type = snapshot.get("adv_type") clock = readings["clock"] values: dict[str, Any] = { - # Identity first: which radio this is. Everything it *can be set to* is - # `config show`'s answer, not this one. + # The identity is first: which device this is. All the values that it can be set + # to are the answer of `config show`, not of this command. "name": snapshot.get("name"), "public_key": str(snapshot.get("public_key") or "").lower() or None, "role": node_type_label(adv_type), @@ -286,7 +290,7 @@ async def status_facts(device: Device, snapshot: dict) -> Facts: def _glossed(key: str, gloss: Callable[[int], str]) -> Column: - """A seconds reading printed as its own number with a readable span beside it.""" + """A reading in seconds, printed as its number with a readable duration next to it.""" from ..ui import script from ..ui.report import Column, Lane @@ -299,14 +303,14 @@ def _glossed(key: str, gloss: Callable[[int], str]) -> Column: def _span_gloss(seconds: int) -> str: - """``93784`` → ``1d 2h``: the figure a person can hold in their head.""" + """``93784`` → ``1d 2h``: a value that a person can easily understand.""" from ..ui import script return script.duration(seconds) def _drift_gloss(seconds: int) -> str: - """The device clock's error, in the direction a reader would say it.""" + """The error of the device clock, in the words that a person uses (fast or slow).""" from ..ui import script if abs(seconds) < 2: @@ -315,15 +319,15 @@ def _drift_gloss(seconds: int) -> str: async def _try(read) -> Any | None: - """Await a device read, returning ``None`` when the firmware doesn't support it.""" + """Await a device read. Return ``None`` if the firmware does not support it.""" try: return await read() - except Exception: # noqa: BLE001 - optional read; absence is acceptable + except Exception: # noqa: BLE001 - an optional read. If it is absent, that is acceptable. return None def _drift(device_epoch: int) -> str: - """Describe the device clock's drift against this computer's clock.""" + """Describe the drift of the device clock, compared with the clock of this computer.""" drift = device_epoch - int(time.time()) if abs(drift) < 2: return "(in sync)" @@ -332,7 +336,7 @@ def _drift(device_epoch: int) -> str: def _uptime(secs: int) -> str: - """Render an uptime as ``3d 2h 41m`` (seconds shown only under a minute).""" + """Render an uptime as ``3d 2h 41m`` (the seconds show only below one minute).""" if secs < 60: return f"{secs} s" days, rem = divmod(secs, 86400) diff --git a/meshterm/tools/livefeed.py b/meshterm/tools/livefeed.py index 9f250ed..206b9fb 100644 --- a/meshterm/tools/livefeed.py +++ b/meshterm/tools/livefeed.py @@ -1,16 +1,16 @@ # SPDX-License-Identifier: Apache-2.0 -"""The ``livefeed`` tool: every packet as it arrives, right under the dashboard. +"""The ``livefeed`` tool: each packet when it arrives, directly below the dashboard. -Opens the full-screen live feed (see :mod:`meshterm.ui.livefeed_screen`): the -streaming packet list that used to be the dashboard's bottom panel, promoted to its -own menu entry — newest first, every class, Enter opening any row in the shared -packet viewer. It sits directly under the dashboard because the two split one -question between them: the dashboard summarizes *what's going on out there*, the -feed shows every individual packet behind those numbers. +The tool opens the full-screen live feed (refer to :mod:`meshterm.ui.livefeed_screen`). +This is the streaming packet list that was the bottom panel of the dashboard before. Now +it has its own menu entry. It shows the newest packets first and all the classes, and +Enter opens any row in the shared packet viewer. It is directly below the dashboard, +because the two tools share one question. The dashboard summarizes what occurs on the +mesh, and the feed shows each packet behind those numbers. -Menu-only: the feed is inherently live (it rides the event hub and repaints every -second), so there is no scripted one-shot to register — the ``monitor`` subcommand -covers scripted packet-watching. +Menu only: the feed is always live (it uses the event hub and paints again each second). +Thus there is no scripted one-shot command to register. The ``monitor`` subcommand is the +script command to watch packets. """ from __future__ import annotations @@ -25,24 +25,24 @@ from .base import Tool, ToolResult, register @register class LiveFeedTool(Tool): - """Watch every packet stream in, newest first, and open any in the viewer.""" + """Watch each packet as it arrives, newest first, and open any packet in the viewer.""" name = "livefeed" title = "Live feed" icon = "📰" help = "Every packet as it arrives, newest first" category = "Watch" - order = 20 # right under the dashboard it was promoted out of + order = 20 # directly below the dashboard, which it came out of async def prompt_params(self, ctx: AppContext) -> dict[str, Any] | None: - """Run the live feed; there are never parameters to collect. + """Run the live feed. It has no parameters to collect. - The screen presents everything itself and returns when dismissed, so - returning ``None`` tells the menu the invocation is complete (the same + The screen shows all its content itself, and it returns when the user leaves it. + Thus the return value ``None`` tells the menu that the run is complete (the same pattern as the ``dashboard`` tool). Args: - ctx: Shared application context. + ctx: The shared application context. Returns: Always ``None``. @@ -53,20 +53,20 @@ class LiveFeedTool(Tool): return None async def run(self, ctx: AppContext, params: dict[str, Any]) -> ToolResult: - """Nothing runs here: the feed lives inside :meth:`prompt_params`. + """Nothing runs here: the feed is in :meth:`prompt_params`. Args: - ctx: Shared application context. - params: Unused. + ctx: The shared application context. + params: Not used. Returns: - An empty :class:`ToolResult` (only reachable from a scripted call). + An empty :class:`ToolResult` (only a scripted call comes here). """ return ToolResult(summary={}) def register_cli(self, app: typer.Typer) -> None: - """Register no CLI command — the feed is a live, menu-only screen. + """Register no CLI command, because the feed is a live screen for the menu only. Args: - app: The Typer application (untouched). + app: The Typer application (not changed). """ diff --git a/meshterm/tools/map.py b/meshterm/tools/map.py index 3819bfb..433e35f 100644 --- a/meshterm/tools/map.py +++ b/meshterm/tools/map.py @@ -1,17 +1,18 @@ # SPDX-License-Identifier: Apache-2.0 -"""The ``map`` tool: plot the mesh's located nodes on an OpenStreetMap terminal map. +"""The ``map`` tool: plot the located nodes of the mesh on an OpenStreetMap terminal map. -Nodes that share their location in adverts are collected from the passive-monitor history -(:meth:`~meshterm.persistence.repository.Repository.heard_nodes`), our own node is added when -its position is known, and everything is drawn over a real street basemap rendered as Unicode -braille (streets, rivers, place names — the same terminal-map idea as ``mapscii``). +The tool collects the nodes that share their location in adverts from the passive-monitor +history (:meth:`~meshterm.persistence.repository.Repository.heard_nodes`). It adds our node +when its position is known. Then it draws all the nodes over a real street basemap, +rendered as Unicode braille (streets, rivers, place names). This is the same terminal-map +idea as ``mapscii``. -Menu-only: it opens a full-screen, pannable/zoomable map (see -:mod:`meshterm.ui.map_screen`) and registers no CLI subcommand, because a map is a picture -and the scripted CLI deals in facts (see :meth:`MapTool.register_cli`). Repeaters are -prioritised over ordinary nodes: a distinct marker, drawn on top. The basemap is -best-effort — with no network (and no cached tiles) the nodes are plotted on a blank grid -instead, and the tool still works offline. +Menu only: the tool opens a full-screen map that the user can pan and zoom (refer to +:mod:`meshterm.ui.map_screen`). It registers no CLI subcommand, because a map is a picture, +and the scripted CLI gives facts (refer to :meth:`MapTool.register_cli`). Repeaters have +priority over ordinary nodes: they have a different marker, drawn on top. The basemap is a +best effort. With no network (and no cached tiles), the tool plots the nodes on a blank +grid, and it still works offline. """ from __future__ import annotations @@ -26,15 +27,15 @@ from .base import Tool, ToolResult, register def _fraction(ctx: AppContext, params: dict[str, Any]) -> float: - """How much of the mesh a map opens framed on: the flag if one was passed, else the preference. + """The fraction of the mesh that a new map frames: the flag if given, else the preference. - ``--fraction`` is resolved here rather than as the Typer option's default because the - options are declared at CLI *registration* time — before a context, and so before the - preferences file has been read. + ``--fraction`` is resolved here, not as the default of the Typer option, because the + options are declared when the CLI is registered. That occurs before a context exists, + and thus before MeshTerm reads the preferences file. Args: - ctx: Shared application context. - params: This invocation's parameters. + ctx: The shared application context. + params: The parameters of this run. Returns: The fraction to frame. @@ -49,7 +50,7 @@ if TYPE_CHECKING: @register class MapTool(Tool): - """Show the mesh's location-sharing nodes on a braille OpenStreetMap map.""" + """Show the nodes of the mesh that share a location on a braille OpenStreetMap map.""" name = "map" title = "Map" @@ -59,16 +60,18 @@ class MapTool(Tool): order = 10 async def run(self, ctx: AppContext, params: dict[str, Any]) -> ToolResult: - """Gather the located nodes and open the interactive map. + """Collect the located nodes and open the interactive map. - Menu-only (see :meth:`register_cli`), so there is one path through here. + The tool is for the menu only (refer to :meth:`register_cli`), so this method has + one path. Args: - ctx: Shared application context. - params: Optional ``fraction`` — how much of the mesh to open framed on. + ctx: The shared application context. + params: An optional ``fraction``: the part of the mesh to frame when the map + opens. Returns: - A :class:`ToolResult` summarizing how many nodes were plotted. + A :class:`ToolResult` with the number of plotted nodes. """ from ..ui.map_screen import open_map @@ -93,25 +96,25 @@ class MapTool(Tool): }, ) - # -- marker gathering ------------------------------------------------------- + # -- the markers ------------------------------------------------------------ async def _gather(self, ctx: AppContext) -> list[MapMarker]: - """Collect every located node to plot (see :func:`gather_markers`).""" + """Collect each located node to plot (refer to :func:`gather_markers`).""" return await gather_markers(ctx) def register_cli(self, app: typer.Typer) -> None: - """Register no CLI command — a map is a picture, and pictures are menu-only. + """Register no CLI command, because a map is a picture, and pictures are menu only. - Every other feature has a scripted face because its answer is a set of facts a - script can act on. A map's answer is a *drawing*: braille cells whose meaning is - their position on a grid and whose nodes are told apart by colour, which is - exactly what the scripted CLI does not have (see :mod:`meshterm.ui.script`). A - one-shot render there would be an unparseable block of glyphs, and stripping its - colour to match the rest of the CLI would make it unreadable as well. + Each other feature has a scripted face, because its answer is a set of facts that + a script can use. The answer of a map is a drawing. Its braille cells get their + meaning from their position on a grid, and colour tells its nodes apart. The + scripted CLI does not have these (refer to :mod:`meshterm.ui.script`). A one-shot + render on the CLI is a block of glyphs that no program can parse. If the render + has no colour, as the rest of the CLI, a person cannot read it either. - The located nodes themselves are still scriptable — ``meshterm contacts`` lists - every one of them, coordinates included. + A script can still get the located nodes: ``meshterm contacts`` lists each of + them, with their coordinates. Args: - app: The Typer application (untouched). + app: The Typer application (not changed). """ diff --git a/meshterm/tools/monitor.py b/meshterm/tools/monitor.py index 02e0b05..c2f1721 100644 --- a/meshterm/tools/monitor.py +++ b/meshterm/tools/monitor.py @@ -1,19 +1,19 @@ # SPDX-License-Identifier: Apache-2.0 -"""The ``monitor`` tool: a bounded foreground capture of what the mesh is saying. +"""The ``monitor`` tool: a foreground capture of the mesh traffic, for a limited time. -Passive monitoring records every advert and telemetry frame the companion overhears — -with SNR, RSSI, and any shared location — to the database, building the longitudinal -history that the map's packet counts and the nodes list read back. It transmits nothing; -it only listens. +Passive monitoring stores each advert and telemetry packet that the companion hears in the +database, with its SNR, its RSSI, and any shared location. Over time, this makes the +history that the packet counts of the map and the nodes list read. The tool transmits +nothing. It only listens. -Recording is always on: the session-wide -:class:`~meshterm.services.event_hub.EventHub` overhears every packet, and -:class:`~meshterm.services.monitor_service.MonitorService` (``ctx.monitor``) writes them -to history as one of its subscribers, from the moment the radio opens. In the menu the -live packet counters show in the persistent header and the accumulated data surfaces -through Nodes and Map, so there is no separate screen here — this tool is CLI-only: -``meshterm monitor --seconds 60`` tails each overheard packet to the console and -summarizes the window when it ends. +MeshTerm always stores this history. The session-wide +:class:`~meshterm.services.event_hub.EventHub` receives each packet, and +:class:`~meshterm.services.monitor_service.MonitorService` (``ctx.monitor``) is one of its +subscribers. From the time that the connection to the device opens, the service writes +the packets to the history. In the menu, the live packet counters show in the header, +which is always visible, and the stored data shows on Nodes and Map. Thus this tool has no +screen, and it is CLI only. ``meshterm monitor --seconds 60`` prints each heard packet to +the console, and it gives a summary of the window when the window ends. """ from __future__ import annotations @@ -37,7 +37,7 @@ if TYPE_CHECKING: # pragma: no cover - typing only @register class MonitorTool(Tool): - """Capture overheard packets in the foreground for a bounded window (CLI only).""" + """Capture heard packets in the foreground for a limited time window (CLI only).""" name = "monitor" title = "Monitor" @@ -45,18 +45,18 @@ class MonitorTool(Tool): help = "Capture overheard packets live for a while and summarize them" category = "Watch" order = 50 - menu_visible = False # recording is always on; in the menu the header/Nodes/Map show it + menu_visible = False # always stored. In the menu, the header, Nodes, and Map show it async def execute(self, ctx: AppContext, params: dict[str, Any]) -> ToolResult: """Run directly, without a logged ``runs`` row. - The capture's observations are recorded under the monitor service's own - ``monitor`` run, so wrapping this invocation in a second run row (as the base - :meth:`Tool.execute` would) would double-log the session. + The monitor service stores the observations of the capture under its own + ``monitor`` run. The base :meth:`Tool.execute` puts each run in a run row. A second + run row for this run logs the session two times. Args: - ctx: Shared application context. - params: Parameters for this invocation. + ctx: The shared application context. + params: The parameters for this run. Returns: The :class:`ToolResult` from :meth:`run`. @@ -64,29 +64,30 @@ class MonitorTool(Tool): return await self.run(ctx, params) async def run(self, ctx: AppContext, params: dict[str, Any]) -> ToolResult: - """Record overheard packets in the foreground for a bounded window. + """Store heard packets in the foreground for a limited time window. - Connects the device, ensures history recording and the event hub are running, - and tails each overheard packet to the console until the window ends (or the - user interrupts). Observations are persisted by the monitor service exactly as - in an interactive session; this adds a live console view and a window-scoped - heard-node summary on top. + The method connects the device, and it makes sure that the history storage and + the event hub run. Then it prints each heard packet to the console until the + window ends (or until the user interrupts it). The monitor service stores the + observations exactly as in an interactive session. This method adds a live + console output, and a summary of the nodes that were heard in the window. Args: - ctx: Shared application context. - params: ``seconds`` — how long to capture (``0``/``None`` = until Ctrl-C). + ctx: The shared application context. + params: ``seconds``: the duration of the capture (``0`` or ``None`` = until + Ctrl-C). Returns: - A :class:`ToolResult` with the window's packet and node counts. + A :class:`ToolResult` with the packet count and the node count of the window. """ from ..ui import script seconds = int(params.get("seconds") or 0) - await ctx.device() # surface connection problems before announcing the capture - await ctx.monitor.start() # register history recording before the hub pumps + await ctx.device() # show a connection problem before the capture is announced + await ctx.monitor.start() # register history storage before the hub sends events await ctx.events.start() - # The announcement is about the run, not part of its answer, so it goes to stderr - # and stays out of `meshterm monitor -s 60 > packets.txt`. + # The announcement is about the run, and it is not part of the answer. Thus it goes + # to stderr, and it stays out of `meshterm monitor -s 60 > packets.txt`. script.stderr_console().print( "monitoring" + (f" for {seconds}s" if seconds else " — press Ctrl-C to stop"), style="muted", @@ -112,8 +113,9 @@ class MonitorTool(Tool): "snr_db": obs.snr, "rssi_dbm": obs.rssi, "position": _position(obs.lat, obs.lon), - # The region a flood was sent into, resolved against the names known - # right now; a direct frame (or a class with no route) has none. + # The region that a flood was sent into, found from the region names + # that are known now. A direct packet (or a class with no route) has + # no region. "scope": ctx.region_store.scope_of(obs.raw), "path": _relays(obs.path), } @@ -125,7 +127,7 @@ class MonitorTool(Tool): if seconds: await asyncio.sleep(seconds) else: - await asyncio.Event().wait() # until Ctrl-C / cancellation + await asyncio.Event().wait() # until Ctrl-C or cancellation except (KeyboardInterrupt, asyncio.CancelledError): # pragma: no cover - interactive pass finally: @@ -137,8 +139,9 @@ class MonitorTool(Tool): by_node.setdefault(obs.node, []).append(obs) nodes = [HeardNode.from_observations(node, group) for node, group in by_node.items()] nodes.sort(key=lambda n: n.last_seen, reverse=True) - # The window is over, so its facts are worth saying — on stderr, where everything - # about a run goes, keeping the packets a caller redirected the run for on their own. + # The window is over, so its facts are useful. They go to stderr, where all the + # information about a run goes. Thus the packets, which are the reason that the + # caller redirected the output, stay alone on stdout. script.stderr_console().print( f"captured {len(seen)} packet{'' if len(seen) == 1 else 's'} " f"from {len(nodes)} node{'' if len(nodes) == 1 else 's'}" @@ -153,7 +156,7 @@ class MonitorTool(Tool): ) def register_cli(self, app: typer.Typer) -> None: - """Register the ``monitor`` subcommand (the bounded foreground capture). + """Register the ``monitor`` subcommand (the foreground capture for a limited time). Args: app: The Typer application. @@ -170,17 +173,18 @@ class MonitorTool(Tool): def _position(lat: float | None, lon: float | None) -> Position | None: - """A reception's shared position, or ``None`` where the packet carried none.""" + """The shared position of a reception, or ``None`` if the packet had no position.""" return Position(lat, lon) if lat is not None and lon is not None else None def _relays(path: str | None) -> list[str] | None: - """A packet's relay chain as hashes, in propagation order. + """The relay chain of a packet as hashes, in the order that the packet went through. - Hashes rather than the shared node shape, and that is the honest answer: nothing - resolves a relay to a node at reception time, so a node object per hop would be four - ``null``s wrapped round a hash. ``[]`` is a direct reception (zero hops); ``None`` - means the packet class carries no path at all, which is a different fact. + The function returns hashes instead of the shared node shape, and that is the correct + answer. At reception time, nothing finds the node for a relay. Thus a node object for + each hop has only four ``null`` values around a hash. ``[]`` is a direct reception + (zero hops). ``None`` means that the packet class has no path, which is a different + fact. """ if path is None: return None @@ -188,14 +192,14 @@ def _relays(path: str | None) -> list[str] | None: def _live_packets() -> Listing: - """The shape the live capture streams: one record per packet, as it lands. + """The shape that the live capture streams: one record for each packet, when it arrives. - ``TIME`` is absolute where a listing's times are ages, and for the reason the whole - rule turns on: every row of a live tail would read ``now``. ``SCOPE`` says which region - a flood was sent into (:func:`~meshterm.ui.fields.scope`), ``null`` in the document for - a frame that has none. The **name goes last**, so - the one field with no width cannot push a lane — which is what finally let the two - streams have columns at all, and with them the quoting could go. + ``TIME`` is an absolute time, but the times of a listing are usually ages. The reason + is the base of that rule: in a live output, an age shows ``now`` in each row. ``SCOPE`` + gives the region that a flood was sent into (:func:`~meshterm.ui.fields.scope`). In + the document, it is ``null`` for a packet that has no scope. The **name goes last**, + so the only field with no width cannot push a lane. This change finally let the two + streams have columns, and with the columns, the quoting was no longer necessary. """ from dataclasses import replace @@ -215,16 +219,17 @@ def _live_packets() -> Listing: columns=( pin(fields.instant("observed_at", "TIME"), 25), node, - # The packet class, which the plain stream has never had room for. New - # surface: the simulator does not exercise every class, so a consumer should - # treat an unfamiliar word as a word rather than an error. + # The packet class. The plain stream never had space for it. This field is new, + # and the simulator does not make each class. Thus a consumer must read an + # unfamiliar word as a word, not as an error. fields.hidden("kind"), pin(fields.snr("snr_db", "SNR_DB"), 6), pin(fields.decimal("rssi_dbm", "RSSI_DBM", ".0f"), 8), pin(fields.position(), 19), - # The flood's scope — a region name, ``unknown`` or ``unscoped``, ``-`` for a - # frame with none. Pinned to hold the two words whole; a long region name - # overruns and pushes the row right, which is why NAME still goes last. + # The scope of the flood: a region name, ``unknown``, or ``unscoped``, and ``-`` + # for a packet with no scope. The width is pinned to hold the two words + # complete. A long region name overruns and pushes the row to the right, so + # NAME still goes last. pin(fields.scope(), 10), fields.hidden("path"), ), @@ -233,18 +238,19 @@ def _live_packets() -> Listing: def _heard(heard: list[HeardNode]) -> Listing: - """The capture window's per-node summary: what each node did over the whole window. + """A summary of the capture window for each node: what the node did in the whole window. - The aggregate the live stream cannot give — a count, a median, a best — one record per - node heard, most recently heard first. + The summary gives the aggregates that the live stream cannot give (a count, a median, + a best value). It has one record for each heard node, and the most recently heard + node is first. - Drawn **for a person only**. Every figure in it is computable from the records that - scrolled past above it, and emitting it as a second *shape* of line in the middle of an - otherwise homogeneous NDJSON stream would cost every consumer a discriminator it would - never otherwise need. + It is drawn **for a person only**. A program can calculate each value in it from the + records above it. The NDJSON stream has lines of only one shape. If the summary was a + second shape of line in that stream, each consumer must have a discriminator, which + no consumer needs for the other lines. Args: - heard: Aggregated per-node statistics for the window. + heard: The aggregated statistics of each node for the window. Returns: The listing. diff --git a/meshterm/tools/preferences.py b/meshterm/tools/preferences.py index d59390f..588315a 100644 --- a/meshterm/tools/preferences.py +++ b/meshterm/tools/preferences.py @@ -1,19 +1,20 @@ # SPDX-License-Identifier: Apache-2.0 -"""The ``preferences`` tool: how MeshTerm itself behaves. +"""The ``preferences`` tool: the behaviour of MeshTerm itself. -Interactively it opens the Preferences page (see :mod:`meshterm.ui.preferences`), which -stages changes and hands them back here to write. On the CLI it exposes the same -preferences as ``show`` / ``get`` / ``set`` / ``reset``, so a value can be changed from a -shell — or from a script setting a machine up — without launching the full-screen session. +In the menu, the tool opens the Preferences page (refer to :mod:`meshterm.ui.preferences`). +The page stages the changes and returns them to this tool, which writes them. On the CLI, +the tool gives the same preferences through ``show``, ``get``, ``set``, and ``reset``. +Thus a user can change a value from a shell, and a script can change it when it sets up a +machine, without the full-screen session. -Everything funnels through :meth:`PreferencesTool.run`, which applies a list of operations -and saves the file once at the end: one write per invocation, whether it came from the page -staging eleven changes or from a single ``preferences set``. +All changes go through :meth:`PreferencesTool.run`. It applies a list of operations and +saves the file one time at the end. Thus each run writes the file one time. This is true +for eleven changes that the page staged, and for one ``preferences set``. -This is deliberately the *app's* tool, not the radio's. It reads nothing from the -companion, transmits nothing, and works with no device attached at all — which is why it -leads the **This app** section (the third owner, after this node and other nodes) rather -than sitting beside Device config. +This tool is the tool of the app, not of the device, on purpose. It reads nothing from the +companion, it transmits nothing, and it works with no device connected. For this reason, +it is the first row of the **This app** section (the third owner, after this node and +other nodes), and it is not next to Device config. """ from __future__ import annotations @@ -39,24 +40,24 @@ if TYPE_CHECKING: # pragma: no cover - typing only @register class PreferencesTool(Tool): - """View and change MeshTerm's own preferences, saved to ``preferences.toml``.""" + """Show and change the preferences of MeshTerm, which are saved to ``preferences.toml``.""" name = "preferences" title = "Preferences" icon = "⚙" help = "How MeshTerm behaves — startup, sending, history, …" category = "This app" - order = 5 # leads the section: the one row there that changes MeshTerm, not describes it + order = 5 # first in the section. Its row changes MeshTerm, and the other rows describe it async def prompt_params(self, ctx: AppContext) -> dict[str, Any] | None: - """Open the Preferences page and collect the changes it staged. + """Open the Preferences page and collect the changes that it staged. Args: - ctx: Shared application context. + ctx: The shared application context. Returns: - ``{"ops": [("set", key, value), …]}`` to write, or ``None`` if the reader left - with nothing staged. + ``{"ops": [("set", key, value), …]}`` to write, or ``None`` if the user left + with no staged changes. """ from ..ui.preferences import edit_preferences @@ -66,22 +67,22 @@ class PreferencesTool(Tool): return {"ops": [("set", key, value) for key, value in staged.items()]} async def run(self, ctx: AppContext, params: dict[str, Any]) -> ToolResult: - """Apply a list of preference operations, saving the file once if anything changed. + """Apply a list of preference operations. If a value changed, save the file one time. - Operations are ``("show",)``, ``("get", key)``, ``("set", key, value)``, and - ``("reset",)``. They run in order, so a scripted ``set`` after a ``reset`` lands on - top of the defaults rather than under them. + The operations are ``("show",)``, ``("get", key)``, ``("set", key, value)``, and + ``("reset",)``. They run in order. Thus a scripted ``set`` after a ``reset`` + changes the value from its default, and the ``reset`` does not remove that change. Args: - ctx: Shared application context. - params: ``ops`` — the operations to perform. + ctx: The shared application context. + params: ``ops``: the operations to do. Returns: - A :class:`ToolResult` counting the preferences changed. + A :class:`ToolResult` with the number of changed preferences. Raises: - PreferenceError: If a key is unknown or a value fails its spec — reported - cleanly by the CLI rather than as a traceback. + PreferenceError: If a key is unknown, or if a value does not agree with its + spec. The CLI reports this as a clear error, not as a traceback. """ from ..services import consolefont from ..ui.preferences import preferences_table @@ -101,9 +102,9 @@ class PreferencesTool(Tool): else: ctx.ui.show(preferences_table(prefs, ctx.console.width)) elif action == "get": - # The bare value and nothing else — the caller named the key, and - # whether it is overridden is what `show`'s DEFAULT lane answers. The - # document keeps both, since a parser has no lane to read them off. + # Only the bare value, because the caller named the key. The DEFAULT lane + # of `show` tells if the value is overridden. The document keeps both, + # because a parser has no lane to read them from. spec = get_spec(op[1]) if scripted: blocks.append(_one(prefs, spec)) @@ -128,16 +129,18 @@ class PreferencesTool(Tool): if changes: prefs.save() if any(c["key"] == "weekly_flood_advert" for c in applied): - # Switching the weekly advert on starts its week rather than sending, so the - # instant is recorded as it happens — from the page and a shell alike — and - # not whenever the scheduler next looks (see meshterm.core.advert_store). + # When the user switches the weekly advert on, its week starts, but nothing is + # sent. Thus MeshTerm stores the instant when it occurs (from the page and from + # a shell), and not when the scheduler next looks (refer to + # meshterm.core.advert_store). ctx.advert_store.set_enabled(bool(prefs.weekly_flood_advert)) if not scripted and any(c["key"] == consolefont.PREFERENCE_KEY for c in applied): - # The one preference whose effect is outside the app: the console's font is - # the console's, so it takes hold now rather than next launch. The kernel - # sends SIGWINCH on a VT font change, so prompt_toolkit repaints the whole - # frame at the new row count by itself. Menu-only — a scripted run was typed - # into a console it does not own (see meshterm.services.consolefont). + # The only preference that has an effect outside the app. The font belongs to + # the console, so the change occurs now, not at the next start. The kernel + # sends SIGWINCH when the font of a VT changes. Thus prompt_toolkit paints the + # whole frame again at the new row count by itself. This occurs only in the + # menu, because a user typed a scripted run into a console that the run does + # not own (refer to meshterm.services.consolefont). consolefont.apply(prefs.get(consolefont.PREFERENCE_KEY)) if scripted and any(op[0] in ("set", "reset") for op in ops): blocks.append(_written(applied, prefs)) @@ -203,20 +206,20 @@ __all__ = ["PreferencesTool", "PreferenceError"] def _script_value(spec: PrefSpec, value: Any) -> str: - """A preference's value in the form ``preferences set`` accepts back. + """The value of a preference, in the form that ``preferences set`` accepts. - :func:`~meshterm.core.preferences.format_value` writes for the page: a number carries - its unit (``5 s``), so a bare figure in the VALUE lane still says what it counts. That - unit is exactly what :func:`~meshterm.core.preferences.parse_value` will not take - back, so the scripted dump drops it. Booleans keep ``on``/``off`` and an enum keeps - its own key, both of which do round-trip. + :func:`~meshterm.core.preferences.format_value` writes for the page: a number has its + unit (``5 s``), so that a bare number in the VALUE lane tells what it counts. But + :func:`~meshterm.core.preferences.parse_value` does not accept that unit, so the + scripted output removes it. A boolean keeps ``on`` or ``off``, and an enum keeps its + own key. Both of these round-trip. Args: - spec: The preference the value belongs to. + spec: The preference that the value is for. value: Its current value. Returns: - The scripted rendering. + The value as text for a script. """ if spec.value_type == "bool": return "on" if value else "off" @@ -228,9 +231,10 @@ def _script_value(spec: PrefSpec, value: Any) -> str: def _row(prefs: Preferences, spec: PrefSpec) -> dict[str, Any]: """One preference as a report row, in the shared setting shape. - ``overridden`` is the fact the plain face makes a reader derive by comparing two - columns; a document that carried the same two numbers and left the comparison to the - consumer would be handing over homework it has the answer to. + On the plain face, the user compares two columns to find if a value is overridden. + ``overridden`` gives this fact directly. If a document gives the same two numbers and + lets the consumer compare them, the consumer must do work for which the document + already has the answer. """ from ..ui.fields import Rendered @@ -239,8 +243,8 @@ def _row(prefs: Preferences, spec: PrefSpec) -> dict[str, Any]: "key": spec.key, "value": Rendered(value, _script_value(spec, value)), "type": spec.value_type, - # The reader's word for an enum's own key — never what `set` takes, which is the - # key itself and rides in `value`. + # The word that the user sees for the key of an enum. It is never what `set` takes: + # `set` takes the key itself, which is in `value`. "label": (spec.choices or {}).get(value) if spec.value_type == "enum" else None, "redacted": False, "default": Rendered(spec.default, _script_value(spec, spec.default)), @@ -250,7 +254,7 @@ def _row(prefs: Preferences, spec: PrefSpec) -> dict[str, Any]: def _columns() -> tuple: - """The preference row's columns, shared by ``show`` and ``get``.""" + """The columns of a preference row, which ``show`` and ``get`` share.""" from ..ui import fields return ( @@ -266,13 +270,13 @@ def _columns() -> tuple: def _listing(prefs: Preferences) -> Listing: - """Every preference, its value, its built-in default, and what it is for. + """Each preference, with its value, its built-in default, and its purpose. - ``DESCRIPTION`` comes straight from :attr:`PrefSpec.help` — the text is already - written, one short line each, and as the *last* column it can never disturb an - alignment or wrap. It used to be cut for parser hygiene, which is a bargain the plain - face no longer has to make: a listing is read by a person now, and a person choosing a - preference is exactly who that sentence was written for. + ``DESCRIPTION`` comes directly from :attr:`PrefSpec.help`. That text is already + written, with one short line for each preference. Because it is the last column, it + can never break an alignment or cause a wrap. Before, the listing removed it, to keep + the output clean for a parser. The plain face does not have to do that now: a person + reads the listing, and the sentence was written for a person who selects a preference. Args: prefs: The preference set to report. @@ -291,7 +295,7 @@ def _listing(prefs: Preferences) -> Listing: def _one(prefs: Preferences, spec: PrefSpec) -> Facts: - """One preference: the bare value plain, the whole setting object in the document.""" + """One preference: the bare value on the plain face, the full setting object in the document.""" from ..ui.report import BARE, Facts return Facts( @@ -304,11 +308,11 @@ def _one(prefs: Preferences, spec: PrefSpec) -> Facts: def _written(applied: list[dict[str, Any]], prefs: Preferences) -> Facts: - """What ``set`` or ``reset`` changed — nothing plain, a record for whoever wants one. + """What ``set`` or ``reset`` changed: nothing on the plain face, and a record for a log. - The plain face says it in the exit status and in the acknowledgement on stderr, which - is the whole answer for a person. A caller managing a machine's configuration wants to - know *what moved*, and had no way to ask. + The plain face gives the result in the exit status and in the acknowledgement on + stderr. For a person, that is the whole answer. A caller that manages the setup of a + machine wants to know what changed, and before, it had no way to ask. """ from ..ui import fields from ..ui.report import SILENT, Column, Facts diff --git a/meshterm/tools/records.py b/meshterm/tools/records.py index 3a49729..a0120fa 100644 --- a/meshterm/tools/records.py +++ b/meshterm/tools/records.py @@ -1,15 +1,16 @@ # SPDX-License-Identifier: Apache-2.0 -"""The Trophy case tool: the record-setting walks the trace tools have turned up. +"""The Trophy case tool: the record-setting walks that the trace tools found. -The menu face opens the browser (:mod:`meshterm.ui.records_screen`): every discipline's -records — longest distance, farthest node, most nodes (with and without revisits), -weakest surviving link, biggest loop — each under its own description, opened for their -full stats, re-walked in Trace path, or deleted. Records are *earned* on the trace -screens, where every walk that comes home is scored and offered to the boards (see -:mod:`meshterm.services.records`); this tool never transmits. +The menu face opens the browser (:mod:`meshterm.ui.records_screen`). It shows the records +of each discipline: longest distance, farthest node, most nodes (with and without +revisits), weakest link that survived, and biggest loop. Each discipline has its own +description. The user can open a record to see all its stats, walk it again in Trace +path, or delete it. The records are earned on the trace screens: each walk that comes +back is scored and offered to the boards (refer to :mod:`meshterm.services.records`). This +tool never transmits. -The CLI face prints the stored boards: ``meshterm records`` reads the tables so a script -(or a curious shell) can see the standings without a device attached. +The CLI face prints the stored boards. ``meshterm records`` reads the tables, so that a +script (or a user at a shell) can see the standings without a connected device. """ from __future__ import annotations @@ -26,7 +27,7 @@ from ..services.records import CATEGORIES, CATEGORY_BY_ID, Category from ..ui.script import NONE from .base import Tool, ToolResult, register -#: The hash widths a record can be set at: MeshCore's path hashes are 1, 2 or 4 bytes. +#: The hash widths at which a record can be set: MeshCore path hashes are 1, 2, or 4 bytes. WIDTHS = (1, 2, 4) if TYPE_CHECKING: # pragma: no cover - typing only @@ -37,24 +38,24 @@ if TYPE_CHECKING: # pragma: no cover - typing only @register class TrophyCaseTool(Tool): - """The record-setting mesh walks the trace tools scored, browsed or listed.""" + """The record-setting mesh walks that the trace tools scored, to browse or to list.""" name = "records" title = "Trophy case" icon = "🏆" help = "Record-setting walks, scored from every trace" category = "Explore" - order = 40 # what the two walks above it score into + order = 40 # the two walks above it put their scores here async def prompt_params(self, ctx: AppContext) -> dict[str, Any] | None: - """Open the browser; returning ``None`` completes the invocation with no run row. + """Open the browser. The return value ``None`` completes the run with no run row. - The screen reads stored records and transmits nothing (and logs no rows of its - own), so it lives in :meth:`prompt_params` and needs no logged run — the mesh walk / - dashboard pattern. + The screen reads stored records and transmits nothing (and it logs no rows of its + own). Thus it is in :meth:`prompt_params`, and it does not need a logged run. The + mesh walk and the dashboard use the same pattern. Args: - ctx: Shared application context. + ctx: The shared application context. Returns: Always ``None``. @@ -65,11 +66,11 @@ class TrophyCaseTool(Tool): return None async def run(self, ctx: AppContext, params: dict[str, Any]) -> ToolResult: - """Print the stored boards — only reachable from a scripted call (never transmits). + """Print the stored boards. Only a scripted call comes here (this never transmits). Args: - ctx: Shared application context. - params: ``category``/``width`` filters and the injected ``_run_id``. + ctx: The shared application context. + params: The ``category`` and ``width`` filters, and the injected ``_run_id``. Returns: A :class:`ToolResult` with the record count. @@ -83,12 +84,12 @@ class TrophyCaseTool(Tool): def _show_records( self, ctx: AppContext, *, category: str | None, width: int | None ) -> ToolResult: - """State the stored record boards (no device, no transmissions). + """Give the stored record boards (with no device, and with no transmission). Args: - ctx: Shared application context. - category: Only this category id, or ``None`` for every discipline. - width: Only this hash width, or ``None`` for every width. + ctx: The shared application context. + category: Only this category id, or ``None`` for all the disciplines. + width: Only this hash width, or ``None`` for all the widths. Returns: A :class:`ToolResult` with the record count. @@ -98,8 +99,8 @@ class TrophyCaseTool(Tool): from ..ui.report import Listing wanted = [CATEGORY_BY_ID[category]] if category in CATEGORY_BY_ID else CATEGORIES - # Names come from stored history alone — no contacts, because this command reads - # the database and must work with no radio attached at all. + # The names come only from the stored history, not from the contacts, because this + # command reads the database. It must work with no device connected. resolve = trace_runner.make_node_resolver(None, ctx.repo.node_names()) rows: list[dict] = [] @@ -125,19 +126,19 @@ class TrophyCaseTool(Tool): key="records", columns=( fields.word("category", "CATEGORY"), - # The contract's word for the concept. The plain heading stays WIDTH, - # which is what a column of 1/2/4 reads as. + # The word of the contract for this concept. The plain heading stays + # WIDTH, because a column of 1, 2, or 4 reads as a width. fields.integer("hash_bytes", "WIDTH"), _score_column(), fields.word("unit", "UNIT"), - # `>=273.0` is not a number, and a consumer comparing scores must be able - # to see the qualifier without string-matching a prefix off its own data. + # `>=273.0` is not a number. A consumer that compares scores must see the + # qualifier without a string match on a prefix of its own data. fields.hidden("lower_bound"), fields.when("recorded_at", "RECORDED"), fields.word("version", "VERSION"), - # The transmitted spec, hop-aligned with the route beside it. It has no - # column — a route line already runs off the right — but it is what a - # caller re-walks with, so the document carries it. + # The transmitted spec, aligned hop for hop with the route next to it. It + # has no column, because a route line already goes past the right edge. + # But a caller uses it to walk the path again, so the document holds it. fields.hidden("path"), fields.route(), ), @@ -152,7 +153,7 @@ class TrophyCaseTool(Tool): ) def register_cli(self, app: typer.Typer) -> None: - """Register the ``records`` subcommand (read-only record listing). + """Register the ``records`` subcommand (a read-only listing of the records). Args: app: The Typer application. @@ -177,9 +178,9 @@ class TrophyCaseTool(Tool): ) -> None: tool_params: dict[str, Any] = {} if category: - # An unknown id used to select *every* discipline, so a misspelled - # `--category long_hual` came back as "no records" — exit 5, which is - # exactly what a real empty result looks like. A closed set refuses. + # Before, an unknown id selected all the disciplines. Thus a misspelled + # `--category long_hual` returned "no records" with exit 5, which is the + # same as a real empty result. A closed set refuses an unknown id. if category not in CATEGORY_BY_ID: choices = ", ".join(CATEGORY_BY_ID) raise typer.BadParameter( @@ -187,9 +188,9 @@ class TrophyCaseTool(Tool): ) tool_params["category"] = category if width is not None: - # The same closed set as --category, for the same reason: `--width 3` - # found nothing and exited 5, indistinguishable from an empty database, - # and `--width 0` was falsy and so quietly listed every width. + # A closed set, as for --category, for the same reason. `--width 3` found + # nothing and exited 5, which was the same as an empty database. And + # `--width 0` was falsy, so it listed all the widths with no warning. if width not in WIDTHS: choices = ", ".join(map(str, WIDTHS)) raise typer.BadParameter(f"--width must be one of: {choices} (got {width})") @@ -199,17 +200,17 @@ class TrophyCaseTool(Tool): @dataclass(frozen=True, slots=True) class _Score: - """A record's score, and the one thing about it a bare number cannot carry. + """The score of a record, and the one fact about it that a bare number cannot hold. - ``format_score`` writes ``273.0 km`` for a reader; the unit is its own column here so - the ``SCORE`` column is one comparable number per row. What has to travel *with* the - number is the ``>=`` on a Longest-distance walk whose kilometre total is incomplete — - some hop on it has no known position, so the distance is a floor rather than a - measurement, and dropping the qualifier would turn a lower bound into a claim. + ``format_score`` writes ``273.0 km`` for a person. Here the unit has its own column, + so that the ``SCORE`` column has one comparable number in each row. But one thing must + stay with the number: the ``>=`` on a Longest-distance walk whose kilometre total is + not complete. A hop on that walk has no known position, so the distance is a minimum, + not a measurement. Without the qualifier, a lower bound becomes a claim. - The plain face wears the prefix; the document keeps the number a number and says - ``lower_bound`` beside it, because a consumer comparing scores cannot be asked to - string-match a prefix off the front of its own data. + The plain face shows the prefix. The document keeps the number as a number, and it + gives ``lower_bound`` next to it. The reason is that a consumer that compares scores + must not have to match a prefix at the start of its own data. """ value: float @@ -218,7 +219,7 @@ class _Score: @property def text(self) -> str: - """The score as the SCORE column prints it, qualifier and all.""" + """The score as the SCORE column prints it, with the qualifier.""" if self.category.unit == "nodes": drawn = str(int(self.value)) elif self.category.unit == "dB": @@ -229,7 +230,7 @@ class _Score: def _score_column() -> Column: - """The SCORE column: the qualified figure plain, the bare number in the document.""" + """The SCORE column: the qualified number on the plain face, the bare number in a document.""" from ..ui.report import Column, Lane return Column( @@ -246,22 +247,23 @@ def _score_column() -> Column: def _route(record: DiscoveredPath, resolve: Callable[[str], str | None]) -> list[NodeRef]: - """A record's walk as the shared route shape. + """The walk of a record, as the shared route shape. - Each hop is named where history knows the node and carries the hash it was actually - transmitted at — the spec's own hop, at this record's width — so the line can be read - against the ``path`` a re-walk would take. Where the two lists disagree in length the - node id stands in, which is the only identity that hop has. + Each hop has a name if the history knows the node. Each hop also has the hash with + which it was transmitted (the hop of the spec itself, at the width of this record). + Thus a person can compare the line with the ``path`` that a new walk uses. If the + two lists have different lengths, the node id is used instead. That id is the only + identity that the hop has. - Our own node never appears in a record's walk: a discovery is scored on what it - reached, and the two ends of it are somebody else's. + Our node is never in the walk of a record. A discovery is scored on what it reached, + and its two ends are the nodes of other persons. Args: record: The record whose walk to render. - resolve: Maps a node id to a friendly name, or ``None`` when unknown. + resolve: Gives the friendly name of a node id, or ``None`` if the name is unknown. Returns: - The hops in propagation order. + The hops, in the order that the packet went through them. """ from ..ui.fields import NodeRef diff --git a/meshterm/tools/regions.py b/meshterm/tools/regions.py index 0953eea..54ed373 100644 --- a/meshterm/tools/regions.py +++ b/meshterm/tools/regions.py @@ -1,23 +1,28 @@ # SPDX-License-Identifier: Apache-2.0 -"""The ``regions`` command: ask a repeater which regions it relays floods for. +"""The ``regions`` command: ask a repeater for which regions it relays floods. -``meshterm regions `` sends the anonymous regions request (firmware 1.12+, no -login) and prints the answer — the regions it relays scoped floods for, and whether it also -relays unscoped ones. One request, one transmission, per invocation: the repeater -rate-limits the question, and nothing here retries it. +``meshterm regions `` sends the anonymous regions request (firmware 1.12 or +later, no login) and prints the answer. The answer gives the regions for which the +repeater relays scoped floods, and it tells if the repeater also relays unscoped floods. +Each run sends one request, which is one transmission. The repeater limits the rate of +this question, and nothing here tries it again. -It is a command-line face only. In the menu the same question lives on a repeater's node -page (*Ask which regions it carries*), beside the answer it last gave, so there is no menu -row for it here. +This tool has only a command-line face. In the menu, the same question is on the node page +of a repeater ("Ask which regions it carries"), next to the last answer of that repeater. +Thus the menu has no row for this tool. -The answer is learned into the region store either way, exactly as the node page learns it, -so a scoped flood heard afterwards can be traced back to a region this repeater named. +In both cases, MeshTerm adds the answer to the region store, exactly as the node page does. +Thus MeshTerm can trace a scoped flood that it hears later back to a region that this +repeater named. -Exit status, per the CLI's rules: ``0`` when it answered with anything (unscoped floods -alone are an answer), ``5`` when it answered and named nothing at all — it relays no floods -— ``2`` for a contact that does not exist or is known not to be a repeater (nothing was -sent), and ``4`` when it never answered, which is what a repeater out of direct reach does: -the request is only answered when it arrives from a neighbour or over a known route. +The exit status, by the rules of the CLI: + +- ``0`` if the repeater answered with any value (only unscoped floods is also an answer). +- ``5`` if it answered and named nothing (it relays no floods). +- ``2`` for a contact that does not exist, or that is known not to be a repeater (nothing + was sent). +- ``4`` if it never answered. A repeater that is out of direct reach does this, because it + answers the request only when the request comes from a neighbour or over a known route. """ from __future__ import annotations @@ -52,16 +57,16 @@ class RegionsTool(Tool): """Send the regions request to one repeater and report its answer. Args: - ctx: Shared application context. - params: ``node``, the repeater's contact name. + ctx: The shared application context. + params: ``node``: the contact name of the repeater. Returns: - The answer as a report; ``NO_RESULT`` when it named nothing. + The answer as a report. ``NO_RESULT`` if the repeater named nothing. Raises: - typer.BadParameter: For an unknown contact, or one known not to be a repeater — - both decided before anything is sent. - DeviceCommandError: When the repeater never answered. + typer.BadParameter: For an unknown contact, or for a contact that is known not + to be a repeater. The method finds both before it sends anything. + DeviceCommandError: If the repeater never answered. """ device = await ctx.device() contacts = await device.get_contacts() @@ -102,11 +107,11 @@ class RegionsTool(Tool): def _answer(node: Contact, unscoped: bool, regions: list[str]) -> Facts: - """The repeater's answer, stated once for both faces. + """The answer of the repeater, given one time for both faces. - Three facts: who answered, whether it relays unscoped floods, and the regions it relays - scoped floods for — the wildcard kept out of that list, since it names no region (see - :func:`~meshterm.ui.fields.regions`). + Three facts: which node answered, if it relays unscoped floods, and the regions for + which it relays scoped floods. That list does not include the wildcard, because the + wildcard names no region (refer to :func:`~meshterm.ui.fields.regions`). """ from ..ui import fields from ..ui.fields import NodeRef diff --git a/meshterm/tools/repeater_admin.py b/meshterm/tools/repeater_admin.py index 223ef5a..efd1e11 100644 --- a/meshterm/tools/repeater_admin.py +++ b/meshterm/tools/repeater_admin.py @@ -1,16 +1,21 @@ # SPDX-License-Identifier: Apache-2.0 """The ``repeater-admin`` tool: set up remote repeaters and room servers over the mesh. -Interactively it opens the repeater-admin flow (see :mod:`meshterm.ui.repeater_admin`): -pick a node (credentialed ones lead the list), log in with a remembered or prompted -password, and land in a device-configuration-style editor speaking the node's text CLI — -including the repeater-only knobs the local editor never had (TX delay, Direct TX delay, -airtime factor, advert intervals) — plus one-shot actions (advert, clock sync, password, -reboot) and the readline-style remote command line. +In the menu, the tool opens the repeater-admin flow (refer to +:mod:`meshterm.ui.repeater_admin`): -On the CLI it stays a scriptable one-shot: ``repeater-admin `` logs in -(remembered password, or ``--password``) and prints the node's reply — one transmission -per invocation, the trace tool's rule. +1. The user selects a node. The nodes with stored credentials are first in the list. +2. The user logs in with a remembered password, or with a password that a prompt asks + for. +3. The user goes to an editor similar to Device config, which uses the text CLI of the + node. The editor includes the settings that only a repeater has, which the local + editor never had (TX delay, Direct TX delay, airtime factor, advert intervals). It also + has one-shot actions (advert, clock sync, password, reboot) and a remote command line + similar to readline. + +On the CLI, the tool stays a one-shot command for scripts. ``repeater-admin +`` logs in (with the remembered password, or with ``--password``) and prints the +reply of the node. Each run does one transmission, which is the rule of the trace tool. """ from __future__ import annotations @@ -31,23 +36,23 @@ if TYPE_CHECKING: # pragma: no cover - typing only @register class RepeaterAdminTool(Tool): - """Configure a remote repeater/room server: settings, actions, and its raw CLI.""" + """Configure a remote repeater or room server: settings, actions, and its raw CLI.""" name = "repeater-admin" title = "Repeater admin" icon = "🗼" help = "Run a remote repeater — settings and actions" category = "Other nodes" - order = 10 # the remote sibling of the local config tools + order = 10 # the remote equivalent of the local config tools async def prompt_params(self, ctx: AppContext) -> dict[str, Any] | None: - """Run the interactive flow; there are never parameters to collect. + """Run the interactive flow. It has no parameters to collect. - The flow presents everything itself (the same pattern as ``config``), - so returning ``None`` tells the menu the invocation is complete. + The flow shows all its content itself (the same pattern as ``config``). Thus the + return value ``None`` tells the menu that the run is complete. Args: - ctx: Shared application context. + ctx: The shared application context. Returns: Always ``None``. @@ -61,21 +66,21 @@ class RepeaterAdminTool(Tool): """Send one CLI command to a remote node and print its reply (scripted path). Args: - ctx: Shared application context. - params: ``node`` (contact name), ``command`` (the CLI text), and an - optional ``password`` overriding the remembered one. + ctx: The shared application context. + params: ``node`` (the contact name), ``command`` (the CLI text), and an + optional ``password`` that replaces the remembered password. Returns: - A :class:`ToolResult` carrying the node's reply (or its absence). + A :class:`ToolResult` with the reply of the node (or with no reply). """ device = await ctx.device() contacts = await device.get_contacts() name = str(params["node"]) node = next((c for c in contacts if c.name == name), None) - # Both of these are the *argument* being wrong, and nothing has gone out over - # the air when either fires — so they are usage errors (2), not device failures - # (4), whose promise to a caller is that a retry is worth trying. `tx-optimize` - # already answered the identical question this way for the identical condition. + # In both cases, the argument is wrong, and nothing went out on the air. Thus they + # are usage errors (2), not device failures (4). A device failure tells a caller + # that a retry can help. `tx-optimize` already gave the same answer for the same + # condition. if node is None: raise typer.BadParameter(f"unknown contact: {name!r}") @@ -103,8 +108,9 @@ class RepeaterAdminTool(Tool): return ToolResult( report=(_answered(node, command, reply),), summary={"node": name, "command": command, "replied": reply is not None}, - # Silence is not failure — the command may well have landed — but there is - # nothing to report, and a script waiting on output should know which it got. + # No reply is not a failure, because the command possibly arrived. But there is + # nothing to report, and a script that waits for output must know which result + # it got. exit_code=exitcodes.OK if reply is not None else exitcodes.NO_RESULT, ) @@ -131,16 +137,16 @@ class RepeaterAdminTool(Tool): def _answered(node: Contact, command: str, reply: str | None) -> Facts: - """What a remote node said back. + """The reply of a remote node. - ``reply`` is the node's own text, whole and verbatim — the plain face prints it bare - (as text and never as markup, so a reply holding a square bracket is a reply holding a - square bracket), and the document carries it raw, multi-line where the node sent - several lines. + ``reply`` is the text of the node, complete and exact. The plain face prints it bare, + as text and never as markup. Thus a square bracket in a reply stays a square bracket. + The document holds it raw, with more than one line if the node sent more than one + line. - It is deliberately **not parsed**. MeshTerm does not know the remote node's CLI - grammar, and a document that pretended to would be inventing structure a consumer - would then depend on. + On purpose, it is **not parsed**. MeshTerm does not know the CLI grammar of the remote + node. If the document parses it, the document invents a structure, and a consumer + then depends on that structure. """ from ..ui import fields from ..ui.fields import NodeRef diff --git a/meshterm/tools/rooms.py b/meshterm/tools/rooms.py index 185ab38..66b73cd 100644 --- a/meshterm/tools/rooms.py +++ b/meshterm/tools/rooms.py @@ -1,13 +1,14 @@ # SPDX-License-Identifier: Apache-2.0 -"""The ``rooms`` tool: the room servers your radio knows, and joining them. +"""The ``rooms`` tool: the room servers that your device knows, and how to join them. -Interactively it opens the Rooms page (see :mod:`meshterm.ui.rooms`) — every room server -the radio knows, joined ones first, each with a page to join it, log in again, open its -board, or forget it. On the CLI it exposes ``list``, ``join`` and ``forget``. +In the menu, the tool opens the Rooms page (refer to :mod:`meshterm.ui.rooms`). The page +lists each room server that the device knows, with the joined rooms first. Each room has a +page where the user can join it, log in again, open its board, or forget it. On the CLI, +the tool gives ``list``, ``join``, and ``forget``. -A room's board is *read* in Chat, the way a channel's messages are; this tool owns -everything to do with getting in, as the ``channels`` tool owns everything to do with -configuring a slot. +The user reads the board of a room in Chat, as for the messages of a channel. This tool +owns all the steps to get in, as the ``channels`` tool owns all the configuration of a +slot. """ from __future__ import annotations @@ -28,24 +29,24 @@ if TYPE_CHECKING: # pragma: no cover - typing only @register class RoomsTool(Tool): - """Join room servers, and keep track of the ones you have.""" + """Join room servers, and keep a list of the rooms that you joined.""" name = "rooms" title = "Rooms" icon = "📌" help = "Join room servers' message boards" category = "Message" - order = 25 # beside Channels: the other half of what Chat lists + order = 25 # next to Channels: the other half of the items that Chat lists async def run(self, ctx: AppContext, params: dict[str, Any]) -> ToolResult: """Open the Rooms page (menu) or run a scripted action (CLI). Args: - ctx: Shared application context. - params: A ``cli_action`` with its arguments (CLI), or empty for the menu. + ctx: The shared application context. + params: A ``cli_action`` and its arguments (CLI), or empty for the menu. Returns: - A :class:`ToolResult` recording what happened (the menu path shows nothing). + A :class:`ToolResult` that holds what occurred. The menu path shows nothing. """ action = params.get("cli_action") if action == "join": @@ -62,12 +63,12 @@ class RoomsTool(Tool): # -- CLI -------------------------------------------------------------------- async def _rooms(self, ctx: AppContext) -> list[Contact]: - """Every room server the radio knows, as the session's contact cache holds it.""" + """Each room server that the device knows, as the contact cache of the session has it.""" await ctx.device() return [c for c in await ctx.devstate.contacts() if c.is_room] async def _room(self, ctx: AppContext, needle: str) -> Contact: - """The room server a name or key prefix names — a usage error for anything else.""" + """The room server for a name or a key prefix. Any other value is a usage error.""" folded = needle.casefold() contacts = await ctx.devstate.contacts() for contact in contacts: @@ -79,7 +80,7 @@ class RoomsTool(Tool): raise typer.BadParameter(f"no room server matches {needle!r}") async def _cli_list(self, ctx: AppContext) -> ToolResult: - """List every room server the radio knows: joined, access, heard, posts, unread.""" + """List each room server that the device knows: joined, access, heard, posts, unread.""" rooms = await self._rooms(ctx) peers = [_peer(r) for r in rooms] lasts = ctx.repo.last_chat_messages(rooms=peers) @@ -105,19 +106,20 @@ class RoomsTool(Tool): ) async def _cli_join(self, ctx: AppContext, params: dict[str, Any]) -> ToolResult: - """Log in to a room server — one exchange — and print the access it granted. + """Log in to a room server (one exchange), and print the access that it gave. - The password is ``--password``, else the one MeshTerm remembers for the room (its - admin password, then its room password); one that works is remembered, exactly as - the Rooms page remembers it. ``--flood`` forgets the route the radio learned to the - room first, the way round a route gone stale. The room then sends every post the - radio hasn't seen, one at a time — they wait on the radio for whatever reads it next - (``chat listen``, the menu), and ``chat history`` has them from then on. + The password is ``--password``. If there is no ``--password``, it is the password + that MeshTerm remembers for the room (its admin password, then its room password). + MeshTerm remembers a password that works, exactly as the Rooms page remembers it. + ``--flood`` first forgets the route to the room that the device learned. This is + the solution for a stale route. Then the room sends each post that the device did + not receive yet, one at a time. The posts wait on the device for the next program + that reads it (``chat listen``, the menu). After that, ``chat history`` has them. - A room never says no: a wrong password gets no reply at all. So silence is a - failure here (exit 4), explained in the Rooms page's own words — how the login went - out, when the room was last heard, and whether this password has worked before — - and whatever password was remembered is kept. + A room never says no: a wrong password gets no reply. Thus no reply is a failure + here (exit 4). The error message uses the words of the Rooms page: how the login + went out, when the room was last heard, and if this password worked before. + MeshTerm keeps the remembered password, if there is one. """ from ..core.connection import DeviceCommandError from ..ui.rooms import silence_explanation, valid_password @@ -147,7 +149,7 @@ class RoomsTool(Tool): ) async def _cli_forget(self, ctx: AppContext, params: dict[str, Any]) -> ToolResult: - """Stop logging in to a room and forget its password; its stored posts are kept.""" + """Do not log in to a room again, and forget its password. Its stored posts stay.""" room = await self._room(ctx, str(params["room"])) was = ctx.rooms.joined(room) ctx.rooms.forget(room) @@ -199,7 +201,7 @@ class RoomsTool(Tool): def _peer(room: Contact) -> str: - """The room's key as its conversation stores it.""" + """The key prefix of the room, as its conversation stores it.""" return (room.key_prefix or room.public_key[:12] or "").lower() @@ -216,11 +218,11 @@ def _node(room: Contact) -> NodeRef: def _listing(records: list[dict]) -> Listing: - """``rooms list``: one room per record, joined ones first. + """``rooms list``: one room in each record, with the joined rooms first. - ``ACCESS`` is ``-`` for a room not joined (the document's ``joined`` says so outright); - ``HEARD`` is when the room was last heard on the air, the one column that says whether - a login has any chance of reaching it. + ``ACCESS`` is ``-`` for a room that is not joined (``joined`` in the document says this + directly). ``HEARD`` is the time when the room was last heard on the air. It is the + only column that shows if a login can possibly get to the room. """ from ..ui import fields from ..ui.report import Listing @@ -241,11 +243,11 @@ def _listing(records: list[dict]) -> Listing: def _joined(room: Contact, access: str, flood: bool | None) -> Facts: - """What ``rooms join`` won: the access a room granted, bare — the one fact asked for. + """What ``rooms join`` got: only the access that a room gave, the one fact asked for. - The room and how the login went out ride in the document; the plain face prints the - access word alone (``member``, ``admin`` or ``read-only``), which is what a script - deciding whether it may post branches on. + The room, and how the login went out, are in the document. The plain face prints only + the access word (``member``, ``admin``, or ``read-only``). A script uses this word to + decide if it can post. """ from ..ui import fields from ..ui.report import BARE, Facts @@ -268,7 +270,7 @@ def _joined(room: Contact, access: str, flood: bool | None) -> Facts: def _forgotten(room: Contact, was: bool) -> Facts: - """What ``rooms forget`` did: silent on the plain face, the room and the fact in JSON.""" + """What ``rooms forget`` did: nothing on the plain face, the room and the fact in JSON.""" from ..ui import fields from ..ui.report import SILENT, Facts diff --git a/meshterm/tools/timemachine.py b/meshterm/tools/timemachine.py index 05acd42..e1ddc37 100644 --- a/meshterm/tools/timemachine.py +++ b/meshterm/tools/timemachine.py @@ -1,14 +1,16 @@ # SPDX-License-Identifier: Apache-2.0 -"""The ``timemachine`` tool: explore everything the recorder ever heard. +"""The ``timemachine`` tool: explore all that the recorder ever heard. -Opens the Time Machine (see :mod:`meshterm.ui.timemachine_screen`): pick the whole mesh -or any node ever observed and read its history as braille charts — reception volume, -the median-SNR band, the hour-of-day rhythm, packets and nodes per day, first-ever -arrivals — over a switchable 24 h / 7 d / 30 d / all-time window. The passive monitor -has been writing this history since the first session; this is where it pays off. +The tool opens the Time Machine (refer to :mod:`meshterm.ui.timemachine_screen`). The +user selects the whole mesh, or any node that MeshTerm ever heard, and reads its history +as braille charts: the reception volume, the median-SNR band, the rhythm by hour of the +day, the packets and nodes for each day, and the first arrivals. The time window is 24 h, +7 d, 30 d, or all the time, and the user can change it. The passive monitor writes this +history, and it started in the first session. This tool is where that history becomes +useful. -Menu-only: the explorer is interactive by nature (subjects, windows, scrolling); the -``monitor`` and ``nodes`` subcommands remain the scripted views over the same data. +Menu only: the explorer is interactive (subjects, time windows, scroll). The ``monitor`` +and ``nodes`` subcommands stay the scripted listings of the same data. """ from __future__ import annotations @@ -23,24 +25,24 @@ from .base import Tool, ToolResult, register @register class TimeMachineTool(Tool): - """Read the mesh's recorded past: per-node timelines, daily volumes, arrivals.""" + """Read the stored history of the mesh: node timelines, daily volumes, arrivals.""" name = "timemachine" title = "Time machine" icon = "⏳" help = "Recorded history — timelines, rhythms, arrivals" category = "Watch" - order = 40 # the past tense of the Dashboard above it + order = 40 # the Dashboard above it, but for the past async def prompt_params(self, ctx: AppContext) -> dict[str, Any] | None: - """Run the explorer; there are never parameters to collect. + """Run the explorer. It has no parameters to collect. - The screen presents everything itself and returns when dismissed, so - returning ``None`` tells the menu the invocation is complete (the same + The screen shows all its content itself, and it returns when the user leaves it. + Thus the return value ``None`` tells the menu that the run is complete (the same pattern as the ``dashboard`` tool). Args: - ctx: Shared application context. + ctx: The shared application context. Returns: Always ``None``. @@ -51,20 +53,20 @@ class TimeMachineTool(Tool): return None async def run(self, ctx: AppContext, params: dict[str, Any]) -> ToolResult: - """Nothing runs here: the Time Machine lives inside :meth:`prompt_params`. + """Nothing runs here: the Time Machine is in :meth:`prompt_params`. Args: - ctx: Shared application context. - params: Unused. + ctx: The shared application context. + params: Not used. Returns: - An empty :class:`ToolResult` (only reachable from a scripted call). + An empty :class:`ToolResult` (only a scripted call comes here). """ return ToolResult(summary={}) def register_cli(self, app: typer.Typer) -> None: - """Register no CLI command — the Time Machine is an interactive explorer. + """Register no CLI command, because the Time Machine is an interactive explorer. Args: - app: The Typer application (untouched). + app: The Typer application (not changed). """ diff --git a/meshterm/tools/trace.py b/meshterm/tools/trace.py index 8e9c17b..17464fe 100644 --- a/meshterm/tools/trace.py +++ b/meshterm/tools/trace.py @@ -1,28 +1,28 @@ # SPDX-License-Identifier: Apache-2.0 -"""The trace tools: path traces, live in the menu, one-shot on the CLI. +"""The trace tools: path traces, live in the menu, and a single run on the CLI. -A trace is one walked path — the protocol has no destination field, so "target" is -purely a UX notion — and the menu splits the feature along exactly that line: +A trace is one walked path. The protocol has no destination field, so "target" is only +a UX concept. The menu divides the feature at exactly that line: -* **Trace target** (``trace``): *can I reach this node?* Pick a target from a - recency-ordered list; the live screen composes/explores symmetric routes that turn - at the target and come home over the mirrored hops. The list stays pushed underneath - for the whole visit, so Esc from a walk lands back on the row that launched it — - freshly re-sorted by what was just traced — and the next node is one Enter away. -* **Trace path** (``trace-path``): *how far can a route I build carry?* No target and - no picker — the whole walk is composed hop by hop and only has to end within our - own earshot. Traces record under the ``(path)`` sentinel, keeping composed walks - out of the target picker's history. +* **Trace target** (``trace``): *can I get to this node?* Select a target from a list in + the order of recency. The live screen composes and explores symmetric routes that turn + at the target and come back over the mirrored hops. The list stays pushed below for + the full visit. Thus Esc from a walk goes back to the row that started it (sorted + again by the last trace), and the next node is one Enter away. +* **Trace path** (``trace-path``): *how far can a route that I make go?* No target and + no picker. The user composes the full walk hop by hop, and it must only end at a node + that our node can hear. The traces are stored under the ``(path)`` sentinel, so the + composed walks stay out of the history of the target picker. -Both open the live trace screen (:mod:`meshterm.ui.trace_screen`) armed but idle: -nothing transmits until Trace is committed, which runs the chosen sample count -(1–8 traces, paced between transmissions — repeaters penalize, and can blacklist, -nodes that burst traffic, so multi-trace runs always sleep a cooldown between sends). -On the CLI each stays a scriptable one-shot: run one trace, print the route and -per-hop SNR, exit. +Both tools open the live trace screen (:mod:`meshterm.ui.trace_screen`) ready but idle. +Nothing transmits until the user starts Trace, which runs the selected sample count +(1–8 traces, with a pause between transmissions). Repeaters penalize, and can +blacklist, nodes that transmit in bursts. Thus a run of more than one trace always +waits a cooldown between sends. On the CLI, each tool stays a scriptable single run: +run one trace, print the route and the SNR of each hop, and exit. -Both front ends persist identically: one ``runs`` row per trace, recorded under it, so -stored history reads the same no matter where it came from. +The two front ends store the same data: one ``runs`` row for each trace, with the trace +stored under it. Thus the stored history is the same, wherever it came from. """ from __future__ import annotations @@ -48,47 +48,48 @@ from .base import Tool, ToolResult, register if TYPE_CHECKING: # pragma: no cover - typing only from ..ui.contactlist import ContactListScreen, ContactRow -#: The characters a stored trace target must consist of to be treated as a hex key -#: prefix when folding it back to a contact name in the target picker. +#: The characters that a stored trace target must contain, and only these, to be a hex key +#: prefix when the target picker folds it back to a contact name. _HEX_DIGITS = frozenset("0123456789abcdef") @register class TraceTool(Tool): - """Trace the path to a target and watch per-hop SNR, live or scripted.""" + """Trace the path to a target and watch the SNR of each hop, live or scripted.""" name = "trace" title = "Trace target" icon = "🎯" help = "Trace a target and watch per-hop SNR" category = "Explore" - order = 30 # see a node above, walk to it here + order = 30 # find a node with the tool above, and walk to it here async def prompt_params(self, ctx: AppContext) -> dict[str, Any] | None: - """Nothing to gather here — the target picker lives inside :meth:`run`. + """Nothing to collect here. The target picker is in :meth:`run`. - The pick and the screen it opens share the contacts read and the routing width, - and the live path skips the base class's run row (see :meth:`execute`), so the - whole entry flow sits in :meth:`_run_live` rather than half of it here. + The selection and the screen that it opens share the read of the contacts and the + routing width. Also, the live path does not use the run row of the base class + (refer to :meth:`execute`). Thus the full entry flow is in :meth:`_run_live`, and + not half of it here. Args: - ctx: Shared application context. + ctx: The shared application context. Returns: - ``{"live": True}`` — the menu's marker for the interactive path. + ``{"live": True}``: the marker of the menu for the interactive path. """ return {"live": True} async def execute(self, ctx: AppContext, params: dict[str, Any]) -> ToolResult: - """Run — without the outer run row on the live path. + """Run, with no outer run row on the live path. - The live screen opens one ``runs`` row *per trace* (matching what a scripted - invocation records), so wrapping the whole screen session in another row would - double-log it. Scripted runs keep the base class's logging. + The live screen opens one ``runs`` row *for each trace* (the same row that a + scripted run stores). If another row goes around the full screen session, the log + has each trace two times. Scripted runs keep the logging of the base class. Args: - ctx: Shared application context. - params: Parameters for this invocation. + ctx: The shared application context. + params: The parameters for this run. Returns: The :class:`ToolResult` from :meth:`run`. @@ -98,16 +99,16 @@ class TraceTool(Tool): return await super().execute(ctx, params) async def run(self, ctx: AppContext, params: dict[str, Any]) -> ToolResult: - """Open the live screen (menu) or run one persisted trace (CLI). + """Open the live screen (menu), or run one stored trace (CLI). Args: - ctx: Shared application context. - params: ``live`` from the menu (the target is picked on the screen); or - ``target`` (str), optional ``path``, and the injected ``_run_id`` - from the CLI. + ctx: The shared application context. + params: ``live`` from the menu (the user selects the target on the screen). + Or, from the CLI: ``target`` (str), the optional ``path``, and the + injected ``_run_id``. Returns: - A :class:`ToolResult` with the trace's outcome. + A :class:`ToolResult` with the result of the trace. """ if params.get("live"): return await self._run_live(ctx) @@ -116,26 +117,27 @@ class TraceTool(Tool): # -- interactive (menu) ------------------------------------------------------- async def _run_live(self, ctx: AppContext) -> ToolResult: - """Ask for the target in a popup, then run the live screen over the menu. + """Ask for the target in a dialog, then run the live screen over the menu. - The picker is a *question*, not a place: a floating list over the menu, gone the - moment a target is picked, so the trace screen opens straight over the menu and - Esc from it lands there. It used to stay pushed as a hub under the trace screen — - Esc out of a trace landed back on the list, which read as two places where the - trace is the whole visit; tracing another node is opening the tool again. + The picker is a *question*, not a place. It is a floating list over the menu, and + it closes immediately when the user selects a target. Thus the trace screen opens + directly over the menu, and Esc from it goes back there. Before, the picker stayed + pushed as a hub under the trace screen, and Esc from a trace went back to the + list. That looked like two places, but the trace is the full visit. To trace + another node, the user opens the tool again. Args: - ctx: Shared application context. + ctx: The shared application context. Returns: - A :class:`ToolResult` counting the screen opened and the traces run. + A :class:`ToolResult` that counts the opened screen and the traces that ran. """ from ..ui.trace_screen import open_trace from ..ui.tui.screen import CANCEL picker = await self._build_picker(ctx) if picker is None: - # Nothing to list (or no full-screen session): the target is typed instead. + # Nothing to list (or no full-screen session): the user types the target. target = await self._prompt_target(ctx) else: chosen = await ctx.ui.session.run_dialog(picker) @@ -145,39 +147,41 @@ class TraceTool(Tool): return ToolResult(summary={"sessions": 1, "traces": await open_trace(ctx, target)}) async def _prompt_target(self, ctx: AppContext) -> str | None: - """Ask for a target by hand — the way in when there is no list to pick from. + """Ask the user to type a target: the way in when there is no list to select from. - Reached with no known contacts at all (an empty list would be nothing to pick from) - and on any surface without a full-screen session. It is also the only way to trace a - bare key prefix for a node the device doesn't carry as a contact. A question like - the list it stands in for, so it floats over the menu rather than filling the frame. + MeshTerm comes here when there are no known contacts (an empty list gives nothing + to select), and on each surface that has no full-screen session. It is also the + only way to trace a bare key prefix of a node that the device does not have as a + contact. It is a question, the same as the list that it replaces. Thus it floats + over the menu, and does not fill the frame. Args: - ctx: Shared application context. + ctx: The shared application context. Returns: - The typed target, or ``None`` if it was left blank or cancelled. + The typed target, or ``None`` if the user left it blank or cancelled it. """ entered = await ctx.ui.text("Target node (name or key prefix):", floating=True) return entered.strip() if entered else None async def _build_picker(self, ctx: AppContext) -> ContactListScreen | None: - """Build the trace-target picker, or ``None`` when there is no list to draw. + """Make the trace target picker, or return ``None`` when there is no list to draw. - The same ``NAME · TRACED · HEARD · PKTS · KEY`` lanes, Ctrl+arrow sort ring, and - type-to-filter the Contacts screen and the courier recipient draw — but with every - node type listed (a trace answers *can I reach this node?* for a repeater or room - just as for a companion) and an extra ``TRACED`` lane: how long ago each node was - last traced. The list opens sorted by ``TRACED`` descending, so the most recently - traced node leads and never-traced ones gather at the bottom. Enter commits the - highlighted node as the target. + It has the same ``NAME · TRACED · HEARD · PKTS · KEY`` lanes, Ctrl+arrow sort ring, + and type-to-filter as the Contacts screen and the courier recipient. But it lists + all the node types (a trace answers *can I get to this node?* for a repeater or a + room, the same as for a companion). It also has one more lane, ``TRACED``: how + long ago each node was last traced. The list opens sorted by ``TRACED``, in + descending order. Thus the most recently traced node comes first, and the nodes + that were never traced are at the bottom. Enter commits the highlighted node as + the target. Args: - ctx: Shared application context. + ctx: The shared application context. Returns: - The picker, or ``None`` when there is nothing to list — see - :meth:`_prompt_target`. + The picker, or ``None`` when there is nothing to list (refer to + :meth:`_prompt_target`). """ from ..ui.contactlist import ( TRACE_LANES, @@ -188,9 +192,10 @@ class TraceTool(Tool): from ..ui.surface import TuiUi from ..ui.widgets import ContactsSort - # Through the session cache: this picker runs on every Trace open, and the contacts - # table is a slow round-trip on a busy node — re-reading it here (in front of the - # already-cached trace screen) is what kept opening Trace feeling like a stall. See + # Read through the session cache. This picker runs each time that Trace opens, and + # the contacts table is a slow round trip on a busy node. When MeshTerm read it + # again here (before the trace screen, which is already cached), Trace seemed to + # stop each time it opened. Refer to # :class:`~meshterm.services.device_state.DeviceState`. contacts = await ctx.devstate.contacts() if not contacts or not isinstance(ctx.ui, TuiUi): @@ -204,26 +209,27 @@ class TraceTool(Tool): footer_hint="↑↓ move · ^←→↑↓ sort · type to filter · Enter select · Esc back", lanes=TRACE_LANES, ) - # The contact list is a full-screen page everywhere else; here it is a question - # asked on the way in, so it floats over the menu like every other lead-in pick. + # In all other places, the contact list is a full-screen page. Here it is a + # question before the screen opens, so it floats over the menu, the same as each + # other selection before a tool. picker.floating = True return picker @staticmethod def _picker_rows(ctx: AppContext, contacts: list[Contact]) -> list[ContactRow]: - """The picker's lane data for ``contacts``, read fresh from stored history. + """The lane data of the picker for ``contacts``, read again from the stored history. - Both the ``TRACED`` ages and the packet counts come from the repository, so this is - cheap enough to redo every time a trace hands the picker back — which is what keeps - the lane the list is *sorted* by honest about the walk that just happened. + The ``TRACED`` ages and the packet counts both come from the repository. Thus it + costs little to do this again each time that a trace returns to the picker. That + keeps the lane by which the list is *sorted* correct for the last walk. Args: - ctx: Shared application context. - contacts: The device's contacts, as listed. + ctx: The shared application context. + contacts: The contacts of the device, as listed. Returns: - One :class:`~meshterm.ui.contactlist.ContactRow` per contact, in the order - given (the screen sorts them). + One :class:`~meshterm.ui.contactlist.ContactRow` for each contact, in the given + order (the screen sorts them). """ from ..ui.contactlist import ContactRow from ..ui.widgets import contact_packets @@ -246,18 +252,18 @@ class TraceTool(Tool): # -- scripted (CLI) ------------------------------------------------------------- async def _run_cli(self, ctx: AppContext, params: dict[str, Any]) -> ToolResult: - """Run one trace, persist it, and print the route and per-hop summary. + """Run one trace, store it, and print the route and the summary of each hop. - One transmission per invocation is a hard rule on the CLI — repeaters - penalize (and can blacklist) nodes that burst traffic — so scripted sampling - means invoking again (with your own pacing between runs). + On the CLI, one transmission for each run is a strict rule, because repeaters + penalize (and can blacklist) nodes that transmit in bursts. Thus, to take more + samples in a script, run the command again (with your own pause between runs). Args: - ctx: Shared application context. - params: ``target`` (str), optional ``path``, and the injected ``_run_id``. + ctx: The shared application context. + params: ``target`` (str), the optional ``path``, and the injected ``_run_id``. Returns: - A :class:`ToolResult` with the trace's outcome. + A :class:`ToolResult` with the result of the trace. """ return await _trace_once_cli( ctx, params["_run_id"], target=params["target"], path_spec=params.get("path") @@ -279,9 +285,10 @@ class TraceTool(Tool): path: str | None = typer.Option( None, "--path", - # No ``-p`` short form: ``-p`` is the global ``--profile``, and - # ``_globals_first`` lifts a group option ahead of the subcommand wherever it - # is typed — so a leaf ``-p`` could never reach this option, only shadow it. + # No ``-p`` short form. ``-p`` is the global ``--profile``, and + # ``_globals_first`` moves a group option in front of the subcommand, at any + # position where it is typed. Thus a leaf ``-p`` can never get to this option. + # It can only hide it. help="Force a route: comma-separated contact names/hex prefixes (e.g. 3d,f2,3d)", ), ) -> None: @@ -293,7 +300,7 @@ class TraceTool(Tool): @register class TracePathTool(Tool): - """Walk a hand-composed route — no target — and see how far it carries.""" + """Walk a route that you compose by hand (no target), and see how far it goes.""" name = "trace-path" title = "Trace path" @@ -303,22 +310,22 @@ class TracePathTool(Tool): order = 32 async def prompt_params(self, ctx: AppContext) -> dict[str, Any] | None: - """No parameters to gather — a path walk has no target to pick. + """No parameters to collect, because a path walk has no target to select. Args: - ctx: Shared application context. + ctx: The shared application context. Returns: - ``{"live": True}`` — the route itself is composed on the screen. + ``{"live": True}``. The user composes the route itself on the screen. """ return {"live": True} async def execute(self, ctx: AppContext, params: dict[str, Any]) -> ToolResult: - """Run — without the outer run row on the live path (see :class:`TraceTool`). + """Run, with no outer run row on the live path (refer to :class:`TraceTool`). Args: - ctx: Shared application context. - params: Parameters for this invocation. + ctx: The shared application context. + params: The parameters for this run. Returns: The :class:`ToolResult` from :meth:`run`. @@ -328,15 +335,15 @@ class TracePathTool(Tool): return await super().execute(ctx, params) async def run(self, ctx: AppContext, params: dict[str, Any]) -> ToolResult: - """Open the live path-walk screen (menu) or run one persisted trace (CLI). + """Open the live path walk screen (menu), or run one stored trace (CLI). Args: - ctx: Shared application context. - params: ``live`` from the menu; or ``path`` (str, required) and the - injected ``_run_id`` from the CLI. + ctx: The shared application context. + params: ``live`` from the menu. Or, from the CLI: ``path`` (str, necessary) + and the injected ``_run_id``. Returns: - A :class:`ToolResult` with the walk's outcome. + A :class:`ToolResult` with the result of the walk. """ if params.get("live"): from ..ui.trace_screen import open_trace_path @@ -363,9 +370,10 @@ class TracePathTool(Tool): path: str = typer.Option( ..., "--path", - # No ``-p`` short form: ``-p`` is the global ``--profile``, and - # ``_globals_first`` lifts a group option ahead of the subcommand wherever it - # is typed — so a leaf ``-p`` could never reach this option, only shadow it. + # No ``-p`` short form. ``-p`` is the global ``--profile``, and + # ``_globals_first`` moves a group option in front of the subcommand, at any + # position where it is typed. Thus a leaf ``-p`` can never get to this option. + # It can only hide it. help="The whole walk: comma-separated contact names/hex prefixes " "(must end within earshot of this node)", ), @@ -376,42 +384,45 @@ class TracePathTool(Tool): async def _trace_once_cli( ctx: AppContext, run_id: int, *, target: str, path_spec: str | None ) -> ToolResult: - """Run one persisted trace and print the route and per-hop summary (CLI body). + """Run one stored trace, and print the route and the summary of each hop (CLI body). - Shared by both scripted trace commands: ``trace`` passes its target (path - optional — the device routes without one), ``trace-path`` passes the - :data:`~meshterm.core.models.PATH_TRACE_TARGET` sentinel with a required path. + The two scripted trace commands share this function. ``trace`` gives its target (the + path is optional, because the device can route without one). ``trace-path`` gives the + :data:`~meshterm.core.models.PATH_TRACE_TARGET` sentinel and a necessary path. Args: - ctx: Shared application context. - run_id: The already-open run row to record under. - target: The label the trace persists under. - path_spec: The forced route as typed (names/hex, comma-separated), if any. + ctx: The shared application context. + run_id: The run row, already open, under which to store the trace. + target: The label under which the trace is stored. + path_spec: The forced route as typed (names or hex, with commas between them), if + there is one. Returns: - A :class:`ToolResult` with the trace's outcome. + A :class:`ToolResult` with the result of the trace. """ from ..ui.surface import TuiUi is_walk = target == PATH_TRACE_TARGET device = await ctx.device() - # Our own device's name labels both endpoints of the path (first hop's origin, - # last hop's destination); fall back to a neutral label if it's unavailable. + # The name of our device is the label of the two ends of the path (the origin of the + # first hop, and the destination of the last hop). If the name is not available, use a + # neutral label. self_info = await device.get_self_info() device_label = str(self_info.get("name") or LOCAL_DEVICE_LABEL) - # Our own public key, so the route's endpoints (us) carry a hash like every - # other hop, addressed at the same path-hash width. + # Our own public key. Thus the ends of the route (our node) have a hash, the same as + # each other hop, at the same path hash width. device_hash = str(self_info.get("public_key") or "") or None - # Resolve repeater hashes in the results to contact names where we know them, - # so the tables read as names instead of opaque hex prefixes. + # Resolve the repeater hashes in the results to contact names, when we know them. Thus + # the tables show names, not hex prefixes that tell nothing. contacts = await device.get_contacts() resolve = trace_runner.make_node_resolver(contacts) - # Resolve an optional forced path (names/hex) to the hex string the radio wants. - # Leaving it blank is fully supported for a *target* trace: the device reuses the - # route it already learned (or floods if it has none). A path walk always has one. + # Resolve an optional forced path (names or hex) to the hex string that the radio + # accepts. A blank path is fully supported for a *target* trace: the device uses again + # the route that it already learned (or floods if it has no route). A path walk always + # has a path. path: str | None = None if path_spec: path = trace_runner.parse_trace_path(path_spec, contacts) @@ -424,8 +435,8 @@ async def _trace_once_cli( stats = TraceStats.from_traces(target, [result]) if isinstance(ctx.ui, TuiUi): - # The stats panel renders route + per-hop readings for the single trace (its - # medians collapse to the readings themselves). + # The stats panel renders the route and the readings of each hop for the single + # trace (its medians are the same as the readings themselves). ctx.ui.show( stats_panel( stats, @@ -459,9 +470,9 @@ async def _trace_once_cli( message = f"[ok]✓[/ok] traced [brand]{target}[/brand]{via}" else: message = f"[err]✗[/err] no reply from [brand]{target}[/brand]{via}" - # A trace that never came home is not a failure of the command — the radio did - # transmit and the walk did run. It is a walk with nothing to report, which is what - # NO_RESULT says, and it is the answer a script most often branches on. + # A trace that never came back is not a failure of the command: the radio transmitted, + # and the walk ran. It is a walk with nothing to report, which is what NO_RESULT says. + # It is also the answer on which a script most often branches. return ToolResult( summary=summary, message=message, @@ -478,30 +489,32 @@ def _trace_report( resolve: Any, device_hash: str | None, ) -> tuple: - """State one trace: the walk's outcome, then its per-hop readings. + """State one trace: the result of the walk, then the readings of each hop. - Two blocks. The first is what the walk *did* — one fact per line, ``route`` among them - as a drawn line, every node named and carrying the hash it was addressed by. The - second is a record per hop, and it names its two ends by that same **hash** rather than - repeating the names: the route line above is where the names are, and the hash is what - joins the two blocks (it is what carries a node's identity here, the way its colour - does on a screen). The document embeds the whole node at both ends instead, because a - structural join needs no key and each edge should be readable on its own. + Two blocks. The first block is what the walk *did*: one fact on each line. ``route`` + is one of these facts, as a drawn line, and each node in it has a name and the hash by + which it was addressed. The second block has a record for each hop. It names the two + ends of a hop by that same **hash**, and does not repeat the names. The names are in + the route line above, and the hash joins the two blocks (here, the hash shows the + identity of a node, as its colour does on a screen). The document puts the full node + at the two ends instead, because a structural join does not use a key, and each edge + must be readable alone. - Our own node is a hop like any other, named and hashed. The menu draws it as ``★`` - because a reader never has to be told which node is theirs; this line is as often read - out of a file by somebody who was not at the prompt when it ran. + Our node is a hop like any other, with a name and a hash. The menu draws it as ``★``, + because the user never has to be told which node is theirs. But this line is often + read from a file by a person who was not at the prompt when it ran. Args: result: The trace that ran. - target: The label it was addressed to. + target: The label to which it was addressed. path: The forced route as hex, or ``None`` when the device routed it. - device_label: Our own node's name, at both ends of the walk. - resolve: Maps a hop hash to a friendly name when known. - device_hash: Our own public key, so our ends carry a hash like every other hop. + device_label: The name of our node, at the two ends of the walk. + resolve: Maps a hop hash to a friendly name, when the name is known. + device_hash: Our own public key, so that our ends have a hash, the same as each + other hop. Returns: - The report's blocks. + The blocks of the report. """ from ..ui import fields from ..ui.fields import NodeRef @@ -510,14 +523,14 @@ def _trace_report( hash_bytes = result.path_hash_bytes def short(value: str | None) -> str | None: - """A hash at the width this trace addressed nodes by.""" + """A hash, at the width with which this trace addressed the nodes.""" if not value: return None raw = value.lower().removeprefix("0x") return raw[: hash_bytes * 2] if hash_bytes else raw def node(label: str) -> NodeRef: - """One end of a hop as the shared node shape.""" + """One end of a hop, in the shared node shape.""" if not label or label == device_label: return NodeRef(name=device_label, hash=short(device_hash), is_self=True) return NodeRef(name=resolve(label) or None, hash=short(label)) @@ -536,11 +549,11 @@ def _trace_report( fields.integer("hops", "hops"), fields.snr("min_snr_db", "min_snr_db"), fields.decimal("rtt_ms", "rtt_ms", ".0f"), - # New surface on the machine face: the model has always carried the TX power - # the walk ran at, and the plain facts block has no room for it. + # A new field on the machine face. The model always had the TX power at which + # the walk ran, and the plain facts block has no space for it. fields.hidden("tx_dbm"), - # What `hash` means on this walk's nodes, so a consumer can join two traces - # that addressed the same node at different widths. + # What `hash` means on the nodes of this walk. Thus a consumer can join two + # traces that addressed the same node at different widths. fields.hidden("hash_bytes"), fields.route("route", "route"), ), @@ -580,22 +593,23 @@ def _trace_report( def _last_traced_by_name( contacts: list[Contact], traced: dict[str, datetime] ) -> dict[str, datetime]: - """Map each contact's name to when that node was last traced. + """Map the name of each contact to the time when that node was last traced. - The Trace picker's ``TRACED`` lane and default sort read this. Stored trace targets are - filed exactly as the user addressed them — a contact name one day, a raw hex key prefix - another — so each target is folded onto the contact it names (by name, case-insensitively, - or as a prefix of a contact's public key) and the *latest* trace time wins, so a node - traced under both spellings still shows one honest "last traced" age. This is the inverse - of the picker's old recent-targets fold, kept per-contact rather than as a name list. + The ``TRACED`` lane and the default sort of the Trace picker read this map. The stored + trace targets are filed exactly as the user addressed them: a contact name one day, a + raw hex key prefix on another day. Thus each target is folded onto the contact that it + names (by name, case-insensitive, or as a prefix of the public key of a contact). The + *latest* trace time wins. Thus a node that was traced under the two spellings still + shows one correct "last traced" age. This is the inverse of the old fold of recent + targets in the picker, kept for each contact, not as a list of names. Args: - contacts: The device's current contacts. + contacts: The current contacts of the device. traced: ``target → last-traced time`` from :meth:`~meshterm.persistence.repository.Repository.target_last_traced`. Returns: - ``contact name → last-traced time`` for every contact the history can place. + ``contact name → last-traced time`` for each contact that the history can find. """ by_fold = {c.name.casefold(): c.name for c in contacts} out: dict[str, datetime] = {} @@ -611,8 +625,8 @@ def _last_traced_by_name( note(named, when) continue needle = target.lower().removeprefix("0x") - # Only fold plausible key prefixes (≥2 bytes of hex) — a short hex-looking *name* - # like "ace" must not be mistaken for an address. + # Fold only possible key prefixes (≥2 bytes of hex). A short *name* that looks like + # hex, such as "ace", must not be mistaken for an address. if len(needle) >= 4 and all(ch in _HEX_DIGITS for ch in needle): for contact in contacts: if (contact.public_key or "").lower().startswith(needle): diff --git a/meshterm/tools/tx_optimize.py b/meshterm/tools/tx_optimize.py index 2eea79a..8abf91f 100644 --- a/meshterm/tools/tx_optimize.py +++ b/meshterm/tools/tx_optimize.py @@ -1,19 +1,25 @@ # SPDX-License-Identifier: Apache-2.0 -"""The ``tx-optimize`` tool: tune a remote node's TX power for the best signal at a target. +"""The ``tx-optimize`` tool: tune the TX power of a remote node for the best signal at a target. -You force a path (just like ``trace``) ending at the **target** node where SNR is -measured. The node one hop *before* the target — one you hold admin rights on — is the -node whose transmit power gets swept and tuned. Admin passwords are remembered between -runs. +You force a path (the same as for ``trace``) that ends at the **target** node, where +MeshTerm measures the SNR. The node one hop *before* the target is the node whose transmit +power MeshTerm sweeps and tunes. You must have admin rights on that node. MeshTerm keeps +the admin passwords from one run to the next. -In the interactive menu one two-step dialog chooses the link — the node to tune -(repeaters you hold credentials for lead the list), then the target whose reception is -optimized — and the live sweep screen (:mod:`meshterm.ui.tx_screen`) takes it from -there, armed but idle: route, range, step, and samples are adjusted in place, nothing -transmits until Sweep is committed, levels land in a bar chart as they are measured, and -the apply decision is made *after* the sweep, over the evidence. On the CLI it stays a -scriptable one-shot with the full flag set (``--path``, range, step, samples, -``--apply``), and progress streams like a trace. +In the interactive menu, one dialog with two steps selects the link. First, it selects +the node to tune (the repeaters for which you have credentials come first in the list). +Then it selects the target whose reception MeshTerm optimizes. Then the live sweep screen +(:mod:`meshterm.ui.tx_screen`) continues. It is ready, but it does nothing yet: + +- You adjust the route, the range, the step, and the samples on the screen. +- Nothing transmits until you start Sweep. +- The levels go into a bar chart as MeshTerm measures them. +- You decide whether to apply the result *after* the sweep, when you can see the + evidence. + +On the CLI, the tool stays a scriptable single run with the full set of flags +(``--path``, range, step, samples, ``--apply``), and it streams its progress as a trace +does. """ from __future__ import annotations @@ -30,47 +36,48 @@ from ..services import trace_runner, tx_optimizer from ..ui.widgets import tx_opt_summary, tx_opt_table from .base import Tool, ToolResult, register -#: Trace count per TX level — kept to single digits so the radio's duty cycle stays sane -#: and the per-level sweep finishes in reasonable time. +#: The number of traces for each TX level. It stays below 10, so that the duty cycle of the +#: radio stays in safe limits and the sweep of each level ends in a reasonable time. MAX_SAMPLES = 9 @register class TxOptimizeTool(Tool): - """Tune a remote node's TX power for the strongest, most reliable signal at a target.""" + """Tune the TX power of a remote node for the strongest, most reliable signal at a target.""" name = "tx-optimize" title = "TX optimize" icon = "📶" help = "Tune a remote node's TX power for a target" category = "Other nodes" - order = 20 # like Repeater admin: a remote radio, changed over the mesh + order = 20 # the same as Repeater admin: a remote radio, changed over the mesh async def prompt_params(self, ctx: AppContext) -> dict[str, Any] | None: - """Nothing to gather here — the link is picked inside :meth:`run`. + """Nothing to collect here. The user selects the link in :meth:`run`. - The two picks are one stepped dialog, and the sweep screen opens the moment it - closes; keeping them together in :meth:`_run_live` keeps the contacts read (the one - slow thing on the way in) shared between the dialog's rows and the sweep's resolver. + The two selections are one dialog with steps, and the sweep screen opens + immediately when that dialog closes. :meth:`_run_live` keeps them together. Thus the + dialog rows and the resolver of the sweep share one read of the contacts (the only + slow step before the screen opens). Args: - ctx: Shared application context. + ctx: The shared application context. Returns: - ``{"live": True}`` — the menu's marker for the interactive path. + ``{"live": True}``: the marker of the menu for the interactive path. """ return {"live": True} async def execute(self, ctx: AppContext, params: dict[str, Any]) -> ToolResult: - """Run — without the outer run row on the live path. + """Run, with no outer run row on the live path. - The live screen opens its own ``runs`` row for the sweep (matching what a - scripted invocation records), so wrapping the screen session in another row - would double-log it. Scripted runs keep the base class's logging. + The live screen opens its own ``runs`` row for the sweep (the same row that a + scripted run stores). If another row goes around the screen session, the log has + the sweep two times. Scripted runs keep the logging of the base class. Args: - ctx: Shared application context. - params: Parameters for this invocation. + ctx: The shared application context. + params: The parameters for this run. Returns: The :class:`ToolResult` from :meth:`run`. @@ -80,16 +87,17 @@ class TxOptimizeTool(Tool): return await super().execute(ctx, params) async def run(self, ctx: AppContext, params: dict[str, Any]) -> ToolResult: - """Open the live sweep (menu) or run the scripted optimization (CLI). + """Open the live sweep (menu), or run the scripted optimization (CLI). Args: - ctx: Shared application context. - params: ``live`` from the menu (both nodes are picked in one dialog); or ``path``, - ``samples``, ``tx_min``, ``tx_max``, ``step``, ``apply``, optional - ``password``/``viz``, and the injected ``_run_id`` from the CLI. + ctx: The shared application context. + params: ``live`` from the menu (the user selects the two nodes in one dialog). + Or, from the CLI: ``path``, ``samples``, ``tx_min``, ``tx_max``, ``step``, + ``apply``, the optional ``password`` and ``viz``, and the injected + ``_run_id``. Returns: - A :class:`ToolResult` with the optimum and any chart path. + A :class:`ToolResult` with the optimum and the chart path, if there is one. """ if params.get("live"): return await self._run_live(ctx) @@ -98,36 +106,38 @@ class TxOptimizeTool(Tool): # -- interactive (menu) --------------------------------------------------------- async def _run_live(self, ctx: AppContext) -> ToolResult: - """Pick the link in one stepped dialog, then run the sweep screen over the menu. + """Select the link in one dialog with steps, then run the sweep screen over the menu. - The two picks — the node to tune, then the node to measure at — are one floating - list that turns its page (:func:`~meshterm.ui.menus.run_wizard`): Esc on the - second step turns back to the first with the picked node still highlighted, Esc - on the first leaves. The dialog is gone before the sweep screen opens, so Esc from - the sweep lands on the main menu: the link was a question on the way in, not a - place to come back to. It used to be two pickers, each kept pushed under the - sweep as a hub — three frames deep for a sweep, and two popups stacked on the way - in, which read as two places rather than one question in two parts. + The two selections (first the node to tune, then the node at which to measure) are + one floating list that turns its page (:func:`~meshterm.ui.menus.run_wizard`). + Esc on the second step turns back to the first step, and the selected node stays + highlighted. Esc on the first step leaves. The dialog closes before the sweep screen + opens, so Esc from the sweep goes to the main menu. The link was a question before + the screen, not a place to come back to. Before, there were two pickers, and each + stayed pushed under the sweep as a hub. That put the sweep three frames deep, and + put two dialogs on top of each other before it. They looked like two places, not + one question in two parts. - No login here: the screen logs in inside the first Sweep commit, so backing - out of an idle screen never touched the radio beyond the contact reads. + There is no login here. The screen logs in when the user starts the first Sweep. + Thus, if the user leaves an idle screen, MeshTerm did nothing with the radio but + read the contacts. Args: - ctx: Shared application context. + ctx: The shared application context. Returns: - A :class:`ToolResult` echoing the sweep's recorded summary. + A :class:`ToolResult` that repeats the stored summary of the sweep. """ from ..ui.admin_picker import admin_picker_rows from ..ui.menus import WizardPage, run_wizard from ..ui.surface import TuiUi from ..ui.tx_screen import open_tx_optimize - if not isinstance(ctx.ui, TuiUi): # pragma: no cover - guarded by the menu-only caller + if not isinstance(ctx.ui, TuiUi): # pragma: no cover - only the menu calls this raise RuntimeError("the live TX sweep is only available in the menu") - # Through the session cache: this entry flow runs on every open, and the contacts - # table is a slow read on a busy node (see + # Read through the session cache. This entry flow runs each time the tool opens, and + # the contacts table is a slow read on a busy node (refer to # :class:`~meshterm.services.device_state.DeviceState`). contacts = await ctx.devstate.contacts() items, candidates = admin_picker_rows(ctx, contacts) @@ -151,8 +161,8 @@ class TxOptimizeTool(Tool): admin = admin_of(values) targets = _target_items(contacts, admin) if not targets: - # The tuned node is the only contact there is: a typed hex key prefix is the - # only way to name the target, floated over the dialog's first page. + # The tuned node is the only contact. Thus a typed hex key prefix is the only + # way to name the target. Its prompt floats over the first page of the dialog. return ctx.ui.session.text( "TX optimize — measure at · step 2 of 2", prompt=f"Hex key prefix of the node that hears {admin.name}:", @@ -167,7 +177,7 @@ class TxOptimizeTool(Tool): ) answers = await run_wizard(ctx.ui.session, [node_page, target_page]) - if answers is None: # Esc on the first step — out to the menu + if answers is None: # Esc on the first step: back to the menu return ToolResult(summary={}) admin_node = admin_of(answers) target = str(answers[1]).strip() @@ -180,7 +190,7 @@ class TxOptimizeTool(Tool): target_hash = target_contact.public_key or target_contact.key_prefix else: target_label = target - target_hash = target # a typed hex prefix stands for itself + target_hash = target # a typed hex prefix is its own hash summary = await open_tx_optimize( ctx, @@ -191,17 +201,19 @@ class TxOptimizeTool(Tool): return ToolResult(summary=summary) async def _login(self, ctx: AppContext, admin_node: Contact, params: dict[str, Any]) -> None: - """Authenticate against the admin node, remembering a working password. + """Log in to the admin node, and keep a password that works. Args: - ctx: Shared application context. - admin_node: The node we're about to tune. - params: Tool params (may carry an explicit ``password`` on the CLI). + ctx: The shared application context. + admin_node: The node that we will tune. + params: The tool parameters (on the CLI, they can hold an explicit + ``password``). Raises: - DeviceCommandError: If the node rejected the login (the stored password, now - known bad, is forgotten so the next run asks fresh) — or if it never - answered, in which case the password is untested and is kept. + DeviceCommandError: If the node refused the login. MeshTerm then forgets the + stored password, because it is known to be bad, and the next run asks + again. Also if the node never answered. Then the password is not tested, + and MeshTerm keeps it. """ device = await ctx.device() password = await self._resolve_password(ctx, admin_node, params) @@ -221,15 +233,15 @@ class TxOptimizeTool(Tool): # -- scripted (CLI) --------------------------------------------------------------- async def _run_cli(self, ctx: AppContext, params: dict[str, Any]) -> ToolResult: - """Resolve the link, log in, sweep TX power, render results, and apply the winner. + """Resolve the link, log in, sweep the TX power, render the results, and apply the best. Args: - ctx: Shared application context. - params: ``path``, ``samples``, ``tx_min``, ``tx_max``, ``step``, ``apply``, - optional ``password``/``viz``, and the injected ``_run_id``. + ctx: The shared application context. + params: ``path``, ``samples``, ``tx_min``, ``tx_max``, ``step``, ``apply``, the + optional ``password`` and ``viz``, and the injected ``_run_id``. Returns: - A :class:`ToolResult` with the optimum and any chart path. + A :class:`ToolResult` with the optimum and the chart path, if there is one. """ from ..ui.surface import TuiUi @@ -237,8 +249,8 @@ class TxOptimizeTool(Tool): device = await ctx.device() contacts = await device.get_contacts() - # Resolve the forced path to hashes, then pull out the target (last hop) and the - # admin node we tune (the hop before it). + # Resolve the forced path to hashes. Then get the target (the last hop) and the admin + # node that we tune (the hop before the target). path = trace_runner.parse_trace_path(params["path"], contacts) admin_node, target_label = _resolve_link(path, contacts) @@ -286,8 +298,9 @@ class TxOptimizeTool(Tool): persist_trace=lambda t: ctx.repo.record_trace(run_id, t), ) - # No trace got through at any TX level: nothing was tuned, the node was left at - # its original power. Usually a wrong/unreachable path rather than a weak link. + # No trace got through at any TX level. Thus nothing was tuned, and the node stays + # at its original power. Usually the cause is a path that is wrong or that cannot be + # reached, not a weak link. no_result = result.best_snr is None if result.applied: ctx.log.info("set TX power %s on %s", result.best_tx, admin_node.name) @@ -316,8 +329,8 @@ class TxOptimizeTool(Tool): return ToolResult( report=report, - # No level got a trace through, so nothing was measured and nothing was tuned: - # the sweep ran and has nothing to report. + # No level got a trace through. Thus nothing was measured and nothing was tuned. + # The sweep ran and has nothing to report. exit_code=exitcodes.NO_RESULT if no_result else exitcodes.OK, summary={ "target": result.target, @@ -336,27 +349,28 @@ class TxOptimizeTool(Tool): async def _resolve_password( self, ctx: AppContext, admin_node: Contact, params: dict[str, Any] ) -> str: - """Find the admin password: explicit flag, remembered, or an interactive prompt. + """Find the admin password: from the flag, from the store, or from a prompt. - The question this asks is **"is anyone there to answer?"**, and it used to ask - ``--json`` instead — a flag about what the output looks like, which cannot answer - it and answered it wrong in both directions: with the flag a piped run failed - cleanly, and without it a scheduled run on a terminal sat waiting for a password - nobody was going to type. ``ctx.interactive`` reads stdin, which is where the - answer actually is. + The question that this method asks is **"is a person there to answer?"**. Before, + it asked ``--json`` instead. That flag is about the look of the output, so it + cannot answer the question, and its answer was wrong in both directions. With the + flag, a piped run failed cleanly. Without it, a scheduled run on a terminal waited + for a password, but no person was there to type it. ``ctx.interactive`` reads stdin, + which is where the answer is. Args: - ctx: Shared application context. - admin_node: The node we're about to log in to. - params: Tool params (may carry an explicit ``password``). + ctx: The shared application context. + admin_node: The node that we will log in to. + params: The tool parameters (they can hold an explicit ``password``). Returns: - The password to log in with. + The password for the login. Raises: - typer.BadParameter: If no password is available and nobody can be asked for - one. A usage error rather than a device failure: nothing was transmitted, - and no retry helps until the command line carries the password. + typer.BadParameter: If no password is available and MeshTerm cannot ask + anyone for one. This is a usage error, not a device failure: nothing was + transmitted, and a retry cannot help until the command line has the + password. """ password = params.get("password") or ctx.admin_store.get(admin_node) if password: @@ -366,8 +380,8 @@ class TxOptimizeTool(Tool): f"no admin password for {admin_node.name!r}; pass --password or run once " "interactively to store it." ) - # This resolver only runs on the scripted CLI path (the menu logs in inside the pushed - # sweep screen), so the surface here is PlainUi — no screen stack, no floating. + # This resolver runs only on the scripted CLI path (the menu logs in from the pushed + # sweep screen). Thus the surface here is PlainUi: no screen stack, no floating. entered = await ctx.ui.text(f"Admin password for {admin_node.name}:", password=True) if not entered: raise typer.BadParameter("an admin password is required to tune a remote node.") @@ -386,9 +400,10 @@ class TxOptimizeTool(Tool): path: str = typer.Option( ..., "--path", - # No ``-p`` short form: ``-p`` is the global ``--profile``, and - # ``_globals_first`` lifts a group option ahead of the subcommand wherever it - # is typed — so a leaf ``-p`` could never reach this option, only shadow it. + # No ``-p`` short form. ``-p`` is the global ``--profile``, and + # ``_globals_first`` moves a group option in front of the subcommand, at any + # position where it is typed. Thus a leaf ``-p`` can never get to this option. + # It can only hide it. help="Forced path ending at the target (e.g. 'Repeater,Target' or '3d,f2')", ), samples: int = typer.Option(3, "--samples", "-n", help="Traces per TX level"), @@ -416,23 +431,24 @@ class TxOptimizeTool(Tool): def _resolve_link(path: str, contacts: list[Contact]) -> tuple[Contact, str]: - """Split a forced path into the admin node we tune and the target's display label. + """Divide a forced path into the admin node that we tune and the label of the target. Args: - path: The comma-separated hash path (output of ``parse_trace_path``). - contacts: Known contacts, used to map hashes back to names/keys. + path: The hash path, with commas between the hops (the output of + ``parse_trace_path``). + contacts: The known contacts. They change hashes back into names and keys. Returns: - ``(admin_node, target_label)`` — the second-to-last hop as a full - :class:`Contact` (needed for login), and a friendly name for the last hop. + ``(admin_node, target_label)``: the second-to-last hop as a full :class:`Contact` + (it is necessary for the login), and a friendly name for the last hop. Raises: - typer.BadParameter: If the path has fewer than two hops — the argument is what is - wrong and nothing was transmitted, so that is a usage error (exit 2), not a - device failure. - DeviceCommandError: If the admin hop can't be matched to a known contact carrying a - public key. That one *is* about the mesh: the path is well formed and we simply - have not heard from the node it names. + typer.BadParameter: If the path has fewer than two hops. The argument is wrong and + nothing was transmitted. Thus that is a usage error (exit 2), not a device + failure. + DeviceCommandError: If no known contact with a public key matches the admin hop. + That error *is* about the mesh: the path is correct, but we have not heard + from the node that it names. """ hops = [h for h in path.split(",") if h] if len(hops) < 2: @@ -451,14 +467,14 @@ def _resolve_link(path: str, contacts: list[Contact]) -> tuple[Contact, str]: def _contact_for_hash(hash_hex: str, contacts: list[Contact]) -> Contact | None: - """Return the contact whose key matches a path-hop hash, if any. + """Return the contact whose key matches the hash of a path hop, if there is one. Args: - hash_hex: A path hop hash (a leading slice of the node's public key). - contacts: Known contacts to match against. + hash_hex: The hash of a path hop (the first part of the public key of the node). + contacts: The known contacts to compare with. Returns: - The matching :class:`Contact`, or ``None``. + The :class:`Contact` that matches, or ``None``. """ needle = hash_hex.lower().removeprefix("0x") for c in contacts: @@ -472,18 +488,20 @@ def _contact_for_hash(hash_hex: str, contacts: list[Contact]) -> Contact | None: def _target_items(contacts: list[Contact], admin: Contact) -> list: - """The *measure at* list's rows, ordered by how recently each node was heard. + """The rows of the *measure at* list, in the order of how recently each node was heard. - Rows carry the contact's **name** as their value, since a typed hex prefix stands in the - same place (see :meth:`TxOptimizeTool._run_live`). Empty when the tuned node is the only - contact there is — the caller falls back to a typed prefix. + The value of each row is the **name** of the contact, because a typed hex prefix can + go in the same place (refer to :meth:`TxOptimizeTool._run_live`). The list is empty + when the tuned node is the only contact. Then the caller asks for a typed prefix. Args: - contacts: The device's known contacts. - admin: The already-picked tuned node (excluded — it can't measure itself). + contacts: The known contacts of the device. + admin: The tuned node, which the user already selected. It is not in the list, + because it cannot measure itself. Returns: - One :class:`~meshterm.ui.tui.select.Choice` per other contact, freshest first. + One :class:`~meshterm.ui.tui.select.Choice` for each other contact, the most + recently heard first. """ from rich.text import Text @@ -492,9 +510,10 @@ def _target_items(contacts: list[Contact], admin: Contact) -> list: from ..ui.widgets import DEFAULT_GLYPH, NODE_GLYPHS def row(contact: Contact) -> Any: - # The type mark keeps its own fixed hue; the *name* takes the node's key-derived - # colour like every other list of nodes (a style on the Text itself would be the - # row's base and would paint the name the type's colour too). + # The type mark keeps its own fixed hue. The *name* gets the hue of the node, which + # comes from its key, the same as in each other list of nodes. (A style on the + # Text itself becomes the base of the row, and then the name also gets the colour + # of the type.) glyph, glyph_style = NODE_GLYPHS.get(contact.node_type, DEFAULT_GLYPH) label = Text() label.append(f"{glyph} ", style=glyph_style) @@ -517,10 +536,10 @@ def _fmt_snr(snr: float | None) -> str: """Format an optional SNR for the progress description. Args: - snr: SNR in dB, or ``None``. + snr: The SNR in dB, or ``None``. Returns: - A short fixed-width string like ``+5.1`` or `` n/a``. + A short string with a fixed width, for example ``+5.1`` or `` n/a``. """ return f"{snr:+.1f}" if snr is not None else " n/a" @@ -528,33 +547,33 @@ def _fmt_snr(snr: float | None) -> str: def _sweep_report( result: TxOptResult, path: str, admin_node: Contact, contacts: list[Contact] ) -> tuple: - """State a TX sweep: the outcome, then every level measured. + """State a TX sweep: the result, then each measured level. - The winner comes first, because it is what the command was asked for and what a caller - acts on; the per-level records follow, so the choice can be checked against the - measurements it was made from. The menu's ``★`` on the winning row has no column here - — ``optimal_tx_dbm`` above the table already names it, and a mark is something to look - at rather than something to test. + The best level comes first, because the command was asked for it, and a caller acts + on it. The records of each level come after it, so that a person can compare the + choice with the measurements that it came from. The ``★`` that the menu puts on the + best row has no column here. ``optimal_tx_dbm`` above the table already names that + level, and a mark is a thing to look at, not a thing to test. - The two nodes become the shared node shape, and here that matters more than anywhere - else: on the plain line they are told apart by nothing but their names, and a caller - correlating a sweep with a trace has no key to join on. + The two nodes use the shared node shape. Here that is more important than in other + places. On the plain line, only their names tell them apart. Without the shape, a + caller who compares a sweep with a trace has no key to join them on. Args: result: The completed sweep. - path: The forced route the traces walked, as hex hops. + path: The forced route that the traces went through, as hex hops. admin_node: The node whose TX power was tuned. - contacts: The contact list, for placing the target by name. + contacts: The contact list, to find the target by its name. Returns: - The report's blocks. + The blocks of the report. """ from ..ui import fields from ..ui.fields import NodeRef from ..ui.report import Facts, Listing def node(name: str) -> NodeRef | None: - """One end of the tuned link as the shared node shape.""" + """One end of the tuned link, in the shared node shape.""" contact = next((c for c in contacts if c.name == name), None) if contact is None: return NodeRef(name=name) if name else None @@ -583,8 +602,8 @@ def _sweep_report( "path": path, "optimal_tx_dbm": result.best_tx, "target_snr_db": result.best_snr, - # A fraction in [0, 1], not a formatted "1.00": the plain column rounds for - # the eye and the document keeps the number a number. + # A fraction in [0, 1], not a formatted "1.00". The plain column rounds it so + # that it is easy to read, and the document keeps the number as a number. "reliability": result.best_success_rate, "previous_tx_dbm": result.original_tx, "applied": result.applied, diff --git a/meshterm/tools/walk.py b/meshterm/tools/walk.py index db67c60..e5e7944 100644 --- a/meshterm/tools/walk.py +++ b/meshterm/tools/walk.py @@ -1,17 +1,17 @@ # SPDX-License-Identifier: Apache-2.0 -"""The ``walk`` tool: the mesh's observed shape, explored one node at a time. +"""The ``walk`` tool: the observed shape of the mesh, explored one node at a time. -Opens the full-screen Mesh walk (see :mod:`meshterm.ui.walk_screen`): a walkable -browser over the evidence graph — trace walks, firmware routes, overheard relay -chains, repeater neighbour tables. One node holds the focus, its neighbourhood draws -as SNR-coloured braille edges on a small clean canvas, and its links list beneath as -rows with quality bars and evidence; Enter walks the graph, ⌫ backtracks along the -breadcrumb trail, and typing finds any node (islands included). The geographic map -answers *where* the mesh is; the walk answers *how it hangs together*. +The tool opens the full-screen Mesh walk (refer to :mod:`meshterm.ui.walk_screen`). It is +a browser in which the user walks over the evidence graph: trace walks, firmware routes, +heard relay chains, and repeater neighbour tables. One node has the focus. Its +neighbourhood draws as SNR-coloured braille edges on a small clean canvas, and its links +show below it as rows with quality bars and evidence. Enter walks the graph, ⌫ goes back +along the breadcrumb trail, and typed text finds any node (also the islands). The +geographic map tells where the mesh is. The walk tells how the nodes of the mesh connect. -Menu-only: the walk is an interactive reading of stored evidence (and transmits -nothing), so there is no scripted one-shot to register — ``trace``-family commands -already print path evidence in scripted runs. +Menu only: with the walk, the user examines stored evidence interactively (and the walk +transmits nothing). Thus there is no scripted one-shot command to register. The commands +of the ``trace`` family already print path evidence in scripted runs. """ from __future__ import annotations @@ -26,29 +26,29 @@ from .base import Tool, ToolResult, register @register class WalkTool(Tool): - """See how the mesh hangs together: the observed link graph, walkable.""" + """See how the nodes of the mesh connect: the observed link graph, which the user walks.""" name = "walk" title = "Mesh walk" - # A single-codepoint emoji (like every other tool icon), not a VS16 sequence: the - # emoji-width calibration strips VS16 on terminals that render it narrow, which would + # A single-codepoint emoji (as all the other tool icons are), not a VS16 sequence. On a + # terminal that renders VS16 narrow, the emoji-width calibration removes VS16. Thus it can # measure a 🕸️ one cell short of how it paints and drift this row's help text right of - # the column the others align to. The wireframe globe reads as the logical topology, - # the geographic map's 🌍 counterpart. + # the column to which the other rows align. The wireframe globe shows the logical + # topology. It is the equivalent of the 🌍 of the geographic map. icon = "🌐" help = "Walk the observed topology — links and SNR" category = "Explore" - order = 20 # beside Map: the logical shape next to the geographic one + order = 20 # next to Map: the logical shape next to the geographic shape async def prompt_params(self, ctx: AppContext) -> dict[str, Any] | None: - """Run the walk; there are never parameters to collect. + """Run the walk. It has no parameters to collect. - The screen presents everything itself and returns when dismissed, so - returning ``None`` tells the menu the invocation is complete (the same + The screen shows all its content itself, and it returns when the user leaves it. + Thus the return value ``None`` tells the menu that the run is complete (the same pattern as the ``dashboard`` tool). Args: - ctx: Shared application context. + ctx: The shared application context. Returns: Always ``None``. @@ -59,20 +59,20 @@ class WalkTool(Tool): return None async def run(self, ctx: AppContext, params: dict[str, Any]) -> ToolResult: - """Nothing runs here: the walk lives inside :meth:`prompt_params`. + """Nothing runs here: the walk is in :meth:`prompt_params`. Args: - ctx: Shared application context. - params: Unused. + ctx: The shared application context. + params: Not used. Returns: - An empty :class:`ToolResult` (only reachable from a scripted call). + An empty :class:`ToolResult` (only a scripted call comes here). """ return ToolResult(summary={}) def register_cli(self, app: typer.Typer) -> None: - """Register no CLI command — the walk is an interactive, menu-only screen. + """Register no CLI command, because the walk is an interactive screen for the menu only. Args: - app: The Typer application (untouched). + app: The Typer application (not changed). """ diff --git a/meshterm/tools/watchtower.py b/meshterm/tools/watchtower.py index 3da564b..6e154f1 100644 --- a/meshterm/tools/watchtower.py +++ b/meshterm/tools/watchtower.py @@ -1,16 +1,21 @@ # SPDX-License-Identifier: Apache-2.0 -"""The ``watchtower`` tool: a passive sentinel over the nodes you care about. +"""The ``watchtower`` tool: a passive sentinel for the nodes that are important to you. -Opens the Watchtower screen (see :mod:`meshterm.ui.watchtower_screen`): the alert log -with acknowledge/clear, the watchlist, and per-node rules. The rules themselves run in -the background for the whole session (see :mod:`meshterm.services.watchtower`) — a -silence alarm when a starred node goes quiet, an SNR-sag warning when its receptions -degrade, a recovery note when it returns, and a mesh-wide heads-up when a never-before- -seen node appears. Unacknowledged alerts show as the ``▲ n`` badge in the header, so -nothing here needs to be open to be on duty. +The tool opens the Watchtower screen (refer to :mod:`meshterm.ui.watchtower_screen`): the +alert log with acknowledge and clear, the watchlist, and the rules for each node. The +rules run in the background for the whole session (refer to +:mod:`meshterm.services.watchtower`): -Menu-only: the sentinel is inherently a live, session-long service; scripted runs can -read the same history through ``monitor``/``nodes``. +- A silence alarm when MeshTerm no longer hears a starred node. +- An SNR-sag warning when the receptions of the node become weaker. +- A recovery note when the node comes back. +- A notice for the whole mesh when a node appears that MeshTerm never heard before. + +The header shows the alerts that are not acknowledged as the ``▲ n`` badge. Thus this +screen does not have to be open for the watch to work. + +Menu only: the sentinel is always a live service for the whole session. Scripted runs can +read the same history through ``monitor`` and ``nodes``. """ from __future__ import annotations @@ -25,24 +30,24 @@ from .base import Tool, ToolResult, register @register class WatchtowerTool(Tool): - """Watch starred nodes: silence alarms, SNR sag, new-node sightings.""" + """Watch starred nodes: silence alarms, SNR sag, and new nodes that are heard.""" name = "watchtower" title = "Watchtower" icon = "🚨" help = "Alerts on watched nodes — silence, SNR sag" category = "Watch" - order = 30 # after the live views: the section's always-on alerting eye + order = 30 # after the live screens: the alerts of the section, which are always on async def prompt_params(self, ctx: AppContext) -> dict[str, Any] | None: - """Run the Watchtower screen; there are never parameters to collect. + """Run the Watchtower screen. It has no parameters to collect. - The screen presents everything itself and returns when dismissed, so - returning ``None`` tells the menu the invocation is complete (the same + The screen shows all its content itself, and it returns when the user leaves it. + Thus the return value ``None`` tells the menu that the run is complete (the same pattern as the ``dashboard`` tool). Args: - ctx: Shared application context. + ctx: The shared application context. Returns: Always ``None``. @@ -53,20 +58,20 @@ class WatchtowerTool(Tool): return None async def run(self, ctx: AppContext, params: dict[str, Any]) -> ToolResult: - """Nothing runs here: the Watchtower lives inside :meth:`prompt_params`. + """Nothing runs here: the Watchtower is in :meth:`prompt_params`. Args: - ctx: Shared application context. - params: Unused. + ctx: The shared application context. + params: Not used. Returns: - An empty :class:`ToolResult` (only reachable from a scripted call). + An empty :class:`ToolResult` (only a scripted call comes here). """ return ToolResult(summary={}) def register_cli(self, app: typer.Typer) -> None: - """Register no CLI command — the Watchtower is a live, menu-only feature. + """Register no CLI command, because the Watchtower is a live feature for the menu only. Args: - app: The Typer application (untouched). + app: The Typer application (not changed). """