Parameter Groups

Parameter groups allow you to (as the name implies!) group parameters into re-usable chunks. A parameter group can then be used for multiple commands, and each of those commands will have all of those params defined.

Creating A group

Parameter groups are fairly simple to create, you just need to decorate a class with the @arc.group decorator.

@arc.group
class MyGroup:
    ...

Adding Parameters to a group

Now, to make a group useful, we need to actually add parameters to it. To do so, we add class-variables with our desired parameter definitions.

For example, let's take this example from the flags page:

examples/parameter_flag.py

import arc


@arc.command
def hello(firstname: str, reverse: bool):
    if reverse:
        firstname = firstname[::-1]

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


hello()

and convert it to use a parameter group instead.

For this example, the transfer is very straight forward, we can just take the argument list definition, and add it to the class body:

@arc.group
class MyGroup:
    firstname: str
    reverse: bool

Using a group

To use a Parameter Group, all we need to do is add an argument to the argument list of a command, with the param group as the type hint.

def hello(group: MyGroup): # Don't need firstname or reverse here anymore

Putting it together

examples/group.py

import arc


@arc.group
class MyGroup:
    firstname: str
    reverse: bool


@arc.command
def hello(group: MyGroup):
    if group.reverse:
        group.firstname = group.firstname[::-1]

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


hello()

$ python group.py --help
USAGE
    group.py [-h] [--reverse] firstname

ARGUMENTS
    firstname

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

$ python group.py Joseph --reverse
Hello, hpesoJ! Hope you have a wonderful day!

And just like that, we have a set of re-usable parameters that we can add to any command at-will!

Some Notes about param groups

• Anything that works for regular parameters also works for Parameter groups. This means that arc.Argument() and it's cohorts can be used to expand the use of a parameter in a group.
• Because there is no bare * or equivelant, there isn't a good way to distinguish between arguments and options. So, any non-flag will be presumed to be an argument unless given an explicit arc.Option() as a default value.
• Groups are allowed to be nested arbitrarily

Param Group Callbacks

You may optionally define callbacks on a param group that will be called before or after execution of the command.

examples/group_callbacks.py

import arc


@arc.group
class Group:
    name: str

    def pre_exec(self):
        arc.print("Before the command executes")

    def post_exec(self):
        arc.print("After the command executes")


@arc.command
def command(group: Group):
    arc.print(f"Hello, {group.name}")


command()

$ python group_callbacks.py Jonathan
Before the command executes
Hello, Jonathan
After the command executes

Excluding Some Annotations

You can exclude certain annotations from being interpreted as parameters

examples/group_exclude.py

import arc


@arc.group(exclude=["val2"])
class Group:
    val1: str
    val2: str


@arc.command
def command(group: Group):
    ...


command()

You can see in the help that val1 is included as a param while val2 is not.

$ python group_exclude.py --help
USAGE
    group_exclude.py [-h] val1

ARGUMENTS
    val1

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

This is useful when you are assiging some attributes of your param group in the pre_exec() callback mentioned above, but still want type checking applying.