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
, orsys.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 tosys.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. Seeprompt_secret()
for a more convenient interface. Defaults toFalse
. - err (bool) – If
True
, prompts are printed onsys.stderr
. Defaults toFalse
.
prompt()
is primarily intended for simple plaintext entry. Seeprompt_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 toTrue
, for consistency withgetpass.getpass()
.
TODO¶
- TODO: InputCancelled exception, to be handled by .run()
- TODO: stuff for prompting choices
- TODO: pre-made –color flag(s) (looks at isatty)