cloup._sections

Classes

Section(title[, commands, sorted])

A group of (sub)commands to show in the same help section of a MultiCommand.

SectionMixin(*args[, commands, sections, ...])

Adds to a click.MultiCommand the possibility to organize its subcommands in multiple help sections.

Attributes

CommandType

Subcommands

Contents

cloup._sections.CommandType
cloup._sections.Subcommands
class cloup._sections.Section(title, commands=(), 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 from SectionMixin.

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

Parameters
  • title (str) –

  • commands (Union[Iterable[click.core.Command], Dict[str, click.core.Command]]) – sequence of commands or dictionary {name: command}

  • sorted (bool) – if True, list_commands() returns the commands in lexicographic order

classmethod sorted(title, commands=())[source]
Parameters
  • title (str) –

  • commands (Subcommands) –

Return type

Section

add_command(cmd, name=None)[source]
Parameters
  • cmd (click.Command) –

  • name (Optional[str]) –

Return type

None

list_commands()[source]
Return type

List[Tuple[str, click.Command]]

__len__()[source]
Return type

int

__repr__()[source]

Return repr(self).

Return type

str

class cloup._sections.SectionMixin(*args, commands=None, sections=(), align_sections=None, **kwargs)[source]

Adds to a click.MultiCommand the possibility to organize its subcommands in multiple help sections.

Sections can be specified in the following ways:

  1. passing a list of Section objects to the constructor setting the argument sections

  2. using add_section() to add a single section

  3. using 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 a click.HelpFormatter is used with a TypeError is raised.

Changed in version 0.8.0: removed format_section. Added make_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(section)[source]

Adds a Section to this group. You can add the same section object a single time.

Parameters

section (Section) –

Return type

None

section(title, *commands, **attrs)[source]

Creates a new Section, adds it to this group and returns it.

Parameters
  • title (str) –

  • commands (click.Command) –

  • attrs (Any) –

Return type

Section

add_command(cmd, name=None, section=None, fallback_to_default_section=True)[source]

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

list_sections(ctx, include_default_section=True)[source]

Returns 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(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

make_commands_help_section(ctx, section)[source]
Parameters
  • ctx (click.Context) –

  • section (Section) –

Return type

Optional[cloup.formatting.HelpSection]

must_align_sections(ctx, default=True)[source]
Parameters
  • ctx (Optional[click.Context]) –

  • default (bool) –

Return type

bool

format_commands(ctx, formatter)[source]
Parameters
  • ctx (click.Context) –

  • formatter (click.HelpFormatter) –

Return type

None