cloup.formatting

Submodules

Classes

HelpFormatter([indent_increment, width, …])

A custom help formatter.

HelpSection(heading, definitions[, help, …])

A container for a help section data.

Functions

Contents

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=None, theme=HelpTheme())[source]

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

Changed in version 0.9.0: the row_sep parameter now:

  • is set to None by default and row_sep="" corresponds to an empty line between rows

  • must not ends with \n; the formatter writes a newline just after it (when it’s not None), so a newline at the end is always enforced

  • accepts instances of SepGenerator and RowSepPolicy.

New in version 0.8.0.

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

  • width (Optional[int]) – content line width, excluding the newline character; 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 (Union[None, str, SepGenerator, RowSepPolicy]) – an “extra” separator to insert between the rows of a definition list (in addition to the normal newline between definitions). If you want an empty line between rows, pass row_sep="". Read Row separators for more.

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

static settings(width=MISSING, max_width=MISSING, indent_increment=MISSING, col1_max_width=MISSING, col2_min_width=MISSING, col_spacing=MISSING, row_sep=MISSING, theme=MISSING)[source]

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 described in HelpFormatter.

Parameters
Return type

Dict[str, Any]

property available_width(self)
Return type

int

write(self, *strings)[source]

Writes a unicode string into the internal buffer.

Parameters

strings (str) –

Return type

None

write_usage(self, prog, args='', prefix=None)[source]

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_aliases(self, aliases)[source]
Parameters

aliases (Sequence[str]) –

Return type

None

write_command_help_text(self, cmd)[source]
Parameters

cmd (click.Command) –

Return type

None

write_heading(self, heading, newline=True)[source]

Writes a heading into the buffer.

Parameters
  • heading (str) –

  • newline (bool) –

Return type

None

write_many_sections(self, sections, aligned=True)[source]
Parameters
Return type

None

write_aligned_sections(self, sections)[source]

Write multiple aligned definition lists.

Parameters

sections (Sequence[HelpSection]) –

Return type

None

write_section(self, s, col1_width=None)[source]
Parameters
Return type

None

write_text(self, text, style=identity)[source]

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)[source]
Parameters
  • rows (Iterable[Definition]) –

  • max_width (int) –

Return type

int

write_dl(self, rows, col_max=None, col_spacing=None, col1_width=None)[source]

Write 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)[source]

Format 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)[source]

Format 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)[source]
Parameters

epilog (str) –

Return type

None

__repr__(self)[source]

Return repr(self).

Return type

str

class cloup.formatting.HelpSection[source]

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.

cloup.formatting.ensure_is_cloup_formatter(formatter)[source]
Parameters

formatter (click.formatting.HelpFormatter) –

Return type

cloup.HelpFormatter

cloup.formatting.unstyled_len(string)[source]
Parameters

string (str) –

Return type

int