Input / Output

Face provides I/O utilities for CLI applications. These functions handle TTY detection, ANSI escape code stripping, and cross-platform concerns so your output behaves correctly whether piped to a file or displayed in a terminal.

Use these instead of bare print() and input() calls. They respect output redirection, handle encoding edge cases, and integrate with face’s error handling.

from face import echo, echo_err, prompt

def my_handler(verbose):
    if verbose:
        echo_err('starting work...')
    result = do_work()
    echo(result)

def interactive_handler():
    name = prompt('Enter your name: ')
    echo(f'Hello, {name}!')
face.echo(msg: str | bytes | object, *, err: bool = False, file: TextIO | None = None, nl: bool = True, end: str | None = None, color: bool | None = None, indent: str | int = '') → None[source]

A better-behaved print() function for command-line applications.

Writes text or bytes to a file or stream and flushes. Seamlessly handles stripping ANSI color codes when the output file is not a TTY.

>>> echo('test')
test
Parameters:

  • msg – A text or byte string to echo.

  • err – Set the default output file to sys.stderr

  • file – Stream or other file-like object to output to. Defaults to sys.stdout, or sys.stderr if err is True.

  • nl – If True, sets end to '\n', the newline character.

  • end – Explicitly set the line-ending character. Setting this overrides nl.

  • color – Set to True/False to always/never echo ANSI color codes. Defaults to inspecting whether file is a TTY.

  • indent – String prefix or number of spaces to indent the output.

face.echo_err(*a, **kw)[source]

A convenience function which works exactly like echo(), but always defaults the output file to sys.stderr.

face.prompt(label, confirm=None, confirm_label=None, hide_input=False, err=False)[source]

A better-behaved input() function for command-line applications.

Ask a user for input, confirming if necessary, returns a text string. Handles Ctrl-C and EOF more gracefully than Python’s built-ins.

Parameters:

  • label (str) – The prompt to display to the user.

  • confirm (bool) – Pass True to ask the user to retype the input to confirm it. Defaults to False, unless confirm_label is passed.

  • confirm_label (str) – Override the confirmation prompt. Defaults to “Retype label” if confirm is True.

  • hide_input (bool) – If True, disables echoing the user’s input as they type. Useful for passwords and other secret entry. See prompt_secret() for a more convenient interface. Defaults to False.

  • err (bool) – If True, prompts are printed on sys.stderr. Defaults to False.

prompt() is primarily intended for simple plaintext entry. See prompt_secret() for handling passwords and other secret user input.

Raises UsageError if confirm is enabled and inputs do not match.

face.prompt_secret(label, **kw)[source]

A convenience function around prompt(), which is preconfigured for secret user input, like passwords.

All arguments are the same, except hide_input is always True, and err defaults to True, for consistency with getpass.getpass().

Note

Additional I/O utilities (choice prompting, color flag integration) may be added in future releases.