cloup._option_groups

Implements the “option groups” feature.

Classes

OptionGroup(title[, help, constraint, hidden])

Contains the information of an option group and identifies it.

OptionGroupMixin(*args[, align_option_groups])

Implements support for:

Functions

has_option_group(param)

get_option_group_of(param)

option_group(title, *args, **kwargs)

Return a decorator that annotates a function with an option group.

Contents

class cloup._option_groups.OptionGroup(title, help=None, constraint=None, hidden=False)[source]

Contains the information of an option group and identifies it. Note that, as far as the clients of this library are concerned, an OptionGroups acts as a “marker” for options, not as a container for related options. When you call @optgroup.option(...) you are not adding an option to a container, you are just adding an option marked with this option group.

New in version 0.8.0: The hidden parameter.

Parameters
property options(self)
Return type

Sequence[click.Option]

get_help_records(self, ctx)[source]
Parameters

ctx (click.Context) –

Return type

List[Tuple[str, str]]

option(self, *param_decls, **attrs)[source]

Refer to cloup.option().

Parameters

  • param_decls (str) –

  • attrs (Any) –

Return type

Callable[[cloup.typing.F], cloup.typing.F]

__iter__(self)[source]
Return type

Iterator[click.Option]

__getitem__(self, i)[source]
Parameters

i (int) –

Return type

click.Option

__len__(self)[source]
Return type

int

__repr__(self)[source]

Return repr(self).

Return type

str

__str__(self)[source]

Return str(self).

Return type

str

cloup._option_groups.has_option_group(param)[source]
Parameters

param (click.Parameter) –

Return type

bool

cloup._option_groups.get_option_group_of(param)[source]
Parameters

param (click.Option) –

Return type

Optional[OptionGroup]

class cloup._option_groups.OptionGroupMixin(*args, align_option_groups=None, **kwargs)[source]

Implements support for:

  • option groups

  • the “Positional arguments” help section; this section is shown only if at least one of your arguments has non-empty help.

Important

In order to check the constraints defined on the option groups, a command must inherits from cloup.ConstraintMixin too!

New in version 0.14.0: added the “Positional arguments” help section.

Changed in version 0.8.0: this mixin now relies on cloup.HelpFormatter to align help sections. If a click.HelpFormatter is used with a TypeError is raised.

Changed in version 0.8.0: removed format_option_group. Added get_default_option_group and make_option_group_help_section.

New in version 0.5.0.

Parameters

  • align_option_groups (Optional[bool]) – whether to align the columns of all option groups’ help sections. This is also available as a context setting having a lower priority than this attribute. Given that this setting should be consistent across all you commands, you should probably use the context setting only.

  • args (Any) – positional arguments forwarded to the next class in the MRO

  • kwargs (Any) – keyword arguments forwarded to the next class in the MRO

option_groups

List of all option groups, except the “default option group”.

ungrouped_options

List of options not explicitly assigned to an user-defined option group. These options will be included in the “default option group”. Note: this list does not include options added automatically by Click based on context settings, like the --help option; use the get_ungrouped_options() method if you need the real full list (which needs a Context object).

get_ungrouped_options(self, ctx)[source]

Return options not explicitly assigned to an option group (eventually including the --help option), i.e. options that will be part of the “default option group”.

Parameters

ctx (click.Context) –

Return type

Sequence[click.Option]

get_argument_help_record(self, arg, ctx)[source]
Parameters
Return type

Tuple[str, str]

get_arguments_help_section(self, ctx)[source]
Parameters

ctx (click.Context) –

Return type

Optional[cloup.formatting.HelpSection]

make_option_group_help_section(self, group, ctx)[source]

Return a HelpSection for an OptionGroup, i.e. an object containing the title, the optional description and the options’ definitions for this option group.

New in version 0.8.0.

Parameters
Return type

cloup.formatting.HelpSection

must_align_option_groups(self, ctx, default=True)[source]

Return True if the help sections of all options groups should have their columns aligned.

New in version 0.8.0.

Parameters
Return type

bool

get_default_option_group(self, ctx, is_the_only_visible_option_group=False)[source]

Return an OptionGroup instance for the options not explicitly assigned to an option group, eventually including the --help option.

New in version 0.8.0.

Parameters
Return type

OptionGroup

format_params(self, ctx, formatter)[source]
Parameters
Return type

None

cloup._option_groups.option_group(title: str, help: str, *options: cloup.typing.Decorator, constraint: Optional[cloup.constraints.Constraint] = None, hidden: bool = False) → Callable[[cloup.typing.F], cloup.typing.F][source]
cloup._option_groups.option_group(title: str, *options: cloup.typing.Decorator, help: Optional[str] = None, constraint: Optional[cloup.constraints.Constraint] = None, hidden: bool = False) → Callable[[cloup.typing.F], cloup.typing.F]

Return a decorator that annotates a function with an option group.

The help argument is an optional description and can be provided either as keyword argument or as 2nd positional argument after the name of the group:

# help as keyword argument
@option_group(name, *options, help=None, ...)

# help as 2nd positional argument
@option_group(name, help, *options, ...)

Changed in version 0.9.0: in order to support the decorator cloup.constrained_params(), @option_group now allows each input decorators to add multiple options.

Parameters

  • title – title of the help section describing the option group.

  • help – an optional description shown below the name; can be provided as keyword argument or 2nd positional argument.

  • options – an arbitrary number of decorators like click.option, which attach one or multiple options to the decorated command function.

  • constraint – an optional instance of Constraint (see Constraints for more info); a description of the constraint will be shown between squared brackets aside the option group title (or below it if too long).

  • hidden – if True, the option group and all its options are hidden from the help page (all contained options will have their hidden attribute set to True).