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


   .. py:method:: get_help_records(ctx)


   .. py:method:: option(*param_decls, **attrs)

      Refer to :func:`cloup.option`.


   .. py:method:: __iter__()


   .. py:method:: __getitem__(i)


   .. py:method:: __len__()


   .. py:method:: __repr__()

      Return repr(self).


   .. py:method:: __str__()

      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(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(arg, ctx)


   .. py:method:: get_arguments_help_section(ctx)


   .. py:method:: 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.

      .. versionadded:: 0.8.0


   .. py:method:: must_align_option_groups(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(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(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 </pages/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``).



                                         