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: Sequence[click.Option]#
Return type:

Sequence[click.Option]

get_help_records(ctx)[source]#
Parameters:

ctx (click.Context) –

Return type:

List[Tuple[str, str]]

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

Refer to cloup.option().

Parameters:
  • param_decls (str) –

  • attrs (Any) –

Return type:

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

__iter__()[source]#
Return type:

Iterator[click.Option]

__getitem__(i)[source]#
Parameters:

i (int) –

Return type:

click.Option

__len__()[source]#
Return type:

int

__repr__()[source]#

Return repr(self).

Return type:

str

__str__()[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(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(arg, ctx)[source]#
Parameters:
  • arg (click.Argument) –

  • ctx (click.Context) –

Return type:

Tuple[str, str]

get_arguments_help_section(ctx)[source]#
Parameters:

ctx (click.Context) –

Return type:

Optional[cloup.formatting.HelpSection]

make_option_group_help_section(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(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:
  • ctx (Optional[click.Context]) –

  • default (bool) –

Return type:

bool

get_default_option_group(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:
  • ctx (click.Context) –

  • is_the_only_visible_option_group (bool) –

Return type:

OptionGroup

format_params(ctx, formatter)[source]#
Parameters:
  • ctx (click.Context) –

  • formatter (click.HelpFormatter) –

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