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 typeNone
and it’s set toNone
; in this case the type of the instantiated command iscloup.Command
for@command
andcloup.Group
for@group
in the other signature, there’s
cls: C
without a default, whereC
is a type variable; in this case the type of the instantiated command isC
.
When and if the MyPy issue is resolved, the overloads will be removed.
Classes¶
|
A |
|
A |
Functions¶
|
Return a decorator that creates a new command using the decorated function as callback. |
|
Return a decorator that instantiates a |
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
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]¶
-
format_epilog
(self, ctx, formatter)[source]¶ Writes the epilog into the formatter if it exists.
- Parameters
ctx (click.Context) –
formatter (click.HelpFormatter) –
- Return type
-
format_help_text
(self, ctx, formatter)[source]¶ Writes the help text to the formatter if it exists.
- Parameters
ctx (click.Context) –
formatter (click.HelpFormatter) –
- Return type
-
format_aliases
(self, ctx, formatter)[source]¶ - Parameters
ctx (click.Context) –
formatter (click.HelpFormatter) –
- Return type
-
format_help
(self, 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:
format_usage()
format_options()
- Parameters
ctx (click.Context) –
formatter (click.HelpFormatter) –
- Return type
-
class
cloup._commands.
Group
(*args, show_subcommand_aliases=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 typecloup.Command
.Refer to superclasses for the documentation of all accepted parameters:
SectionMixin
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]) –
-
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_command
(self, 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 unlesssection
is provided. This is useful for internal code and subclasses. Don’t disable it unless you know what you are doing.
- Return type
-
resolve_command_name
(self, 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
(self, ctx, args)[source]¶ - Parameters
ctx (click.Context) –
args (List[str]) –
- Return type
Tuple[Optional[str], Optional[click.Command], List[str]]
-
handle_bad_command_name
(self, 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
-
must_show_subcommand_aliases
(self, ctx)[source]¶ - Parameters
ctx (click.Context) –
- Return type
-
format_subcommand_name
(self, 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
-
static
format_subcommand_aliases
(aliases, theme)[source]¶ - Parameters
aliases (Sequence[str]) –
theme (cloup.HelpTheme) –
- Return type
-
command
(self, 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][source]¶ -
command
(self, 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
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
(self, 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][source]¶ -
group
(self, 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
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: 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][source]¶ -
cloup._commands.
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
cloup.Command
supports constraints, provided that
cls
inherits fromConstraintMixin
likecloup.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 customcls
make sure you don’t set these:formatter_settings
align_option_groups
(cls
needs to inherit fromOptionGroupMixin
)show_constraints
(cls
needs to inheritConstraintMixin
).
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 passedhidden – 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
andOption
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: 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][source]¶ -
cloup._commands.
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.Changed in version 0.10.0: the
cls
argument can now be anyclick.Group
(previously had to be acloup.Group
) and the type of the instantiated command matches it (previously, the type wascloup.Group
even ifcls
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 iscloup.Group
by default. Note that some of the arguments are only supported bycloup.Group
.sections – a list of Section objects containing the subcommands of this
Group
. This argument is only supported by commands inheriting fromcloup.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
andOption
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.