cloup.formatting

Classes

HelpSection(heading, definitions[, help, …])	A container for a help section data.
HelpFormatter([indent_increment, width, …])	A custom help formatter.

Functions

ensure_is_cloup_formatter(formatter)
unstyled_len(string)
iter_defs(rows, col2_width)

Attributes

FORMATTER_TYPE_ERROR
Definition

Contents

cloup.formatting.FORMATTER_TYPE_ERROR = Multiline-String

Show Value

since cloup v0.8.0, this class relies on cloup.HelpFormatter to align help
sections. So, you need to make sure your command class uses cloup.HelpFormatter
as formatter class.

If you have your own custom HelpFormatter, know that cloup.HelpFormatter is
more easily customizable then Click's one, so consider extending it instead
of extending click.HelpFormatter.

cloup.formatting.ensure_is_cloup_formatter(formatter)

Parameters

formatter (click.formatting.HelpFormatter) –

Return type

cloup.formatting.HelpFormatter

cloup.formatting.unstyled_len(string)

Parameters

string (str) –

Return type

int

cloup.formatting.Definition

class cloup.formatting.HelpSection

A container for a help section data.

Parameters

• heading (str) –

• definitions (Sequence[Tuple[str, Union[str, Callable[[int], str]]]]) –

• help (Optional[str]) –

• constraint (Optional[str]) –

Return type

None

heading :str

Help section title.

definitions :Sequence[Definition]

Rows with 2 columns each. The 2nd element of each row can also be a function taking an integer (the available width for the 2nd column) and returning a string.

help :Optional[str]

(Optional) long description of the section.

constraint :Optional[str]

(Optional) option group constraint description.

class cloup.formatting.HelpFormatter(indent_increment=2, width=None, max_width=None, col1_max_width=30, col2_min_width=35, col_spacing=2, row_sep='', theme=HelpTheme())

Bases: click.HelpFormatter

A custom help formatter. Features include:

• more attributes for controlling the output of the formatter

• a col1_width parameter in write_dl() that allows Cloup to align multiple definition lists without resorting to hacks

• a “linear layout” for definition lists that kicks in when the available terminal width is not enough for the standard 2-column layout (see argument col2_min_width)

• the first column width, when not explicitly given in write_dl is computed excluding the rows that exceed col1_max_width (called col_max in write_dl for compatibility with Click).

New in version 0.8.0.

Parameters

• indent_increment (int) – width of each indentation increment.

• width (Optional[int]) – content line width; by default it’s initialized to min(terminal_width - 1, max_width) where max_width is another argument.

• max_width (Optional[int]) – maximum content line width (equivalent to Context.max_content_width). Used to compute width when it is not provided, ignored otherwise.

• col1_max_width (int) – the maximum width of the first column of a definition list; as in Click, if the text of a row exceeds this threshold, the 2nd column is printed on a new line.

• col2_min_width (int) – the minimum width for the second column of a definition list; if the available space is less than this value, the formatter switches from the standard 2-column layout to the “linear layout” (that this decision is taken for each definition list). If you want to always use the linear layout, you can set this argument to a very high number (or math.inf). If you never want it (not recommended), you can set this argument to zero.

• col_spacing (int) – the number of spaces between the column boundaries of a definition list.

• row_sep (str) – a string printed after each row of a definition list (including the last).

• theme (cloup.styling.HelpTheme) – an HelpTheme instance specifying how to style the various elements of the help page.

static settings(*, width=None, max_width=None, indent_increment=None, col1_max_width=None, col2_min_width=None, col_spacing=None, row_sep=None, theme=None)

A utility method for creating a formatter_settings dictionary to pass as context settings or command attribute. This method exists for one only reason: it enables auto-complete for formatter options, thus improving the developer experience.

Parameters are pretty self-explanatory. Refer to HelpFormatter in case of doubts.

Parameters

• width (Optional[int]) –

