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

# `cloup._commands`

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

`Command`(*args[, aliases, formatter_settings]) | A `click.Command` supporting option groups and constraints.
`Group`(*args[, show_subcommand_aliases, commands]) | A `click.Group` that allows to organize its subcommands in multiple help sections and whose subcommands are, by default, of type `cloup.Command`.

## Functions

`command`([name, aliases, cls]) | Return a decorator that creates a new command using the decorated function as callback.
`group`([name, cls]) | Return a decorator that instantiates a `Group` (or a subclass of it) using the decorated function as callback.

## Attributes

`C` |
`G` |

## Contents

cloup._commands.C

cloup._commands.G

class cloup._commands.Command(*args, aliases=None, formatter_settings=None, **kwargs)

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

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

  Refer to superclasses for the documentation of all accepted parameters:

  - `ConstraintMixin`

  - `OptionGroupMixin`

  - `click.Command`

  Besides other things, this class also:

  - adds a `formatter_settings` instance attribute.

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

  New in version 0.8.0.

  Parameters:

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

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

    - args (Any) – positional arguments forwarded to the next class in the MRO

    - kwargs (Any) – keyword arguments forwarded to the next class in the MRO

    - aliases (Optional[Iterable[str]]) –

    - formatter_settings (Optional[Dict[str, Any]]) –

  context_class :Type[cloup._context.Context]
  get_normalized_epilog()
    Return type:

      str

  format_epilog(ctx, formatter)

    Writes the epilog into the formatter if it exists.

    Parameters:

      - ctx (click.Context) –

      - formatter (click.HelpFormatter) –

    Return type:

      None

  format_help_text(ctx, formatter)

    Writes the help text to the formatter if it exists.

    Parameters:

      - ctx (click.Context) –

      - formatter (click.HelpFormatter) –

    Return type:

      None

  format_aliases(ctx, formatter)
    Parameters:

      - ctx (click.Context) –

      - formatter (click.HelpFormatter) –

    Return type:

      None

  format_help(ctx, formatter)

    Writes the help into the formatter if it exists.

    This is a low-level method called by `get_help()`.

    This calls the following methods:

    - `format_usage()`

    - `format_help_text()`

    - `format_options()`

    - `format_epilog()`

    Parameters:

      - ctx (click.Context) –

      - formatter (click.HelpFormatter) –

    Return type:

      None

