Parameter Sources

While generally, input is parsed from the command line, there are a few other sources that parameters can recieve values from

The precedence of sources is:

Command Argument
Command Line
Environment Variables
Input Prompt
Getter Function
Default Value

Type Conversion

All input sources, except for default values and getter functions, will still pass through the type conversion systems that arc provides. So you're free to use int, float, bool, or any other type that you've defined. arc will handle the conversion from enviroment variables and input prompts for you.

Command Argument¶

When an arc command is executed it will check sys.argv for input. However, you can actually provide explcit input as the first argument to call:

examples/command_string.py

import arc


@arc.command
def hello(name: str):
    arc.print(f"Hello {name}!")


hello("Sean")

$ python command_string.py 
Hello Sean!

You generally don't need to do this, but it's useful for when you want to test your interface. (In fact, that's how pretty much all of arc's own tests are defined).

Note that the command string is treated as if it was the command line input, so if the command string is provided, sys.argv will be ignored.

Command Line¶

This is the default you're probably used to. If you provide an argument on the command line, it will be parsed as the value for that parameter.

examples/hello.py

import arc


@arc.command
def hello(name: str):
    """Greets someone by name"""
    arc.print(f"Hello {name}!")


hello()

$ python hello.py Joseph
Hello Joseph!

Environment Variables¶

examples/from_env.py

import arc
import os

os.environ["VAL"] = "2"


@arc.command
def command(val: int = arc.Argument(envvar="VAL")):
    arc.print(f"VAL: {val}")


command()

Now, if the argument isn't present on the command line, it will be parsed from the environment variable VAL

$ python from_env.py 
VAL: 2
$ python from_env.py 10
VAL: 10

Input Prompt¶

If there is no input provided on the command line for name (and there was no enviroment variable), arc will prompt the user for input.

examples/from_prompt.py

import arc


@arc.command
def command(name: str = arc.Argument(prompt="What is your first name? ")):
    arc.print("Hello, " + name)


command()

$ python from_prompt.py Jolyne
Hello, Jolyne

$ python from_prompt.py
What is your name? Jolyne
Hello, Jolyne

If the parameter is optional, the user will be still be prompted, but the user can enter an empty input by just pressing Enter and the default will be used.

You can customize the prompt via a configuration parameter.

Getter Function¶

Getter functions are a way to provide a default for an argument, based on the result of a function call.

examples/from_getter.py

import arc


def get_default_name():
    return "Josuke"


@arc.command
def command(name: str = arc.Argument(get=get_default_name)):
    arc.print(f"Good morning {name}")


command()

$ python from_getter.py Sean
Good morning Sean
$ python from_getter.py 
Good morning Josuke

Different Syntax¶

Getter functions may also be defined using this decorator syntax

examples/from_getter_alias.py

import arc


@arc.command
def command(name: str = arc.Argument()):
    arc.print(f"Good morning {name}")


@command.get("name")
def get_default_name():
    return "Josuke"


command()

Default Value¶

If none of the above are satisfied first, arc will check for a default value of your parameter.

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

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

If there is no default (like with firstname above), arc will emit an error

$ python parameter_default.py 
USAGE
    parameter_default.py [-h] firstname [lastname]

The following arguments are required: firstname

Checking origin of parameter value¶

You can check what the origin of a value is like this:

examples/origins.py

import arc


@arc.command()
def command(ctx: arc.Context, value: int = 2):
    origin = ctx.get_origin("value")
    arc.print(value, origin)


command()

$ python origins.py 
2 default
$ python origins.py 10
10 command_line