Add Arguments to a Command
First, all control mechanisms for commands are managed by a single decorator called @argument
. The full signature for this decorator is:
- name: the argument name, must match the provided arg/kwarg in the wrapped python function (Required)
- python_type: the python type to apply when passing to the wrapped function. Must be one of (“str”, “int”, “float”), default “str”
- takes_value: does the argument consumer a trailing value, default True
- default_value: the default value to apply if none is provided, default None
- is_flag: whether this argument is a flag, default False
- require_equals: the applied value requires an equal sign (i.e.
--arg=value
), default None - multiple_values: the argument takes multiple values, default None
- number_of_values: the argument takes a specific number of values, default None
- max_values: the argument takes at most X values, default None
- min_values: the argument takes at min X values, default None
- short: the short name for the argument, a single character (i.e.
-i
in the CLI would be ‘i’), default None - long: the long name for the argument, a single word (i.e.
--information
in the CLI would be ‘information’), default None - long_help: the help message to show when a long help message is requested via
--help
, default None - help: the short help message to show during failure or when
-h
is requested, default None - required: whether this argument is required at run time, default None
Arguments are positional after the defined command.
import angreal
@angreal.command(name="echo", about="an echo replacement")
@angreal.argument(name="phrase", help="the phrase to echo", required=True)
def command_echo(phrase):
print(phrase)
angreal echo --help ─╯
echo
an echo replacement
USAGE:
echo <phrase>
ARGS:
<phrase> the phrase to echo
OPTIONS:
-h, --help Print help information
An option is usually something that takes an argument in order control command behavior.
import angreal
green = "\33[32m"
red = "\33[31m"
end = "\33[0m"
@angreal.command(name="echo", about="an echo replacement")
@angreal.argument(name="phrase", help="the phrase to echo", required=True)
@angreal.argument(name="color", long="color", short='c', help="apply a color to the echo phrase")
def command_echo(phrase,color=None):
if color=="red":
print(red + phrase + end )
return
if color=="green":
print(green + phrase + end )
return
print(phrase)
$ angreal echo --help ─╯
echo
an echo replacement
USAGE:
echo [OPTIONS] <phrase>
ARGS:
<phrase> the phrase to echo
OPTIONS:
-c, --color <color> apply a color to the echo phrase
-h, --help Print help information
A flag is just a binary value that will set a resulting value to True without taking a value.
import angreal
green = "\33[32m"
red = "\33[31m"
end = "\33[0m"
@angreal.command(name="echo", about="an echo replacement")
@angreal.argument(name="phrase", help="the phrase to echo", required=True)
@angreal.argument(name="color", long="color", short='c', help="apply a color to the echo phrase")
@angreal.argument(name="yell", long="yell", short='y', takes_value=False, help="yell it from the tree tops", is_flag=True)
def command_echo(phrase,color=None,yell=False):
if yell:
phrase = phrase.upper() + "! ! !"
if color=="red":
print(red + phrase + end )
return
if color=="green":
print(green + phrase + end )
return
print(phrase)
$ angreal echo --help ─╯
echo
an echo replacement
USAGE:
echo [OPTIONS] <phrase>
ARGS:
<phrase> the phrase to echo
OPTIONS:
-c, --color <color> apply a color to the echo phrase
-h, --help Print help information
-y, --yell yell it from the tree tops