class cloup._commands.Group(*args, show_subcommand_aliases=None, commands=None, **kwargs)

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

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

  Refer to superclasses for the documentation of all accepted parameters:

  - `SectionMixin`

  - `Command`

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

  Changed in version 0.14.0: this class now supports option groups and constraints.

  New in version 0.10.0: the “command aliases” feature, including the `show_subcommand_aliases` parameter/attribute.

  Changed in version 0.8.0: this class now inherits from `cloup.BaseCommand`.

  Parameters:

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

    - args (Any) – positional arguments forwarded to the next class in the MRO

    - kwargs (Any) – keyword arguments forwarded to the next class in the MRO

    - show_subcommand_aliases (Optional[bool]) –

    - commands (Optional[Union[MutableMapping[str, click.Command], Sequence[click.Command]]]) –

  SHOW_SUBCOMMAND_ALIASES :bool = False
  show_subcommand_aliases

    Whether to show subcommand aliases.

  alias2name :Dict[str, str]

    Dictionary mapping each alias to a command name.

  add_multiple_commands(commands)
    Parameters:

      commands (Union[Mapping[str, click.Command], Sequence[click.Command]]) –

    Return type:

      None

  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.

    Parameters:

      - cmd (click.Command) –

      - name (Optional[str]) –

      - section (Optional[cloup._sections.Section]) – a `Section` instance. The command must not be in the section already.

      - fallback_to_default_section (bool) – 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.

    Return type:

      None

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

    Parameters:

      - ctx (click.Context) –

      - name (str) –

    Return type:

      Optional[str]

  resolve_command(ctx, args)
    Parameters:

      - ctx (click.Context) –

      - args (List[str]) –

    Return type:

      Tuple[Optional[str], Optional[click.Command], List[str]]

  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.

    Parameters:

      - bad_name (str) – the command name that could not be resolved.

      - valid_names (List[str]) – the list of valid command names, including aliases.

      - error (click.UsageError) – the original error coming from Click.

    Returns:

      the original error or a new one.

    Return type:

      click.UsageError

  must_show_subcommand_aliases(ctx)
    Parameters:

      ctx (click.Context) –

    Return type:

      bool

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

    Parameters:

      - ctx (click.Context) –

      - name (str) –

      - cmd (click.Command) –

    Return type:

      str

  static format_subcommand_aliases(aliases, theme)
    Parameters:

      - aliases (Sequence[str]) –

      - theme (cloup.HelpTheme) –

    Return type:

      str

  command(name: str | None = None, *, aliases: Iterable[str] | None = None, cls: None = None, section: cloup._sections.Section | None = None, context_settings: Dict[str, Any] | None = None, formatter_settings: Dict[str, Any] | None = None, help: str | None = None, epilog: str | None = None, short_help: str | None = None, options_metavar: str | None = '[OPTIONS]', add_help_option: bool = True, no_args_is_help: bool = False, hidden: bool = False, deprecated: bool = False, align_option_groups: bool | None = None, show_constraints: bool | None = None, params: List[click.Parameter] | None = None) → Callable[[cloup.typing.AnyCallable], click.Command]
  command(name: str | None = None, *, aliases: Iterable[str] | None = None, cls: Type[C], section: cloup._sections.Section | None = None, context_settings: Dict[str, Any] | None = None, help: str | None = None, epilog: str | None = None, short_help: str | None = None, options_metavar: str | None = '[OPTIONS]', add_help_option: bool = True, no_args_is_help: bool = False, hidden: bool = False, deprecated: bool = False, params: List[click.Parameter] | None = 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 `command()` plus:

    `section`: `Optional[Section]`

      if provided, put the subcommand in this section.

    Changed in version 0.10.0: all arguments but `name` are now keyword-only.

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

    `section`: `Optional[Section]`

      if provided, put the subcommand in this section.

    Changed in version 0.10.0: all arguments but `name` are now keyword-only.

cloup._commands.command(name: str | None = None, *, aliases: Iterable[str] | None = None, cls: None = None, context_settings: Dict[str, Any] | None = None, formatter_settings: Dict[str, Any] | None = None, help: str | None = None, short_help: str | None = None, epilog: str | None = None, options_metavar: str | None = '[OPTIONS]', add_help_option: bool = True, no_args_is_help: bool = False, hidden: bool = False, deprecated: bool = False, align_option_groups: bool | None = None, show_constraints: bool | None = None, params: List[click.Parameter] | None = None) → Callable[[cloup.typing.AnyCallable], Command]
cloup._commands.command(name: str | None = None, *, aliases: Iterable[str] | None = None, cls: Type[C], context_settings: Dict[str, Any] | None = None, help: str | None = None, short_help: str | None = None, epilog: str | None = None, options_metavar: str | None = '[OPTIONS]', add_help_option: bool = True, no_args_is_help: bool = False, hidden: bool = False, deprecated: bool = False, params: List[click.Parameter] | None = 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 `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`).

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

  Changed in version 0.9.0: all arguments but `name` are now keyword-only arguments.

  Parameters:

    - name – the name of the command to use unless a group overrides it.

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

    - cls – the command class to instantiate.

    - context_settings – an optional dictionary with defaults that are passed to the context object.

    - formatter_settings – arguments for the formatter; you can use `HelpFormatter.settings()` to build this dictionary.

    - help – the help string to use for this command.

    - epilog – like the help string but it’s printed at the end of the help page after everything else.

    - short_help – the short help to use for this command. This is shown on the command listing of the parent command.

    - options_metavar – metavar for options shown in the command’s usage string.

    - add_help_option – by default each command registers a `--help` option. This can be disabled by this parameter.

    - 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

    - hidden – hide this command from help outputs.

    - deprecated – issues a message indicating that the command is deprecated.

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

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

    - params – (click >= 8.1.0) a list of parameters (`Argument` and `Option` instances). Params added with `@option` and `@argument` are appended to the end of the list if given.

    - kwargs – any other argument accepted by the instantiated command class (`cls`).

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

  Changed in version 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).

  Changed in version 0.9.0: all arguments but `name` are now keyword-only arguments.

  Parameters:

    - name – the name of the command to use unless a group overrides it.

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

    - sections – a list of Section objects containing the subcommands of this `Group`. This argument is only supported by commands inheriting from `cloup.SectionMixin`.

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

    - context_settings – an optional dictionary with defaults that are passed to the context object.

    - formatter_settings – arguments for the formatter; you can use `HelpFormatter.settings()` to build this dictionary.

    - help – the help string to use for this command.

    - short_help – the short help to use for this command. This is shown on the command listing of the parent command.

    - epilog – like the help string but it’s printed at the end of the help page after everything else.

    - options_metavar – metavar for options shown in the command’s usage string.

    - add_help_option – by default each command registers a `--help` option. This can be disabled by this parameter.

    - hidden – hide this command from help outputs.

    - deprecated – issues a message indicating that the command is deprecated.

    - invoke_without_command – this controls how the multi command itself is invoked. By default it’s only invoked if a subcommand is provided.

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

    - subcommand_metavar – string used in the command’s usage string to indicate the subcommand place.

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

    - params – (click >= 8.1.0) a list of parameters (`Argument` and `Option` instances). Params added with `@option` and `@argument` are appended to the end of the list if given.

    - kwargs – any other argument accepted by the instantiated command class.