• max_width (Optional[int]) –

• indent_increment (Optional[int]) –

• col1_max_width (Optional[int]) –

• col2_min_width (Optional[int]) –

• col_spacing (Optional[int]) –

• row_sep (Optional[str]) –

• theme (Optional[cloup.styling.HelpTheme]) –

Return type

Dict[str, Any]

property available_width(self)

Return type

int

write(self, *strings)

Writes a unicode string into the internal buffer.

Parameters

strings (str) –

Return type

None

write_usage(self, prog, args='', prefix='Usage:')

Writes a usage line into the buffer.

Parameters

• prog (str) – the program name.

• args (str) – whitespace separated list of arguments.

• prefix (Optional[str]) – The prefix for the first line. Defaults to "Usage: ".

Return type

None

write_command_help_text(self, cmd)

Parameters

cmd (click.Command) –

Return type

None

write_heading(self, heading, newline=True)

Writes a heading into the buffer.

Parameters

• heading (str) –

• newline (bool) –

Return type

None

write_many_sections(self, sections, aligned=True)

Parameters

• sections (Sequence[HelpSection]) –

• aligned (bool) –

Return type

None

write_aligned_sections(self, sections)

Writes multiple aligned definition lists.

Parameters

sections (Sequence[HelpSection]) –

Return type

None

write_section(self, s, col1_width=None)

Parameters

• s (HelpSection) –

• col1_width (Optional[int]) –

Return type

None

write_text(self, text, style=identity)

Writes re-indented text into the buffer. This rewraps and preserves paragraphs.

Parameters

• text (str) –

• style (cloup.styling.IStyle) –

Return type

None

compute_col1_width(self, rows, max_width)

Parameters

• rows (Iterable[Definition]) –

• max_width (int) –

Return type

int

write_dl(self, rows, col_max=None, col_spacing=None, col1_width=None)

Writes a definition list into the buffer. This is how options and commands are usually formatted.

If there’s enough space, definition lists are rendered as a 2-column pseudo-table: if the first column text of a row doesn’t fit in the provided/computed col1_width, the 2nd column is printed on the following line.

If the available space for the 2nd column is below self.col2_min_width, the 2nd “column” is always printed below the 1st, indented with a minimum of 3 spaces (or one indent_increment if that’s greater than 3).

Parameters

• rows (Sequence[Definition]) – a list of two item tuples for the terms and values.

• col_max (Optional[int]) – the maximum width for the 1st column of a definition list; this argument is here to not break compatibility with Click; if provided, it overrides the attribute self.col1_max_width.

• col_spacing (Optional[int]) – number of spaces between the first and second column; this argument is here to not break compatibility with Click; if provided, it overrides self.col_spacing.

• col1_width (Optional[int]) – the width to use for the first column; if not provided, it’s computed as the length of the longest string under self.col1_max_width; useful when you need to align multiple definition lists.

Return type

None

write_tabular_dl(self, rows, col1_width, col_spacing, col2_width)

Formats a definition list as a 2-column “pseudo-table”. If the first column of a row exceeds col1_width, the 2nd column is written on the subsequent line. This is the standard way of formatting definition lists and it’s the default if there’s enough space.

Parameters

• rows (Sequence[Definition]) –

• col1_width (int) –

• col_spacing (int) –

• col2_width (int) –

Return type

None

write_linear_dl(self, dl)

Formats a definition list as a “linear list”. This is the default when the available width for the definitions (2nd column) is below self.col2_min_width.

Parameters

dl (Sequence[Definition]) –

Return type

None

write_epilog(self, epilog)

Parameters

epilog (str) –

Return type

None

__repr__(self)

Return repr(self).

cloup.formatting.iter_defs(rows, col2_width)

Parameters

• rows (Iterable[Tuple[str, Union[str, Callable[[int], str]]]]) –

• col2_width (int) –

Return type

Iterator[Tuple[str, str]]