Options

An arc option is a (usually optional) parameter that is referenced by name on the command line.

We can take the example from the previous page and convert both of the arguments to options by only adding 2 characters:

examples/parameter_option.py

import arc


@arc.command
def hello(*, firstname: str, lastname: str | None):
    name = firstname
    if lastname:
        name += f" {lastname}"

    arc.print(f"Hello, {name}! Hope you have a wonderful day!")


hello()

Now we can run it, but we must reference each argument by name (prefixed with --)

$ python parameter_option.py --firstname Joesph --lastname Joestar
Hello, Joesph Joestar! Hope you have a wonderful day!

Notice the difference? We've added a *, to the start of the argument list. In Python, any argument that comes after a bare * is a keyword-only argument. In arc, this indicates that the arguments are options.

Documentation

$ python parameter_option.py --help
USAGE
    parameter_option.py [-h] [--lastname LASTNAME] --firstname FIRSTNAME

OPTIONS
    --help (-h)  Displays this help message
    --firstname
    --lastname

Note

lastname appears before firstname in the USAGE because arc sorts optionals first

Alternative Syntax

Like arguments, options also have an alternative syntax.

Taking the function definition above:

def hello(*, firstname: str, lastname: str | None):

We could also have written it as:

def hello(
    firstname: str = arc.Option(),
    lastname: str | None = arc.Option()
):

Note that the base * is no longer present. When arc.Option() is present, it is no longer required because you are explictly telling arc what kind of parameter it is. However, it is still allowed.

Check the reference for a full rundown of the capabilities