A command is the basic building block of a clip application. You can create a command out of a regular function in one of two ways:
-
By specifying it as the main function of an app
@app.main() def f(): pass
-
By specifying it as a subcommand of another command
@some_command.subcommand() def f(): pass
This section will look at the ways that you can customize your commands via decorator keyword arguments.
Keyword Arguments
default=None
A string specifying the default input to use when no input is given by the user. For example:
@app.main(default='x --num 19')
def f():
pass
@f.subcommand(default='-h')
@clip.opt('--num', type=int, required=True)
def x(num):
clip.echo('I was invoked with the number {}!'.format(num))
Produces:
$ python f.py x --num 5
I was invoked with the number 5!
$ python f.py x
f x
Usage: x {{options}}
Options:
-h, --help Show this help message and exit
--num [int]
$ python f.py
I was invoked with the number 19!
As you can see, default
is especially good for specifying default subcommands to run, or printing the help text when no input is entered.
description=None
A command's description is printed out in help message screens. For example:
@app.main(description='This thing does awesome stuff!')
def f():
pass
@f.subcommand(description='This is a sweet subcommand!')
def sub():
pass
Produces the following:
$ python f.py -h
f: This thing does awesome stuff!
Usage: f {{options}} {{subcommand}}
Options:
-h, --help Show this help message and exit
Subcommands:
sub This is a sweet subcommand!
$ python f.py sub -h
f sub: This is a sweet subcommand!
Usage: sub {{options}}
Options:
-h, --help Show this help message and exit
epilogue=None
Text printed at the very end of the command's help screen. For example:
@app.main(epilogue='So long and thanks for all the fish!')
def f():
pass
Produces:
$ python f.py -h
f
Usage: f {{options}}
Options:
-h, --help Show this help message and exit
So long and thanks for all the fish!
inherits=None
In clip commands can be nested indefinitely, so it only makes sense that commands can also inherit parameters from their parents. This concept is covered in the Inheriting Parameters section.
tree_view=None
Pass the name of a Flag that, if called, will display a recursive tree view of the command and all its subcommands. For example:
@app.main(tree_view='-t')
@clip.flag('-t', '--tree', hidden=True)
def w():
pass
@w.subcommand()
def x():
pass
@x.subcommand()
def y():
pass
@y.subcommand()
def z():
pass
Produces:
$ python f.py --tree
w
x
y
z
This is particularly useful for a brief overview of a large program with many commands. Note that you should not use the given flag for anything except a placeholder to invoke the tree view, as many of its attributes will be overridden.