Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
View this page
Toggle table of contents sidebar

# `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` |

## Contents

cloup.formatting.sep.SepType

class cloup.formatting.sep.SepGenerator

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

      width (int)

    Return type:

      str

class cloup.formatting.sep.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.

  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]]`.

  abstractmethod __call__(rows, col_widths, col_spacing)

    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

  Bases: `Protocol`

  Determines when a definition list should use a row separator.

  __call__(rows, col_widths, col_spacing)

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

  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:

    - condition (RowSepCondition) – a `RowSepCondition` that determines when to add the (extra) row separator.

    - sep (str | SepGenerator) – either a string or a `SepGenerator`, i.e. a function `(width: int) -> str` (e.g. `Hline`). The empty string corresponds to an empty line separator.

  condition
  sep
  __call__(rows, col_widths, col_spacing)

    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)

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

    - rows (Sequence[Sequence[str]])

    - col_widths (Sequence[int])

  Return type:

    int

cloup.formatting.sep.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.

  Parameters:

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

    RowSepCondition

class cloup.formatting.sep.Hline(pattern)

  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
  pattern
  __call__(width)
    Parameters:

      width (int)

    Return type:

      str