pybricks-cli 1.0.0b1__py3-none-any.whl

pb_cli/__init__.py

@@ -0,0 +1,8 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 The Pybricks Authors
+
+"""The Pybricks command line interface."""
+
+__version__ = "1.0.0b1"
+
+__all__ = ["__version__"]

pb_cli/__main__.py

@@ -0,0 +1,7 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 The Pybricks Authors
+
+from pb_cli.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pb_cli/app.py

@@ -0,0 +1,127 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 The Pybricks Authors
+
+"""The command line's shape: the app itself, its groups, and shared options.
+
+Separate from the commands so that the command modules can all import it
+without importing each other. :mod:`pb_cli.cli` pulls those modules in, which is
+what registers them.
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+from collections.abc import Sequence
+from typing import Annotated
+
+import cyclopts
+
+from pb_cli import __version__
+from pb_cli.config import config_sources
+from pb_core.logging import TRACE, setup_logging
+
+__all__ = [
+    "HUB_COMMANDS",
+    "PROGRAM_COMMANDS",
+    "SERVICE_COMMANDS",
+    "Verbose",
+    "app",
+    "configure_logging",
+    "service_app",
+]
+
+app = cyclopts.App(
+    name="pb",
+    version=__version__,
+    help=(
+        "Talk to Pybricks hubs.\n\n"
+        "A hub stays connected between commands, so you only need to run "
+        "pb connect once."
+    ),
+    # Every command is in a group of its own, so what is left in the default
+    # panel is --help and --version. Calling that panel "Commands" would be a
+    # lie, and putting it last keeps the commands at the top where someone
+    # reading the help is looking.
+    group_commands=cyclopts.Group("Options", sort_key=3),
+    config=config_sources(),
+)
+
+HUB_COMMANDS = cyclopts.Group("Hubs", sort_key=0)
+"""Finding a hub, holding on to one, and asking what it is doing.
+
+Ordered by what someone actually has to do, which is why each command carries
+an explicit ``sort_key`` rather than falling back to alphabetical. ``connect``
+comes first, because it is the one command nobody gets anywhere without, with
+its opposite ``disconnect`` beside it.
+
+The rest are things a user may want rather than steps they must take, so they
+come after: ``status`` and ``list`` report on what is already connected, and
+``scan`` comes last because nobody has to run it at all -- ``connect`` does its
+own looking, and ``connect --scan`` shows the same list when the choice
+matters.
+"""
+
+PROGRAM_COMMANDS = cyclopts.Group("Programs", sort_key=1)
+"""Getting a program onto a hub and controlling it once it is there."""
+
+SERVICE_COMMANDS = cyclopts.Group("Background service", sort_key=2)
+"""The thing holding the connections open. Rarely needed, so it comes last."""
+
+service_app = cyclopts.App(
+    name="service",
+    help="Manage the background service that keeps hubs connected.",
+    group=SERVICE_COMMANDS,
+    # Not inherited from the root app, where the default panel holds only the
+    # flags: down here it really is the list of commands.
+    group_commands=cyclopts.Group("Commands"),
+)
+app.command(service_app)
+
+
+Verbose = Annotated[
+    Sequence[bool],
+    cyclopts.Parameter(
+        name=["-v", "--verbose"],
+        help="Increase log detail. Repeat for more (-v, -vv, -vvv).",
+        show_default=False,
+        # No --no-verbose: there is nothing to turn off, and offering it
+        # would be one more thing in every command's help for no reason.
+        negative=(),
+    ),
+]
+"""How loud to be, counted rather than measured.
+
+A sequence of flags rather than a number, because that is what makes the help
+true. As an ``int`` this took a value -- ``-v 1`` worked and ``-v`` was an
+error saying it "requires an argument", while every command's help said to
+repeat it. Collecting the flags gives ``-v``, ``-v -v`` and the stacked
+``-vv``, which is what anybody typing it expects.
+"""
+
+
+def configure_logging(verbose: Verbose | int = ()) -> None:
+    """Map repeated ``-v`` flags onto log levels.
+
+    Args:
+        verbose: The flags as they were given, or how many there
+            were. Both, because the commands hand over what they
+            were passed and a count reads better everywhere else.
+    """
+    count = verbose if isinstance(verbose, int) else len(verbose)
+    if count <= 0:
+        level = logging.WARNING
+    elif count == 1:
+        level = logging.INFO
+    elif count == 2:
+        level = logging.DEBUG
+    else:
+        level = TRACE
+
+    setup_logging(
+        level=level,
+        style="rich" if sys.stderr.isatty() else "plain",
+        # bleak is noisy enough to bury our own lines, and is only interesting
+        # once someone is debugging the radio itself.
+        quiet_loggers=("bleak", "asyncio") if count < 3 else (),
+    )

pb_cli/banner.py

@@ -0,0 +1,338 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 The Pybricks Authors
+
+"""The status line along the bottom of an interactive session.
+
+Pybricks Code keeps a bar at the foot of its window naming the hub and showing
+its battery, and it is genuinely useful: what a user needs to know while typing
+at a hub is which hub they are typing at, whether anything is listening, and
+whether the battery is about to end the conversation. None of that belongs in
+the scrolling text, where it would be pushed away by the next line of output.
+
+**The line is pinned with a scrolling margin** -- ``DECSTBM``, which every
+terminal in use here supports, conhost included. With the margin set to every
+row but the last, the hub's output scrolls in the region above and the bottom
+row is simply never touched by it. The hub's own line editing then behaves
+exactly as it would with no status line at all, which matters more than it
+sounds: the interpreter moves the cursor about as it echoes, and any scheme
+that redrew the bar around that editing would fight it on every keystroke.
+
+The alternate screen buffer was the other candidate and is what a full-screen
+program would normally use. It is not used here because leaving it takes the
+whole session with it, and the last thing printed at a REPL is usually the
+thing you wanted to keep.
+
+**Nothing here draws with rich.** In raw mode a bare newline does not return
+the carriage, so every line this module writes ends with a carriage return of
+its own, and a library that emits its own newlines would staircase down the
+screen instead.
+"""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Final
+
+import pb_client
+from pb_cli import escape
+from pb_cli.console import Console
+
+__all__ = ["NOTICE_SECONDS", "WARNINGS", "Banner", "describe_running"]
+
+NOTICE_SECONDS: Final = 4.0
+"""How long a passing message stays in the status line before it fades."""
+
+WARNINGS: Final[Mapping[str, str]] = {
+    "BATTERY_LOW_VOLTAGE_SHUTDOWN": "battery empty",
+    "BATTERY_HIGH_TEMP_SHUTDOWN": "battery too hot",
+    "BATTERY_LOW_VOLTAGE_WARNING": "battery low",
+    "BATTERY_HIGH_TEMP_WARNING": "battery hot",
+    "BATTERY_HIGH_CURRENT": "drawing too much",
+    "BLE_LOW_SIGNAL": "weak signal",
+    "SHUTDOWN_REQUEST": "switching off",
+}
+"""Status flags worth a word in the bar, worst first.
+
+Only one is shown, because the bar has one line and the worst of them is the
+one that matters. Ordinary states -- connected, advertising, a program running
+-- are missing on purpose: they are either uninteresting or already said.
+
+The battery is low or it is not: the hub reports two bits about it and no
+level, so there is nothing here to draw a gauge from. See "Wanted from the
+firmware" in the design notes.
+"""
+
+_SET_MARGIN = "\x1b[1;{bottom}r"
+_RESET_MARGIN = "\x1b[r"
+_SAVE_CURSOR = "\x1b7"
+_RESTORE_CURSOR = "\x1b8"
+_GOTO = "\x1b[{row};1H"
+_CLEAR_LINE = "\x1b[2K"
+_REVERSE = "\x1b[7m"
+_NORMAL = "\x1b[0m"
+
+_SEPARATOR = "  "
+
+
+def describe_running(status: pb_client.Status | None) -> str:
+    """Say what the hub is doing, in the words a user would use.
+
+    Args:
+        status: The hub's last report, or ``None`` if it has not made one.
+
+    Returns:
+        A short phrase for the status line.
+    """
+
+    if status is None:
+        return "waiting for the hub"
+
+    if status.repl_running:
+        return "REPL"
+
+    if status.program_running:
+        return "program running"
+
+    return "nothing running"
+
+
+def worst_warning(status: pb_client.Status | None) -> str | None:
+    """Return the most serious thing the hub is complaining about.
+
+    Args:
+        status: The hub's last report.
+
+    Returns:
+        The warning to show, or ``None`` if all is well.
+    """
+
+    if status is None:
+        return None
+
+    for flag, text in WARNINGS.items():
+        if flag in status.names:
+            return text
+
+    return None
+
+
+@dataclass
+class _Layout:
+    """What the status line says, before it is fitted to the screen."""
+
+    left: str
+    right: str
+
+    def fit(self, columns: int) -> str:
+        """Lay the two halves out across the given width.
+
+        Args:
+            columns: How wide the terminal is.
+
+        Returns:
+            One line of exactly ``columns - 1`` characters. One short of the
+            width on purpose: writing the last cell of the last row makes some
+            terminals scroll, which would take the status line with it.
+        """
+        width = max(1, columns - 1)
+        right = self.right if len(self.left) + len(self.right) + 2 <= width else ""
+        room = width - len(right)
+        left = self.left[: max(0, room)]
+        return f"{left}{' ' * (room - len(left))}{right}"
+
+
+class Banner:
+    """The status line, and the terminal region it lives outside of."""
+
+    def __init__(self, console: Console, hub: pb_client.HubInfo) -> None:
+        """Prepare a status line for one hub's session.
+
+        Args:
+            console: The terminal, already in raw mode.
+            hub: The hub being talked to, for the part of the line that never
+                changes.
+        """
+        self._console = console
+        self._hub = hub
+        self._status: pb_client.Status | None = None
+        self._notice: str | None = None
+        self._notice_until = 0.0
+        self._size = (0, 0)
+        self._drawn: str | None = None
+        self._active = False
+
+    # ------------------------------------------------------------- lifecycle
+
+    def __enter__(self) -> Banner:
+        """Reserve the bottom row and start drawing there.
+
+        Returns:
+            This banner.
+        """
+        columns, rows = self._console.size()
+        self._size = (columns, rows)
+        # A fresh line first, so the row about to be reserved is not the one
+        # the shell's prompt is sitting on.
+        self._console.write(b"\r\n")
+
+        if rows >= 2:
+            self._write(_SET_MARGIN.format(bottom=rows - 1))
+            self._write(_GOTO.format(row=rows - 1))
+
+        self._active = True
+        self.draw()
+        return self
+
+    def __exit__(self, *exc: object) -> bool:
+        """Give the bottom row back and leave the cursor on it.
+
+        Synchronous, so no cancellation can skip it: a terminal left with a
+        scrolling margin set is as broken as one left in raw mode, and in the
+        same invisible way.
+
+        Args:
+            *exc: The exception being propagated, if any.
+
+        Returns:
+            False, so nothing is swallowed.
+        """
+        self._active = False
+        _columns, rows = self._size
+        self._write(_RESET_MARGIN)
+
+        if rows >= 1:
+            self._write(_GOTO.format(row=rows) + _CLEAR_LINE)
+
+        return False
+
+    # ---------------------------------------------------------------- output
+
+    def write(self, data: bytes) -> None:
+        """Put the hub's output on the screen, above the status line.
+
+        Args:
+            data: The bytes from the hub, exactly as they arrived.
+        """
+        self._console.write(data)
+
+    def line(self, text: str) -> None:
+        """Print one of our own lines into the session.
+
+        Args:
+            text: What to say. A carriage return is added as well as the
+                newline, since output processing is off in raw mode.
+        """
+        self._console.write(text.encode("utf-8", "replace") + b"\r\n")
+
+    # ---------------------------------------------------------------- status
+
+    def update(self, status: pb_client.Status) -> None:
+        """Take a new status report.
+
+        Args:
+            status: What the hub now says about itself.
+        """
+        self._status = status
+        self.draw()
+
+    def notice(self, text: str) -> None:
+        """Say something in the status line for a few seconds.
+
+        For the things that are worth mentioning but not worth interrupting
+        the session's text for: an input the hub would not take, an unknown
+        escape command.
+
+        Args:
+            text: The message.
+        """
+        self._notice = text
+        self._notice_until = time.monotonic() + NOTICE_SECONDS
+        self.draw()
+
+    def tick(self) -> None:
+        """Redraw if anything that is not an event has changed.
+
+        Covers the two things nothing tells us about: the window being
+        resized, and a passing message reaching its end. Called on a timer, so
+        it must be cheap and must not draw when nothing has changed.
+        """
+
+        if self._console.size() != self._size:
+            self._resize()
+        elif self._notice is not None and time.monotonic() >= self._notice_until:
+            self._notice = None
+            self.draw()
+
+    def _resize(self) -> None:
+        """Move the status line to the new bottom row."""
+        columns, rows = self._console.size()
+        self._size = (columns, rows)
+        self._drawn = None
+
+        if rows >= 2:
+            self._write(_SET_MARGIN.format(bottom=rows - 1))
+
+        self.draw()
+
+    # --------------------------------------------------------------- drawing
+
+    def compose(self) -> str:
+        """Build the status line's text.
+
+        Returns:
+            The line, before it is fitted to the terminal's width.
+        """
+        parts = [self._hub.name]
+
+        if self._hub.hub_type:
+            parts.append(self._hub.hub_type)
+
+        parts.append(describe_running(self._status))
+        warning = worst_warning(self._status)
+        if warning:
+            parts.append(warning)
+
+        if self._notice:
+            parts.append(self._notice)
+
+        left = _SEPARATOR.join(parts)
+        stop = escape.describe(escape.STOP_KEY)
+        # A panic key nobody knows about is not a panic key, so it is on the
+        # line for the whole session rather than only in the opening lines,
+        # which have scrolled away by the time anybody wants it. It goes with
+        # the help, and _Layout drops both together on a narrow terminal.
+        right = f"{stop} {stop} stops{_SEPARATOR}{escape.describe()} h for help"
+        columns, _rows = self._size
+        return _Layout(left, right).fit(columns)
+
+    def draw(self) -> None:
+        """Put the status line on the screen, if it has changed."""
+
+        if not self._active:
+            return
+
+        _columns, rows = self._size
+        if rows < 2:
+            # No room for a line of our own. The session still works.
+            return
+
+        text = self.compose()
+        if text == self._drawn:
+            return
+
+        self._drawn = text
+        self._write(
+            _SAVE_CURSOR
+            + _GOTO.format(row=rows)
+            + _CLEAR_LINE
+            + _REVERSE
+            + text
+            + _NORMAL
+            + _RESTORE_CURSOR
+        )
+
+    def _write(self, text: str) -> None:
+        """Write one of our own control sequences."""
+        self._console.write(text.encode("ascii", "replace"))

pb_cli/cli.py

@@ -0,0 +1,123 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 The Pybricks Authors
+
+"""The ``pb`` command line.
+
+This module is the entry point and little else. The commands live in
+:mod:`pb_cli.commands`, one module per group of the help, and importing them
+here is what registers them with the app -- the same arrangement the service
+uses for its RPC methods.
+
+Three rules shape the whole package. Data goes to stdout and everything else --
+progress, spinners, logs, prompts -- goes to stderr, so piping a command into
+another program stays clean; :mod:`pb_cli.ui` is where that is enforced. Commands
+are thin: they parse arguments, call ``pb_client``, and render, with no
+protocol logic anywhere in this package. And no command catches its own
+failures, because a task group would have wrapped them in an ``ExceptionGroup``
+anyway -- :mod:`pb_cli.errors` does that in one place, for all of them.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Annotated
+
+import cyclopts
+
+# Imported for the side effect: importing a command module registers it with
+# the app, so nothing here reads the names. Said on each line, because a
+# comment is not something a linter can read.
+import pb_cli.commands.hub  # pyright: ignore[reportUnusedImport]
+import pb_cli.commands.program  # pyright: ignore[reportUnusedImport]
+import pb_cli.commands.repl  # pyright: ignore[reportUnusedImport]
+import pb_cli.commands.service  # noqa: F401 # pyright: ignore[reportUnusedImport]
+from pb_cli import ui
+from pb_cli.app import app
+from pb_cli.config import (
+    KNOWN_KEYS,
+    ProjectConfigError,
+    check_project_file,
+    config_sources,
+    find_project_file,
+)
+from pb_cli.errors import EXIT_OK
+
+__all__ = ["app", "launcher", "main"]
+
+
+@app.meta.default
+def launcher(
+    *tokens: Annotated[str, cyclopts.Parameter(show=False, allow_leading_hyphen=True)],
+    directory: Annotated[
+        Path | None,
+        cyclopts.Parameter(
+            # The long name first, because it is what names the environment
+            # variable: with -C first that came out as PB_C, which says
+            # nothing. Both spellings work either way, and -C is the one
+            # anybody will type.
+            name=["--directory", "-C"],
+            show_default=False,
+            # The same panel --help and --version are in, rather than a
+            # "Parameters" panel of its own above the commands. Somebody
+            # reading the help is looking for the commands first.
+            group=cyclopts.Group("Options", sort_key=3),
+        ),
+    ] = None,
+) -> int:
+    """Run a command, optionally as if from somewhere else.
+
+    Args:
+        tokens: The command to run, and its arguments.
+        directory: Work as if run from here, the way ``git -C`` does. Point it
+            at the directory holding a project's ``pyproject.toml``, or at the
+            root of the source when there is no project file. It settles which
+            project's settings apply, what a relative path means, and where a
+            program's imports resolve from -- which is what makes a monorepo of
+            several robot projects work from any shell.
+
+    Returns:
+        The process exit code.
+    """
+
+    if directory is not None:
+        try:
+            os.chdir(directory)
+        except OSError as exc:
+            # A directory that is not there is a typo, not a crash.
+            reason = exc.strerror or str(exc)
+            return ui.usage(
+                f"Cannot work from {directory}: {reason.lower()}.",
+                "Give [bold]-C[/] a directory that exists.",
+            )
+
+    try:
+        # After the change of directory and before the command runs: a project
+        # file that says something unrecognised should be reported rather than
+        # quietly not applied, and which file that is depends on -C.
+        check_project_file()
+        # Hand cyclopts the file this found, rather than letting it search on
+        # its own and stop at the first pyproject.toml. See find_project_file.
+        app.config = config_sources(find_project_file())
+    except ProjectConfigError as exc:
+        return ui.usage(
+            str(exc),
+            # The square bracket is escaped: rich reads "[tool.pb]" as a style
+            # tag and swallows it, which is how this line first came out as
+            # "Check ...toml.  understands hub."
+            f"Check [bold]{exc.path}[/]. [bold]\\[tool.pb][/] understands "
+            f"{', '.join(sorted(KNOWN_KEYS))}.",
+        )
+
+    result = app(tokens)
+    return result if isinstance(result, int) else EXIT_OK
+
+
+def main() -> int:
+    """Run the CLI.
+
+    Returns:
+        The process exit code.
+    """
+    result = app.meta()
+    return result if isinstance(result, int) else EXIT_OK

pb_cli/commands/__init__.py

@@ -0,0 +1,16 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 The Pybricks Authors
+
+"""The commands ``pb`` offers, grouped the way its help groups them.
+
+One module per group -- :mod:`pb_cli.commands.hub` for finding and holding a hub,
+:mod:`pb_cli.commands.program` for getting programs onto it, :mod:`pb_cli.commands.repl`
+for talking to it directly, and :mod:`pb_cli.commands.service` for the thing that
+keeps the connection open.
+
+Importing a module is what registers its commands with the application in
+:mod:`pb_cli.app`, so :mod:`pb_cli.cli` imports them all and there is no second list of
+commands to keep in step with this one.
+"""
+
+from __future__ import annotations