Let a tool state its answer instead of printing it

The CLI said what it found by printing it: run() called ctx.ui.show(<a table>)
and handed back a ToolResult carrying only bookkeeping. By the time the boundary
saw that result the contacts had gone down the pipe already rendered, and there
was nothing left to offer a second format — which is exactly why --json reached
two commands out of twenty and stopped, each one growing an `if ctx.json_output:`
branch above the rendering that restated the whole answer in a dialect nobody
else could reuse.

exit_code has always worked the other way round: the tool states it, the boundary
turns it into a process status, and no tool calls sys.exit. The answer now travels
the same way. A tool states a Report; a renderer turns it into bytes; --json picks
the renderer.

ui/report.py holds the model — a Listing of records or a set of Facts, whose rows
carry the typed value and whose columns carry both projections of it. ui/fields.py
is the shared shapes, one constructor per concept, so every listing that mentions
a node speaks the same five-key object by construction rather than by review.
ui/renderers.py is the two faces: aligned text for a person, and the bare document
for a program — an array for a listing, an object for a set of facts, no envelope,
because the report a caller needs is still $?.

Nothing is migrated yet: report defaults to None and every command renders exactly
as it did. The script vocabulary the plain face will need lands alongside — ages,
durations, locations, the arrow-drawn route, the comma-joined spec, pinned lanes
for a live stream, and a wrap for the written pages — with the quoting still in
place until its callers move off it.

Also here, because the field library needs it: cli_time_format, the preference that
says whether the command line prints ages or timestamps, with --absolute as its
per-run override rather than a second switch beside it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Jean-Pierre MartineauandClaude Opus 5 committed 2026-09-08 03:16:57 -04:00
1 parent 59f10f904c
commit 1c24f9149d
9 files changed
+1776 -41

No files matched your search

