cloup._option_groups
¶
Implements the “option groups” feature.
Classes¶
|
Contains the information of an option group and identifies it. |
|
Implements support to: |
Functions¶
|
|
|
|
|
Returns 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
title (str) –
help (Optional[str]) –
constraint (Optional[cloup.constraints.Constraint]) –
hidden (bool) –
- property options: Sequence[click.Option]¶
- Return type
Sequence[click.Option]
- option(*param_decls, **attrs)[source]¶
Refer to
cloup.option()
.- Parameters
param_decls (str) –
attrs (Any) –
- Return type
Callable[[cloup.typing.F], cloup.typing.F]
- 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 to:
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 aclick.HelpFormatter
is used with aTypeError
is raised.Changed in version 0.8.0: removed
format_option_group
. Addedget_default_option_group
andmake_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 theget_ungrouped_options()
method if you need the real full list (which needs aContext
object).
- get_ungrouped_options(ctx)[source]¶
Returns 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]¶
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
- must_align_option_groups(ctx, default=True)[source]¶
Returns
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]¶
Returns 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
- 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]
Returns 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 thename
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 theirhidden
attribute set toTrue
).