Command Paramaters
In arc, command-line parameters are defined using Python function arguments. arc has several kinds of parameters. Each corresponds with different input syntax and different declaration syntax.
arc.Argument
¶
Argument
parameters are passed in positionally.
Example¶
import arc
@arc.command()
def hello(firstname=arc.Argument(), lastname=arc.Argument(default="")):
print(f"Hello, {firstname} {lastname}! Hope you have a wonderful day!")
hello()
Usage¶
Notes¶
- If no default value is given, the argument is required.
Arguments to arc.Argument()
¶
name: str
: The name that will be used the the param on the command linedefault: Any
: The default value for the paramdescription: str
: A string that documents the use / purpose of the parameter. Will be used in--help
documentationcallback: Callable
: a function which will be called with the parsed value from the command linecomplete: CompletionFunc
: a function which will be called to provide completions for the parameter. This argument will superscede completions for the parameters type
arc.Option
¶
Options are (usually optional) parameters that are identified by keyword.
Example¶
import arc
@arc.command()
def hello(firstname=arc.Option(), lastname=arc.Option(default="")):
print(f"Hello, {firstname} {lastname}! Hope you have a wonderful day!")
hello()
Usage¶
$ python parameter_option.py --firstname Joesph --lastname Joestar
Hello, Joesph Joestar! Hope you have a wonderful day!
Notes¶
- Just like
Argument
, anOption
is optional if the argument is given a default value, and required otherwise. However, it is usually good practice to makeOptions
optional (hence the name).
Arguments to arc.Option()
¶
name: str
: The name that will be used the the param on the command lineshort: str
: A length-one string that will be used for the short-name of this option (--help -> -h
)default: Any
: The default value for the paramdescription: str
: A string that documents the use / purpose of the parameter. Will be used in--help
documentationcallback: Callable
: a function which will be called with the parsed value from the command line-
complete: CompletionFunc
: a function which will be called to provide completions for the parameter. This argument will superscede completions for the parameters type
arc.Flag
¶
Flags are similar to Option
parameters as they are referenced by name, but they can only represent a boolean value (True / False) and do not recieve an associated value.
Example¶
import arc
@arc.command()
def hello(firstname=arc.Argument(), reverse=arc.Flag()):
if reverse:
firstname = firstname[::-1]
print(f"Hello, {firstname}! Hope you have a wonderful day!")
hello()
Usage¶
$ python parameter_flag.py Joseph
Hello, Joseph! Hope you have a wonderful day!
$ python parameter_flag.py Joseph --reverse
Hello, hpesoJ! Hope you have a wonderful day!
Notes¶
- Because flags can only represent two possible values, They are always optional. Absence of the flag implies False; presence of the flag implies True. That can be reversed by giving the argument a default of
True
.
Arguments to arc.Flag()
¶
name: str
: The name that will be used the the param on the command lineshort: str
: A length-one string that will be used for the short-name of this option (--help -> -h
)default: bool
: The default value for the param. Defaults toFalse
description: str
: A string that documents the use / purpose of the parameter. Will be used in--help
documentationcallback: Callable
: a function which will be called with the parsed value from the command line
arc.Count
¶
Count
is a special kind of flag that instead of representing a boolean values, counts how many times it is referred to.
Example¶
import arc
@arc.command()
def hello(firstname=arc.Argument(), repeat: int = arc.Count()):
print(f"Repeat {repeat} time(s)")
for i in range(0, repeat):
print(f"Hello, {firstname}! Hope you have a wonderful day!")
hello()
Usage¶
$ python parameter_count.py Joseph
Repeat 0 time(s)
$ python parameter_count.py Joseph --repeat
Repeat 1 time(s)
Hello, Joseph! Hope you have a wonderful day!
$ python parameter_count.py Joseph --repeat --repeat
Repeat 2 time(s)
Hello, Joseph! Hope you have a wonderful day!
Hello, Joseph! Hope you have a wonderful day!
Arguments to arc.Count()
¶
name: str
: The name that will be used the the param on the command lineshort: str
: A length-one string that will be used for the short-name of this option (--help -> -h
)default: int
: Default value if the param is not present in the input. Defaults to0
.description: str
: A string that documents the use / purpose of the parameter. Will be used in--help
documentationcallback: Callable
: a function which will be called with the parsed value from the command line
Parameter Shorthand¶
If you've read any other arc documentation, you may have noticed them use parameters without using Argument
, Option
, and Flag
. For convenience, arc allows a shorthand for parameters. For example, we can simplify this command:
import arc
@arc.command()
def hello(
firstname = arc.Argument(),
lastname = arc.Option(default=""),
reverse = arc.Flag()
):
...
To:
Now, let's break this down by parameter.firstname
Python considers firstname
a "positional or keyword" parameter; in arc, this means it is a positional Argument
. For implementation reasons, positional-only arguments are not allowed.
lastname
In Python, any argument that comes after a bare *
is a keyword-only argument. Since Options
are analogous to keyword-only arguments, arc uses these same semantics. Because lastname
comes after the bare *
, is is an Option
.
reverse
Finally, annotating reverse
as bool
makes it a Flag
because flags represent boolean values. While bool
has a special meaning in arc it isn't the only valid annotaion. Refer to the section below for more info.
Note
The shorthand is only useful for very simple params. Any additional features (documentation, short names, callbacks, etc..) still make use of Argument / Option / Flag
. Additionally,
there is no shorthand for Count
so it must be explictly specified every time.
Tip
Classful syntax only supports Flag
shorthand using the bool
type annotation.
Type Annotations¶
arc uses argument type hints for data validation / conversion. For example, say we want to write a command that can sum two numbers together:
from arc import CLI
cli = CLI()
@cli.command()
def add(val1: int, val2: int):
print(f"The answer is: {val1 + val2}")
cli()
Some note about types:
- if a parameter does not specify a type, arc implicitly types it as
str
. - Reference Parameter Types for a comprehensive list of all supported types.
Parameter Sources¶
While generally, input is parsed from the command line, there are a few other sources that can be used to provide input.
The precedence of sources is:
- Commane Line
- Environment Variables
- Input Prompt
- Default Value
Environment Variables¶
import arc
import os
os.environ["VAL"] = "2"
@arc.command()
def command(val: int = arc.Argument(envvar="VAL")):
print(f"VAL: {val}")
command()
VAL
Input Prompt¶
If there is no input provided on the command line for name
, arc will prompt the user for input.