Arguments

An arc argument is a parameter which get passed to the command positionally. They are defined using regular Python function arguments.

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

Notice that we annotated the first argument as str, but the second argument as str | None? We do this because we want firstname to be required and lastname to be optional. By giving lastname a union type that includes None, we're letting arc know that if no value is passed in from the command line, it's ok for it to be None.

Using None

In arc, defining parameters as allowing None, can be done in several ways, all of which are equivelant. The following are all equivelant:

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

Setting it explictly

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

If you set the default as None, you don't actually have to annotate as such if not desired

def hello(firstname: str, lastname: str = None):

We can see it in action here

$ python parameter_argument.py Joseph
Hello, Joseph! Hope you have a wonderful day!

And adding the optional lastname

$ python parameter_argument.py Joseph Joestar
Hello, Joseph Joestar! Hope you have a wonderful day!

Documentation

$ python parameter_argument.py --help
USAGE
    parameter_argument.py [-h] firstname [lastname]

ARGUMENTS
    firstname
    lastname

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

Note

The brackets around lastname in the USAGE indicate that it is optional

Default Values

Often, we don't just want a None when a value isn't provided, but we want some sort of default. This can be accomplished by simply giving the argument a default value.

examples/parameter_default.py

import arc


@arc.command
def hello(firstname: str, lastname: str = "Joestar"):
    name = f"{firstname} {lastname}"
    arc.print(f"Hello, {name}! Hope you have a wonderful day!")


hello()

Note the lack of None in the type signature. Now that we have a default, the value will always be a string, and we don't need to tell arc that the value is optional.

Check it:

$ python parameter_default.py Sean
Hello, Sean Joestar! Hope you have a wonderful day!
$ python parameter_default.py Sean Collings
Hello, Sean Collings! Hope you have a wonderful day!

Alternative Syntax

arc has an alternative syntax fo defining arguments

Take this argument from the last example

lastname: str = "Joestar"

Could also be defined as:

lastname: str = arc.Argument(default="Joestar")

Now, arc.Argument is unnecessary here, but comes with some additional bells and whistles that make it more useful. Some of these features will be explored in future guides, or you check the reference for full details on what it provides.