GitHub

terminal

API reference for terminal.

The terminal as a service (Effect's Terminal): its size, a line or key presses from the user, and text shown to them::

term = yield from Terminal()
yield from term.display("Name? ")
name = yield from term.read_line   # QuitError at the end of input

layer is standard input and output (live(should_quit=...) for another quit key); TerminalService(...) builds one for tests.

Values

AttributeTypeDescription
layerLayer[Terminal]

Standard input and output.

Classes

Functions

decode

decode(text) -> list[UserInput]

The key presses in text read at once, with no input after it: a trailing ESC is the escape key, an unfinished sequence gives none.

ParameterTypeDescription
textstr

Returns list[UserInput]

def decode(text: str) -> list[UserInput]:
    """The key presses in ``text`` read at once, with no input after it: a
    trailing ESC is the escape key, an unfinished sequence gives none."""
    decoder = KeyDecoder()
    events = decoder.feed(text)
    if decoder.escape_pending:
        events += decoder.timeout()
    return events

live

live(*, should_quit=default_should_quit, input=None, output=None) -> TerminalService

A terminal over the file descriptor input and the text stream output (standard input and output, looked up when used). A key press for which should_quit is true ends read_input's queue after it is delivered.

ParameterTypeDescription
should_quitCallable[[UserInput], bool] = default_should_quit
inputint | None = None
outputTextIO | None = None

Returns TerminalService

def live(
    *,
    should_quit: Callable[[UserInput], bool] = default_should_quit,
    input: int | None = None,
    output: TextIO | None = None,
) -> TerminalService:
    """A terminal over the file descriptor ``input`` and the text stream
    ``output`` (standard input and output, looked up when used). A key
    press for which ``should_quit`` is true ends ``read_input``'s queue
    after it is delivered."""

    def input_fd() -> int:
        return sys.stdin.fileno() if input is None else input

    def out() -> TextIO:
        return sys.stdout if output is None else output

    source = _Input(input_fd)
    raw_mode = _RawMode(input_fd)

    def filled(wait: float) -> Effect[None]:
        # A stopped reader waits out its read (at most ``wait``), so no
        # thread reads the descriptor after it and takes the next reader's
        # input. Windows reads cannot time out, so there they are left.
        read = blocking(lambda: source.fill(wait))
        return read if os.name == "nt" else read.uninterruptible()

    fill = filled(_WAIT)
    fill_within_escape_timeout = filled(ESCAPE_CODE_TIMEOUT)

    def read_line() -> Generator[Effect[Any, QuitError], Any, str]:
        while True:
            line = source.take_line()
            if line is not None:
                return line
            if source.ended:
                return (yield from QuitError())
            yield from fill

    def read_input() -> Generator[Effect[Any, Never, Scope], Any, Dequeue[UserInput, Done]]:
        queue = yield from Queue[UserInput, Done].unbounded()
        yield from acquire_release(sync(raw_mode.acquire), lambda _a, _e: sync(raw_mode.release))
        text = codecs.getincrementaldecoder("utf-8")(errors="replace")
        keys = KeyDecoder()

        def pump() -> Generator[Effect[Any], Any]:
            while True:
                data = source.take_all()
                if data:
                    events = keys.feed(text.decode(data))
                elif source.ended:
                    # As Effect's reader, the end of input ends the queue
                    # before a trailing ESC's timeout could name it.
                    yield from queue.end()
                    return
                elif keys.escape_pending:
                    yield from fill_within_escape_timeout
                    if source.waiting():
                        continue
                    events = keys.timeout()
                else:
                    yield from fill
                    continue
                for event in events:
                    yield from queue.offer(event)
                    if should_quit(event):
                        yield from queue.end()
                        return

        yield from gen(pump).fork_scoped()
        return queue

    def write(text: str) -> None:
        target = out()
        target.write(text)
        target.flush()

    def display(text: str) -> Effect[None, PlatformError]:
        return try_blocking(
            lambda: write(text),
            lambda cause: bad_argument(
                module="Terminal",
                method="display",
                description="Failed to write prompt to stdout",
                cause=cause,
            ),
        ).uninterruptible()

    def columns() -> int:
        size = _size(out())
        return 0 if size is None else size.columns

    def rows() -> int:
        size = _size(out())
        return 0 if size is None else size.lines

    def current() -> Size:
        size = _size(out())
        return Size(0, 0) if size is None else Size(size.columns, size.lines)

    return TerminalService(
        columns=sync(columns),
        rows=sync(rows),
        size=_sizes(current),
        read_input=gen(read_input),
        read_line=gen(read_line),
        display=display,
    )

default_should_quit

default_should_quit(event) -> bool

Escape, Ctrl+C and Ctrl+D quit, as in Effect's Node terminal.

ParameterTypeDescription
eventUserInput

Returns bool

def default_should_quit(event: UserInput) -> bool:
    """Escape, Ctrl+C and Ctrl+D quit, as in Effect's Node terminal."""
    key = event.key
    return key.name == "escape" or (key.ctrl and key.name in ("c", "d"))