+58 -8
View File
@@ -31,7 +31,8 @@ from .persistence.repository import Repository
from .platforms import Resolution, resolve, set_platform, without_emoji
from .tools import all_tools
from .tools.base import Tool, ToolResult
from .ui import script
from .ui import renderers, script
from .ui.renderers import OutputFormat
from .ui.termfont import emoji_support
from .ui.theme import make_console
@@ -86,6 +87,9 @@ def main_callback(
mock: bool = typer.Option(False, "--mock", help="Use the built-in simulator"),
db_path: Path | None = typer.Option(None, "--db", help="SQLite database path"),
json_output: bool = typer.Option(False, "--json", help="Machine-readable output"),
absolute: bool = typer.Option(
False, "--absolute", help="Print absolute timestamps instead of relative ages"
),
quiet: bool = typer.Option(False, "--quiet", "-q", help="Suppress console logging"),
platform: str | None = typer.Option(
None,
@@ -104,7 +108,8 @@ def main_callback(
tcp: Explicit network address ``host[:port]``, selecting the TCP transport.
mock: Whether to use the simulator instead of real hardware.
db_path: Override the database location.
json_output: Request machine-readable output from tools.
json_output: Print the answer as JSON instead of aligned text.
absolute: Print times as ISO-8601 instants rather than relative ages, for this run.
quiet: Suppress console logging (file logging continues).
platform: Explicit ``--platform`` override; see :func:`meshterm.platforms.resolve`.
"""
@@ -138,6 +143,12 @@ def main_callback(
# Loaded before logging is configured, because how much goes in the file is one of
# them — and handed to the context afterwards so the file is not read twice.
prefs = Preferences.load(settings.config_dir / "preferences.yaml")
if absolute:
# An override of the preference rather than a second switch beside it: *how
# MeshTerm behaves* is a preference by this project's own rule, and a flag that
# bypassed the registry would be a behaviour a reader could not find. Set, never
# saved — it is a claim about this run.
prefs.set("cli_time_format", "absolute")
configure_logging(
# A scripted run's stdout carries its answer and nothing else, so log records go
# to stderr instead of interleaving with the data a caller is parsing.
@@ -173,7 +184,10 @@ def main_callback(
ble_override=ble,
tcp_override=tcp,
ble_pin=ble_pin,
json_output=json_output,
output=OutputFormat.JSON if json_output else OutputFormat.PLAIN,
# Whether a tool may stop and ask, which is a different question from what its
# output looks like. A pipe on stdin means nobody is there to answer.
interactive=_stdin_is_a_person(),
explicit_selection=(
profile is not None or port is not None or ble is not None or tcp is not None
),
@@ -182,6 +196,12 @@ def main_callback(
ctx.call_on_close(app_ctx.repo.close)
if ctx.invoked_subcommand is None:
if json_output:
# There is no document an interactive session can emit, and launching the
# full-screen menu for a caller that asked for JSON would hang whatever was
# waiting to parse it.
raise typer.BadParameter("--json needs a subcommand; the menu has no document")
from .ui.menu import run_menu
# Before prompt_toolkit takes the screen: this can change the console's own font,
@@ -480,9 +500,21 @@ def specimen_command() -> None:
(rather than the plain one every other subcommand prints on — see
:mod:`meshterm.ui.script`). This is not scripted output that happens to be pretty: the
colour *is* the output. A monochrome specimen would test nothing.
It is also the one command that *refuses* ``--json``, loudly and as a usage error.
There is no data behind a colour card, so a document of it would be either a lie or an
empty gesture — and a loud refusal is the same answer this project already gives for
the map, the dashboard and the live feed, which simply have no subcommand to refuse
from.
"""
from .ui.specimen import specimen_lines
assert _state is not None # set by the callback that always runs first
if _state.output is not OutputFormat.PLAIN:
raise typer.BadParameter(
"specimen has no machine-readable output — its output is the colour"
)
console = make_console()
for line in specimen_lines():
console.print(line)
@@ -539,6 +571,23 @@ def run_tool_command(tool: Tool, params: dict) -> None:
raise typer.Exit(result.exit_code)
def _stdin_is_a_person() -> bool:
"""Whether something is there to answer a prompt.
The test a tool actually wants before it stops and asks: a redirected or piped stdin
means nobody is watching, and a command that blocks there has hung rather than failed.
``tx-optimize`` used to ask ``--json`` instead — a flag about output format, which
answers a different question and answered this one wrong in both directions.
Returns:
``True`` only where stdin is a terminal.
"""
try:
return bool(sys.stdin.isatty())
except (AttributeError, ValueError): # pragma: no cover - stdin closed or replaced
return False
def _reported(tool: Tool, problem: object, code: int) -> typer.Exit:
"""Log a failure, say so on stderr, and build the exit it should end on.
@@ -587,12 +636,12 @@ async def _drive(coro, ctx: AppContext): # noqa: ANN201 - passes the awaited va
async def _execute_and_render(tool: Tool, params: dict, ctx: AppContext) -> ToolResult:
"""Run a tool and print any file it produced.
"""Run a tool and render the answer it stated.
A tool's ``message`` is not printed here. It is the menu's closing line — "✓ applied
3 changes", "✓ traced Alice" — and on the command line it restates what the output
above it already showed and what ``$?`` already says. Where a scripted run has a fact
to report that the listing does not carry, the tool prints that fact itself.
The one place a report becomes output. The tool says what happened as data and this
hands it to whichever renderer ``--json`` selected, exactly as ``exit_code`` is stated
here and turned into a process status by the caller — which is what lets a third format
be a new renderer rather than an edit to twenty tools.
Args:
tool: The tool to execute.
@@ -603,6 +652,7 @@ async def _execute_and_render(tool: Tool, params: dict, ctx: AppContext) -> Tool
The tool's :class:`ToolResult`.
"""
result = await tool.execute(ctx, params)
renderers.for_format(ctx.output, ctx.console).render(result.report)
# A produced file is a fact, and its path is the whole of it: bare, one per line, so
# `meshterm config backup out.toml` can be read by the thing that runs it.
for artifact in result.artifacts:
+13 -2
View File
@@ -30,6 +30,7 @@ from .core.settings_store import SettingsStore
from .core.watch_store import WatchStore
from .persistence.logging import get_logger
from .persistence.repository import Repository
from .ui.renderers import OutputFormat
if TYPE_CHECKING:
from .services.advert_scheduler import AdvertScheduler
@@ -91,7 +92,16 @@ class AppContext:
interactive picker), selecting the TCP transport. Takes precedence over
``ble_override`` and ``port_override``.
ble_pin: Optional BLE pairing PIN for the chosen Bluetooth device.
json_output: Whether tools should emit machine-readable output.
output: Which format a scripted run prints its answer in (see
:class:`~meshterm.ui.renderers.OutputFormat`). A tool never reads this to
decide *what* to say — it states its answer as a
:class:`~meshterm.ui.report.Report` and the CLI boundary picks the renderer —
and the two streaming commands read it only to open the right kind of stream.
interactive: Whether this run may stop and ask a person something. False for every
scripted run whose stdin is not a terminal, which is the question a tool
actually wants answered before it prompts. ``tx-optimize`` used to ask
``--json`` instead, and a flag about *output format* cannot answer it: without
the flag, a scheduled run on a terminal would sit waiting for a password.
selected_device: The discovered device chosen for this session, when known, so it
can be remembered after a successful connection.
explicit_selection: Whether ``--port``/``--ble``/``--profile`` was passed explicitly
@@ -118,7 +128,8 @@ class AppContext:
ble_override: str | None = None
tcp_override: str | None = None
ble_pin: str | None = None
json_output: bool = False
output: OutputFormat = OutputFormat.PLAIN
interactive: bool = True
selected_device: DiscoveredDevice | None = None
explicit_selection: bool = False
_device: Device | None = field(default=None, init=False, repr=False)
+17
View File
@@ -109,6 +109,10 @@ class PrefSpec:
return f"{self.help} (next launch)" if self.relaunch else self.help
#: The two languages the plain CLI can print a time in. Named for what the reader sees
#: rather than for the mechanism: an *age* is how long ago, a *timestamp* is when.
_CLI_TIME_CHOICES: dict[str, str] = {"relative": "ages", "absolute": "timestamps"}
#: The silence-rule choices, drawn from the Watchtower's own ring so the two never drift.
_SILENCE_CHOICES: dict[int, str] = {
**{h: f"{h} h" for h in SILENCE_CHOICES_H},
@@ -284,6 +288,19 @@ PREFERENCES: tuple[PrefSpec, ...] = (
maximum=5000,
),
# --- Display -----------------------------------------------------------------
PrefSpec(
key="cli_time_format",
label="Command-line times",
help="Whether the command line prints ages or timestamps",
group="Display",
value_type="enum",
# Relative, because a person at a prompt asking "heard recently?" should not have
# to subtract an ISO instant from `date` to find out. `--absolute` overrides this
# for one run, and the JSON face is UTC either way — it is read somewhere else and
# often later, where a relative age has nothing to be relative to.
default="relative",
choices=_CLI_TIME_CHOICES,
),
PrefSpec(
key="fast_render",
label="Fast redraw",
+16
View File
@@ -18,6 +18,7 @@ if TYPE_CHECKING: # avoid importing typer/context at module load for fast start
import typer
from ..context import AppContext
from ..ui.report import Report
@dataclass(slots=True)
@@ -36,12 +37,27 @@ class ToolResult:
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.
``None`` for the menu path and for a feature with no scripted face at all (the
map, the dashboard), which keep working unchanged.
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.
"""
summary: dict[str, Any] = field(default_factory=dict)
message: str | None = None
artifacts: list[str] = field(default_factory=list)
exit_code: int = exitcodes.OK
report: Report | None = None
class Tool(ABC):
+413
View File
@@ -0,0 +1,413 @@
"""The shared shapes a report is built out of — one constructor per concept.
A node means the same thing in ``contacts``, ``monitor``, ``courier list``, ``trace`` and
``records``, and it should *look* the same in all five and parse the same in all five. The
way to guarantee that is not review, it is construction: every listing that mentions a
node asks this module for the column, so there is exactly one definition of what a node's
plain lanes are called and what its machine object holds.
Each constructor returns one :class:`~meshterm.ui.report.Column`, which carries both
projections of one typed value. The typed value is what a row holds — a :class:`NodeRef`,
a :class:`Position`, a :class:`~datetime.datetime`, a bare float — never a formatted cell,
so the plain face can print ``+5.1`` and the machine face ``5.1`` without either one
parsing the other's output back.
The interesting one is :func:`node`, and it is what earns the design: **one machine key
expands to as many plain columns as the surface has room for.** ``contacts`` spends four
(a name, a role, a hash, a key), ``monitor``'s live stream spends two, a trace's per-hop
table spends one — and all four documents carry the same five-key object, because the
lanes are a rendering choice and the shape is not.
Two absences, kept apart on purpose. ``None`` is *we do not know*, and it reads as
:data:`~meshterm.ui.script.NONE` plain and ``null`` in JSON. A word standing in for an
absence is not the same thing: ``unknown`` in a ``TYPE`` column is a word a reader
understands, so the plain face keeps it, while the document writes ``null`` — because a
consumer already has one spelling for "there is nothing here" and a second one costs it a
special case.
"""
from __future__ import annotations
from collections.abc import Sequence
from dataclasses import dataclass
from datetime import datetime
from typing import Any
from . import script
from .report import Column, Lane, normalise
# -- the shared value shapes -----------------------------------------------------------
@dataclass(frozen=True, slots=True)
class NodeRef:
"""A mesh participant's identity, and nothing else.
The most repeated concept in either face. *Identity only*: when a node was heard, how
strong it came in, where it says it is — those belong to the **row**, because they
differ per surface and a node object that carried them would mean something different
in every one.
Attributes:
name: The name the node advertises, or ``None`` where none was ever heard —
including where a surface substitutes a bare hash for one.
key: The full public key, lowercase hex, **never truncated**: a key cut short is
not something a caller can hand back to ``--to`` or ``--path``. ``None`` where
only a hash was ever heard.
hash: The short derived id, at the width the surrounding surface addressed the
node by — never ``key`` shortened by this module's own choosing.
type: The advertised role in the lexicon's words (``node``, ``repeater``,
``room``, ``sensor``), or ``None`` where the advert never said.
is_self: Whether this is our own node. The plain face draws it like any other hop,
which is the point: "you already know who this is" is true of the person at
the prompt and false of whoever reads the file afterwards. The machine face
carries it as ``self``, because a parser has no way to work it out at all.
"""
name: str | None = None
key: str | None = None
hash: str | None = None
type: str | None = None
is_self: bool = False
@dataclass(frozen=True, slots=True)
class Position:
"""A shared location, in decimal degrees.
Unrounded in the document, as stored: the plain face's five decimals are a column-width
concession and a consumer should not inherit one.
"""
lat: float
lon: float
@dataclass(frozen=True, slots=True)
class ChannelRef:
"""One channel slot's identity. The secret is deliberately not in it.
A channel object travels through listings and send receipts, and a key that rode along
in all of them would be a key printed by commands nobody asked to print one. It
appears only where the caller explicitly asked (``channels share``), under its own
field, beside this.
Attributes:
slot: The 0-based index every ``channels`` subcommand's ``INDEX`` takes.
name: The channel name.
public: Whether the key is derived from the name (a ``#`` channel or a firmware
default) rather than secret.
hash: The channel hash, lowercase hex.
"""
slot: int
name: str
public: bool
hash: str | None = None
def node_json(ref: NodeRef | None) -> dict[str, Any] | None:
"""One node as its machine object, or ``null`` where there is no node at all."""
if ref is None:
return None
return {
"name": ref.name or None,
"key": (ref.key or None) and ref.key.lower(),
"hash": (ref.hash or None) and ref.hash.lower(),
"type": ref.type or None,
"self": ref.is_self,
}
def position_json(where: Position | None) -> dict[str, Any] | None:
"""One position as its machine object, or ``null`` where none was ever shared.
The whole object is ``null`` rather than a pair of ``null``s: a latitude without a
longitude is not half a location, it is no location.
"""
return None if where is None else {"lat": where.lat, "lon": where.lon}
def channel_json(channel: ChannelRef | None) -> dict[str, Any] | None:
"""One channel as its machine object, or ``null`` for an empty slot."""
if channel is None:
return None
return {
"slot": channel.slot,
"name": channel.name,
"public": channel.public,
"hash": (channel.hash or None) and channel.hash.lower(),
}
# -- the constructors ------------------------------------------------------------------
#: How each of a node's plain lanes reads its cell. A surface picks the ones it has room
#: for; the machine object is the same five keys either way.
_NODE_LANES = {
"name": lambda ref: script.name(ref.name if ref else None),
# The word, not a glyph: `▲` without its colour would need a legend and the CLI has no
# legends. `unknown` is a word a reader acts on; the document writes `null`.
"type": lambda ref: ref.type if ref and ref.type else "unknown",
"hash": lambda ref: ((ref.hash or "").lower() if ref else "") or script.NONE,
"key": lambda ref: ((ref.key or "").lower() if ref else "") or script.NONE,
}
def node(key: str = "node", *, lanes: Sequence[tuple[str, str]] = (("name", "NAME"),)) -> Column:
"""One node: the shared five-key object, and whichever plain lanes fit.
Args:
key: The machine key, and the key the row holds its :class:`NodeRef` at.
lanes: ``(part, header)`` pairs naming the plain columns to draw, in order. The
parts are ``name``, ``type``, ``hash`` and ``key``. A surface with one column
to spend draws the name; a per-hop table draws the hash, because that is what
joins it to the route line above it.
Returns:
The column.
"""
return Column(
key=key,
lanes=tuple(Lane(header=header, render=_NODE_LANES[part]) for part, header in lanes),
json=node_json,
)
def position(key: str = "position", header: str = "LOCATION") -> Column:
"""A shared location: one plain column, one machine object.
One column and not two. A coordinate pair is one fact to a reader, it is what goes
into a map's search box verbatim, and two columns of ``-`` for every node that has
never shared a position is worse than one.
"""
return Column(
key=key,
lanes=(Lane(header=header, render=_position_cell),),
json=position_json,
)
def channel(
key: str = "channel",
*,
lanes: Sequence[tuple[str, str]] = (("name", "NAME"),),
) -> Column:
"""One channel slot: the shared four-key object, and whichever plain lanes fit.
Args:
key: The machine key.
lanes: ``(part, header)`` pairs; the parts are ``slot``, ``name``, ``type`` and
``hash``. ``type`` is the plain face's word for the ``public`` boolean —
``public``/``private`` reads where ``true``/``false`` would need the heading
to say which way round it runs.
"""
parts = {
"slot": lambda c: script.number(c.slot if c else None),
"name": lambda c: script.name(c.name if c else None),
"type": lambda c: ("public" if c.public else "private") if c else script.NONE,
"hash": lambda c: ((c.hash or "").lower() if c else "") or script.NONE,
}
return Column(
key=key,
lanes=tuple(Lane(header=header, render=parts[part]) for part, header in lanes),
json=channel_json,
)
def when(key: str, header: str, *, absent: str = script.NONE) -> Column:
"""A time the reader reads as an age: ``5m``, ``3h``, ``never``.
The default form for every time in a listing, because "recently?" is the question the
reader typed the command to ask and an ISO instant makes them do arithmetic to answer
it. ``--absolute`` swaps the whole language back for a run; the document is UTC
regardless, since it is read somewhere else and often later.
Args:
key: The machine key. It ends in ``_at`` by convention — a JSON key is a type hint
for a parser, and the suffix is the hint.
header: The plain heading.
absent: What an unknown time reads as plain. ``never`` where the row exists and
the event has not happened (a node not yet heard, a conversation with nothing
said in it); the default token where the row has no such time at all.
Returns:
The column.
"""
return Column(
key=key,
lanes=(Lane(header=header, render=lambda v: _time(v, absent=absent), align="right"),),
)
def instant(key: str, header: str) -> Column:
"""A time that *is* the fact, printed absolutely whatever ``--absolute`` says.
Three surfaces want this and each for the same reason — the instant is the answer, not
a way of saying how long ago something was. The device's own clock. An appointment set
with ``--at``, which is a wall-clock time the caller chose. And a live capture's own
``TIME`` column, every row of which would otherwise read ``now``.
"""
return Column(key=key, lanes=(Lane(header=header, render=script.stamp),))
def snr(key: str, header: str) -> Column:
"""A signal-to-noise reading: ``+5.1`` plain, ``5.1`` in the document.
The plain sign is a column convention — a lane of readings only reads as a ladder when
every one of them declares its direction. A number in JSON carries its own sign and a
leading ``+`` would make it a string.
"""
return Column(
key=key,
lanes=(Lane(header=header, render=lambda v: script.number(v, "+.1f"), align="right"),),
json=lambda v: None if v is None else round(float(v), 1),
)
def integer(key: str, header: str) -> Column:
"""A whole number, right-aligned so a column of them is comparable by eye."""
return Column(key=key, lanes=(Lane(header=header, render=script.number, align="right"),))
def decimal(key: str, header: str, spec: str = ".1f") -> Column:
"""A measured number, formatted for the column and left unrounded in the document."""
return Column(
key=key,
lanes=(Lane(header=header, render=lambda v: script.number(v, spec), align="right"),),
)
def flag(key: str, header: str) -> Column:
"""A boolean: ``yes``/``no`` for a reader, ``true``/``false`` for a parser.
``None`` is a third answer and stays one — ``acked`` on a channel message is not
``false``, it is *there is no acknowledgement on a channel*, and the two are different
things to anyone counting delivery failures.
"""
return Column(
key=key,
lanes=(Lane(header=header, render=_flag_cell),),
)
def word(key: str, header: str) -> Column:
"""A member of a closed set — a state, a role, an outcome — as its own lowercase word.
Both faces say the same word, so ``courier send``'s ``no ack`` reads the same in a
document as it does on the line the help lists it on.
"""
return Column(key=key, lanes=(Lane(header=header, render=lambda v: v or script.NONE),))
def name(key: str, header: str) -> Column:
"""A bare name that is not a node's — a channel label, a conversation, a device."""
return Column(key=key, lanes=(Lane(header=header, render=script.name),))
def free(key: str, header: str) -> Column:
"""Free text a stranger filled in: escaped so it can never end its own record.
Always the last lane in a listing, because it is the one field with no width. The
document carries it **raw and unshortened** — a JSON string holds a newline natively,
so the escaping is a plain-text necessity rather than something to inflict on a
consumer.
"""
return Column(key=key, lanes=(Lane(header=header, render=script.text),))
def route(key: str = "route", header: str = "ROUTE") -> Column:
"""A walked hop sequence: drawn with arrows plain, an array of nodes in the document.
The row holds :class:`NodeRef` objects in propagation order, so the document's hops are
the same objects a listing's rows carry and a consumer's node handler is written once.
``None`` where nothing came home — never ``[]``, which would claim a walk of no hops.
"""
return Column(
key=key,
lanes=(
Lane(
header=header,
render=lambda hops: (
script.route([(h.name, h.hash) for h in hops]) if hops else script.NONE
),
),
),
json=lambda hops: None if hops is None else [node_json(hop) for hop in hops],
)
def spec(key: str = "path", header: str = "path") -> Column:
"""A forced path exactly as the radio was given it: ``a1,d4,a1``, or absent.
The one line on either face that round-trips into ``--path``, so it keeps its commas
and grows nothing. ``None`` means the device routed the walk itself: the plain face
says ``auto`` because a reader needs a word there, and the document says ``null``
because ``auto`` is not a path spec and R3 already has a token for "there is no spec
here".
"""
return Column(
key=key,
lanes=(Lane(header=header, render=lambda v: v if v else "auto"),),
)
def hexid(key: str, header: str) -> Column:
"""A hash or a key on its own, lowercase, never truncated and never elided."""
return Column(
key=key,
lanes=(Lane(header=header, render=lambda v: (v or "").lower() or script.NONE),),
json=lambda v: (v or None) and str(v).lower(),
)
def note(key: str, header: str) -> Column:
"""Prose for a reader, with no machine face at all.
A preference's DESCRIPTION is the case: it explains a preference to somebody deciding
whether to change it, and there is nothing in it a program would branch on. Declaring
it as a column rather than smuggling it in keeps the listing's two faces stated in one
place.
"""
return Column(key=key, lanes=(Lane(header=header, render=script.text),), json=None)
def hidden(key: str) -> Column:
"""A fact the document carries and the plain face has no room for.
The mirror of :func:`note`. ``config show`` prints a setting's key and its value —
that is what a reader came for — while the document also says what type it is, what an
enum's number is called, and whether the value was withheld.
"""
return Column(key=key)
def _position_cell(where: Position | None) -> str:
"""One position's cell: the pair, or the absent token."""
return script.NONE if where is None else script.location(where.lat, where.lon)
def _flag_cell(value: bool | None) -> str:
"""One boolean's cell, keeping ``None`` as an absence rather than a ``no``."""
return script.NONE if value is None else ("yes" if value else "no")
def _time(value: Any, *, absent: str) -> str:
"""Render a time in whichever language this run speaks (see :func:`when`)."""
if isinstance(value, datetime) or value is None:
return script.stamp(value) if _absolute() else script.age(value, absent=absent)
return normalise(value) # pragma: no cover - a row holding something else is a bug
def _absolute() -> bool:
"""Whether this run prints absolute times.
Read from the preference registry rather than a module flag, because *how MeshTerm
behaves* is a preference by this project's own rule — and ``--absolute`` is then
simply that preference overridden for one run (see
:func:`~meshterm.cli.main_callback`), rather than a second switch saying the same
thing in a place a reader cannot find.
"""
from ..core.preferences import current
return str(current().cli_time_format) == "absolute"
+307
View File
@@ -0,0 +1,307 @@
"""The two faces of one answer: a renderer turns a report into bytes.
A tool states its answer as a :mod:`~meshterm.ui.report`; this module is where that
becomes output, and the CLI boundary picks which one runs (see
:func:`~meshterm.cli.main_callback`). Nothing above here knows what a gutter or a comma is,
and nothing below here knows what a contact is. That separation is the whole point: a
third format later — YAML, CSV, whatever somebody needs — is a new class in this file and
not an edit to twenty tools.
**Plain** (:class:`PlainRenderer`) is for a person at a prompt: aligned columns, ages, a
route drawn with arrows, and a ``sysctl -a`` block for a set of facts about one thing. It
is written in the vocabulary of :mod:`meshterm.ui.script`, which is where the reasons for
each of its rules live.
**JSON** (:class:`JsonRenderer`) is for a program, often on another machine and often
later. It prints **the answer itself** — an array for a listing, an object for a set of
facts — compact, one line, UTF-8, no ASCII escaping, keys in the order the report declares
them. There is no wrapper: ``meshterm contacts --json | jq '.[].node.name'`` reads what it
looks like it reads, and the report a caller needs is still ``$?``, exactly as it is
without the flag. So a failure prints **nothing at all** on stdout — the ``meshterm: what
went wrong`` line stays on stderr where every utility puts it, and stdout holding a valid
document is then a reliable signal that the command worked.
Two rules cover a report of more than one block, and between them they produce the
documents ``trace`` and ``tx-optimize`` are specified with. A **single-block** report *is*
its block's document. A **multi-block** report is one object: each :class:`Listing` under
its own key, and each :class:`Facts` merged in at the top level — a facts block is the set
of facts about the one thing the command answered, so it is the document rather than a
compartment inside it.
"""
from __future__ import annotations
import json
from collections.abc import Iterator, Mapping, Sequence
from contextlib import contextmanager
from enum import Enum
from typing import TYPE_CHECKING, Any
from rich.console import Console
from rich.text import Text
from . import script
from .report import BARE, SILENT, Block, Facts, Lane, Listing, Report
if TYPE_CHECKING: # pragma: no cover - typing only
from ..context import AppContext
class OutputFormat(str, Enum):
"""The formats a scripted run can print its answer in.
An enum rather than the ``--json`` boolean it replaces, because the boolean was
already being asked questions it could not answer — ``tx-optimize`` read it as "may I
prompt?" — and because a third member here costs one renderer and no tool changes at
all. ``--json`` stays the documented spelling and is sugar for this.
"""
PLAIN = "plain"
JSON = "json"
class Renderer:
"""Turns a report into bytes. One subclass per format."""
def render(self, report: Report | None) -> None:
"""Print a completed report, or nothing at all when there is none."""
raise NotImplementedError
@contextmanager
def stream(self, listing: Listing) -> Iterator[Any]:
"""Open a live listing whose rows arrive one at a time.
The narrow second seam, and it exists because a stream has no end to return from:
``monitor`` and ``chat listen`` run until a window closes or somebody interrupts
them, so their answer cannot be a value handed back at the end. Two commands use
it. Nothing else should — a command that can build a whole report should, because
a report is the thing every format already knows how to read.
Args:
listing: The shape of the records to come — its columns, its lane order, and
(for the plain face) the width each lane is pinned to. Its ``rows`` are
ignored; rows arrive through the yielded callable.
Yields:
A callable taking one typed row mapping.
"""
raise NotImplementedError
class PlainRenderer(Renderer):
"""The face a person reads: aligned text on the scripted console.
Attributes:
console: The plain console (see :func:`meshterm.ui.script.console`).
"""
def __init__(self, console: Console) -> None:
"""Bind the renderer to the console its output goes to."""
self.console = console
def render(self, report: Report | None) -> None:
"""Draw each block in order, one blank line between them."""
for index, block in enumerate(report or ()):
drawn = self._block(block)
if drawn is None:
continue
if index:
self.console.print(script.blank())
self.console.print(drawn)
def _block(self, block: Block) -> Any:
"""The renderable for one block, or ``None`` where it prints nothing."""
if isinstance(block, Listing):
return self._listing(block) if block.rows else None
if isinstance(block, Facts):
return self._facts(block)
raise TypeError(f"unrenderable block: {block!r}") # pragma: no cover - closed set
def _listing(self, block: Listing) -> Any:
"""A listing as its header line and its padded records."""
lanes = block.lanes()
table = script.columns(
*(lane.header for _, lane in lanes),
right=[lane.header for _, lane in lanes if lane.align == "right"],
)
# `config show` is an array to a parser and a `sysctl -a` block to a reader, so it
# keeps the columns and drops the heading row. Same table either way — the padding,
# the no-wrap and the crop are what make a record splittable, and none of them is
# the header's doing.
table.show_header = block.headed
for row in block.rows:
table.add_row(*(lane.render(row.get(column.key)) for column, lane in lanes))
return table
def _facts(self, block: Facts) -> Any:
"""A facts block as a key/value listing, one bare value, or nothing."""
if block.shape == SILENT:
return None
if block.shape == BARE:
column = next(c for c in block.fields if c.key == block.bare)
# As a Text, not a markup string: this is a private key, a share URL or a
# remote node's own reply, and Rich would read a bracket in one as a style tag.
return Text(column.lanes[0].render(block.values.get(column.key)))
rows: list[tuple[str, str]] = []
for column in block.fields:
value = block.values.get(column.key)
if block.omit_absent and (value is None or value == ""):
continue
for lane in column.lanes:
rows.append((lane.header, lane.render(value)))
return script.pairs(rows)
@contextmanager
def stream(self, listing: Listing) -> Iterator[Any]:
"""Print the header line, then one pinned-lane record per row as it arrives."""
lanes = listing.lanes()
pinned = script.stream(
*((lane.header, _lane_width(lane)) for _, lane in lanes),
right=[lane.header for _, lane in lanes if lane.align == "right"],
)
self.console.print(pinned.header, highlight=False)
def row(record: Mapping[str, Any]) -> None:
cells = [lane.render(record.get(column.key)) for column, lane in lanes]
self.console.print(pinned.record(*cells), highlight=False)
yield row
class JsonRenderer(Renderer):
"""The face a program reads: one compact document, or one per streamed record.
Attributes:
console: The plain console, used only for its stream — the document is written
through :func:`json.dumps` rather than by Rich, so nothing can pad, wrap,
highlight or otherwise adorn it.
"""
def __init__(self, console: Console) -> None:
"""Bind the renderer to the console its output goes to."""
self.console = console
def render(self, report: Report | None) -> None:
"""Print the report as one document, or nothing when there is no report at all."""
if report is None:
return
blocks = [block for block in report if not block.plain_only]
if not blocks:
return
self._write(self._document(blocks))
def _document(self, blocks: Sequence[Block]) -> Any:
"""Fold the blocks into the one value this command answers with."""
if len(blocks) == 1:
return self._value(blocks[0])
document: dict[str, Any] = {}
for block in blocks:
if isinstance(block, Facts):
document.update(self._facts(block))
else:
document[block.key] = self._value(block)
return document
def _value(self, block: Block) -> Any:
"""One block's document: an array for a listing, an object for a set of facts."""
if isinstance(block, Listing):
return [self._row(block, row) for row in block.rows]
if isinstance(block, Facts):
return self._facts(block)
raise TypeError(f"unrenderable block: {block!r}") # pragma: no cover - closed set
@staticmethod
def _row(block: Listing, row: Mapping[str, Any]) -> dict[str, Any]:
"""One record, with every declared key present (``null`` where it is absent)."""
return {
column.key: column.json(row.get(column.key))
for column in block.columns
if column.json is not None
}
@staticmethod
def _facts(block: Facts) -> dict[str, Any]:
"""One facts block as an object, keeping every declared key.
``omit_absent`` is a *plain* concession — ``info`` leaves out a reading the
firmware does not answer for, so a dash never claims the radio reported nothing.
A consumer cannot act on that distinction and pays a membership test on every
field for it, so the document keeps the key and writes ``null``.
"""
return {
column.key: column.json(block.values.get(column.key))
for column in block.fields
if column.json is not None
}
def _write(self, document: Any) -> None:
"""Write one compact document and terminate it with a newline."""
line = json.dumps(
document,
# A node name in Cyrillic is a node name, not a run of `\uXXXX`. The scripted
# console already reconfigures stdout to UTF-8 for exactly this class of
# character.
ensure_ascii=False,
# Compact and one line, so a stream and a one-shot answer are read the same
# way and `jq .` can re-indent for a person at no cost. Nothing can un-stream
# a document that was pretty-printed across four hundred lines.
separators=(",", ":"),
)
self.console.file.write(line + "\n")
self.console.file.flush()
@contextmanager
def stream(self, listing: Listing) -> Iterator[Any]:
"""Print one document per record, flushed, as each arrives.
Every line is the same shape, which is what makes the stream readable without a
discriminator: a consumer reads line by line and never has to ask which kind of
record it is holding. The closing per-node summary the plain face draws is marked
``plain_only`` for that reason — it is derivable from the records above it, and a
second shape mid-stream would cost every reader a branch it otherwise never needs.
"""
def row(record: Mapping[str, Any]) -> None:
self._write(self._row(listing, record))
yield row
def for_format(output: OutputFormat, console: Console) -> Renderer:
"""The renderer for one output format.
Args:
output: What the caller asked for.
console: The console to print on.
Returns:
The renderer.
"""
return JsonRenderer(console) if output is OutputFormat.JSON else PlainRenderer(console)
@contextmanager
def stream(ctx: AppContext, listing: Listing) -> Iterator[Any]:
"""Open a live listing on whichever renderer this run is using.
Args:
ctx: The application context, for its output format and console.
listing: The stream's shape (see :meth:`Renderer.stream`).
Yields:
A callable taking one typed row mapping.
"""
with for_format(ctx.output, ctx.console).stream(listing) as row:
yield row
def _lane_width(lane: Lane) -> int:
"""How wide a streamed lane is pinned.
A live capture cannot size its columns the way :func:`~meshterm.ui.script.columns`
does, because it has not seen the records yet. So each lane declares the width it is
pinned to, and a value wider than that overruns and pushes the rest of its row right
rather than being cut — which is why the one unbounded field goes last (see
:class:`meshterm.ui.script.Lanes`).
"""
return max(len(lane.header), lane.width)
+243
View File
@@ -0,0 +1,243 @@
"""What a tool answers with, stated as data before anything decides how it looks.
A scripted run used to say its answer by *printing* it: ``Tool.run`` called
``ctx.ui.show(<a table built by ui/script.py>)`` and returned a :class:`ToolResult`
carrying only bookkeeping. By the time the CLI boundary saw that result the contacts had
already gone down the pipe as a space-aligned table, and there was nothing left to hand a
second format. That is exactly why ``--json`` reached two commands out of twenty and
stopped: each one that wanted it grew an ``if ctx.json_output:`` branch *above* the
rendering, restating the whole answer in a second dialect nobody else could reuse.
``exit_code`` already showed the shape that works — the tool states it, the boundary turns
it into a process status, and no tool has ever called :func:`sys.exit`. This module lets
the answer travel the same way:
**A tool states its answer as data. A renderer turns data into bytes. The CLI
boundary picks the renderer** (see :mod:`meshterm.ui.renderers`).
A report is a short sequence of blocks, and there are only two kinds because the plain
face proved only two are needed — a :class:`Listing` (records under a header line) and
:class:`Facts` (one thing described key by key). A :class:`Facts` block covers the
one-scalar answer too, through :data:`BARE`: ``config get`` prints its value alone
*because the caller named the key*, while the machine face still gets the object with the
key, the type and the label in it. Splitting that into a third block type would have
bought a second name for the same data.
**A row holds the typed value.** ``6.0``, ``None``, a :class:`~datetime.datetime` — never
a formatted cell. Each :class:`Column` carries both projections instead: the plain
:class:`Lane` that turns the value into text, and the JSON function that normalises it.
One typed row, two projections, and a third format later is a third function rather than a
third row-builder. :mod:`meshterm.ui.fields` builds the columns for the concepts the whole
app shares — a node, a time, an SNR, a route — so every listing speaks the same shapes by
construction rather than by review.
Nothing here renders. A block does not know what a gutter is, and a column does not know
whether anyone will ever ask it for JSON.
"""
from __future__ import annotations
from collections.abc import Callable, Mapping, Sequence
from dataclasses import dataclass, field
from datetime import datetime, timezone
from enum import Enum
from pathlib import Path
from typing import Any
#: How a :class:`Facts` block reaches the *plain* face. The machine face is the same
#: object either way — this only chooses what a person at a prompt is shown.
PAIRS = "pairs"
#: One named field's value, alone, with no key in front of it. What ``config get`` prints:
#: the caller named the key, so repeating it back is one more thing to strip off.
BARE = "bare"
#: Nothing at all. An acknowledgement — ``config advert``, ``channels join`` — whose plain
#: report is its exit status. The machine face still gets a document, because "prints
#: nothing" is an answer a person can act on and a program cannot.
SILENT = "silent"
def _text(value: Any) -> str:
"""The last-resort plain projection: the value as text, or the absent token."""
from . import script
return script.NONE if value is None else str(value)
def normalise(value: Any) -> Any:
"""A typed value in its machine form: JSON-ready, and the same on every host.
The one place the contract's cross-cutting value rules are applied, so a command
cannot forget one:
* a **time** is UTC, RFC 3339, ``Z``-suffixed, to the second — always twenty
characters, so string comparison is time comparison. A local offset is a fact about
the machine that ran the command rather than about the event, and two hosts asking
the same radio the same question must produce the same document. A *naive* time is
one whose offset we do not actually know, which is not a fact, so it reads as absent
exactly as it does on the plain face.
* an **enum** is its value, not its Python name.
* a **path** is its text.
* everything else travels as it is, typed: ``9`` and not ``"9"``, ``false`` and not
``"false"``, ``None`` and not the plain face's ``-``.
Args:
value: The typed value from a report row.
Returns:
The value in a form :mod:`json` can write.
"""
if isinstance(value, datetime):
if value.tzinfo is None:
return None
return value.astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
if isinstance(value, Enum):
return normalise(value.value)
if isinstance(value, Path):
return str(value)
if isinstance(value, (list, tuple)):
return [normalise(item) for item in value]
return value
@dataclass(frozen=True, slots=True, kw_only=True)
class Lane:
"""One plain-text column, drawn from its :class:`Column`'s typed value.
A lane is the *reader's* half of a column. Several may share one column where the
plain face spends more room on a concept than the machine face does — a node is one
JSON object and up to four plain columns (its name, its role, its hash, its key),
which is the whole reason a column owns a list of these rather than one header string.
Attributes:
header: The uppercase heading, and the field a caller greps for. Renaming one
silently breaks a script, so it is as much a contract as the exit status.
render: Turns the column's typed value into this lane's cell.
align: ``"right"`` for a lane of magnitudes — a column of numbers or ages is only
comparable by eye once the digits line up.
width: The cells this lane is pinned to in a *live* listing, where the widths
cannot be measured because the records have not arrived yet. Ignored by an
ordinary listing, which sizes every lane to its widest value.
"""
header: str
render: Callable[[Any], str] = _text
align: str = "left"
width: int = 0
@dataclass(frozen=True, slots=True, kw_only=True)
class Column:
"""One concept in a report, with a projection for each face.
Attributes:
key: The name this concept goes under: the JSON key, and the key a row's mapping
holds its typed value at.
lanes: The plain columns this concept draws — usually one. **Empty means the
concept has no plain face**, which is how ``config show`` carries a setting's
type and enum label into the document while printing the two fields a reader
wants.
json: The typed value's machine projection, or ``None`` where the concept has no
machine face — the mirror of an empty ``lanes``, and what a preference's
DESCRIPTION is: prose for whoever is choosing a value, carrying nothing a
program would branch on. Defaults to :func:`normalise`, which handles the
scalars; a shared shape (a node, a position) passes its own.
"""
key: str
lanes: tuple[Lane, ...] = ()
json: Callable[[Any], Any] | None = normalise
@dataclass(frozen=True, slots=True, kw_only=True)
class Block:
"""One part of an answer.
Attributes:
key: The name this block goes under in a multi-block document.
plain_only: Whether this block is a rendering for a person that the machine face
has no use for. The one case is a stream's closing summary: ``monitor`` prints
a per-node aggregate under its live capture, and a consumer holding every
record of that capture can compute the same thing — where a second *shape* of
line in the middle of an otherwise homogeneous NDJSON stream costs every
reader a discriminator it would otherwise never need.
"""
key: str
plain_only: bool = False
@dataclass(frozen=True, slots=True, kw_only=True)
class Listing(Block):
"""Records under a header line: a listing plain, an array of objects in JSON.
Attributes:
columns: The concepts each record carries, in machine-face order.
rows: One mapping per record, keyed by ``Column.key`` and holding **typed**
values.
order: The lane headers in plain draw order. Empty means "as declared", which is
what most listings want; a listing states it where the two orders genuinely
differ — ``contacts`` puts HEARD and PKTS between a node's TYPE and its HASH,
and ``monitor`` puts the one unbounded field (a node's name) last so it can
never push a column.
headed: Whether the plain face draws the header line. ``config show`` is the one
listing that does not: it is an array of settings to a parser and a
``sysctl -a`` block to a reader, and a header line over two columns whose keys
are the answer would be furniture.
"""
columns: tuple[Column, ...]
rows: Sequence[Mapping[str, Any]] = ()
order: tuple[str, ...] = ()
headed: bool = True
def __post_init__(self) -> None:
"""Reject an ``order`` that does not name this listing's own lanes.
A typo here draws a listing with a column missing and no complaint, which is the
one failure a header line cannot show. Cheaper to raise at construction.
"""
if not self.order:
return
known = {lane.header for column in self.columns for lane in column.lanes}
if set(self.order) != known or len(self.order) != len(known):
raise ValueError(f"{self.key}: order must name every lane exactly once")
def lanes(self) -> list[tuple[Column, Lane]]:
"""The plain columns in draw order, each with the column it reads from."""
pairs = [(column, lane) for column in self.columns for lane in column.lanes]
if not self.order:
return pairs
by_header = {lane.header: (column, lane) for column, lane in pairs}
return [by_header[header] for header in self.order]
@dataclass(frozen=True, slots=True, kw_only=True)
class Facts(Block):
"""One thing, described key by key: a ``sysctl -a`` block plain, an object in JSON.
Attributes:
fields: The concepts, in the order both faces present them.
values: The typed value per ``Column.key``.
shape: :data:`PAIRS`, :data:`BARE` or :data:`SILENT` — what the *plain* face
prints. The machine face is the object either way.
bare: With :data:`BARE`, the one field whose value is printed alone.
omit_absent: Whether a field with no value is left out of the plain block
entirely. Only ``info`` wants this, and deliberately: its readings are
optional device queries, so a missing key says "this radio does not report
it" where a dash would claim it reported nothing. The machine face keeps every
declared key and writes ``null``, because "does not report" and "reported
nothing" are the same fact to a caller and a variable key set costs every
consumer a membership test on every field.
"""
fields: tuple[Column, ...]
values: Mapping[str, Any] = field(default_factory=dict)
shape: str = PAIRS
bare: str = ""
omit_absent: bool = False
#: A tool's whole answer. Deliberately a bare sequence rather than a class of its own:
#: there is nothing a report *does*, and the two rules about how several blocks combine
#: belong to the renderer that combines them (see :mod:`meshterm.ui.renderers`).
Report = tuple[Block, ...]
+308 -31
View File
@@ -48,6 +48,7 @@ Nothing here is reachable from the menu, and nothing in the menu is reachable fr
from __future__ import annotations
from collections.abc import Iterable, Sequence
from dataclasses import dataclass
from datetime import datetime
from typing import Any
@@ -71,6 +72,18 @@ GUTTER = 2
#: parser) learns it once. Never ``—``, ``n/a``, ``never``, or an empty cell.
NONE = "-"
#: The separator between a route's hops, spaced — the same ``→`` the menu's path lines
#: draw with (:data:`meshterm.ui.pathline._ARROW`), and device-verified present in the
#: PicoCalc console font. It carries the direction the packet travelled, and it is what
#: makes the quoting unnecessary: a comma inside a node's name can no longer be read as a
#: hop boundary.
ARROW = " → "
#: How wide a *written page* wraps. Not the terminal's width: the same paragraph must read
#: the same when it is piped, redirected, or shipped as the machine face's ``text`` field,
#: and 72 is the width every screen in this app is already held to.
PAGE_WIDTH = 72
#: The characters with a readable escape of their own. Everything else that cannot travel
#: in a record falls through to ``\xNN``/``\uNNNN`` below.
@@ -160,9 +173,33 @@ def oneline(value: str | None) -> str:
return NONE if value is None else _escaped(value)
def text(value: str | None) -> str:
r"""Free text as a field that can end a record without breaking it.
For the field a listing puts last because it *is* the rest of the line — a message
body, a preference's description. "The rest of the line" and "anything at all" are not
compatible: a body holding a newline ended its record early and left the remainder
indented under the other columns, reading as a second record with an empty ``TIME``.
A body is also the field a stranger fills in, so that is not a hypothetical shape of
message.
Args:
value: The free text. ``None`` gives :data:`NONE`.
Returns:
The text with its line breaks and tabs escaped.
"""
return NONE if value is None else _escaped(value)
def stamp(when: datetime | None) -> str:
"""Format a timestamp as local ISO-8601 to the second, or :data:`NONE`.
Kept for the times where the instant *is* the fact rather than a way of saying how
long ago something was: the device's own clock, an appointment set with ``--at``, a
live capture's per-row time (every row of which would otherwise read ``now``), and
every column under ``--absolute``.
Stored times are timezone-aware UTC; a naive one is a time whose offset we do not
actually know, which is not a fact and so reads as absent — the same rule
:func:`~meshterm.ui.widgets._age_seconds` applies to ages.
@@ -178,6 +215,31 @@ def stamp(when: datetime | None) -> str:
return when.astimezone().isoformat(timespec="seconds")
def age(when: datetime | None, *, absent: str = NONE) -> str:
"""How long ago ``when`` was: ``now``, ``5m``, ``3h``, ``2d``, ``4w``.
The default time form, and the reason is the premise change: a person at a prompt
reading ``2026-09-07T19:58:53-04:00`` is doing arithmetic to answer "recently?", which
is the question they typed the command to ask. Delegates to
:func:`~meshterm.ui.widgets._format_age` so the two faces cannot drift apart.
Args:
when: The instant to age. A naive datetime has no offset we know, so it reads as
absent, exactly as :func:`stamp` treats it.
absent: What an unknown time reads as. A heard-age passes ``"never"`` — a node
that has never been heard is a fact, not a missing field — and everything else
takes the default token, which says this row has no such time at all. The same
distinction :func:`name` draws between ``-`` and an empty name, one axis over.
Returns:
The age, or ``absent``.
"""
from .widgets import _age_seconds, _format_age
seconds = _age_seconds(when)
return absent if seconds is None else _format_age(seconds)
def number(value: Any, spec: str = "") -> str:
"""Format a number, or :data:`NONE` when it is absent.
@@ -193,13 +255,146 @@ def number(value: Any, spec: str = "") -> str:
return format(value, spec) if spec else str(value)
#: The units :func:`duration` counts in, largest first.
_UNITS: tuple[tuple[int, str], ...] = ((86400, "d"), (3600, "h"), (60, "m"), (1, "s"))
def duration(seconds: float | None) -> str:
"""A span of seconds as something readable: ``93784`` → ``1d 2h``, ``360`` → ``6m``.
Two units at most and always adjacent, so the magnitude arrives at a glance and the
precision never outruns what anyone would act on. Used only as a *gloss* beside the
raw figure (``uptime_s 93784 (1d 2h)``), never in place of it — the key says what
the number counts, and a caller reading the key must still find a number under it.
Args:
seconds: The span. ``None`` reads as absent; the sign is dropped, since a caller
glossing a signed reading says which way in its own words.
Returns:
The span in one or two units, or :data:`NONE`.
"""
if seconds is None:
return NONE
whole = int(abs(seconds))
amounts: list[tuple[int, str]] = []
for size, unit in _UNITS:
amounts.append((whole // size, unit))
whole %= size
lead = next((i for i, (amount, _) in enumerate(amounts) if amount), len(amounts) - 1)
parts = [f"{amounts[lead][0]}{amounts[lead][1]}"]
if lead + 1 < len(amounts) and amounts[lead + 1][0]:
parts.append(f"{amounts[lead + 1][0]}{amounts[lead + 1][1]}")
return " ".join(parts)
def location(lat: float | None, lon: float | None) -> str:
"""A shared position as one field: ``45.50190,-73.56740``, or :data:`NONE`.
One column rather than two. A coordinate pair is one fact to a reader, it is what goes
into a map's search box verbatim, and two columns of ``-`` for every contact that has
never shared a position is worse than one.
Args:
lat: Latitude in decimal degrees.
lon: Longitude in decimal degrees.
Returns:
The pair to five decimals, or :data:`NONE` when either half is missing.
"""
if lat is None or lon is None:
return NONE
return f"{lat:.5f},{lon:.5f}"
def route(hops: Iterable[tuple[str | None, str | None]]) -> str:
"""A walked hop sequence, drawn: ``Yagi-Repeater (a1) → Alice (d4) → Yagi (a1)``.
A *route* is what a walk actually did, so it is a picture and not a spec — which is
why it takes :data:`ARROW` and not the comma ``--path`` accepts. Rendering it with
commas made it look pasteable, which it is not: the names are in it, and it is a
round trip nothing has.
The hash rides on every hop and always. It is the join key to the per-hop table below
a trace, the token ``--path`` takes, and the disambiguator for two contacts sharing a
name. Dropping it "where the name is unique" would make one line's grammar depend on
another line's content.
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; here the line is as often
read out of a file by someone who was not at the prompt when it ran.
Args:
hops: ``(label, hash)`` pairs in propagation order. A hop with both halves reads
``Name (hash)``; a hop with one half is that half alone, never an empty
``()`` — which is how the menu's :class:`~meshterm.ui.pathline.PathLine`
labels an unresolved hop too.
Returns:
The joined route, or :data:`NONE` when there are no hops.
"""
parts: list[str] = []
for label, value in hops:
if label and value:
parts.append(f"{_escaped(label)} ({value})")
else:
parts.append(_escaped(label) if label else (value or NONE))
return ARROW.join(parts) if parts else NONE
def spec(hops: Iterable[str]) -> str:
"""A forced path as the radio was given it: ``a1,d4,a1``.
The other half of the split :func:`route` names. This is the *spec* — comma-separated
hashes, exactly what ``--path`` takes back — so it is the one line on either face that
round-trips, and it must never grow a name, an arrow or a space.
Args:
hops: The hop hashes in propagation order.
Returns:
The comma-joined spec, or :data:`NONE` when there are no hops.
"""
parts = [hop for hop in hops if hop]
return ",".join(parts) if parts else NONE
def path(hops: Iterable[tuple[str, str | None]]) -> str:
"""Render a hop sequence as the CLI's path line.
``"Origin" (3d),"Relay" (f2),"Us" (a1)`` — each node's name quoted (:func:`quote`),
its hash in parentheses *outside* the quotes, hops separated by a bare comma.
The hash is there because the CLI has no colour. On a screen a route's hops are told
apart by their key-derived hues, and matched to a route graph's one-byte labels the
same way; with the colour gone, the hash is what carries that identity.
Our own node is a hop like any other — named and hashed, never the menu's ``★``. The
star says "you already know who this is", which is true of a reader and false of a
parser.
The comma is the separator ``--path`` already takes, and the quoting is what keeps the
line splittable when a name contains one.
Args:
hops: ``(label, hash)`` pairs in propagation order; a ``None`` hash prints the
name alone, for a node whose identity is genuinely unknown.
Returns:
The joined path line, or :data:`NONE` when there are no hops.
"""
parts = [f"{quote(label)} ({value})" if value else quote(label) for label, value in hops]
return ",".join(parts) if parts else NONE
def columns(*headers: str, right: Sequence[str] = ()) -> Table:
"""Build the scripted table: an uppercase header line, then padded records.
The shape ``ps`` and ``df`` print — no box, no title, no edge padding, every column
sized to its widest value and separated by :data:`GUTTER` spaces, nothing wrapped and
nothing elided. Numeric lanes right-align, which is what makes a column of magnitudes
comparable by eye without changing what splitting it yields.
comparable by eye without changing what splitting it yields; an *age* lane aligns the
same way, so the ladder from ``now`` to ``4w`` reads down the column.
Args:
*headers: The column headings, already uppercase.
@@ -240,8 +435,8 @@ def pairs(rows: Iterable[tuple[str, str]]) -> Table:
"""Build the scripted key/value listing: key then value, aligned, no header line.
What a set of facts about one thing prints as (``meshterm info``, ``config show``,
``preferences show``) — the ``sysctl -a`` shape. Keys are the ones the matching
``get``/``set`` subcommand takes, so a line read out of ``show`` can be typed back in.
``trace``) — the ``sysctl -a`` shape. Keys are the ones the matching ``get``/``set``
subcommand takes, so a line read out of ``show`` can be typed back in.
Args:
rows: ``(key, value)`` pairs in display order.
@@ -264,32 +459,97 @@ def pairs(rows: Iterable[tuple[str, str]]) -> Table:
return table
def path(hops: Iterable[tuple[str, str | None]]) -> str:
"""Render a hop sequence as the CLI's path line.
@dataclass(frozen=True, slots=True)
class Lanes:
"""A fixed-width column layout for output whose widths arrive with the data.
``"Origin" (3d),"Relay" (f2),"Us" (a1)`` — each node's name quoted (:func:`quote`),
its hash in parentheses *outside* the quotes, hops separated by a bare comma.
:func:`columns` sizes each lane to its widest value, which it can only do once it has
seen every record. A live capture has no "once": ``monitor`` prints a row the instant
a packet lands, and the row after it may be twice as wide. Those two streams used to
be gutter-joined with no alignment at all, which is why a name in one still carried
its quotes — nothing else said where the field ended.
The hash is there because the CLI has no colour. On a screen a route's hops are told
apart by their key-derived hues, and matched to a route graph's one-byte labels the
same way; with the colour gone, the hash is what carries that identity.
Pinning the lanes up front fixes it properly. A value wider than its lane **overruns
and pushes the rest of that row right** rather than being elided: one row out of many
is simply wider, and nothing lies about what it holds. Put the one unbounded field
(a node's name, a message body) last and it cannot push anything at all.
Our own node is a hop like any other — named and hashed, never the menu's ``★``. The
star says "you already know who this is", which is true of a reader and false of a
parser.
Attributes:
widths: ``(header, width)`` per lane, in order.
right: The headers whose cells right-align.
"""
The comma is the separator ``--path`` already takes, and the quoting is what keeps the
line splittable when a name contains one.
widths: tuple[tuple[str, int], ...]
right: frozenset[str] = frozenset()
@property
def header(self) -> str:
"""The one header line, printed before the first record."""
return self.record(*(header for header, _ in self.widths))
def record(self, *cells: str) -> str:
"""One record, padded into the lanes and joined by the gutter."""
out: list[str] = []
for (header, width), cell in zip(self.widths, cells, strict=True):
out.append(cell.rjust(width) if header in self.right else cell.ljust(width))
return (" " * GUTTER).join(out).rstrip()
def stream(*widths: tuple[str, int], right: Sequence[str] = ()) -> Lanes:
"""Build a fixed-lane layout for a live stream (see :class:`Lanes`).
Args:
hops: ``(label, hash)`` pairs in propagation order; a ``None`` hash prints the
name alone, for a node whose identity is genuinely unknown.
*widths: ``(header, width)`` per lane, in order.
right: The headings whose values right-align.
Returns:
The joined path line, or :data:`NONE` when there are no hops.
The layout, which prints its own header and formats each record.
"""
parts = [f"{quote(label)} ({value})" if value else quote(label) for label, value in hops]
return ",".join(parts) if parts else NONE
return Lanes(widths=widths, right=frozenset(right))
def wrap(body: str, width: int = PAGE_WIDTH) -> str:
"""Fold a written page's paragraphs to ``width``, leaving its structure alone.
The deliberate exception to "no wrapping", and the reason the rule exists says why:
wrapping splits a *record* and lands half its fields under the wrong headings. A
written page has no records and no headings — and left unwrapped, ``meshterm about``
prints paragraphs six hundred cells long that no terminal can read.
A line's own indent is kept and carried onto its continuations, so a bullet stays a
bullet and an indented block stays indented; a blank line stays blank; a line that is
already short is untouched.
Args:
body: The page, as its plain renderer laid it out.
width: The cell width to fold to.
Returns:
The page with every over-long line folded under its own indent.
"""
import textwrap
out: list[str] = []
for line in body.splitlines():
stripped = line.lstrip()
if not stripped:
out.append("")
continue
indent = line[: len(line) - len(stripped)]
# A bullet's continuations hang under its text, not under its marker.
hanging = indent + (" " if stripped[:1] in "-*•" else "")
out.extend(
textwrap.wrap(
stripped,
width=max(width - len(indent), 20),
initial_indent=indent,
subsequent_indent=hanging,
break_long_words=False,
break_on_hyphens=False,
)
or [indent + stripped]
)
return "\n".join(out)
# -- the console ---------------------------------------------------------------------
@@ -385,9 +645,16 @@ def stderr_console() -> Console:
"""The console for everything that is *about* the run rather than part of its answer.
stdout carries what the command was asked for and nothing else, so a progress bar, a
log line and an error message all go here instead — visible in a terminal, absent from
``meshterm contacts > contacts.txt``. This one keeps its colour and its wrapping: a
terminal is the only thing that ever reads it.
log line, an acknowledgement and an error message all go here instead — visible in a
terminal, absent from ``meshterm contacts > contacts.txt``. This one keeps its colour,
because a terminal is usually the only thing that reads it.
**Off a terminal it stops wrapping**, and that is the point of the width below. Rich
falls back to 80 cells when it cannot measure the destination, so ``2> errors.log``
used to hard-wrap every message at 80 — and ``grep 'not already connected'`` then
found nothing, because the sentence it was looking for had been broken across three
lines by the logger. In a real terminal the width is left alone: a progress bar sized
to 16384 cells is not a progress bar.
Returns:
A themed :class:`~rich.console.Console` writing to ``sys.stderr``.
@@ -396,7 +663,17 @@ def stderr_console() -> Console:
from .theme import active_theme
return Console(file=sys.stderr, theme=active_theme(), markup=False, emoji=False)
try:
wraps = bool(sys.stderr.isatty())
except (AttributeError, ValueError): # pragma: no cover - a closed or exotic stream
wraps = False
return Console(
file=sys.stderr,
theme=active_theme(),
markup=False,
emoji=False,
width=None if wraps else WIDTH,
)
# -- the safety net ------------------------------------------------------------------
@@ -405,15 +682,15 @@ def stderr_console() -> Console:
def flatten(renderable: RenderableType) -> list[RenderableType]:
"""Strip framing from anything reaching the scripted console still wearing it.
Every CLI surface is *written* plain — the tools build their output through
:func:`columns`, :func:`pairs` and :func:`path`. This is the net under that, for a
renderable shared with the menu that still arrives boxed: a :class:`Panel` gives up
its border and title and yields its body, a :class:`Table` gives up its box, title and
expansion, and a :class:`Group` is flattened member by member.
Every CLI surface is *written* plain — a tool states its answer as a
:mod:`~meshterm.ui.report` and the plain renderer builds it through :func:`columns`
and :func:`pairs`. This is the net under that, for a renderable shared with the menu
that still arrives boxed: a :class:`Panel` gives up its border and title and yields
its body, a :class:`Table` gives up its box, title and expansion, and a :class:`Group`
is flattened member by member.
It is deliberately not a *design*: a screen's table has the menu's columns, not the
CLI's, so passing it through here makes it printable, not right. Anything a script is
meant to read gets a plain renderer of its own.
CLI's, so passing it through here makes it printable, not right.
Args:
renderable: What a tool handed to :meth:`~meshterm.ui.surface.PlainUi.show`.
+401
View File
@@ -0,0 +1,401 @@
"""Tests for the seam between a tool's answer and its rendering.
:mod:`meshterm.ui.report` is where a tool states what it found, :mod:`meshterm.ui.fields`
is where the shapes it states it in are defined once, and :mod:`meshterm.ui.renderers` is
where that becomes bytes. The claim the whole design rests on is that **one typed row
projects two ways** — so almost every test here builds one report and asserts both faces
of it, because a rule that holds in only one of them is exactly the drift this replaced.
"""
from __future__ import annotations
import io
import json
from datetime import datetime, timezone
import pytest
from meshterm.ui import fields, script
from meshterm.ui.renderers import JsonRenderer, OutputFormat, PlainRenderer, for_format
from meshterm.ui.report import BARE, SILENT, Column, Facts, Lane, Listing
_WHEN = datetime(2026, 9, 7, 22, 22, 41, tzinfo=timezone.utc)
def _plain(*blocks) -> str: # noqa: ANN002 - blocks vary per test
"""Render a report through the plain face and return what came out."""
buffer = io.StringIO()
PlainRenderer(script.console(buffer)).render(blocks)
buffer.flush()
return buffer.getvalue()
def _json(*blocks): # noqa: ANN002, ANN202 - blocks vary per test
"""Render a report through the machine face and return the parsed document."""
buffer = io.StringIO()
JsonRenderer(script.console(buffer)).render(blocks)
lines = [line for line in buffer.getvalue().splitlines() if line]
assert len(lines) == 1, lines
return json.loads(lines[0])
def _contacts(rows) -> Listing: # noqa: ANN001 - rows vary per test
"""A listing in the shape ``contacts`` uses: a node, an age and a count."""
return Listing(
key="contacts",
columns=(
fields.node(
"node",
lanes=(("name", "NAME"), ("type", "TYPE"), ("hash", "HASH"), ("key", "KEY")),
),
fields.when("heard_at", "HEARD", absent="never"),
fields.integer("packets", "PKTS"),
),
rows=rows,
order=("NAME", "TYPE", "HEARD", "PKTS", "HASH", "KEY"),
)
_ALICE = {
"node": fields.NodeRef(name="Alice", key="d4" * 32, hash="d4", type="node"),
"heard_at": _WHEN,
"packets": 12,
}
# -- one row, two faces ----------------------------------------------------------------
def test_one_typed_row_reaches_both_faces_without_either_parsing_the_other() -> None:
"""The claim the seam exists for: a row holds the value, not somebody's rendering.
The plain face writes ``+5.1`` because a column of readings only compares by eye once
every one declares its sign; the document writes ``5.1`` because a number carries its
own. Neither could be derived from the other without a parser, which is what the two
hand-written ``if ctx.json_output:`` branches were.
"""
block = Listing(key="hops", columns=(fields.snr("snr_db", "SNR_DB"),), rows=[{"snr_db": 5.14}])
assert _plain(block).splitlines()[1].strip() == "+5.1"
assert _json(block) == [{"snr_db": 5.1}]
def test_a_node_is_one_object_however_many_columns_it_is_worth() -> None:
"""One machine key, four plain lanes — the thing :func:`fields.node` earns.
Every listing that mentions a node asks for the same column, so ``jq '.[].node.key'``
reads the same on contacts, courier and monitor and a consumer's node handler is
written once. What differs is only how much room the surface has for it.
"""
header, record = _plain(_contacts([_ALICE])).splitlines()
assert header.split() == ["NAME", "TYPE", "HEARD", "PKTS", "HASH", "KEY"]
assert len(record.split()) == len(header.split())
assert "Alice" in record and "d4" * 32 in record
assert _json(_contacts([_ALICE]))[0]["node"] == {
"name": "Alice",
"key": "d4" * 32,
"hash": "d4",
"type": "node",
"self": False,
}
def test_a_listing_may_draw_its_lanes_in_an_order_the_document_does_not_use() -> None:
"""``contacts`` puts HEARD and PKTS between a node's TYPE and its HASH.
The lane order is a reading decision — the fields a person scans first go left — and
the key order is the document's. Tying them together would have meant choosing which
face to make worse.
"""
header = _plain(_contacts([_ALICE])).splitlines()[0].split()
assert header.index("HEARD") < header.index("HASH")
assert list(_json(_contacts([_ALICE]))[0]) == ["node", "heard_at", "packets"]
def test_a_listing_refuses_an_order_that_does_not_name_its_own_lanes() -> None:
"""A typo here draws a listing with a column missing and no complaint.
That is the one failure a header line cannot show — the records still line up, under
the wrong headings — so it is caught where it is written instead.
"""
with pytest.raises(ValueError, match="every lane"):
Listing(
key="x",
columns=(fields.integer("a", "A"), fields.integer("b", "B")),
order=("A", "NOPE"),
)
# -- absences --------------------------------------------------------------------------
def test_the_two_faces_spell_absence_in_their_own_alphabets() -> None:
"""``-`` is learned once by a reader; ``null`` is what a parser already has.
Same fact, and neither face has to know the other's token — which is what stopped the
plain ``-`` from ever reaching a document as a string.
"""
empty = {"node": None, "heard_at": None, "packets": None}
record = _plain(_contacts([empty])).splitlines()[1]
assert record.split() == ["-", "unknown", "never", "-", "-", "-"]
assert _json(_contacts([empty]))[0] == {"node": None, "heard_at": None, "packets": None}
def test_a_word_standing_in_for_an_absence_stays_a_word_only_on_the_plain_face() -> None:
"""``unknown`` is a word a reader acts on; a consumer already has ``null`` for it.
Carrying both would give a program two spellings for one fact and a special case to
remember on every field.
"""
row = {"node": fields.NodeRef(hash="a1")}
block = Listing(key="n", columns=(fields.node("node", lanes=(("type", "TYPE"),)),), rows=[row])
assert _plain(block).splitlines()[1].strip() == "unknown"
assert _json(block)[0]["node"]["type"] is None
def test_a_never_heard_node_is_a_fact_and_an_undated_row_is_an_absence() -> None:
"""Two different things, and the age lane says which without a second column.
A node that has never been heard *has* a heard-age; a row with no such time at all
does not. Flattening both onto ``-`` would have made "we have not heard from it" and
"this kind of row has no heard time" the same reading.
"""
assert script.age(None, absent="never") == "never"
assert script.age(None) == script.NONE
def test_info_leaves_out_a_reading_the_radio_does_not_answer_for_and_json_keeps_the_key() -> None:
"""The one deliberate disagreement between the faces, and why it is deliberate.
A missing plain key says "this radio does not report it", where a dash would claim it
reported nothing — a distinction a person can act on. A consumer cannot, and a
variable key set costs it a membership test on every field, so the document keeps the
key and writes ``null``.
"""
block = Facts(
key="info",
fields=(fields.word("model", "model"), fields.integer("uptime_s", "uptime_s")),
values={"model": None, "uptime_s": 42},
omit_absent=True,
)
assert _plain(block).split() == ["uptime_s", "42"]
assert _json(block) == {"model": None, "uptime_s": 42}
# -- facts, bare and silent ------------------------------------------------------------
def test_a_get_prints_its_value_alone_and_still_documents_the_key() -> None:
"""The caller named the key, so repeating it back is one more thing to strip off.
``$(meshterm config get name)`` needs no stripping — an argument entirely about shell
substitution, which a JSON consumer is not doing, so the document keeps the key, the
type and the label the bare form threw away.
"""
block = Facts(
key="setting",
fields=(
fields.word("key", "key"),
fields.word("value", "value"),
fields.hidden("type"),
),
values={"key": "tx_power", "value": "20", "type": "int"},
shape=BARE,
bare="value",
)
assert _plain(block).strip() == "20"
assert _json(block) == {"key": "tx_power", "value": "20", "type": "int"}
def test_an_acknowledgement_prints_nothing_and_is_still_a_document() -> None:
"""Printing nothing is an answer a person can act on and a program cannot.
``config advert`` says everything it has to say in its exit status, and that is the
right plain answer. A caller that needs to log *what was sent* has nowhere to read it,
which is what the document is for.
"""
block = Facts(
key="advert",
fields=(fields.flag("sent", "sent"), fields.flag("flood", "flood")),
values={"sent": True, "flood": False},
shape=SILENT,
)
assert _plain(block) == ""
assert _json(block) == {"sent": True, "flood": False}
# -- several blocks --------------------------------------------------------------------
def test_a_single_block_report_is_its_block_and_nothing_around_it() -> None:
"""``meshterm contacts --json | jq '.[].node.name'`` reads what it looks like.
There is no envelope: the report a caller needs is ``$?``, exactly as it is without
the flag, so nothing has to be reached through to get at the answer.
"""
assert isinstance(_json(_contacts([_ALICE])), list)
def test_several_blocks_make_one_object_with_the_facts_at_its_top_level() -> None:
"""A trace is a set of facts *and* a per-hop table, and the document says so.
The facts block is the set of facts about the one thing the command answered, so it is
the document rather than a compartment inside it; a listing needs a name and takes its
own key.
"""
facts = Facts(
key="trace", fields=(fields.flag("success", "success"),), values={"success": True}
)
edges = Listing(key="edges", columns=(fields.integer("index", "HOP"),), rows=[{"index": 0}])
assert _json(facts, edges) == {"success": True, "edges": [{"index": 0}]}
assert _plain(facts, edges).splitlines() == ["success yes", "", "HOP", " 0"]
def test_a_block_drawn_only_for_a_person_never_reaches_the_document() -> None:
"""``monitor``'s closing per-node summary is derivable from the records above it.
Emitting it as a second *shape* of line mid-stream would cost every reader a
discriminator it otherwise never needs, so the plain face keeps the aggregate and the
stream stays homogeneous.
"""
facts = Facts(
key="window", fields=(fields.integer("packets", "packets"),), values={"packets": 2}
)
summary = Listing(
key="heard",
columns=(fields.integer("packets", "PKTS"),),
rows=[{"packets": 2}],
plain_only=True,
)
assert "PKTS" in _plain(facts, summary)
assert _json(facts, summary) == {"packets": 2}
# -- the document's own rules ----------------------------------------------------------
def test_a_document_is_one_compact_line_that_never_escapes_a_name() -> None:
r"""A node name in Cyrillic is a node name, not a run of ``\\uXXXX``.
One line, so a stream and a one-shot answer are read the same way and ``jq .`` can
re-indent for a person at no cost. Nothing can un-stream a document that was
pretty-printed across four hundred lines.
"""
buffer = io.StringIO()
row = {"node": fields.NodeRef(name="Наблюдатель", hash="c3")}
block = Listing(key="n", columns=(fields.node("node"),), rows=[row])
JsonRenderer(script.console(buffer)).render((block,))
out = buffer.getvalue()
assert out.endswith("\n") and out.count("\n") == 1
assert "Наблюдатель" in out
assert ", " not in out and ": " not in out
def test_every_time_in_a_document_is_utc_to_the_second() -> None:
"""Twenty characters, always, so string comparison is time comparison.
A local offset is a fact about the machine that ran the command rather than about the
event, and two hosts asking the same radio the same question must produce the same
document.
"""
stamped = _json(_contacts([_ALICE]))[0]["heard_at"]
assert stamped == "2026-09-07T22:22:41Z"
assert len(stamped) == 20
def test_a_time_whose_offset_we_do_not_know_is_absent_on_both_faces() -> None:
"""A naive datetime is not a fact, and neither face may invent an offset for it."""
naive = {"node": None, "heard_at": datetime(2026, 9, 7, 22, 22, 41), "packets": None}
assert "2026" not in _plain(_contacts([naive]))
assert _json(_contacts([naive]))[0]["heard_at"] is None
def test_a_concept_may_have_a_face_on_only_one_side() -> None:
"""Both directions, and each has a real call site.
A preference's DESCRIPTION is prose for whoever is choosing a value and carries
nothing a program would branch on; a setting's declared type is the reverse — a fact
the document wants and a reader dumping ``config show`` does not.
"""
block = Listing(
key="prefs",
columns=(
fields.word("key", "PREFERENCE"),
fields.note("help", "DESCRIPTION"),
fields.hidden("type"),
),
rows=[{"key": "trace_cooldown_s", "help": "Wait this long", "type": "int"}],
)
assert "Wait this long" in _plain(block)
assert _json(block) == [{"key": "trace_cooldown_s", "type": "int"}]
# -- streams ---------------------------------------------------------------------------
def _stream_listing() -> Listing:
"""A live listing in the shape ``monitor`` uses: pinned lanes, the name last."""
return Listing(
key="observations",
columns=(
fields.instant("observed_at", "TIME"),
fields.node("node", lanes=(("hash", "NODE"), ("name", "NAME"))),
),
order=("TIME", "NODE", "NAME"),
)
def test_a_stream_pins_its_lanes_because_the_widths_arrive_with_the_data() -> None:
"""A live capture has no "once every record is in", which is when columns are sized.
Both streams used to be gutter-joined with no alignment at all, which is why a name in
one still carried its quotes — nothing else said where the field ended.
"""
buffer = io.StringIO()
listing = _stream_listing()
with PlainRenderer(script.console(buffer)).stream(listing) as row:
row({"observed_at": _WHEN, "node": fields.NodeRef(name="Alice", hash="d4e5f6a7")})
row({"observed_at": _WHEN, "node": fields.NodeRef(name="A Very Long Node Name", hash="c3")})
header, first, second = buffer.getvalue().splitlines()
assert header.split() == ["TIME", "NODE", "NAME"]
assert first.index("d4e5f6a7") == second.index("c3")
def test_a_streamed_document_is_one_record_per_line_all_the_same_shape() -> None:
"""A consumer reads line by line and never has to ask which kind of record it holds."""
buffer = io.StringIO()
listing = _stream_listing()
with JsonRenderer(script.console(buffer)).stream(listing) as row:
row({"observed_at": _WHEN, "node": fields.NodeRef(hash="d4")})
row({"observed_at": _WHEN, "node": fields.NodeRef(hash="a1")})
documents = [json.loads(line) for line in buffer.getvalue().splitlines()]
assert [set(d) for d in documents] == [{"observed_at", "node"}] * 2
assert [d["node"]["hash"] for d in documents] == ["d4", "a1"]
# -- the boundary ----------------------------------------------------------------------
def test_the_format_picks_the_renderer_and_nothing_else_does() -> None:
"""One choice, made once, at the one place that knows what the caller asked for."""
console = script.console(io.StringIO())
assert isinstance(for_format(OutputFormat.PLAIN, console), PlainRenderer)
assert isinstance(for_format(OutputFormat.JSON, console), JsonRenderer)
def test_a_tool_with_no_scripted_face_renders_nothing_at_all() -> None:
"""The map and the dashboard state no report, and both renderers must be fine with it."""
assert _plain() == ""
buffer = io.StringIO()
JsonRenderer(script.console(buffer)).render(None)
assert buffer.getvalue() == ""
def test_a_lane_and_a_column_are_separable_so_a_third_format_needs_neither() -> None:
"""The point of the split, stated as a test: a format is a function of the typed row.
A renderer that wanted CSV would read the same columns and the same rows and write its
own cells. Nothing about the report knows a gutter, a comma or a brace.
"""
column = Column(key="n", lanes=(Lane(header="N", render=lambda v: f"<{v}>"),))
assert column.lanes[0].render(3) == "<3>"
assert column.json(3) == 3