Echo
clip provides a clip.echo()
function that prints to your app's out/err streams instead of the system standard out/err. It is recommended that you use this instead of the regular Python print()
function whenever possible, especially if your app has custom streams.
Parameters
message
: The message to echo.err=False
: Whether this is an error message.
Exit
clip.exit()
raises a ClipExit
exception, optionally printing a message beforehand. This is especially useful for short-circuiting the execution of your app, such as when displaying a version string:
app = clip.App()
def print_version(value):
clip.exit('Version 0.0.0')
@app.main()
@clip.flag('--version', callback=print_version, hidden=True)
def f():
clip.echo('This should not be called')
Parameters
message=None
: An optional message to print before exiting. Note that this message is also passed onward to the underlyingClipExit
.err=False
: Whether this exit is occuring because of an error.
Confirmation Prompt
Use clip.confirm()
to prompt the user for confirmation. It returns a boolean value indicating the user's response:
if clip.confirm('Do you want to continue?'):
clip.echo('Launching missiles...')
You can also abort immediately if the user enters a negative response (this will raise a ClipExit
with an error status):
clip.confirm('Do you want to continue?', abort=True)
When embedding an app, you can specify the function to use to prompt users for input. See the Embedding section for more details.
Parameters
prompt
: A string representing the prompt to display to the user.default=None
: A default value for the prompt if the user simply presses Enter. Must be one of'yes'
,'no'
, orNone
. IfNone
, then input is required from the user.show_default=True
: Whether to display the prompt defaults.abort=False
: Whether to abort upon a negative response.input_function=None
: The function to use to prompt users for input, defaults to Python's standardinput()
orraw_input()
.
Input Prompt
Use clip.prompt()
to prompt the user for input. It returns the user's response:
num = clip.prompt('Enter a number', default=42)
When embedding an app, you can specify the function to use to prompt users for input. See the Embedding section for more details.
Parameters
text
: A string representing the prompt to display to the user.default=None
: A default value for the prompt if the user simply presses Enter. Like with clip parameters, you can pass a function whose return value will become the default.show_default=True
: Whether to display the prompt default.invisible=False
: IfTrue
, user input is not echoed to the shell. Good for password prompts.confirm=False
: IfTrue
, the user is prompted a second time for confirmation.type=None
: A type to coerce the return value into. If no type is provided, the type of the default value is used. If no default value is provided, the type is assumed to be a string.input_function=None
: The function to use to prompt users for input, defaults to Python's standardinput()
orraw_input()
in the case of a visible prompt and thegetpass
module for an invisible prompt.