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

# `cloup.formatting._formatter`

## Classes

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

## Functions

`iter_defs`(rows, col2_width) |

## Attributes

`Definition` |

## Contents

cloup.formatting._formatter.Definition

class cloup.formatting._formatter.HelpSection

  A container for a help section data.

  Parameters:

    - heading (str) –

    - definitions (Sequence[Tuple[str, str | Callable[[int], str]]]) –

    - help (str | None) –

    - constraint (str | 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._formatter.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())

  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 (int | None) – 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 (int | None) – 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 (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 (HelpTheme) – an `HelpTheme` instance specifying how to style the various elements of the help page.

  property available_width: int
    Return type:

      int

  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)

    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:

      - width (cloup.typing.Possibly[Optional[int]]) –

      - max_width (cloup.typing.Possibly[Optional[int]]) –

      - indent_increment (cloup.typing.Possibly[int]) –

      - col1_max_width (cloup.typing.Possibly[int]) –

      - col2_min_width (cloup.typing.Possibly[int]) –

      - col_spacing (cloup.typing.Possibly[int]) –

      - row_sep (cloup.typing.Possibly[Union[None, str, cloup.formatting.sep.SepGenerator, cloup.formatting.sep.RowSepPolicy]]) –

      - theme (cloup.typing.Possibly[cloup.styling.HelpTheme]) –

    Return type:

      Dict[str, Any]

  write(*strings)

    Writes a unicode string into the internal buffer.

    Parameters:

      strings (str) –

    Return type:

      None

  write_usage(prog, args='', prefix=None)

    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(aliases)
    Parameters:

      aliases (Sequence[str]) –

    Return type:

      None

  write_command_help_text(cmd)
    Parameters:

      cmd (click.Command) –

    Return type:

      None

  write_heading(heading, newline=True)

    Writes a heading into the buffer.

    Parameters:

      - heading (str) –

      - newline (bool) –

    Return type:

      None

  write_many_sections(sections, aligned=True)
    Parameters:

      - sections (Sequence[HelpSection]) –

      - aligned (bool) –

    Return type:

      None

  write_aligned_sections(sections)

    Write multiple aligned definition lists.

    Parameters:

      sections (Sequence[HelpSection]) –

    Return type:

      None

  write_section(s, col1_width=None)
    Parameters:

      - s (HelpSection) –

      - col1_width (Optional[int]) –

    Return type:

      None

  write_text(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(rows, max_width)
    Parameters:

      - rows (Iterable[Definition]) –

      - max_width (int) –

    Return type:

      int

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

    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(rows, col1_width, col_spacing, col2_width)

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

    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(epilog)
    Parameters:

      epilog (str) –

    Return type:

      None

  __repr__()

    Return repr(self).

    Return type:

      str

cloup.formatting._formatter.iter_defs(rows, col2_width)
  Parameters:

    - rows (Iterable[Tuple[str, str | Callable[[int], str]]]) –

    - col2_width (int) –

  Return type:

    Iterator[Tuple[str, str]]