Input / Output¶

Face includes a variety of utilities designed to make it easy to write applications that adhere to command-line conventions and user expectations.

face.echo(msg, **kw)[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 (str) – A text or byte string to echo.
err (bool) – Set the default output file to sys.stderr
file (file) – Stream or other file-like object to output to. Defaults to sys.stdout, or sys.stderr if err is True.
nl (bool) – If True, sets end to '\n', the newline character.
end (str) – Explicitly set the line-ending character. Setting this overrides nl.
color (bool) – Set to True/False to always/never echo ANSI color codes. Defaults to inspecting whether file is a TTY.

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().

TODO¶