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)[source]#

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()[source]#
Return type:

str

format_epilog(ctx, formatter)[source]#

Writes the epilog into the formatter if it exists.

Parameters:

  • ctx (click.Context) –

  • formatter (click.HelpFormatter) –

Return type:

None

format_help_text(ctx, formatter)[source]#

Writes the help text to the formatter if it exists.

Parameters:

  • ctx (click.Context) –

  • formatter (click.HelpFormatter) –

Return type:

None

format_aliases(ctx, formatter)[source]#
Parameters:

  • ctx (click.Context) –

  • formatter (click.HelpFormatter) –

Return type:

None

format_help(ctx, formatter)[source]#

Writes the help into the formatter if it exists.

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

This calls the following methods:

Parameters:

  • ctx (click.Context) –

  • formatter (click.HelpFormatter) –

Return type:

None

class cloup._commands.Group(*args, show_subcommand_aliases=None, commands=None, **kwargs)[source]#

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:

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)[source]#
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)[source]#

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)[source]#

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)[source]#
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)[source]#

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)[source]#
Parameters:

ctx (click.Context) –

Return type:

bool

format_subcommand_name(ctx, name, cmd)[source]#

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)[source]#
Parameters:
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][source]#
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][source]#
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][source]#
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][source]#
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.