cloup._option_groups

Implements support to option group.

Classes

OptionGroup(name[, help, constraint, hidden])	Contains the information of an option group and identifies it.
GroupedOption(*args[, group])	A click.Option with an extra field group of type OptionGroup
OptionGroupMixin(*args[, align_option_groups])	Implements support to option groups.

Functions

has_option_group(param)
get_option_group_of(param[, default])
option(*param_decls[, group, cls])
option_group(name, *args, **kwargs)	Returns a decorator that annotates a function with an option group.

Attributes

C
OptionAdder	A decorator that registers an option to the wrapped function.
OptionGroupAdder	A decorator that registers an option group to the wrapped function.

Contents

cloup._option_groups.C

cloup._option_groups.OptionAdder

A decorator that registers an option to the wrapped function.

cloup._option_groups.OptionGroupAdder

A decorator that registers an option group to the wrapped function.

class cloup._option_groups.OptionGroup(name, help=None, constraint=None, hidden=False)

Parameters

• name (str) –

• help (Optional[str]) –

• constraint (Optional[cloup.constraints._core.Constraint]) –

• hidden (bool) –

property options(self)

Return type

Sequence[click.Option]

get_help_records(self, ctx)

Parameters

ctx (click.Context) –

Return type

List[Tuple[str, str]]

option(self, *param_decls, **attrs)

__iter__(self)

__getitem__(self, i)

Parameters

i (int) –

Return type

click.Option

__len__(self)

Return type

int

__repr__(self)

Return repr(self).

Return type

str

__str__(self)

Return str(self).

Return type

str

class cloup._option_groups.GroupedOption(*args, group=None, **attrs)

Bases: click.Option

A click.Option with an extra field group of type OptionGroup

Parameters

group (Optional[cloup._option_groups.OptionGroup]) –

cloup._option_groups.has_option_group(param)

Return type

bool

cloup._option_groups.get_option_group_of(param, default=None)

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

Implements support to option groups.

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.

Important

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

Parameters

align_option_groups (Optional[bool]) –

get_ungrouped_options(self, ctx)

Parameters

ctx (click.Context) –

Return type

Sequence[click.Option]

make_option_group_help_section(self, group, ctx)

Returns 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

• group (OptionGroup) –

• ctx (click.Context) –

Return type

cloup.formatting.HelpSection

must_align_option_groups(self, ctx, default=True)

New in version 0.8.0.

Parameters

ctx (Optional[click.Context]) –

Return type

bool

get_default_option_group(self, ctx)

New in version 0.8.0.

Parameters

ctx (click.Context) –

Return type

OptionGroup

format_options(self, ctx, formatter)

Parameters

• ctx (click.Context) –

• formatter (click.HelpFormatter) –

Return type

None

cloup._option_groups.option(*param_decls, group=None, cls=GroupedOption, **attrs)

Parameters

• group (Optional[cloup._option_groups.OptionGroup]) –

• cls (Type[click.core.Option]) –

Return type

Callable[[C], C]

cloup._option_groups.option_group(name: str, help: str, *options: OptionAdder, constraint: Optional[cloup.constraints.Constraint] = None, hidden: bool = False) → OptionGroupAdder

cloup._option_groups.option_group(name: str, *options: OptionAdder, help: Optional[str] = None, constraint: Optional[cloup.constraints.Constraint] = None, hidden: bool = False) → OptionGroupAdder

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

The help 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, ...)

Parameters

• name – this is shown as heading 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 annotate the input function with one Option.

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