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:
1 parent
59f10f904c
commit
1c24f9149d
9 files changed
+1776
-41
No files matched your search
+58
-8
@@ -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
@@ -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)
|
||||
|
||||
@@ -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",
|
||||
|
||||
@@ -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):
|
||||
|
||||
@@ -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"
|
||||
@@ -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)
|
||||
@@ -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
@@ -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`.
|
||||
|
||||
@@ -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
|
||||
Reference in new issue
Block a user