
:mod:`cloup`
============

.. py:module:: cloup

.. autoapi-nested-parse::

   Top-level package for cloup.


Subpackages
-----------
.. toctree::
   :titlesonly:
   :maxdepth: 2

   constraints <constraints/index.rst>
   formatting <formatting/index.rst>

Submodules
----------
.. toctree::
   :titlesonly:
   :maxdepth: 1

   styling <styling/index.rst>
   types <types/index.rst>
   typing <typing/index.rst>
   warnings <warnings/index.rst>


                              
Classes
-------

.. autosummary::

   ~cloup.HelpTheme
   ~cloup.Style
   ~cloup.Color
   ~cloup.HelpFormatter
   ~cloup.HelpSection
   ~cloup.Context
   ~cloup.Argument
   ~cloup.Option
   ~cloup.OptionGroup
   ~cloup.OptionGroupMixin
   ~cloup.Section
   ~cloup.SectionMixin
   ~cloup.Command
   ~cloup.Group
   ~cloup.ConstraintMixin

Functions
---------

.. autosummary::

   ~cloup.get_current_context
   ~cloup.pass_context
   ~cloup.argument
   ~cloup.option
   ~cloup.option_group
   ~cloup.command
   ~cloup.group
   ~cloup.constrained_params
   ~cloup.constraint
   ~cloup.dir_path
   ~cloup.file_path
   ~cloup.path


                                           
Contents
--------
.. py:class:: HelpTheme

   A collection of styles for several elements of the help page.

   A "style" is just a function or a callable that takes a string and returns
   a styled version of it. This means you can use your favorite styling/color
   library (like rich, colorful etc). Nonetheless, given that Click has some
   basic styling functionality built-in, Cloup provides the :class:`Style`
   class, which is a wrapper of the ``click.style`` function.

   :param invoked_command:
       Style of the invoked command name (in Usage).
   :param command_help:
       Style of the invoked command description (below Usage).
   :param heading:
       Style of help section headings.
   :param constraint:
       Style of an option group constraint description.
   :param section_help:
       Style of the help text of a section (the optional paragraph below the heading).
   :param col1:
       Style of the first column of a definition list (options and command names).
   :param col2:
       Style of the second column of a definition list (help text).
   :param epilog:
       Style of the epilog.
   :param alias:
       Style of subcommand aliases in a definition lists.
   :param alias_secondary:
       Style of separator and eventual parenthesis/brackets in subcommand alias lists.
       If not provided, the ``alias`` style will be used.


   .. py:attribute:: invoked_command
      :type:  IStyle

      Style of the invoked command name (in Usage).



   .. py:attribute:: command_help
      :type:  IStyle

      Style of the invoked command description (below Usage).



   .. py:attribute:: heading
      :type:  IStyle

      Style of help section headings.



   .. py:attribute:: constraint
      :type:  IStyle

      Style of an option group constraint description.



   .. py:attribute:: section_help
      :type:  IStyle

      Style of the help text of a section (the optional paragraph below the heading).



   .. py:attribute:: col1
      :type:  IStyle

      Style of the first column of a definition list (options and command names).



   .. py:attribute:: col2
      :type:  IStyle

      Style of the second column of a definition list (help text).



   .. py:attribute:: alias
      :type:  IStyle

      Style of subcommand aliases in a definition lists.



   .. py:attribute:: alias_secondary
      :type:  Optional[IStyle]
      :value: None


      Style of separator and eventual parenthesis/brackets in subcommand alias lists.
      If not provided, the ``alias`` style will be used.



   .. py:attribute:: epilog
      :type:  IStyle

      Style of the epilog.



   .. py:method:: with_(invoked_command = None, command_help = None, heading = None, constraint = None, section_help = None, col1 = None, col2 = None, alias = None, alias_secondary = MISSING, epilog = None)


   .. py:method:: dark()
      :staticmethod:


      A theme assuming a dark terminal background color.



   .. py:method:: light()
      :staticmethod:


      A theme assuming a light terminal background color.



.. py:class:: Style

   Wraps :func:`click.style` for a better integration with :class:`HelpTheme`.

   Available colors are defined as static constants in :class:`Color`.

   Arguments are set to ``None`` by default. Passing ``False`` to boolean args
   or ``Color.reset`` as color causes a reset code to be inserted.

   With respect to :func:`click.style`, this class:

   - has an argument less, ``reset``, which is always ``True``
   - add the ``text_transform``.

   .. warning::
       The arguments ``overline``, ``italic`` and ``strikethrough`` are only
       supported in Click 8 and will be ignored if you are using Click 7.

   :param fg: foreground color
   :param bg: background color
   :param bold:
   :param dim:
   :param underline:
   :param overline:
   :param italic:
   :param blink:
   :param reverse:
   :param strikethrough:
   :param text_transform:
       a generic string transformation; useful to apply functions like ``str.upper``

   .. versionadded:: 0.8.0


   .. py:attribute:: fg
      :type:  Optional[str]
      :value: None



   .. py:attribute:: bg
      :type:  Optional[str]
      :value: None



   .. py:attribute:: bold
      :type:  Optional[bool]
      :value: None



   .. py:attribute:: dim
      :type:  Optional[bool]
      :value: None



   .. py:attribute:: underline
      :type:  Optional[bool]
      :value: None



   .. py:attribute:: overline
      :type:  Optional[bool]
      :value: None



   .. py:attribute:: italic
      :type:  Optional[bool]
      :value: None



   .. py:attribute:: blink
      :type:  Optional[bool]
      :value: None



   .. py:attribute:: reverse
      :type:  Optional[bool]
      :value: None



   .. py:attribute:: strikethrough
      :type:  Optional[bool]
      :value: None



   .. py:attribute:: text_transform
      :type:  Optional[IStyle]
      :value: None



   .. py:method:: __call__(text)


