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 inputlayer is standard input and output (live(should_quit=...) for
another quit key); TerminalService(...) builds one for tests.
Values#
| Attribute | Type | Description |
|---|---|---|
layer | Layer[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.
| Parameter | Type | Description |
|---|---|---|
text | str |
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 eventslive#
live(*, should_quit=default_should_quit, input=None, output=None) -> TerminalServiceA 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.
| Parameter | Type | Description |
|---|---|---|
should_quit | Callable[[UserInput], bool] = default_should_quit | |
input | int | None = None | |
output | TextIO | 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) -> boolEscape, Ctrl+C and Ctrl+D quit, as in Effect's Node terminal.
| Parameter | Type | Description |
|---|---|---|
event | UserInput |
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"))