cloup._sections
¶
Classes¶
|
A group of (sub)commands to show in the same help section of a |
|
Adds to a |
Attributes¶
Contents¶
-
cloup._sections.
CommandType
¶
-
cloup._sections.
Subcommands
¶
-
class
cloup._sections.
Section
(title, commands=(), is_sorted=False)[source]¶ A group of (sub)commands to show in the same help section of a
MultiCommand
. You can use sections with any Command that inherits fromSectionMixin
.Changed in version 0.6.0: removed the deprecated old name
GroupSection
.Changed in version 0.5.0: introduced the new name
Section
and deprecated the oldGroupSection
.- Parameters
title (str) –
commands (Union[Iterable[click.core.Command], Dict[str, click.core.Command]]) – sequence of commands or dict of commands keyed by name
is_sorted (bool) – if True,
list_commands()
returns the commands in lexicographic order
-
add_command
(self, cmd, name=None)[source]¶ - Parameters
cmd (click.Command) –
name (Optional[str]) –
- Return type
-
list_commands
(self)[source]¶ - Return type
List[Tuple[str, click.Command]]
-
class
cloup._sections.
SectionMixin
(*args, commands=None, sections=(), align_sections=None, **kwargs)[source]¶ Adds to a
click.MultiCommand
the possibility of organizing its subcommands into multiple help sections.Sections can be specified in the following ways:
passing a list of
Section
objects to the constructor setting the argumentsections
using
add_section()
to add a single sectionusing
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.
Changed in version 0.8.0: this mixin now relies on
cloup.HelpFormatter
to align help sections. If aclick.HelpFormatter
is used with aTypeError
is raised.Changed in version 0.8.0: removed
format_section
. Addedmake_commands_help_section
.New in version 0.5.0.
- Parameters
align_sections (Optional[bool]) – 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
commands (Optional[Dict[str, click.core.Command]]) –
sections (Iterable[cloup._sections.Section]) –
-
add_section
(self, section)[source]¶ Add a
Section
to this group. You can add the same section object a single time.
-
section
(self, title, *commands, **attrs)[source]¶ Create a new
Section
, adds it to this group and returns it.- Parameters
title (str) –
commands (click.Command) –
attrs (Any) –
- Return type
-
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[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
-
list_sections
(self, ctx, include_default_section=True)[source]¶ 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.- Parameters
ctx (click.Context) –
include_default_section (bool) –
- Return type
List[Section]
-
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
-
make_commands_help_section
(self, ctx, section)[source]¶ - Parameters
ctx (click.Context) –
section (Section) –
- Return type
Optional[cloup.formatting.HelpSection]
-
must_align_sections
(self, ctx, default=True)[source]¶ - Parameters
ctx (Optional[click.Context]) –
default (bool) –
- Return type
-
format_commands
(self, ctx, formatter)[source]¶ - Parameters
ctx (click.Context) –
formatter (click.HelpFormatter) –
- Return type