pybricks-cli 1.0.0b1__py3-none-any.whl

pb_cli/commands/service.py

@@ -0,0 +1,369 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 The Pybricks Authors
+
+"""Managing the background service that keeps hubs connected.
+
+Rarely needed: the service starts by itself when something wants it and stops
+when nothing has for a while. These exist for the times it has to be looked at
+directly -- after an upgrade, or when a hub is behaving oddly and the log is
+the only place the reason will be.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import logging
+from contextlib import aclosing
+from pathlib import Path
+from typing import Annotated, NamedTuple
+
+import anyio
+import cyclopts
+from rich.console import Console
+
+# The unknown here is watchfiles' own AnyEvent union, which names trio's
+# Event as one of the things a stop_event may be. trio is not installed and
+# never will be -- bleak pins this to asyncio -- and nothing here passes a
+# stop_event at all, since aclosing is what stops the watch.
+from watchfiles import awatch  # pyright: ignore[reportUnknownVariableType]
+
+import pb_client
+from pb_cli import errors, ui
+from pb_cli.app import Verbose, configure_logging, service_app
+from pb_cli.errors import EXIT_OK
+from pb_core.paths import log_file
+
+logger = logging.getLogger(__name__)
+
+__all__ = [
+    "service_log",
+    "service_start",
+    "service_status",
+    "service_stop",
+]
+
+_HANDLED_HERE = (pb_client.PbClientError, BaseExceptionGroup)
+"""What to catch when a command deals with a failure itself.
+
+Catching the error's own type is not enough: anything raised inside an
+``async with pb_client.connect()`` block comes back wrapped in a group of one,
+so the type to catch is not the type that was raised.
+"""
+
+
+@service_app.command(name="status")
+async def service_status(*, verbose: Verbose = (), start: bool = False) -> int:
+    """Show whether the background service is running.
+
+    Args:
+        verbose: Increase log detail.
+        start: Start the service if it is not running, instead of reporting
+            that it is not.
+    """
+    configure_logging(verbose)
+    return await errors.run(_service_status, start)
+
+
+async def _service_status(start: bool) -> int:
+    out, err = ui.console(), ui.console(err=True)
+
+    try:
+        async with pb_client.connect(autostart=start) as service:
+            info = await service.info()
+    except _HANDLED_HERE as exc:
+        # "It is not running" is the answer to the question, not a failure to
+        # answer it, so it is reported here rather than as an error.
+        if errors.find(exc, pb_client.ServiceUnavailable) is None:
+            raise
+
+        err.print("[yellow]Not running.[/]")
+        err.print("It starts by itself when needed, or run [bold]pb service start[/].")
+        return errors.EXIT_NOTHING_CONNECTED
+
+    ui.rows(
+        out,
+        [
+            ("status", "running"),
+            ("version", info.version),
+            ("protocol", str(info.protocol_version)),
+            ("pid", str(info.pid)),
+            ("uptime_s", f"{info.uptime_s:.1f}"),
+            ("endpoint", info.endpoint),
+            ("clients", str(info.clients)),
+            ("log", info.log_file),
+        ],
+    )
+    return EXIT_OK
+
+
+@service_app.command(name="start")
+async def service_start(*, verbose: Verbose = ()) -> int:
+    """Start the background service if it is not already running.
+
+    Args:
+        verbose: Increase log detail.
+    """
+    configure_logging(verbose)
+    return await errors.run(_service_start)
+
+
+async def _service_start() -> int:
+    err = ui.console(err=True)
+
+    async with pb_client.connect(autostart=True) as service:
+        info = await service.info()
+
+    err.print(f"Running (pid {info.pid}).")
+    return EXIT_OK
+
+
+@service_app.command(name="stop")
+async def service_stop(*, verbose: Verbose = ()) -> int:
+    """Stop the background service, disconnecting any hubs.
+
+    Args:
+        verbose: Increase log detail.
+    """
+    configure_logging(verbose)
+    return await errors.run(_service_stop)
+
+
+async def _service_stop() -> int:
+    err = ui.console(err=True)
+
+    try:
+        async with pb_client.connect(autostart=False) as service:
+            await service.shutdown()
+    except _HANDLED_HERE as exc:
+        # Stopping something that is already stopped succeeded.
+        if errors.find(exc, pb_client.ServiceUnavailable) is None:
+            raise
+
+        err.print("Not running.")
+        return EXIT_OK
+
+    err.print("Stopping.")
+    return EXIT_OK
+
+
+TAIL_BYTES = 1024 * 1024
+"""How much of the end of the log to read when only the last lines are wanted.
+
+The file rotates at 2 MiB, so this is most of one, and it saves reading all of
+a large file to answer a question about its last few lines.
+"""
+
+FOLLOW_STEP_MS = 20
+"""How long the watcher waits for quiet before reporting what it has seen.
+
+The pause after a burst of writing, so a line reaches the screen about as fast
+as the terminal can draw it.
+"""
+
+FOLLOW_DEBOUNCE_MS = 100
+"""The longest the watcher groups changes before reporting them anyway.
+
+A log being written steadily never goes quiet for :data:`FOLLOW_STEP_MS`, so
+without this it would be reported only when the writing paused. The library's
+own default is 1600 ms, which is fine for rebuilding a project and far too slow
+for watching output arrive.
+"""
+
+
+@service_app.command(name="log")
+async def service_log(
+    *,
+    lines: int = 50,
+    follow: Annotated[bool, cyclopts.Parameter(name=["-f", "--follow"])] = False,
+    verbose: Verbose = (),
+) -> int:
+    """Show what the background service has been doing.
+
+    The service has no terminal of its own, so its log is the only place its
+    side of the story is written down. This reads the file directly and never
+    contacts the service, which means it still works when the service is not
+    running -- which is when it is most likely to be wanted.
+
+    Args:
+        lines: How many lines from the end to show. Zero shows the whole file.
+        follow: Keep watching, printing new lines as they arrive. Ctrl-C
+            leaves.
+        verbose: Increase log detail.
+    """
+    configure_logging(verbose)
+    return await errors.run(_service_log, lines, follow)
+
+
+async def _service_log(lines: int, follow: bool) -> int:
+    out, err = ui.console(), ui.console(err=True)
+    path = log_file()
+    if not path.is_file():
+        # Nothing written is an answer rather than a failure: the service has
+        # not run since this machine last tidied up after it.
+        err.print("The background service has not written a log yet.")
+        err.print("It starts by itself when needed, or run [bold]pb service start[/].")
+        return EXIT_OK
+
+    offset = _print_the_end(out, path, lines)
+
+    if not follow:
+        return EXIT_OK
+
+    err.print(f"Watching [bold]{path}[/]. Ctrl-C to stop.")
+
+    with contextlib.suppress(KeyboardInterrupt):
+        # Caught rather than left to the top level: Ctrl-C is how this command
+        # is meant to end, so it is not an interruption of anything.
+        await _follow(out, path, offset)
+
+    return EXIT_OK
+
+
+def _print_the_end(out: Console, path: Path, lines: int) -> int:
+    """Print the last of the log, and say where reading reached.
+
+    Args:
+        out: Where the lines go.
+        path: The log file.
+        lines: How many to print, or zero for all of them.
+
+    Returns:
+        The offset reading reached, for following on from.
+    """
+    end = path.stat().st_size
+    start = max(0, end - TAIL_BYTES) if lines > 0 else 0
+
+    with path.open("rb") as handle:
+        handle.seek(start)
+        block = handle.read()
+
+    if start:
+        # The seek lands in the middle of a line, and half a line is worse
+        # than one line fewer.
+        block = block.split(b"\n", 1)[-1]
+
+    text = _decode(block).splitlines()
+
+    for line in text[-lines:] if lines > 0 else text:
+        ui.plain(out, line)
+
+    return end
+
+
+async def _follow(out: Console, path: Path, offset: int) -> None:
+    """Print what is added to the log, until the caller is interrupted.
+
+    Waits to be told rather than asking. The directory is watched rather than
+    the file, because a tail has two questions and only one of them is about
+    the file it is holding: the log rotates at 2 MiB, and the replacement
+    arriving is a change to the directory.
+
+    Args:
+        out: Where the lines go.
+        path: The log file.
+        offset: Where reading has already reached.
+    """
+    # anyio's Path, not pathlib's: this runs for as long as somebody watches,
+    # and a file system that has gone slow -- a network drive, a sleeping disk
+    # -- must not stall the event loop it is running in.
+    watched = anyio.Path(path)
+    state = _Tail(offset=offset)
+    # Once before waiting, since the service may have written something
+    # between the tail above and the watch starting, and a line missed here
+    # would never be reported by any later change.
+    state = await _drain(out, watched, state)
+
+    # aclosing because this generator holds a thread and the watcher behind
+    # it, released when its stop event is set on the way out. Leaving on
+    # Ctrl-C is the ordinary way this command ends, so that path is the one
+    # that has to be tidy. See the async rules in CONTRIBUTING.md.
+    async with aclosing(
+        awatch(
+            path.parent,
+            # Every change, rather than the library's default filter, which
+            # exists for source trees and has opinions about file names.
+            watch_filter=None,
+            recursive=False,
+            step=FOLLOW_STEP_MS,
+            debounce=FOLLOW_DEBOUNCE_MS,
+            # Overriding watchfiles' own choice, deliberately and with a
+            # measurement behind it. It turns polling on automatically for the
+            # whole of WSL, because inotify does not work for files on a
+            # Windows drive mounted through drvfs -- but its polling reports
+            # *nothing at all* for a file on tmpfs, measured on WSL2 with
+            # Ubuntu 26.04: three appends over a second, and no event in the
+            # three seconds that followed. The same watch with this set to
+            # False reported every one of them 20 ms after it happened. The
+            # log lives in the state directory, which on WSL is inside the
+            # Linux file system where inotify works. A log on a Windows drive
+            # is the case this gives up on, and it is the case where the
+            # alternative reports nothing anyway.
+            force_polling=False,
+        )
+    ) as changes:
+        async for _ in changes:
+            state = await _drain(out, watched, state)
+
+
+class _Tail(NamedTuple):
+    """Where reading has reached, and the part of a line still waiting."""
+
+    offset: int
+    """How much of the file has been read."""
+
+    pending: bytes = b""
+    """Bytes after the last newline, held back until the rest arrives."""
+
+
+async def _drain(out: Console, watched: anyio.Path, state: _Tail) -> _Tail:
+    """Print whatever has been added since the last read.
+
+    Args:
+        out: Where the lines go.
+        watched: The log file.
+        state: Where reading had reached.
+
+    Returns:
+        Where reading has reached now.
+    """
+
+    try:
+        size = (await watched.stat()).st_size
+    except FileNotFoundError:
+        # Rotated away, and the replacement is not there yet.
+        return _Tail(offset=0)
+
+    if size < state.offset:
+        # Rotated: what is here now is a new file, so a position from the old
+        # one means nothing.
+        state = _Tail(offset=0)
+
+    if size == state.offset:
+        return state
+
+    async with await watched.open("rb") as handle:
+        await handle.seek(state.offset)
+        block = await handle.read()
+
+    # A line can arrive in two pieces, so hold back anything after the last
+    # newline until the rest of it turns up.
+    complete, _, pending = (state.pending + block).rpartition(b"\n")
+
+    for line in _decode(complete).splitlines():
+        ui.plain(out, line)
+
+    return _Tail(offset=state.offset + len(block), pending=pending)
+
+
+def _decode(block: bytes) -> str:
+    """Turn log bytes into text without ever failing on them.
+
+    Args:
+        block: What was read.
+
+    Returns:
+        The text. The service writes UTF-8, but a file cut mid-character by
+        rotation, or written by an older build, has to stay readable rather
+        than raise.
+    """
+    return block.decode("utf-8", "replace")

pb_cli/config.py

@@ -0,0 +1,213 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 The Pybricks Authors
+
+"""Where an option comes from when it is not on the command line.
+
+Three layers, highest first: what was typed, then the environment, then the
+project's ``pyproject.toml``. Below them the command decides for itself -- for
+a hub that means the one chosen with ``pb use``, and then the only one
+connected.
+
+The project layer is what makes a robot project work for whoever clones it:
+``[tool.pb] hub`` names the hub once, and every shell opened anywhere inside
+the project agrees, without anybody having to remember a flag.
+"""
+
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+from typing import cast
+
+import cyclopts
+
+__all__ = [
+    "ENV_PREFIX",
+    "KNOWN_KEYS",
+    "PROJECT_FILE",
+    "ProjectConfigError",
+    "check_project_file",
+    "config_sources",
+    "find_project_file",
+]
+
+PROJECT_FILE = "pyproject.toml"
+"""Where a project says which hub it belongs to.
+
+Under ``[tool.pb]``, found by walking up from the working directory.
+"""
+
+ENV_PREFIX = "PB_"
+"""How an option is spelled in the environment: ``--hub`` is ``PB_HUB``.
+
+Every option, not only that one. One prefix is easier to remember than a list
+of blessed variables, and an environment variable is ephemeral -- it belongs to
+one shell and one moment -- so being generous costs little.
+"""
+
+KNOWN_KEYS = frozenset({"hub", "transport"})
+"""What ``[tool.pb]`` is allowed to contain.
+
+Deliberately a short list rather than "any option this tool happens to have".
+The file is committed and read by everyone who clones the project, which makes
+it documented surface rather than a convenience, and surface should say what it
+covers. Adding a key here is how it grows.
+
+``transport`` earns its place for the same reason ``hub`` did: a project whose
+robot drives away from the desk wants Bluetooth every time, and saying so once
+in the file beats everyone who clones it remembering a flag.
+"""
+
+
+class ProjectConfigError(Exception):
+    """The project file says something this tool does not understand."""
+
+    def __init__(self, message: str, path: Path) -> None:
+        """Build the error.
+
+        Args:
+            message: What is wrong, as a sentence.
+            path: The file it is wrong in.
+        """
+        super().__init__(message)
+        self.path = path
+
+
+def config_sources(
+    project_file: Path | None = None,
+) -> tuple[cyclopts.config.Env, cyclopts.config.Toml]:
+    """Build the layers an option falls back to when it is not given.
+
+    Args:
+        project_file: The project file to read, when it has already been
+            found. Given by the launcher, which knows where ``-C`` pointed and
+            applies the "nearest file with a ``[tool.pb]`` table" rule. Left
+            out, cyclopts searches upwards from the working directory itself
+            and stops at the first ``pyproject.toml`` it finds, which is the
+            older and less careful behaviour.
+
+    Returns:
+        The sources, in the order cyclopts consults them: the environment
+        first, then the project file. Anything typed on the command line beats
+        both.
+    """
+    return (
+        cyclopts.config.Env(ENV_PREFIX, command=False),
+        cyclopts.config.Toml(
+            project_file if project_file is not None else PROJECT_FILE,
+            root_keys=("tool", "pb"),
+            # From the working directory upwards, so it is the project that
+            # matters rather than where in it the command was run.
+            search_parents=project_file is None,
+            # One table for every command rather than a table per command:
+            # [tool.pb] hub, not [tool.pb.run] hub.
+            use_commands_as_keys=False,
+            # Necessary rather than lenient. A key is matched against the
+            # parameters of the command being run, so "hub" would otherwise be
+            # an unknown option to every command that does not take one -- pb
+            # check and pb list among them, which would then fail merely
+            # because the file exists. What this gives up, a misspelled key
+            # passing unnoticed, is taken back by check_project_file.
+            allow_unknown=True,
+        ),
+    )
+
+
+def _settings(path: Path) -> dict[str, object] | None:
+    """Read one file's ``[tool.pb]`` table.
+
+    Args:
+        path: A ``pyproject.toml``.
+
+    Returns:
+        The table, or ``None`` if the file does not exist or has no
+        ``[tool.pb]``.
+
+    Raises:
+        ProjectConfigError: If the file exists but cannot be read or parsed,
+            or if ``[tool.pb]`` is not a table. A file that cannot be read is
+            worth saying so about, where a file that simply says nothing about
+            this tool is not.
+    """
+
+    if not path.is_file():
+        return None
+
+    try:
+        document = tomllib.loads(path.read_text(encoding="utf-8"))
+    except OSError as exc:
+        raise ProjectConfigError(f"{PROJECT_FILE} could not be read.", path) from exc
+    except tomllib.TOMLDecodeError as exc:
+        raise ProjectConfigError(f"{PROJECT_FILE} is not valid TOML.", path) from exc
+
+    table: object = document.get("tool")
+    settings = (
+        cast("dict[str, object]", table).get("pb") if isinstance(table, dict) else None
+    )
+    if settings is None:
+        return None
+
+    if not isinstance(settings, dict):
+        raise ProjectConfigError("[tool.pb] is not a table.", path)
+
+    return cast("dict[str, object]", settings)
+
+
+def find_project_file(start: Path | None = None) -> Path | None:
+    """Find the project file that applies here.
+
+    A file with no ``[tool.pb]`` is searched *past* rather than stopping the
+    search. Otherwise a monorepo cannot name its hub once at the top and
+    override it per project -- a member's own ``pyproject.toml``, which it has
+    for entirely unrelated reasons, would shadow it -- and an unrelated project
+    file anywhere in the path would turn the feature off silently, which is the
+    worst way for it to be off.
+
+    Args:
+        start: Where to look from, defaulting to the working directory.
+
+    Returns:
+        The nearest ``pyproject.toml`` at or above ``start`` that has a
+        ``[tool.pb]`` table, or ``None``.
+
+    Raises:
+        ProjectConfigError: If a candidate cannot be read or parsed.
+    """
+    here = (start or Path.cwd()).resolve()
+
+    for directory in (here, *here.parents):
+        candidate = directory / PROJECT_FILE
+        if _settings(candidate) is not None:
+            return candidate
+
+    return None
+
+
+def check_project_file(start: Path | None = None) -> None:
+    """Refuse a project file that says something unrecognised.
+
+    Args:
+        start: Where to look from, defaulting to the working directory.
+
+    Raises:
+        ProjectConfigError: If the file cannot be read, or ``[tool.pb]`` holds
+            a key this tool does not understand. Being strict here is the point
+            of reading it ourselves: cyclopts has to be told to ignore unknown
+            keys, and a hub that is quietly not applied because of a typo is
+            exactly the kind of thing somebody spends an afternoon on.
+    """
+    path = find_project_file(start)
+    if path is None:
+        return
+
+    settings = _settings(path)
+    if settings is None:  # pragma: no cover - find_project_file just read it
+        return
+
+    unknown = sorted(set(settings) - KNOWN_KEYS)
+    if unknown:
+        named = ", ".join(unknown)
+        raise ProjectConfigError(
+            f"[tool.pb] does not understand {named}.",
+            path,
+        )

pb_cli/console/__init__.py

@@ -0,0 +1,117 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 The Pybricks Authors
+
+"""The terminal, in raw mode, as bytes in and bytes out.
+
+This is the piece :mod:`pb_cli.keys` deliberately is not. A chooser only has to
+tell up from down from Enter; a session with a hub has to deliver *every* byte
+a key produces, unchanged, including the ones that would otherwise be a signal
+-- Ctrl-C is a byte for the interpreter on the hub, not an interrupt for us.
+
+Three properties are what make this tractable, and each one removes a class of
+bug that hand-rolled terminal code is famous for.
+
+**Waiting is waiting, and reading never blocks.** The two are separate calls:
+:meth:`Console.wait` returns once there may be something to read, and
+:meth:`Console.read` takes whatever is there without ever blocking. So a
+keystroke wakes the session in microseconds rather than at the next turn of a
+timer, and nothing anywhere polls the keyboard. Splitting them is what makes
+that possible on both platforms at once, because the two arrive at it
+differently: POSIX waits on the file descriptor itself, and Windows waits on a
+console handle in a thread, since no event loop will do it. Neither ever blocks
+inside the read, which is the thing that cannot be cancelled.
+
+**Windows and POSIX produce the same bytes.** Setting
+``ENABLE_VIRTUAL_TERMINAL_INPUT`` makes the console encode special keys as the
+escape sequences a terminal would send, so an arrow key really does arrive as
+``ESC [ A`` on both. Measured, not assumed. Everything above this package is
+therefore shared, and none of the vkey-to-sequence translation tables that
+other tools carry is needed.
+
+**Leaving raw mode is a synchronous ``__exit__``.** A sync exit cannot be
+cancelled at all, which is stronger than shielding, so the terminal is restored
+on every ordinary path -- return, exception, cancellation -- by the language
+itself rather than by anything this module remembers to do.
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import Protocol, runtime_checkable
+
+if sys.platform == "win32":
+    from pb_cli.console.windows import platform_problem, raw_console
+
+else:
+    from pb_cli.console.posix import platform_problem, raw_console
+
+__all__ = ["Console", "available", "raw_console", "why_unavailable"]
+
+
+@runtime_checkable
+class Console(Protocol):
+    """A terminal that has been put into raw mode."""
+
+    async def wait(self) -> None:
+        """Wait until there may be something to read.
+
+        Returns when the terminal has input, which is not a promise that
+        :meth:`read` will yield any bytes: a console reports more than typing,
+        and the window merely gaining focus counts as input here. The caller
+        reads, gets nothing, and waits again.
+        """
+        ...
+
+    def read(self) -> bytes:
+        """Take whatever has been typed.
+
+        Returns:
+            The bytes waiting, or empty if nothing has been typed. Never
+            blocks.
+        """
+        ...
+
+    def write(self, data: bytes) -> None:
+        """Put bytes on the screen exactly as given.
+
+        Args:
+            data: What to write. Not decoded, not translated: it may be part
+                of an escape sequence, or half of a character whose other half
+                has not arrived.
+        """
+        ...
+
+    def size(self) -> tuple[int, int]:
+        """Return the terminal's size.
+
+        Returns:
+            Columns and rows.
+        """
+        ...
+
+
+def why_unavailable() -> str | None:
+    """Explain why a raw terminal cannot be had here.
+
+    Returns:
+        A sentence naming the problem, or ``None`` if there is no problem.
+    """
+
+    for name, stream in (("input", sys.stdin), ("output", sys.stdout)):
+        try:
+            if not stream.isatty():
+                return f"standard {name} is not a terminal"
+
+        except (AttributeError, ValueError):  # pragma: no cover - odd embeddings
+            return f"there is no standard {name}"
+
+    return platform_problem()
+
+
+def available() -> bool:
+    """Whether an interactive session is possible here.
+
+    Returns:
+        True if this process has a terminal it can put into raw mode.
+    """
+    return why_unavailable() is None