:orphan:

:mod:`cloup._commands`
======================

.. py:module:: cloup._commands

.. autoapi-nested-parse::

   This modules contains Cloup command classes and decorators.

   Note that Cloup commands *are* Click commands. Apart from supporting more
   features, Cloup command decorators have detailed type hints and are generics so
   that type checkers can precisely infer the type of the returned command based on
   the ``cls`` argument.

   Why did you overload all decorators?
   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   I wanted that the return type of decorators depended from the ``cls`` argument
   but MyPy doesn't allow to set a default value on a generic argument, see:
   https://github.com/python/mypy/issues/3737.
   So I had to resort to a workaround using @overload which makes things more
   verbose. The ``@overload`` is on the ``cls`` argument:

   - in one signature, ``cls`` has type ``None`` and it's set to ``None``; in this
     case the type of the instantiated command is ``cloup.Command`` for ``@command``
     and ``cloup.Group`` for ``@group``
   - in the other signature, there's ``cls: C`` without a default, where ``C`` is
     a type variable; in this case the type of the instantiated command is ``C``.

   When and if the MyPy issue is resolved, the overloads will be removed.





                              
Classes
-------

.. autosummary::

   ~cloup._commands.Command
   ~cloup._commands.Group

Functions
---------

.. autosummary::

   ~cloup._commands.command
   ~cloup._commands.group

Attributes
----------

.. autoapisummary::

   cloup._commands.C
   cloup._commands.G

                                           
Contents
--------
.. py:data:: C
   

   

.. py:data:: G
   

   

.. 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
      :annotation: :Type[cloup._context.Context]

      

   .. 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
      :annotation: :bool = False

      

   .. py:attribute:: show_subcommand_aliases
      

      Whether to show subcommand aliases.


   .. py:attribute:: alias2name
      :annotation: :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) -> 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) -> 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.



                                         