cloup.formatting.sep

This module contains anything related to separators. Currently, it contains an implementation of “row sep policies”, e.g. components that decide if and how to add an extra separator/spacing between the rows of a definition list (only for tabular layout). In the future, it may be expanded with something analogous for help sections.

Classes

SepGenerator(*args, **kwargs)

Generate a separator given a width.

RowSepPolicy()

A callable that can be passed as row_sep to HelpFormatter in order to decide if a definition list should get a row separator (in addition to \n) and which separator.

RowSepCondition(*args, **kwargs)

Determines when a definition list should use a row separator.

RowSepIf(condition[, sep])

Inserts a row separator between the rows of a definition list only if a condition is satisfied.

Hline(pattern)

Returns a function that generates an horizontal line of a given length.

Functions

get_total_width(col_widths, col_spacing)

Return the total width of a definition list (or, more generally, a table).

count_multiline_rows(rows, col_widths)

multiline_rows_are_at_least(count_or_percentage)

Return a RowSepStrategy that returns a row separator between all rows of a definition list, only if the number of rows taking multiple lines is greater than or equal to a certain threshold.

Attributes

SepType

solid

Return a line like ────────.

dashed

Return a line like --------.

densely_dashed

Return a line like ╌╌╌╌╌╌╌╌.

dotted

Return a line like ┄┄┄┄┄┄┄┄.

Contents

cloup.formatting.sep.SepType
class cloup.formatting.sep.SepGenerator[source]

Bases: Protocol

Generate a separator given a width. When used as row_sep, this width corresponds to HelpFormatter.available_width, i.e. the line width excluding the current indentation width.

Note: the length of the returned separator may differ from width.

__call__(self, width)[source]
Parameters

width (int) –

Return type

str

class cloup.formatting.sep.RowSepPolicy[source]

A callable that can be passed as row_sep to HelpFormatter in order to decide if a definition list should get a row separator (in addition to \n) and which separator.

In practice, the row separator should be the same for all definition lists that satisfy a given condition. That’s why RowSepIf exists, you probably want to use that.

Nonetheless, this protocol exists mainly for one reason: it leaves open the door to policies that can decide a row separator for each individual row (feature I’m personally against to for now), without breaking changes. This would make possible to implement the old Click 7.2 behavior, which inserted an empty line only after options with a long help. Adding this feature would be possible without breaking changes, by extending the return type to Union[None, str, Sequence[str]].

abstract __call__(self, rows, col_widths, col_spacing)[source]

Decide which row separator to use (eventually none) in the given definition list.

Parameters
  • rows (Sequence[Sequence[str]]) –

  • col_widths (Sequence[int]) –

  • col_spacing (int) –

Return type

Optional[str]

class cloup.formatting.sep.RowSepCondition[source]

Bases: Protocol

Determines when a definition list should use a row separator.

__call__(self, rows, col_widths, col_spacing)[source]

Return True if the input definition list should use a row separator (in addition to the usual \n).

Parameters
  • rows (Sequence[Sequence[str]]) –

  • col_widths (Sequence[int]) –

  • col_spacing (int) –

Return type

bool

class cloup.formatting.sep.RowSepIf(condition, sep='')[source]

Bases: RowSepPolicy

Inserts a row separator between the rows of a definition list only if a condition is satisfied. This class implements the RowSepPolicy protocol and does two things:

  • enforces the use of a single row separator for all rows of a

    definition lists and for all definition lists; note that RowSepPolicy doesn’t for implementation reasons but it’s probably what you want;

  • allows you to implement different conditions (see type

    RowSepCondition) without worrying about the generation part, which is always the same.

Parameters
__call__(self, rows, col_widths, col_spacing)[source]

Decide which row separator to use (eventually none) in the given definition list.

Parameters
  • rows (Sequence[Sequence[str]]) –

  • col_widths (Sequence[int]) –

  • col_spacing (int) –

Return type

Optional[str]

cloup.formatting.sep.get_total_width(col_widths, col_spacing)[source]

Return the total width of a definition list (or, more generally, a table). Useful when implementing a RowSepStrategy.

Parameters
  • col_widths (Sequence[int]) –

  • col_spacing (int) –

Return type

int

cloup.formatting.sep.count_multiline_rows(rows, col_widths)[source]
Parameters
  • rows (Sequence[Sequence[str]]) –

  • col_widths (Sequence[int]) –

Return type

int

cloup.formatting.sep.multiline_rows_are_at_least(count_or_percentage)[source]

Return a RowSepStrategy that returns a row separator between all rows of a definition list, only if the number of rows taking multiple lines is greater than or equal to a certain threshold.

Parameters

count_or_percentage (Union[int, float]) – a threshold for multiline rows above which the returned strategy will insert a row separator. It can be either an absolute count (int) or a percentage relative to the total number of rows expressed as a float between 0 and 1 (0 and 1 excluded).

Return type

cloup.formatting.sep.RowSepCondition

class cloup.formatting.sep.Hline(pattern)[source]

Bases: SepGenerator

Returns a function that generates an horizontal line of a given length.

This class has different static members for different line styles like Hline.solid, Hline.dashed, Hline.densely_dashed and Hline.dotted.

Parameters

pattern (str) – a string (usually a single character) that is repeated to generate the line.

solid :Hline
dashed :Hline
densely_dashed :Hline
dotted :Hline
__call__(self, width)[source]
Parameters

width (int) –

Return type

str

cloup.formatting.sep.solid

Return a line like ────────.

cloup.formatting.sep.dashed

Return a line like --------.

cloup.formatting.sep.densely_dashed

Return a line like ╌╌╌╌╌╌╌╌.

cloup.formatting.sep.dotted

Return a line like ┄┄┄┄┄┄┄┄.