Add Arguments to a Task

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

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 task_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

Options

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 task_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

Flags

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 task_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