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

# `cloup._sections`

## Classes

`Section`(title[, commands, is_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 of organizing its subcommands into multiple help sections.

## Attributes

`CommandType` |
`Subcommands` |

## Contents

cloup._sections.CommandType

cloup._sections.Subcommands

class cloup._sections.Section(title, commands=(), is_sorted=False)

  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 (Iterable[Command] | Dict[str, Command]) – sequence of commands or dict of commands keyed by name

    - is_sorted (bool) – if True, `list_commands()` returns the commands in lexicographic order

  classmethod sorted(title, commands=())
    Parameters:

      - title (str) –

      - commands (Subcommands) –

    Return type:

      Section

  add_command(cmd, name=None)
    Parameters:

      - cmd (click.Command) –

      - name (Optional[str]) –

    Return type:

      None

  list_commands()
    Return type:

      List[Tuple[str, click.Command]]

  __len__()
    Return type:

      int

  __repr__()

    Return repr(self).

    Return type:

      str

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

  Adds to a `click.MultiCommand` the possibility of organizing its subcommands into 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 (bool | None) – 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 (Dict[str, Command] | None) –

    - sections (Iterable[Section]) –

  add_section(section)

    Add a `Section` to this group. You can add the same section object only a single time.

    See Also:

      `section()`

    Parameters:

      section (Section) –

    Return type:

      None

  section(title, *commands, **attrs)

    Create 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)

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

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

  make_commands_help_section(ctx, section)
    Parameters:

      - ctx (click.Context) –

      - section (Section) –

    Return type:

      Optional[cloup.formatting.HelpSection]

  must_align_sections(ctx, default=True)
    Parameters:

      - ctx (Optional[click.Context]) –

      - default (bool) –

    Return type:

      bool

  format_commands(ctx, formatter)
    Parameters:

      - ctx (click.Context) –

      - formatter (click.HelpFormatter) –

    Return type:

      None