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

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

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

Required named option

To make an option mandatory, set required=True. Because takes_value defaults to True, the option consumes a value (it is not a flag), and required=True makes the CLI refuse to run unless the option is supplied. Stack the @argument under @command, and give the wrapped function a matching parameter:

import angreal

@angreal.command(name="greet", about="greet someone by name")
@angreal.argument(name="name", long="name", required=True, help="who to greet")
def command_greet(name):
    print(f"Hello, {name}!")

$ angreal greet --name=World
Hello, World!

$ angreal greet                                                                                                                                 ─╯
error: The following required arguments were not provided:
    --name <name>

USAGE:
    greet --name <name>

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