Group

clap.group

group(cls: type[T]) -> type[T]

group(
    *,
    title: Optional[str] = None,
    about: Optional[str] = None,
    long_about: Optional[str] = None,
    required: bool = False,
    multiple: bool = True,
) -> Callable[[type[T]], type[T]]

group(
    cls: Optional[type[T]] = None,
    /,
    *,
    title: Optional[str] = None,
    about: Optional[str] = None,
    long_about: Optional[str] = None,
    required: bool = False,
    multiple: bool = True,
) -> Union[type[T], Callable[[type[T]], type[T]]]

Configure a class as an argument group.

Argument groups allow organizing related arguments together, both in help output and in code structure. Arguments within a group are accessed as nested attributes.

Parameters:

• cls (Optional[type[T]], default: None ) –

  The class to be decorated (when used without parentheses).

• title (Optional[str], default: None ) –

  The title for the argument group in the help output.

• about (Optional[str], default: None ) –

  The group's description for the short help (-h).

• long_about (Optional[str], default: None ) –

  The group's description for the long help (--help).

• required (bool, default: False ) –

  Require an argument from the group to be present when parsing. Note: Currently, it only works when multiple = False.

• multiple (bool, default: True ) –

  Allows more than one of the Args in this group to be used.

Example:

import clap
from clap import arg, long
from typing import Optional

@clap.group(title="Input Options")
class InputOpts:
    input_file: Optional[str] = arg(long)

@clap.group(title="Output Options")
class OutputOpts:
    output_file: Optional[str] = arg(long)

@clap.command
class Cli(clap.Parser):
    input_opts: InputOpts
    output_opts: OutputOpts

cli = Cli.parse()
print(cli.input_opts.input_file)
print(cli.output_opts.output_dir)

Source code in clap/api.py

@dataclass_transform()
def group[T](
    cls: Optional[type[T]] = None,
    /,
    *,
    title: Optional[str] = None,
    about: Optional[str] = None,
    long_about: Optional[str] = None,
    required: bool = False,
    multiple: bool = True,
) -> Union[type[T], Callable[[type[T]], type[T]]]:
    """Configure a class as an argument group.

    Argument groups allow organizing related arguments together, both in
    help output and in code structure. Arguments within a group are accessed
    as nested attributes.

    Args:
        cls: The class to be decorated (when used without parentheses).
        title: The title for the argument group in the help output.
        about: The group's description for the short help (`-h`).
        long_about: The group's description for the long help (`--help`).
        required: Require an argument from the group to be present when parsing.
            Note: Currently, it only works when `multiple = False`.
        multiple: Allows more than one of the Args in this group to be used.

    Example:

    ```python
    import clap
    from clap import arg, long
    from typing import Optional

    @clap.group(title="Input Options")
    class InputOpts:
        input_file: Optional[str] = arg(long)

    @clap.group(title="Output Options")
    class OutputOpts:
        output_file: Optional[str] = arg(long)

    @clap.command
    class Cli(clap.Parser):
        input_opts: InputOpts
        output_opts: OutputOpts

    cli = Cli.parse()
    print(cli.input_opts.input_file)
    print(cli.output_opts.output_dir)
    ```
    """

    def wrap(cls: type[T]) -> type[T]:
        nonlocal title, about, long_about
        if cls.__doc__ is not None:
            doc_about, doc_long_about = get_help_from_docstring(cls.__doc__.strip())
            if about is None:
                about = doc_about
            if long_about is None:
                long_about = doc_long_about

        setattr(cls, _GROUP_MARKER, True)
        setattr(
            cls,
            _GROUP_DATA,
            Group(
                title=title,
                about=about,
                long_about=long_about,
                required=required,
                multiple=multiple,
            ),
        )

        # clear default values of fields so that `dataclass` does not complain
        # about mutable defaults (`Arg`)
        attrs = {}
        for name in cls.__annotations__:
            if attr := getattr(cls, name, None):
                attrs[name] = attr
                setattr(cls, name, None)
        setattr(cls, _ATTR_DEFAULTS, attrs)

        dataclass(cls, slots=True)

        return cls

    if cls is None:
        return wrap
    return wrap(cls)

Nesting groups is not allowed. However, sometimes, a group may have some arguments that have to be mutually exclusive. In this case, Group can be used to create a group field, i.e., group = Group(required=True, multiple=False), and those arguments can have this as their group: verbose: bool = arg(long, group=group), quiet: bool = arg(long, group=group). In the future, I will add a conflicts_with argument to arg, which will be more general than this workaround.

clap.Group dataclass

Group(
    title: Optional[str] = None,
    about: Optional[str] = None,
    long_about: Optional[str] = None,
    required: bool = False,
    multiple: bool = True,
)

Family of related arguments.

Example:

from pathlib import Path

import clap
from clap import Group, arg

@clap.command
class Cli(clap.Parser):
    output_options = Group(title="Output Options")
    """Configure output settings."""
    output_dir: Path = arg(long="output", group=output_options, value_name="DIR")
    """Path to output directory"""

Attributes:

• about (Optional[str]) –

  The group's description for the short help (-h).

• long_about (Optional[str]) –

  The group's description for the long help (--help).

• multiple (bool) –

  Allows more than one of the Args in this group to be used.

• required (bool) –

  Require an argument from the group to be present when parsing. See note below.

• title (Optional[str]) –

  The title for the argument group in the help output.

about class-attribute instance-attribute

about: Optional[str] = None

The group's description for the short help (-h).

If Group.long_about is not specified, this message will be displayed for --help.

long_about class-attribute instance-attribute

long_about: Optional[str] = None

The group's description for the long help (--help).

If not set, Group.about will be used for long help in addition to short help (-h).

multiple class-attribute instance-attribute

multiple: bool = True

Allows more than one of the Args in this group to be used.

required class-attribute instance-attribute

required: bool = False

Require an argument from the group to be present when parsing. See note below.

Note: Currently, it only works when multiple = False.

title class-attribute instance-attribute

title: Optional[str] = None

The title for the argument group in the help output.