Group Validators

Group validators operate on a set of parameters, ensuring that their values are mutually compatible. Cyclopts has some builtin common group validators in the cyclopts.validators module.

LimitedChoice

Limits the number of specified arguments within the group. Most commonly used for mutually-exclusive arguments (default behavior).

from cyclopts import App, Group, Parameter, validators
from typing import Annotated

app = App()

vehicle = Group(
    "Vehicle (choose one)",
    default_parameter=Parameter(negative=""),  # Disable "--no-" flags
    validator=validators.LimitedChoice(),  # Mutually Exclusive Options
)

@app.default
def main(
    *,
    car: Annotated[bool, Parameter(group=vehicle)] = False,
    truck: Annotated[bool, Parameter(group=vehicle)] = False,
):
    if car:
        print("I'm driving a car.")
    if truck:
        print("I'm driving a truck.")

app()
$ python drive.py --help
Usage: main COMMAND [OPTIONS]

╭─ Commands ─────────────────────────────────────────────────────────╮
│ --help -h  Display this message and exit.                          │
│ --version  Display application version.                            │
╰────────────────────────────────────────────────────────────────────╯
╭─ Vehicle (choose one) ─────────────────────────────────────────────╮
│ --car    [default: False]                                          │
│ --truck  [default: False]                                          │
╰────────────────────────────────────────────────────────────────────╯

$ python drive.py --car
I'm driving a car.

$ python drive.py --car --truck
╭─ Error ────────────────────────────────────────────────────────────╮
│ Invalid values for group "Vehicle (choose one)". Mutually          │
│ exclusive arguments: {--car, --truck}                              │
╰────────────────────────────────────────────────────────────────────╯

See the LimitedChoice docs for more info.

MutuallyExclusive

Alias for LimitedChoice with default arguments. Exists primarily because the usage/implication will be more directly obvious and searchable to developers than LimitedChoice.