.. py:class:: Color

   Bases: :py:obj:`cloup._util.FrozenSpace`


   Colors accepted by :class:`Style` and :func:`click.style`.


   .. py:attribute:: black
      :value: 'black'



   .. py:attribute:: red
      :value: 'red'



   .. py:attribute:: green
      :value: 'green'



   .. py:attribute:: yellow
      :value: 'yellow'



   .. py:attribute:: blue
      :value: 'blue'



   .. py:attribute:: magenta
      :value: 'magenta'



   .. py:attribute:: cyan
      :value: 'cyan'



   .. py:attribute:: white
      :value: 'white'



   .. py:attribute:: reset
      :value: 'reset'



   .. py:attribute:: bright_black
      :value: 'bright_black'



   .. py:attribute:: bright_red
      :value: 'bright_red'



   .. py:attribute:: bright_green
      :value: 'bright_green'



   .. py:attribute:: bright_yellow
      :value: 'bright_yellow'



   .. py:attribute:: bright_blue
      :value: 'bright_blue'



   .. py:attribute:: bright_magenta
      :value: 'bright_magenta'



   .. py:attribute:: bright_cyan
      :value: 'bright_cyan'



   .. py:attribute:: bright_white
      :value: 'bright_white'



.. py:class:: HelpFormatter(indent_increment = 2, width = None, max_width = None, col1_max_width = 30, col2_min_width = 35, col_spacing = 2, row_sep = None, theme = HelpTheme())

   Bases: :py:obj:`click.HelpFormatter`


   A custom help formatter. Features include:

   - more attributes for controlling the output of the formatter
   - a ``col1_width`` parameter in :meth:`write_dl` that allows Cloup to align
     multiple definition lists without resorting to hacks
   - a "linear layout" for definition lists that kicks in when the available
     terminal width is not enough for the standard 2-column layout
     (see argument ``col2_min_width``)
   - the first column width, when not explicitly given in ``write_dl`` is
     computed excluding the rows that exceed ``col1_max_width``
     (called ``col_max`` in ``write_dl`` for compatibility with Click).

   .. versionchanged:: 0.9.0
       the ``row_sep`` parameter now:

       - is set to ``None`` by default and ``row_sep=""`` corresponds to an
         empty line between rows
       - must not ends with ``\n``; the formatter writes a newline just after
         it (when it's not ``None``), so a newline at the end is always enforced
       - accepts instances of :class:`~cloup.formatting.sep.SepGenerator` and
         :class:`~cloup.formatting.sep.RowSepPolicy`.

   .. versionadded:: 0.8.0

   :param indent_increment:
       width of each indentation increment.
   :param width:
       content line width, excluding the newline character; by default it's
       initialized to ``min(terminal_width - 1, max_width)`` where
       ``max_width`` is another argument.
   :param max_width:
       maximum content line width (equivalent to ``Context.max_content_width``).
       Used to compute ``width`` when it is not provided, ignored otherwise.
   :param col1_max_width:
       the maximum width of the first column of a definition list; as in Click,
       if the text of a row exceeds this threshold, the 2nd column is printed
       on a new line.
   :param col2_min_width:
       the minimum width for the second column of a definition list; if the
       available space is less than this value, the formatter switches from the
       standard 2-column layout to the "linear layout" (that this decision
       is taken for each definition list). If you want to always use the linear
       layout, you can set this argument to a very high number (or ``math.inf``).
       If you never want it (not recommended), you can set this argument to zero.
   :param col_spacing:
       the number of spaces between the column boundaries of a definition list.
   :param row_sep:
       an "extra" separator to insert between the rows of a definition list (in
       addition to the normal newline between definitions). If you want an empty
       line between rows, pass ``row_sep=""``.
       Read :ref:`Row separators <row-separators>` for more.
   :param theme:
       an :class:`~cloup.HelpTheme` instance specifying how to style the various
       elements of the help page.


   .. py:attribute:: width
      :type:  int


   .. py:attribute:: col1_max_width


   .. py:attribute:: col2_min_width


   .. py:attribute:: col_spacing


   .. py:attribute:: theme


   .. py:attribute:: row_sep


   .. py:method:: settings(*, width = MISSING, max_width = MISSING, indent_increment = MISSING, col1_max_width = MISSING, col2_min_width = MISSING, col_spacing = MISSING, row_sep = MISSING, theme = MISSING)
      :staticmethod:


      A utility method for creating a ``formatter_settings`` dictionary to
      pass as context settings or command attribute. This method exists for
      one only reason: it enables auto-complete for formatter options, thus
      improving the developer experience.

      Parameters are described in :class:`HelpFormatter`.



   .. py:property:: available_width
      :type: int



   .. py:method:: write(*strings)

      Writes a unicode string into the internal buffer.



   .. py:method:: write_usage(prog, args = '', prefix = None)

      Writes a usage line into the buffer.

      :param prog: the program name.
      :param args: whitespace separated list of arguments.
      :param prefix: The prefix for the first line. Defaults to
          ``"Usage: "``.



   .. py:method:: write_aliases(aliases)


   .. py:method:: write_command_help_text(cmd)


   .. py:method:: write_heading(heading, newline = True)

      Writes a heading into the buffer.



   .. py:method:: write_many_sections(sections, aligned = True)


   .. py:method:: write_aligned_sections(sections)

      Write multiple aligned definition lists.



   .. py:method:: write_section(s, col1_width = None)


   .. py:method:: write_text(text, style = identity)

      Writes re-indented text into the buffer.  This rewraps and
      preserves paragraphs.



   .. py:method:: compute_col1_width(rows, max_width)


   .. py:method:: write_dl(rows, col_max = None, col_spacing = None, col1_width = None)

      Write a definition list into the buffer. This is how options
      and commands are usually formatted.

      If there's enough space, definition lists are rendered as a 2-column
      pseudo-table: if the first column text of a row doesn't fit in the
      provided/computed ``col1_width``, the 2nd column is printed on the
      following line.

      If the available space for the 2nd column is below ``self.col2_min_width``,
      the 2nd "column" is always printed below the 1st, indented with a minimum
      of 3 spaces (or one ``indent_increment`` if that's greater than 3).

      :param rows:
          a list of two item tuples for the terms and values.
      :param col_max:
          the maximum width for the 1st column of a definition list; this
          argument is here to not break compatibility with Click; if provided,
          it overrides the attribute ``self.col1_max_width``.
      :param col_spacing:
          number of spaces between the first and second column;
          this argument is here to not break compatibility with Click;
          if provided, it overrides ``self.col_spacing``.
      :param col1_width:
          the width to use for the first column; if not provided, it's
          computed as the length of the longest string under ``self.col1_max_width``;
          useful when you need to align multiple definition lists.



   .. py:method:: write_tabular_dl(rows, col1_width, col_spacing, col2_width)

      Format a definition list as a 2-column "pseudo-table". If the first
      column of a row exceeds ``col1_width``, the 2nd column is written on
      the subsequent line. This is the standard way of formatting definition
      lists and it's the default if there's enough space.



   .. py:method:: write_linear_dl(dl)

      Format a definition list as a "linear list". This is the default when
      the available width for the definitions (2nd column) is below
      ``self.col2_min_width``.



   .. py:method:: write_epilog(epilog)


   .. py:method:: __repr__()


.. py:class:: HelpSection

   A container for a help section data.


   .. py:attribute:: heading
      :type:  str

      Help section title.



   .. py:attribute:: definitions
      :type:  Sequence[Definition]

      Rows with 2 columns each. The 2nd element of each row can also be a function
      taking an integer (the available width for the 2nd column) and returning a string.



   .. py:attribute:: help
      :type:  Optional[str]
      :value: None


      (Optional) long description of the section.



   .. py:attribute:: constraint
      :type:  Optional[str]
      :value: None


      (Optional) option group constraint description.



.. py:class:: Context(*ctx_args, align_option_groups = None, align_sections = None, show_subcommand_aliases = None, show_constraints = None, check_constraints_consistency = None, formatter_settings = {}, **ctx_kwargs)

   Bases: :py:obj:`click.Context`


   A custom context for Cloup.

   Look up :class:`click.Context` for the list of all arguments.

   .. versionadded:: 0.9.0
       added the ``check_constraints_consistency`` parameter.

   .. versionadded:: 0.8.0

   :param ctx_args:
       arguments forwarded to :class:`click.Context`.
   :param align_option_groups:
       if True, align the definition lists of all option groups of a command.
       You can override this by setting the corresponding argument of ``Command``
       (but you probably shouldn't: be consistent).
   :param align_sections:
       if True, align the definition lists of all subcommands of a group.
       You can override this by setting the corresponding argument of ``Group``
       (but you probably shouldn't: be consistent).
   :param show_subcommand_aliases:
       whether to show the aliases of subcommands in the help of a ``cloup.Group``.
   :param show_constraints:
       whether to include a "Constraint" section in the command help (if at
       least one constraint is defined).
   :param check_constraints_consistency:
       enable additional checks for constraints which detects mistakes of the
       developer (see :meth:`cloup.Constraint.check_consistency`).
   :param formatter_settings:
       keyword arguments forwarded to :class:`HelpFormatter` in ``make_formatter``.
       This args are merged with those of the (eventual) parent context and then
       merged again (being overridden) by those of the command.
       **Tip**: use the static method :meth:`HelpFormatter.settings` to create this
       dictionary, so that you can be guided by your IDE.
   :param ctx_kwargs:
       keyword arguments forwarded to :class:`click.Context`.


   .. py:attribute:: formatter_class
      :type:  Type[cloup.formatting.HelpFormatter]


   .. py:attribute:: align_option_groups


   .. py:attribute:: align_sections


   .. py:attribute:: show_subcommand_aliases


   .. py:attribute:: show_constraints


   .. py:attribute:: check_constraints_consistency


   .. py:attribute:: formatter_settings


   .. py:method:: get_formatter_settings()


   .. py:method:: make_formatter()

      Creates the :class:`~click.HelpFormatter` for the help and
      usage output.

      To quickly customize the formatter class used without overriding
      this method, set the :attr:`formatter_class` attribute.

      .. versionchanged:: 8.0
          Added the :attr:`formatter_class` attribute.



   .. py:method:: settings(*, auto_envvar_prefix = MISSING, default_map = MISSING, terminal_width = MISSING, max_content_width = MISSING, resilient_parsing = MISSING, allow_extra_args = MISSING, allow_interspersed_args = MISSING, ignore_unknown_options = MISSING, help_option_names = MISSING, token_normalize_func = MISSING, color = MISSING, show_default = MISSING, align_option_groups = MISSING, align_sections = MISSING, show_subcommand_aliases = MISSING, show_constraints = MISSING, check_constraints_consistency = MISSING, formatter_settings = MISSING)
      :staticmethod:


      Utility method for creating a ``context_settings`` dictionary.

      :param auto_envvar_prefix:
          the prefix to use for automatic environment variables. If this is
          `None` then reading from environment variables is disabled. This
          does not affect manually set environment variables which are always
          read.
      :param default_map:
          a dictionary (like object) with default values for parameters.
      :param terminal_width:
          the width of the terminal. The default is inherited from parent
          context. If no context defines the terminal width then auto-detection
          will be applied.
      :param max_content_width:
          the maximum width for content rendered by Click (this currently
          only affects help pages). This defaults to 80 characters if not
          overridden. In other words: even if the terminal is larger than
          that, Click will not format things wider than 80 characters by
          default.  In addition to that, formatters might add some safety
          mapping on the right.
      :param resilient_parsing:
          if this flag is enabled then Click will parse without any
          interactivity or callback invocation. Default values will also be
          ignored. This is useful for implementing things such as completion
          support.
      :param allow_extra_args:
          if this is set to `True` then extra arguments at the end will not
          raise an error and will be kept on the context. The default is to
          inherit from the command.
      :param allow_interspersed_args:
          if this is set to `False` then options and arguments cannot be
          mixed.  The default is to inherit from the command.
      :param ignore_unknown_options:
          instructs click to ignore options it does not know and keeps them
          for later processing.
      :param help_option_names:
          optionally a list of strings that define how the default help
          parameter is named. The default is ``['--help']``.
      :param token_normalize_func:
          an optional function that is used to normalize tokens (options,
          choices, etc.). This for instance can be used to implement
          case-insensitive behavior.
      :param color:
          controls if the terminal supports ANSI colors or not. The default
          is auto-detection. This is only needed if ANSI codes are used in
          texts that Click prints which is by default not the case. This for
          instance would affect help output.
      :param show_default: Show defaults for all options. If not set,
          defaults to the value from a parent context. Overrides an
          option's ``show_default`` argument.
      :param align_option_groups:
          if True, align the definition lists of all option groups of a command.
          You can override this by setting the corresponding argument of ``Command``
          (but you probably shouldn't: be consistent).
      :param align_sections:
          if True, align the definition lists of all subcommands of a group.
          You can override this by setting the corresponding argument of ``Group``
          (but you probably shouldn't: be consistent).
      :param show_subcommand_aliases:
          whether to show the aliases of subcommands in the help of a ``cloup.Group``.
      :param show_constraints:
          whether to include a "Constraint" section in the command help (if at
          least one constraint is defined).
      :param check_constraints_consistency:
          enable additional checks for constraints which detects mistakes of the
          developer (see :meth:`cloup.Constraint.check_consistency`).
      :param formatter_settings:
          keyword arguments forwarded to :class:`HelpFormatter` in ``make_formatter``.
          This args are merged with those of the (eventual) parent context and then
          merged again (being overridden) by those of the command.
          **Tip**: use the static method :meth:`HelpFormatter.settings` to create this
          dictionary, so that you can be guided by your IDE.



.. py:function:: get_current_context() -> Context
                 get_current_context(silent: bool = False) -> Optional[Context]

   Equivalent to :func:`click.get_current_context` but casts the returned
   :class:`click.Context` object to :class:`cloup.Context` (which is safe when using
   cloup commands classes and decorators).


.. py:function:: pass_context(f)

   Marks a callback as wanting to receive the current context object as first
   argument. Equivalent to :func:`click.pass_context` but assumes the current context
   is of type :class:`cloup.Context`.


.. py:class:: Argument(*args, help=None, **attrs)

   Bases: :py:obj:`click.Argument`


   A :class:`click.Argument` with help text.


   .. py:attribute:: help


   .. py:method:: get_help_record(ctx)


.. py:class:: Option(*args, group=None, **attrs)

   Bases: :py:obj:`click.Option`


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


   .. py:attribute:: group


.. py:function:: argument(*param_decls, cls=None, **attrs)

.. py:function:: option(*param_decls, cls=None, group=None, **attrs)

   Attach an ``Option`` to the command.
   Refer to :class:`click.Option` and :class:`click.Parameter` for more info
   about the accepted parameters.

   In your IDE, you won't see arguments relating to shell completion,
   because they are different in Click 7 and 8 (both supported by Cloup):

   - in Click 7, it's ``autocompletion``
   - in Click 8, it's ``shell_complete``.

   These arguments have different semantics, refer to Click's docs.


.. 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:attribute:: title


   .. py:attribute:: help


   .. py:attribute:: constraint


   .. py:attribute:: hidden


   .. 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__()


   .. py:method:: __str__()


.. 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:: align_option_groups


   .. py:attribute:: arguments


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


.. py:class:: Section(title, commands = (), is_sorted = False)

   A group of (sub)commands to show in the same help section of a
   ``MultiCommand``. You can use sections with any `Command` that inherits
   from :class:`SectionMixin`.

   .. versionchanged:: 0.6.0
       removed the deprecated old name ``GroupSection``.

   .. versionchanged:: 0.5.0
       introduced the new name ``Section`` and deprecated the old ``GroupSection``.

   :param title:
   :param commands: sequence of commands or dict of commands keyed by name
   :param is_sorted:
       if True, ``list_commands()`` returns the commands in lexicographic order


   .. py:attribute:: title


   .. py:attribute:: is_sorted


   .. py:attribute:: commands
      :type:  collections.OrderedDict[str, click.Command]


   .. py:method:: sorted(title, commands = ())
      :classmethod:



   .. py:method:: add_command(cmd, name = None)


   .. py:method:: list_commands()


   .. py:method:: __len__()


   .. py:method:: __repr__()


.. py:class:: SectionMixin(*args, commands = None, sections = (), align_sections = None, **kwargs)

   Adds to a :class:`click.MultiCommand` the possibility of organizing its subcommands
   into multiple help sections.

   Sections can be specified in the following ways:

   #. passing a list of :class:`Section` objects to the constructor setting
      the argument ``sections``
   #. using :meth:`add_section` to add a single section
   #. using :meth:`add_command` with the argument `section` set

   Commands not assigned to any user-defined section are added to the
   "default section", whose title is "Commands" or "Other commands" depending
   on whether it is the only section or not. The default section is the last
   shown section in the help and its commands are listed in lexicographic order.

   .. 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_section``. Added ``make_commands_help_section``.

   .. versionadded:: 0.5.0

   :param align_sections:
       whether to align the columns of all subcommands' 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:: align_sections


   .. py:method:: add_section(section)

      Add a :class:`Section` to this group. You can add the same
      section object only a single time.

      See Also:
          :meth:`section`



   .. py:method:: section(title, *commands, **attrs)

      Create a new :class:`Section`, adds it to this group and returns it.



   .. py:method:: add_command(cmd, name = None, section = None, fallback_to_default_section = True)

      Add a subcommand to this ``Group``.

      **Implementation note:** ``fallback_to_default_section`` looks not very
      clean but, even if it's not immediate to see (it wasn't for me), I chose
      it over apparently cleaner options.

      :param cmd:
      :param name:
      :param section:
          a ``Section`` instance. The command must not be in the section already.
      :param fallback_to_default_section:
          if ``section`` is None and this option is enabled, the command is added
          to the "default section". If disabled, the command is not added to
          any section unless ``section`` is provided. This is useful for
          internal code and subclasses. Don't disable it unless you know what
          you are doing.



   .. py:method:: list_sections(ctx, include_default_section = True)

      Return the list of all sections in the "correct order".

      If ``include_default_section=True`` and the default section is non-empty,
      it will be included at the end of the list.



   .. py:method:: format_subcommand_name(ctx, name, cmd)

      Used to format the name of the subcommands. This method is useful
      when you combine this extension with other click extensions that override
      :meth:`format_commands`. Most of these, like click-default-group, just
      add something to the name of the subcommands, which is exactly what this
      method allows you to do without overriding bigger methods.



   .. py:method:: make_commands_help_section(ctx, section)


   .. py:method:: must_align_sections(ctx, default = True)


   .. py:method:: format_commands(ctx, formatter)


.. py:class:: Command(*args, aliases = None, formatter_settings = None, **kwargs)

   Bases: :py:obj:`cloup.constraints.ConstraintMixin`, :py:obj:`cloup._option_groups.OptionGroupMixin`, :py:obj:`click.Command`


   A ``click.Command`` supporting option groups and constraints.

   Refer to superclasses for the documentation of all accepted parameters:

   - :class:`ConstraintMixin`
   - :class:`OptionGroupMixin`
   - :class:`click.Command`

   Besides other things, this class also:

   * adds a ``formatter_settings`` instance attribute.

   Refer to :class:`click.Command` for the documentation of all parameters.

   .. versionadded:: 0.8.0

   :param constraints:
       sequence of constraints bound to specific groups of parameters.
       Note that constraints applied to option groups are collected from
       the option groups themselves, so they don't need to be included in
       this argument.
   :param show_constraints:
       whether to include a "Constraint" section in the command help. This
       is also available as a context setting having a lower priority than
       this attribute.
   :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:: context_class
      :type:  Type[cloup._context.Context]


   .. py:attribute:: aliases
      :type:  List[str]


   .. py:attribute:: formatter_settings
      :type:  Dict[str, Any]


   .. py:method:: get_normalized_epilog()


   .. py:method:: format_epilog(ctx, formatter)

      Writes the epilog into the formatter if it exists.



   .. py:method:: format_help_text(ctx, formatter)

      Writes the help text to the formatter if it exists.



   .. py:method:: format_aliases(ctx, formatter)


   .. py:method:: format_help(ctx, formatter)

      Writes the help into the formatter if it exists.

      This is a low-level method called by :meth:`get_help`.

      This calls the following methods:

      -   :meth:`format_usage`
      -   :meth:`format_help_text`
      -   :meth:`format_options`
      -   :meth:`format_epilog`



.. py:class:: Group(*args, show_subcommand_aliases = None, commands = None, **kwargs)

   Bases: :py:obj:`cloup._sections.SectionMixin`, :py:obj:`Command`, :py:obj:`click.Group`


   A ``click.Group`` that allows to organize its subcommands in multiple help
   sections and whose subcommands are, by default, of type :class:`cloup.Command`.

   Refer to superclasses for the documentation of all accepted parameters:

   - :class:`SectionMixin`
   - :class:`Command`
   - :class:`click.Group`

   Apart from superclasses arguments, the following is the only additional parameter:

   ``show_subcommand_aliases``: ``Optional[bool] = None``
       whether to show subcommand aliases; aliases are shown by default and
       can be disabled using this argument or the homonym context setting.

   .. versionchanged:: 0.14.0
       this class now supports option groups and constraints.

   .. versionadded:: 0.10.0
       the "command aliases" feature, including the ``show_subcommand_aliases``
       parameter/attribute.

   .. versionchanged:: 0.8.0
       this class now inherits from :class:`cloup.BaseCommand`.

   :param align_sections:
       whether to align the columns of all subcommands' 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:: SHOW_SUBCOMMAND_ALIASES
      :type:  bool
      :value: False



   .. py:attribute:: show_subcommand_aliases

      Whether to show subcommand aliases.



   .. py:attribute:: alias2name
      :type:  Dict[str, str]

      Dictionary mapping each alias to a command name.



   .. py:method:: add_multiple_commands(commands)


   .. py:method:: add_command(cmd, name = None, section = None, fallback_to_default_section = True)

      Add a subcommand to this ``Group``.

      **Implementation note:** ``fallback_to_default_section`` looks not very
      clean but, even if it's not immediate to see (it wasn't for me), I chose
      it over apparently cleaner options.

      :param cmd:
      :param name:
      :param section:
          a ``Section`` instance. The command must not be in the section already.
      :param fallback_to_default_section:
          if ``section`` is None and this option is enabled, the command is added
          to the "default section". If disabled, the command is not added to
          any section unless ``section`` is provided. This is useful for
          internal code and subclasses. Don't disable it unless you know what
          you are doing.



   .. py:method:: resolve_command_name(ctx, name)

      Map a string supposed to be a command name or an alias to a normalized
      command name. If no match is found, it returns ``None``.



   .. py:method:: resolve_command(ctx, args)


   .. py:method:: handle_bad_command_name(bad_name, valid_names, error)

      This method is called when a command name cannot be resolved.
      Useful to implement the "Did you mean <x>?" feature.

      :param bad_name: the command name that could not be resolved.
      :param valid_names: the list of valid command names, including aliases.
      :param error: the original error coming from Click.
      :return: the original error or a new one.



   .. py:method:: must_show_subcommand_aliases(ctx)


   .. py:method:: format_subcommand_name(ctx, name, cmd)

      Used to format the name of the subcommands. This method is useful
      when you combine this extension with other click extensions that override
      :meth:`format_commands`. Most of these, like click-default-group, just
      add something to the name of the subcommands, which is exactly what this
      method allows you to do without overriding bigger methods.



   .. py:method:: format_subcommand_aliases(aliases, theme)
      :staticmethod:



   .. py:method:: command(name: Optional[str] = None, *, aliases: Optional[Iterable[str]] = None, cls: None = None, section: Optional[cloup._sections.Section] = None, context_settings: Optional[Dict[str, Any]] = None, formatter_settings: Optional[Dict[str, Any]] = None, help: Optional[str] = None, epilog: Optional[str] = None, short_help: Optional[str] = None, options_metavar: Optional[str] = '[OPTIONS]', add_help_option: bool = True, no_args_is_help: bool = False, hidden: bool = False, deprecated: bool = False, align_option_groups: Optional[bool] = None, show_constraints: Optional[bool] = None, params: Optional[List[click.Parameter]] = None) -> Callable[[cloup.typing.AnyCallable], click.Command]
                  command(name: Optional[str] = None, *, aliases: Optional[Iterable[str]] = None, cls: Type[C], section: Optional[cloup._sections.Section] = None, context_settings: Optional[Dict[str, Any]] = None, help: Optional[str] = None, epilog: Optional[str] = None, short_help: Optional[str] = None, options_metavar: Optional[str] = '[OPTIONS]', add_help_option: bool = True, no_args_is_help: bool = False, hidden: bool = False, deprecated: bool = False, params: Optional[List[click.Parameter]] = None, **kwargs: Any) -> Callable[[cloup.typing.AnyCallable], C]

      Return a decorator that creates a new subcommand of this ``Group``
      using the decorated function as callback.

      It takes the same arguments of :func:`command` plus:

      ``section``: ``Optional[Section]``
          if provided, put the subcommand in this section.

      .. versionchanged:: 0.10.0
          all arguments but ``name`` are now keyword-only.



   .. py:method:: group(name: Optional[str] = None, *, aliases: Optional[Iterable[str]] = None, cls: None = None, section: Optional[cloup._sections.Section] = None, sections: Iterable[cloup._sections.Section] = (), align_sections: Optional[bool] = None, invoke_without_command: bool = False, no_args_is_help: bool = False, context_settings: Optional[Dict[str, Any]] = None, formatter_settings: Dict[str, Any] = {}, help: Optional[str] = None, epilog: Optional[str] = None, short_help: Optional[str] = None, options_metavar: Optional[str] = '[OPTIONS]', subcommand_metavar: Optional[str] = None, add_help_option: bool = True, chain: bool = False, hidden: bool = False, deprecated: bool = False, show_subcommand_aliases: bool = False) -> Callable[[cloup.typing.AnyCallable], click.Group]
                  group(name: Optional[str] = None, *, aliases: Optional[Iterable[str]] = None, cls: Optional[Type[G]] = None, section: Optional[cloup._sections.Section] = None, invoke_without_command: bool = False, no_args_is_help: bool = False, context_settings: Optional[Dict[str, Any]] = None, help: Optional[str] = None, epilog: Optional[str] = None, short_help: Optional[str] = None, options_metavar: Optional[str] = '[OPTIONS]', subcommand_metavar: Optional[str] = None, add_help_option: bool = True, chain: bool = False, hidden: bool = False, deprecated: bool = False, params: Optional[List[click.Parameter]] = None, **kwargs: Any) -> Callable[[cloup.typing.AnyCallable], G]

      Return a decorator that creates a new subcommand of this ``Group``
      using the decorated function as callback.

      It takes the same argument of :func:`group` plus:

      ``section``: ``Optional[Section]``
          if provided, put the subcommand in this section.

      .. versionchanged:: 0.10.0
          all arguments but ``name`` are now keyword-only.



.. py:function:: command(name: Optional[str] = None, *, aliases: Optional[Iterable[str]] = None, cls: None = None, context_settings: Optional[Dict[str, Any]] = None, formatter_settings: Optional[Dict[str, Any]] = None, help: Optional[str] = None, short_help: Optional[str] = None, epilog: Optional[str] = None, options_metavar: Optional[str] = '[OPTIONS]', add_help_option: bool = True, no_args_is_help: bool = False, hidden: bool = False, deprecated: bool = False, align_option_groups: Optional[bool] = None, show_constraints: Optional[bool] = None, params: Optional[List[click.Parameter]] = None) -> Callable[[cloup.typing.AnyCallable], Command]
                 command(name: Optional[str] = None, *, aliases: Optional[Iterable[str]] = None, cls: Type[C], context_settings: Optional[Dict[str, Any]] = None, help: Optional[str] = None, short_help: Optional[str] = None, epilog: Optional[str] = None, options_metavar: Optional[str] = '[OPTIONS]', add_help_option: bool = True, no_args_is_help: bool = False, hidden: bool = False, deprecated: bool = False, params: Optional[List[click.Parameter]] = None, **kwargs: Any) -> Callable[[cloup.typing.AnyCallable], C]

   Return a decorator that creates a new command using the decorated function
   as callback.

   The only differences with respect to ``click.command`` are:

   - the default command class is :class:`cloup.Command`
   - supports constraints, provided that ``cls`` inherits from ``ConstraintMixin``
     like ``cloup.Command`` (the default)
   - this function has detailed type hints and uses generics for the ``cls``
     argument and return type.

   Note that the following arguments are about Cloup-specific features and are
   not supported by all ``click.Command``, so if you provide a custom ``cls``
   make sure you don't set these:

   - ``formatter_settings``
   - ``align_option_groups`` (``cls`` needs to inherit from ``OptionGroupMixin``)
   - ``show_constraints`` (``cls`` needs to inherit ``ConstraintMixin``).

   .. versionchanged:: 0.10.0
       this function is now generic: the return type depends on what you provide
       as ``cls`` argument.

   .. versionchanged:: 0.9.0
       all arguments but ``name`` are now keyword-only arguments.

   :param name:
       the name of the command to use unless a group overrides it.
   :param aliases:
       alternative names for this command. If ``cls`` is not a Cloup command class,
       aliases will be stored in the instantiated command by monkey-patching
       and aliases won't be documented in the help page of the command.
   :param cls:
       the command class to instantiate.
   :param context_settings:
       an optional dictionary with defaults that are passed to the context object.
   :param formatter_settings:
       arguments for the formatter; you can use :meth:`HelpFormatter.settings`
       to build this dictionary.
   :param help:
       the help string to use for this command.
   :param epilog:
       like the help string but it's printed at the end of the help page after
       everything else.
   :param short_help:
       the short help to use for this command.  This is shown on the command
       listing of the parent command.
   :param options_metavar:
       metavar for options shown in the command's usage string.
   :param add_help_option:
       by default each command registers a ``--help`` option.
       This can be disabled by this parameter.
   :param no_args_is_help:
       this controls what happens if no arguments are provided. This option is
       disabled by default. If enabled this will add ``--help`` as argument if
       no arguments are passed
   :param hidden:
       hide this command from help outputs.
   :param deprecated:
       issues a message indicating that the command is deprecated.
   :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 show_constraints:
       whether to include a "Constraint" section in the command help. This
       is also available as a context setting having a lower priority than
       this attribute.
   :param params:
       **(click >= 8.1.0)** a list of parameters (:class:`Argument` and
       :class:`Option` instances). Params added with ``@option`` and ``@argument``
       are appended to the end of the list if given.
   :param kwargs:
       any other argument accepted by the instantiated command class (``cls``).


.. py:function:: group(name: Optional[str] = None, *, cls: None = None, aliases: Optional[Iterable[str]] = None, sections: Iterable[cloup._sections.Section] = (), align_sections: Optional[bool] = None, invoke_without_command: bool = False, no_args_is_help: bool = False, context_settings: Optional[Dict[str, Any]] = None, formatter_settings: Dict[str, Any] = {}, help: Optional[str] = None, short_help: Optional[str] = None, epilog: Optional[str] = None, options_metavar: Optional[str] = '[OPTIONS]', subcommand_metavar: Optional[str] = None, add_help_option: bool = True, chain: bool = False, hidden: bool = False, deprecated: bool = False, params: Optional[List[click.Parameter]] = None, show_subcommand_aliases: bool = False) -> Callable[[cloup.typing.AnyCallable], Group]
                 group(name: Optional[str] = None, *, cls: Type[G], aliases: Optional[Iterable[str]] = None, invoke_without_command: bool = False, no_args_is_help: bool = False, context_settings: Optional[Dict[str, Any]] = None, help: Optional[str] = None, short_help: Optional[str] = None, epilog: Optional[str] = None, options_metavar: Optional[str] = '[OPTIONS]', subcommand_metavar: Optional[str] = None, add_help_option: bool = True, chain: bool = False, hidden: bool = False, deprecated: bool = False, params: Optional[List[click.Parameter]] = None, **kwargs: Any) -> Callable[[cloup.typing.AnyCallable], G]

   Return a decorator that instantiates a ``Group`` (or a subclass of it)
   using the decorated function as callback.

   .. versionchanged:: 0.10.0
       the ``cls`` argument can now be any ``click.Group`` (previously had to
       be a ``cloup.Group``) and the type of the instantiated command matches
       it (previously, the type was ``cloup.Group`` even if ``cls`` was a subclass
       of it).

   .. versionchanged:: 0.9.0
       all arguments but ``name`` are now keyword-only arguments.

   :param name:
       the name of the command to use unless a group overrides it.
   :param cls:
       the ``click.Group`` (sub)class to instantiate. This is ``cloup.Group``
       by default. Note that some of the arguments are only supported by
       ``cloup.Group``.
   :param sections:
       a list of Section objects containing the subcommands of this ``Group``.
       This argument is only supported by commands inheriting from
       :class:`cloup.SectionMixin`.
   :param align_sections:
       whether to align the columns of all subcommands' 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 context_settings:
       an optional dictionary with defaults that are passed to the context object.
   :param formatter_settings:
       arguments for the formatter; you can use :meth:`HelpFormatter.settings`
       to build this dictionary.
   :param help:
       the help string to use for this command.
   :param short_help:
       the short help to use for this command.  This is shown on the command
       listing of the parent command.
   :param epilog:
       like the help string but it's printed at the end of the help page after
       everything else.
   :param options_metavar:
       metavar for options shown in the command's usage string.
   :param add_help_option:
       by default each command registers a ``--help`` option.
       This can be disabled by this parameter.
   :param hidden:
       hide this command from help outputs.
   :param deprecated:
       issues a message indicating that the command is deprecated.
   :param invoke_without_command:
       this controls how the multi command itself is invoked. By default it's
       only invoked if a subcommand is provided.
   :param no_args_is_help:
       this controls what happens if no arguments are provided. This option is
       enabled by default if `invoke_without_command` is disabled or disabled
       if it's enabled. If enabled this will add ``--help`` as argument if no
       arguments are passed.
   :param subcommand_metavar:
       string used in the command's usage string to indicate the subcommand place.
   :param chain:
       if this is set to `True`, chaining of multiple subcommands is enabled.
       This restricts the form of commands in that they cannot have optional
       arguments but it allows multiple commands to be chained together.
   :param params:
       **(click >= 8.1.0)** a list of parameters (:class:`Argument` and
       :class:`Option` instances). Params added with ``@option`` and ``@argument``
       are appended to the end of the list if given.
   :param kwargs:
       any other argument accepted by the instantiated command class.


.. py:class:: ConstraintMixin(*args, constraints = (), show_constraints = None, **kwargs)

   Provides support for constraints.

   :param constraints:
       sequence of constraints bound to specific groups of parameters.
       Note that constraints applied to option groups are collected from
       the option groups themselves, so they don't need to be included in
       this argument.
   :param show_constraints:
       whether to include a "Constraint" section in the command help. This
       is also available as a context setting having a lower priority than
       this attribute.
   :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:: show_constraints


   .. py:attribute:: optgroup_constraints

      Constraints applied to ``OptionGroup`` instances.



   .. py:attribute:: param_constraints
      :type:  Tuple[BoundConstraint, Ellipsis]

      Constraints registered using ``@constraint`` (or equivalent method).



   .. py:attribute:: all_constraints

      All constraints applied to parameter/option groups of this command.



   .. py:method:: parse_args(ctx, args)


   .. py:method:: get_param_by_name(name)


   .. py:method:: get_params_by_name(names)


   .. py:method:: format_constraints(ctx, formatter)


   .. py:method:: must_show_constraints(ctx)


.. py:function:: constrained_params(constr, *param_adders)

   Return a decorator that adds the given parameters and applies a constraint
   to them. Equivalent to::

       @param_adders[0]
       ...
       @param_adders[-1]
       @constraint(constr, <param names>)

   This decorator saves you to manually (re)type the parameter names.
   It can also be used inside ``@option_group``.

   Instead of using this decorator, you can also call the constraint itself::

       @constr(*param_adders)

   but remember that:

   - Python 3.9 is the first that allows arbitrary expressions on the right of ``@``;
   - using a long conditional/composite constraint as decorator may be less
     readable.

   In these cases, you may consider using ``@constrained_params``.

   .. versionadded:: 0.9.0

   :param constr: an instance of :class:`Constraint`
   :param param_adders:
       function decorators, each attaching a single parameter to the decorated
       function.


.. py:function:: constraint(constr, params)

   Register a constraint on a list of parameters specified by (destination) name
   (e.g. the default name of ``--input-file`` is ``input_file``).


.. py:function:: dir_path(*, path_type = pathlib.Path, exists = False, readable = True, writable = False, executable = False, resolve_path = False, allow_dash = False)

   Shortcut for :class:`click.Path` with
   ``file_okay=False, path_type=pathlib.Path``.


.. py:function:: file_path(*, path_type = pathlib.Path, exists = False, readable = True, writable = False, executable = False, resolve_path = False, allow_dash = False)

   Shortcut for :class:`click.Path` with
   ``dir_okay=False, path_type=pathlib.Path``.


.. py:function:: path(*, path_type = pathlib.Path, exists = False, file_okay = True, dir_okay = True, readable = True, writable = False, executable = False, resolve_path = False, allow_dash = False)

   Shortcut for :class:`click.Path` with ``path_type=pathlib.Path``.



                                         