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')
  • 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.

  • 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: InputCancelled exception, to be handled by .run()
  • TODO: stuff for prompting choices
  • TODO: pre-made –color flag(s) (looks at isatty)