pybricks-cli 1.0.0b1__py3-none-any.whl

pb_cli/escape.py

@@ -0,0 +1,258 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 The Pybricks Authors
+
+"""Telling keys meant for the hub from keys meant for ``pb``.
+
+In a session with a hub every keystroke belongs to the hub, Ctrl-C included --
+that is the point, since Ctrl-C is how a running program is interrupted. So
+there has to be one key that does not, and after it a letter saying what to do.
+This is the arrangement ``telnet``, ``screen``, ``picocom`` and ``microcom``
+all use, and users of those tools already know the shape of it.
+
+**Which key it is matters more here than in those tools**, because the thing on
+the other end is MicroPython, and MicroPython's REPL claims an unusual number
+of control characters. Its line editor uses Ctrl-A, B, D, E, F, K, N, P, U and
+W, and the REPL itself gives Ctrl-A, B, C, D and E meanings of their own: raw
+mode, friendly mode, interrupt, soft reset and paste mode. That rules out the
+usual choices immediately -- ``screen`` and ``picocom`` escape with Ctrl-A,
+which is raw REPL, and ``tmux`` with Ctrl-B, which is friendly REPL.
+
+``Ctrl-]`` is what is left, and it is the one with the best claim anyway: it is
+telnet's, so it is the most widely recognised of them, and MicroPython does not
+use it for anything. Checked rather than assumed -- neither ``readline.c`` nor
+``pyexec.c`` mentions ``0x1d`` at all. Sending the escape key to the hub is
+still possible, by pressing it twice, which is also telnet's convention.
+
+**Stopping has a second way in, because it is the one done in a hurry.**
+``Ctrl-] s`` is a modifier, a bracket and a remembered letter at the moment
+somebody wants their robot to stop, so :data:`STOP_KEY` -- Escape, pressed
+twice -- does the same thing. It is one key, it is on every keyboard, and a
+hand finds it without looking.
+
+Escape is also the first byte of every arrow key, and the hub's line editor
+needs those, so the two have to be told apart. **Two Escapes in a row are
+unambiguous in the byte stream**: a terminal's escape sequences are always
+Escape followed by an introducer -- ``[``, ``O`` and the like -- so no sequence
+can contain two Escapes running, and no timing window is needed to know which
+this is. That is the whole reason it is two presses rather than one; one press
+could only be told from an arrow key by how long nothing followed it, and a
+window is a thing that is wrong occasionally rather than never.
+
+The cost is that a lone Escape is held back until the next byte arrives, and
+that is imperceptible: the hub gets both together, and its line editor was
+waiting for the second byte anyway. What is left is Alt-Escape and the habit
+of pressing Escape twice in ``vi``, neither of which means anything at a
+MicroPython prompt, and both of which land on the safe side -- for a robot, an
+unasked-for stop is the better way to be wrong.
+
+The matching is a byte at a time and carries its state in the value it hands
+back, because both pairs can easily arrive in separate reads: on Windows the
+console hands over one key at a time, so a user typing at any ordinary speed
+splits them almost always. Assuming a whole sequence arrives in one read is the
+single most common bug in code like this, and a state machine of three states
+-- nothing pending, a command awaited, an Escape held -- is both the fix and
+something that can be tested exhaustively without a terminal anywhere near it.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, replace
+from enum import Enum
+from typing import Final
+
+__all__ = ["ESCAPE_KEY", "STOP_KEY", "Action", "Filter", "describe", "help_lines"]
+
+ESCAPE_KEY: Final = 0x1D
+"""Ctrl-], the byte that means the next key is for ``pb``.
+
+Telnet's, and free: MicroPython gives it no meaning, so nothing is taken away
+from the hub by reserving it.
+"""
+
+STOP_KEY: Final = 0x1B
+"""Escape, which stops what is running on the hub when pressed twice.
+
+Not taken from the hub, because one press still reaches it -- held only until
+the key after it says whether it began a sequence. See the module docstring for
+why two presses can be recognised with no timing at all.
+"""
+
+_NAMES: Final[Mapping[int, str]] = {STOP_KEY: "Esc"}
+"""Keys with a name of their own, rather than the Ctrl-something they encode.
+
+Escape is Ctrl-[ as far as the byte is concerned, and nobody has called it that
+since terminals had a key marked Meta.
+"""
+
+
+class Action(Enum):
+    """What an escape command asks for."""
+
+    QUIT = "quit"
+    STOP = "stop"
+    HELP = "help"
+    UNKNOWN = "unknown"
+    """A key that follows the escape and means nothing. Reported rather than
+    ignored, so the user is shown the help instead of wondering."""
+
+
+COMMANDS: Final[Mapping[int, Action]] = {
+    ord("q"): Action.QUIT,
+    ord("Q"): Action.QUIT,
+    0x04: Action.QUIT,
+    ord("s"): Action.STOP,
+    ord("S"): Action.STOP,
+    ord("h"): Action.HELP,
+    ord("H"): Action.HELP,
+    ord("?"): Action.HELP,
+}
+"""What each key after the escape does.
+
+Ctrl-D is here as a second way to quit because it is what fingers do at a
+prompt when they mean "I am finished", and on its own it belongs to the hub
+where it is a soft reset.
+
+Help is advertised as ``h`` and answers to ``?`` as well. Both are worth
+having: ``?`` is what the other escape-key tools use, and ``h`` is the one a
+hand can reach without a shift key.
+
+There is deliberately no "restart the interpreter". A session that finds a
+program running starts the interpreter by itself as soon as that program ends,
+and a session whose interpreter stops is over, so nothing is left for a restart
+command to do that the session does not already do on its own.
+"""
+
+
+def help_lines(
+    key: int = ESCAPE_KEY, stop_key: int = STOP_KEY
+) -> list[tuple[str, str]]:
+    """List the escape commands, as a user would have to type them.
+
+    Args:
+        key: The escape byte in use.
+        stop_key: The byte that stops the hub when pressed twice.
+
+    Returns:
+        Each command's keystrokes and what it does, in the order to show them.
+        Stopping comes first, because it is the one somebody is reading this
+        list in a hurry to find.
+    """
+    name = describe(key)
+    stop = describe(stop_key)
+    return [
+        (f"{stop} {stop}", "stop what is running, ending the session"),
+        (f"{name} q", "leave the session"),
+        (f"{name} s", f"the same as {stop} {stop}"),
+        (f"{name} h", "show this help"),
+        (f"{name} {name}", f"send {name} to the hub"),
+    ]
+
+
+def describe(key: int = ESCAPE_KEY) -> str:
+    """Name a control byte the way a person would say it.
+
+    Args:
+        key: The byte.
+
+    Returns:
+        Something like ``Ctrl-]``, or the key's own name where it has one.
+    """
+    named = _NAMES.get(key)
+    if named is not None:
+        return named
+
+    if 0 < key < 0x20:
+        return f"Ctrl-{chr(key + 0x40)}"
+
+    return repr(chr(key))
+
+
+@dataclass(frozen=True, slots=True)
+class Filter:
+    """Splits what was typed into bytes for the hub and commands for ``pb``.
+
+    A value rather than something a session edits: :meth:`feed` returns the
+    filter to read the *next* keys with, so what a half-finished escape needs
+    is carried in the value rather than accumulated in an object. That is worth
+    the extra name at the call site, because a read ending between the escape
+    key and its command is the ordinary case and not an edge one -- a console
+    hands over one key at a time, so the two halves nearly always arrive in
+    separate reads -- and a value makes each step of that a thing a test can
+    state on one line.
+    """
+
+    key: int = ESCAPE_KEY
+    """The byte that starts a command."""
+
+    stop_key: int = STOP_KEY
+    """The byte that stops the hub when it arrives twice running."""
+
+    armed: bool = False
+    """Whether the escape key has been seen and its command is awaited."""
+
+    held: bool = False
+    """Whether a :attr:`stop_key` is being held back to see what follows it.
+
+    One press belongs to the hub and two are the stop, and which it was is
+    known as soon as the next byte arrives -- so the first one waits rather
+    than being guessed at. Nothing is lost by waiting: the hub's line editor
+    reads an escape as the start of a sequence and is waiting for that same
+    byte itself.
+    """
+
+    def feed(self, data: bytes) -> tuple[Filter, bytes, tuple[Action, ...]]:
+        """Sort one read from the terminal.
+
+        Args:
+            data: The bytes just typed.
+
+        Returns:
+            The filter to read the next keys with, what to send to the hub,
+            and the commands that were asked for, in the order they were
+            typed.
+        """
+        armed = self.armed
+        held = self.held
+        for_hub = bytearray()
+        actions: list[Action] = []
+
+        for byte in data:
+            if armed:
+                armed = False
+
+                if byte == self.key:
+                    # Pressed twice, so it was meant for the hub after all.
+                    for_hub.append(byte)
+                else:
+                    actions.append(COMMANDS.get(byte, Action.UNKNOWN))
+
+                continue
+
+            if held:
+                held = False
+
+                if byte == self.stop_key:
+                    actions.append(Action.STOP)
+
+                    continue
+
+                # Whatever this is, it is not a second press, so the one being
+                # held belonged to the hub -- and this byte is then read as if
+                # it had never been held at all, since it may perfectly well be
+                # the escape key starting a command of its own.
+                for_hub.append(self.stop_key)
+
+            if byte == self.key:
+                armed = True
+            elif byte == self.stop_key:
+                held = True
+            else:
+                for_hub.append(byte)
+
+        # Unchanged is the common case, and a value that did not change has no
+        # reason to be a different object.
+        if armed == self.armed and held == self.held:
+            return self, bytes(for_hub), tuple(actions)
+
+        return replace(self, armed=armed, held=held), bytes(for_hub), tuple(actions)

pb_cli/keys.py

@@ -0,0 +1,332 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 The Pybricks Authors
+
+"""Reading single keystrokes, for the few places that ask a person to choose.
+
+Deliberately small, and not to be confused with :mod:`pb_cli.console`, which is
+what a session with a hub reads its keyboard through: that one forwards every
+byte a key produces, in raw mode, and getting it right is most of a project.
+This one only has to tell up from down from Enter, which is enough for a
+chooser.
+
+Three properties make it much safer than it looks:
+
+**Nothing blocks.** :func:`read_ready` returns immediately whether or not a key
+is waiting, so the caller stays in its own event loop. There is no reader thread
+to abandon and no uninterruptible read to cancel, which is where the difficulty
+in this area really lives.
+
+**Waiting is a separate call, and is real waiting where the platform allows
+it.** :func:`wait_for_key` returns once there may be something to read. On
+POSIX that is a wait on the terminal's own file descriptor, so a keypress is
+acted on in microseconds and nothing is woken while nobody is typing. Windows
+cannot do the same: a console handle is signalled by records that carry no
+character, and :mod:`msvcrt` neither reports those nor removes them, so a wait
+on the handle would return at once and go on returning. Seeing them means
+reading them with the console API, which is :mod:`pb_cli.console`'s job and
+costs a change of console mode -- and that would take Ctrl-C away from the
+operating system, which is the one thing here that must keep working. So
+Windows waits on a short timer instead.
+
+**Windows needs no mode change at all.** :mod:`msvcrt` reads the console input
+buffer directly, so there is no console state to save and none to restore, and
+therefore no way to leave the terminal wedged. Only POSIX needs cbreak mode,
+and it is entered and left by a *synchronous* context manager, whose
+``__exit__`` cannot be cancelled -- which is stronger than shielding.
+
+Only the reading and the waiting are per platform. Deciding what a keystroke
+means is shared,
+and understands both grammars at once: Windows reports an arrow as a prefix
+character followed by a scan code, while a terminal reports it as an escape
+sequence. Neither can be mistaken for the other, so one function handles both
+and can be tested on either platform.
+
+Ctrl-C is left to the operating system rather than read as a byte. It arrives
+as :class:`KeyboardInterrupt`, so the way out of a chooser works even if
+everything else here is wrong.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import sys
+from collections.abc import Generator
+from enum import Enum
+from typing import Final
+
+import anyio
+
+__all__ = [
+    "Key",
+    "keys_available",
+    "poll_key",
+    "read_ready",
+    "read_second",
+    "reading_keys",
+    "wait_for_key",
+]
+
+
+class Key(Enum):
+    """The handful of keys a chooser cares about."""
+
+    UP = "up"
+    DOWN = "down"
+    ENTER = "enter"
+    CANCEL = "cancel"
+    """Escape or ``q``. Ctrl-C arrives as ``KeyboardInterrupt`` instead."""
+
+    OTHER = "other"
+    """Anything else, reported so a caller can ignore it deliberately."""
+
+
+_WINDOWS_PREFIXES = ("\x00", "\xe0")
+"""What the console sends before the scan code of a special key."""
+
+_WINDOWS_SCAN_CODES = {"H": Key.UP, "P": Key.DOWN}
+
+_CSI_FINAL_BYTES = {"A": Key.UP, "B": Key.DOWN}
+"""The last character of a terminal's escape sequence for the arrows."""
+
+
+def keys_available() -> bool:
+    """Whether single keystrokes can be read at all.
+
+    Returns:
+        True when standard input is a terminal this can read from. False for a
+        pipe, a file, or a shell that emulates a terminal over pipes -- Git
+        Bash's ``mintty`` being the one on hand, where a native Windows Python
+        sees a pipe and no console. A caller must check this and say something
+        useful rather than waiting for a keystroke that cannot arrive.
+    """
+
+    try:
+        if not sys.stdin.isatty():
+            return False
+    except (AttributeError, ValueError):  # pragma: no cover - odd embeddings
+        # A closed or replaced stdin, which is not a terminal either.
+        return False
+
+    return _is_console()
+
+
+def poll_key() -> Key | None:
+    """Read one keystroke if one is waiting.
+
+    Returns:
+        What was pressed, or ``None`` if nothing has been typed. Never blocks,
+        so a caller can redraw a display between calls.
+    """
+    char = read_ready()
+    if char is None:
+        return None
+
+    if not char:
+        # The terminal has gone away, so there is nothing left to choose
+        # with, and leaving is the same answer as Escape. Saying so matters
+        # more than it looks: a descriptor at end of file stays readable for
+        # ever, so anything else here would spin rather than wait.
+        return Key.CANCEL
+
+    if char in _WINDOWS_PREFIXES:
+        # A Windows special key, which arrives as a prefix and then its
+        # scan code. read_second rather than read_ready: the two halves
+        # are not both in the console buffer, so asking whether anything
+        # is waiting gets the wrong answer. See read_second.
+        return _WINDOWS_SCAN_CODES.get(read_second() or "", Key.OTHER)
+
+    if char == "\x1b":
+        # Escape either stands alone or opens a sequence such as "\x1b[A" for
+        # the up arrow. Telling those apart is the classic trap here, and
+        # polling answers it directly: if nothing more is waiting this
+        # instant, the key really was Escape.
+        if read_ready() != "[":
+            return Key.CANCEL
+
+        return _CSI_FINAL_BYTES.get(read_ready() or "", Key.OTHER)
+
+    if char in ("\r", "\n"):
+        return Key.ENTER
+
+    if char in ("q", "Q"):
+        return Key.CANCEL
+
+    return Key.OTHER
+
+
+if sys.platform == "win32":
+    POLL_SECONDS: Final = 0.05
+    """How long to wait before looking for a keystroke again.
+
+    Windows only, and standing in for a wait that cannot be had here -- see
+    the module docstring. Fast enough that a keypress feels immediate and slow
+    enough to be free.
+    """
+
+    async def wait_for_key() -> None:
+        """Wait a short while, since the console cannot be waited on.
+
+        A poll, and the one the repository keeps deliberately. It is bounded
+        by how long somebody spends choosing a hub, and the alternative costs
+        a change of console mode that would take Ctrl-C away from the
+        operating system.
+        """
+        await anyio.sleep(POLL_SECONDS)
+
+    @contextlib.contextmanager
+    def reading_keys() -> Generator[None]:
+        """Do nothing, because Windows needs nothing done.
+
+        Yields:
+            Nothing. ``msvcrt`` reads the console buffer without changing the
+            console mode, so there is no state to restore.
+        """
+        yield
+
+    def read_ready() -> str | None:
+        """Read one character if the console has one waiting.
+
+        Returns:
+            The character, or ``None`` if nothing has been typed.
+        """
+        import msvcrt
+
+        return msvcrt.getwch() if msvcrt.kbhit() else None
+
+    def read_second() -> str | None:
+        """Read the second half of a special key, which is already held.
+
+        A special key reaches a program as two characters: a prefix,
+        and then the key's scan code. The runtime hands over the first
+        and keeps the second, and -- measured, by writing a down arrow
+        into a real console with ``WriteConsoleInputW`` -- ``kbhit``
+        then says nothing is waiting, because nothing is: the second
+        half is in the runtime rather than in the console's buffer.
+
+        Guarding this read with ``kbhit`` therefore loses every arrow
+        key, and strands its scan code to be read back later as a
+        keystroke of its own -- so the next key pressed is misread as
+        well.
+
+        Returns:
+            The second character. The read is unguarded, which is safe
+            precisely because a prefix means the runtime is holding it:
+            it returned in under a millisecond when measured.
+        """
+        import msvcrt
+
+        return msvcrt.getwch()
+
+    def _is_console() -> bool:
+        """Whether standard input really is a console.
+
+        ``isatty`` is not enough here, and the difference is a hang rather
+        than a wrong answer. Windows calls every character device a terminal,
+        so redirecting from ``NUL`` reports a terminal, and then nothing is
+        ever typed at it. Asking the console API settles it: the call fails
+        for anything that is not a console.
+
+        Returns:
+            True if keystrokes can arrive.
+        """
+        import ctypes
+
+        # ctypes rather than pywin32 throughout: importing pythoncom
+        # initialises COM as an apartment and makes bleak hang.
+        stdin_handle = -10  # STD_INPUT_HANDLE
+        handle = ctypes.windll.kernel32.GetStdHandle(stdin_handle)
+        mode = ctypes.c_uint()
+        return bool(ctypes.windll.kernel32.GetConsoleMode(handle, ctypes.byref(mode)))
+
+else:
+
+    async def wait_for_key() -> None:
+        """Wait until the terminal has something to read.
+
+        Nothing is woken while nobody is typing, and a keypress is acted on
+        as it arrives rather than at the next turn of a timer.
+        """
+        await anyio.wait_readable(sys.stdin.fileno())
+
+    @contextlib.contextmanager
+    def reading_keys() -> Generator[None]:
+        """Put the terminal in cbreak mode for the duration of the block.
+
+        Cbreak rather than raw, so that the kernel still turns Ctrl-C into a
+        signal. That way the way out of a chooser does not depend on this
+        module reading and interpreting a byte correctly.
+
+        Yields:
+            Nothing. The previous settings are restored on the way out, by a
+            synchronous ``__exit__`` that cannot be cancelled.
+        """
+        import termios
+        import tty
+
+        fd = sys.stdin.fileno()
+        saved = termios.tcgetattr(fd)
+
+        try:
+            tty.setcbreak(fd)
+            yield
+        finally:
+            # TCSADRAIN so that anything already written is not cut off.
+            termios.tcsetattr(fd, termios.TCSADRAIN, saved)
+
+    def read_second() -> str | None:
+        """Read the next character of a sequence, if one is waiting.
+
+        The counterpart of the Windows version, and here it is simply
+        another read: every byte of an escape sequence is in the
+        terminal's own buffer, so asking whether one is waiting is the
+        right question.
+
+        Returns:
+            The character, or ``None`` if nothing more has arrived.
+        """
+        return read_ready()
+
+    def read_ready() -> str | None:
+        """Read one character if the terminal has one waiting.
+
+        The read is from the file descriptor rather than through
+        :data:`sys.stdin`, and that is the whole correctness of this module
+        on POSIX. ``sys.stdin`` is a text wrapper with a buffer of its own,
+        and a terminal sends an arrow key's three bytes in one go -- so
+        reading the escape through it drew all three into that buffer,
+        ``select`` on the descriptor then truthfully reported nothing waiting,
+        and :func:`poll_key` concluded the Escape had stood alone. Every arrow
+        key was read as leave, and its remaining two bytes as two more
+        keystrokes. Measured against a real pseudo-terminal, which is the only
+        way it could have been found: down, up and Enter came back as
+        ``CANCEL``, ``OTHER``, ``OTHER``. What is asked about and what is read
+        from have to be the same thing.
+
+        Returns:
+            The character, or ``None`` if nothing has been typed, or the empty
+            string if the terminal has gone away.
+        """
+        import os
+        import select
+
+        fd = sys.stdin.fileno()
+        readable, _, _ = select.select([fd], [], [], 0)
+
+        if not readable:
+            return None
+
+        # One byte at a time, as Latin-1 so that nothing here can raise
+        # part-way through a character. A key that produces several bytes is
+        # not one this module knows, and comes out as OTHER either way.
+        return os.read(fd, 1).decode("latin-1")
+
+    def _is_console() -> bool:
+        """Whether standard input really is a terminal.
+
+        On POSIX ``isatty`` means what it says, so there is nothing more to
+        ask. The Windows implementation has to work harder.
+
+        Returns:
+            True, the caller having already checked ``isatty``.
+        """
+        return True