Hide navigation sidebar
Hide table of contents sidebar
Back to top
Toggle table of contents sidebar

# `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)

  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]

  get_help_records(ctx)
    Parameters:

      ctx (click.Context) –

    Return type:

      List[Tuple[str, str]]

  option(*param_decls, **attrs)

    Refer to `cloup.option()`.

    Parameters:

      - param_decls (str) –

      - attrs (Any) –

    Return type:

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

  __iter__()
    Return type:

      Iterator[click.Option]

  __getitem__(i)
    Parameters:

      i (int) –

    Return type:

      click.Option

  __len__()
    Return type:

      int

  __repr__()

    Return repr(self).

    Return type:

      str

  __str__()

    Return str(self).

    Return type:

      str

cloup._option_groups.has_option_group(param)
  Parameters:

    param (click.Parameter) –

  Return type:

    bool

cloup._option_groups.get_option_group_of(param)
  Parameters:

    param (click.Option) –

  Return type:

    Optional[OptionGroup]

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

  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)

    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)
    Parameters:

      - arg (click.Argument) –

      - ctx (click.Context) –

    Return type:

      Tuple[str, str]

  get_arguments_help_section(ctx)
    Parameters:

      ctx (click.Context) –

    Return type:

      Optional[cloup.formatting.HelpSection]

  make_option_group_help_section(group, ctx)

    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:

      - group (OptionGroup) –

      - ctx (click.Context) –

    Return type:

      cloup.formatting.HelpSection

  must_align_option_groups(ctx, default=True)

    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)

    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)
    Parameters:

      - ctx (click.Context) –

      - formatter (click.HelpFormatter) –

    Return type:

      None

cloup._option_groups.option_group(title: str, help: str, *options: cloup.typing.Decorator, constraint: cloup.constraints.Constraint | None = None, hidden: bool = False) → Callable[[cloup.typing.F], cloup.typing.F]
cloup._option_groups.option_group(title: str, *options: cloup.typing.Decorator, help: str | None = None, constraint: cloup.constraints.Constraint | None = 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`).