API Reference¶

Programmatic REPL session — raw REPL over pyserial.

:class:ReplSession is a context manager that opens a serial connection to a CircuitPython or MicroPython board, drives the raw REPL (Ctrl-A entry, Ctrl-D exec, OK<stdout>\x04<stderr>\x04> framing), and exposes three primitives:

• :meth:~ReplSession.exec — run a block of code, return stdout.
• :meth:~ReplSession.call — call a named function with literal arguments, return the parsed repr of the result.
• :meth:~ReplSession.read_until — read raw bytes until a pattern matches, for callers that bypass raw REPL entirely (tailing the friendly REPL, for instance).

The raw-REPL framing is identical between CircuitPython and MicroPython — neither runtime adds a runtime-specific header to either the prompt or the response — so a single code path handles both. The only divergence is what a soft-reboot (Ctrl-D in the friendly REPL) prints: MicroPython emits MPY: soft reboot, CircuitPython is silent. :meth:ReplSession.exec never exits raw REPL, so that divergence never surfaces here; it is a concern for the :func:~chumicro_repl.tail path and the interactive TUI.

with ReplSession(device) as session:
    output = session.exec("print(1 + 2)")
    value = session.call("os.uname")

OK<stdout>\x04<stderr>\x04>

Stream REPL output for a bounded window.

:func:tail opens a serial port, reads for seconds of wall-clock time, decodes bytes UTF-8 safely, writes them to output with ANSI highlighting, and returns an :class:ExitCode describing why the window ended. When the device drops mid-stream, tail can hold the window open and reopen the port on replug.

Tail does not touch the REPL mode (no Ctrl-A / Ctrl-B sent). The caller decides whether the board is in raw or friendly REPL before tail runs, and what to do with the returned :class:ExitCode.

Interactive REPL TUI — forwards stdin ↔ serial with highlighting.

The TUI is deliberately thin: stdin bytes are passed through to the board unchanged, serial bytes are UTF-8 decoded and ANSI-highlighted before being written to stdout. The board does its own line editing — arrow keys, backspace, paste-mode (Ctrl-E) all reach the device verbatim.

Keybindings mirror mpremote repl:

• Ctrl-C — forwarded to the board. Raises :class:KeyboardInterrupt on-device, which cancels whatever is running and returns to the friendly REPL.
• Ctrl-D — forwarded to the board. Soft-reboots the runtime (MicroPython prints MPY: soft reboot, CircuitPython is silent but rewinds).
• Ctrl-E — forwarded to the board. Enters MicroPython paste mode; CircuitPython ignores it.
• Ctrl-X — intercepted locally. Exits the TUI without rebooting or interrupting the board.

The loop is structured so tests can drive it without real terminal machinery: :func:run_loop takes injectable input / output / port / time dependencies; :func:interactive is the thin wrapper that opens a real pyserial port and puts stdin into raw mode.

Classifies chumicro-repl session-start failures and coaches the user through a fix.

A bad cable, a held port, a missing dialout membership, or a board stuck in unresponsive user code all surface as OSError or :class:ReplSessionError when a caller opens a :class:ReplSession. This module maps those exceptions to a small enum of recognized failure kinds, pairs each kind with a :class:RecoveryPlan of ordered physical steps the user can take, and offers a coaching loop that prints the plan and retries the session start.

Public surface:

• :class:ReplFailureKind — enum of session-start failure modes.
• :class:RecoveryPlan — headline + ordered fix-steps for one kind.
• :func:classify_session_failure — map a session-start exception to a :class:ReplFailureKind.
• :func:recovery_plan_for — look up the plan registered for a kind.
• :func:coached_session_start — reusable classify-render-retry loop around any zero-arg session-opening callable.
• :class:InteractiveReplSession — context manager that applies the coaching loop around a :class:ReplSession.

Mid-session disconnects do not route through this module. The auto-reconnect loop in :func:chumicro_repl.tail and :func:chumicro_repl.tui.run_loop handles the "device was open and then dropped" case; this module only addresses the "it never opened in the first place" failures.

from chumicro_repl import InteractiveReplSession

with InteractiveReplSession(device) as session:
    session.exec("print('hello')")

Pattern detectors for CircuitPython and MicroPython REPL output.

Detects the banners and blocks that mean "something noteworthy happened on the board" so the TUI can colorize them and so tail() can fail a deploy when a traceback arrives.

Recognized kinds:

• :attr:PatternKind.TRACEBACK — the Traceback (most recent call last): header that both runtimes emit at the start of an uncaught exception block. Spans from the header line through the blank line that follows the exception summary.
• :attr:PatternKind.SAFE_MODE — CircuitPython's safe mode block, printed when the supervisor drops into safe mode after repeated crashes or after supervisor.reload() into a broken state.
• :attr:PatternKind.HARD_FAULT — the CircuitPython Hard fault message and the register dump that follows it.
• :attr:PatternKind.SOFT_REBOOT — the MicroPython MPY: soft reboot banner that follows a machine.soft_reset() or a Ctrl-D in the interactive REPL.

The detector is line-oriented — pass a decoded string of lines (or a single complete line) to :func:detect_patterns and get back a list of :class:PatternMatch records, each carrying a span into the input string plus the detected kind.

ANSI colorization for detected REPL patterns.

Renders :class:~chumicro_repl.patterns.PatternMatch spans into terminal escape sequences. A small :class:Theme dataclass maps each :class:~chumicro_repl.patterns.PatternKind to an ANSI SGR string; the default theme uses the same color choices as mpremote + rich.traceback: red/bold for tracebacks and hard faults, yellow for safe mode, dim/cyan for soft-reboot banners.

Emits raw ANSI escape sequences only, with no rich dependency. Output destined for a non-TTY stream can be passed through :func:strip_ansi_sequences downstream to recover plain text.

UTF-8 safe streaming decoder.

Serial reads arrive in arbitrary-sized chunks. A single UTF-8 code-point can span up to four bytes, and a read boundary can fall in the middle of a multi-byte sequence — so naive bytes.decode("utf-8") on each chunk raises :class:UnicodeDecodeError on anything above ASCII. :class:Utf8StreamDecoder buffers the tail bytes of a chunk that look like the start of a not-yet-complete sequence and prepends them to the next chunk.

Also forgives one class of garbage: if the stream emits invalid bytes (e.g. an interrupted power glitch), the decoder replaces them with U+FFFD so the user sees a replacement character instead of a crash.

decoder = Utf8StreamDecoder()
first_half = bytes([0xF0, 0x9F])  # start of "🙂" (4 bytes)
second_half = bytes([0x99, 0x82])
assert decoder.decode(first_half) == ""
assert decoder.decode(second_half) == "🙂"

Test fakes for chumicro-repl.

Provides three fakes for host-side tests:

• :class:FakeSerialPort — drop-in replacement for serial.Serial in :class:chumicro_repl.session.ReplSession, :func:chumicro_repl.tail, and :func:chumicro_repl.tui.run_loop. Records writes, replays scripted reads.
• :class:FakeKeyboard — replays scripted keystrokes for :func:chumicro_repl.tui.run_loop tests.
• :class:FakeTime — deterministic seconds-domain time source that satisfies the TimeSource protocol so tests never sleep.