:orphan: :mod:`cloup._option_groups` =========================== .. py:module:: cloup._option_groups .. autoapi-nested-parse:: Implements the "option groups" feature. Classes ------- .. autosummary:: ~cloup._option_groups.OptionGroup ~cloup._option_groups.OptionGroupMixin Functions --------- .. autosummary:: ~cloup._option_groups.has_option_group ~cloup._option_groups.get_option_group_of ~cloup._option_groups.option_group Contents -------- .. py:class:: 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. .. versionadded:: 0.8.0 The ``hidden`` parameter. .. py:method:: options(self) :property: .. py:method:: get_help_records(self, ctx) .. py:method:: option(self, *param_decls, **attrs) Refer to :func:`cloup.option`. .. py:method:: __iter__(self) .. py:method:: __getitem__(self, i) .. py:method:: __len__(self) .. py:method:: __repr__(self) Return repr(self). .. py:method:: __str__(self) Return str(self). .. py:function:: has_option_group(param) .. py:function:: get_option_group_of(param) .. py:class:: 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 :class:`cloup.ConstraintMixin` too! .. versionadded:: 0.14.0 added the "Positional arguments" help section. .. versionchanged:: 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. .. versionchanged:: 0.8.0 removed ``format_option_group``. Added ``get_default_option_group`` and ``make_option_group_help_section``. .. versionadded:: 0.5.0 :param align_option_groups: 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. :param args: positional arguments forwarded to the next class in the MRO :param kwargs: keyword arguments forwarded to the next class in the MRO .. py:attribute:: option_groups List of all option groups, except the "default option group". .. py:attribute:: 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 :meth:`get_ungrouped_options` method if you need the real full list (which needs a ``Context`` object). .. py:method:: get_ungrouped_options(self, 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". .. py:method:: get_argument_help_record(self, arg, ctx) .. py:method:: get_arguments_help_section(self, ctx) .. py:method:: make_option_group_help_section(self, 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. .. versionadded:: 0.8.0 .. py:method:: must_align_option_groups(self, ctx, default = True) Return ``True`` if the help sections of all options groups should have their columns aligned. .. versionadded:: 0.8.0 .. py:method:: get_default_option_group(self, 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. .. versionadded:: 0.8.0 .. py:method:: format_params(self, ctx, formatter) .. py:function:: 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] 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, ...) .. versionchanged:: 0.9.0 in order to support the decorator :func:`cloup.constrained_params`, ``@option_group`` now allows each input decorators to add multiple options. :param title: title of the help section describing the option group. :param help: an optional description shown below the name; can be provided as keyword argument or 2nd positional argument. :param options: an arbitrary number of decorators like ``click.option``, which attach one or multiple options to the decorated command function. :param constraint: an optional instance of :class:`~cloup.constraints.Constraint` (see :doc:`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). :param 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``).