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¶
|
Generate a separator given a width. |
A callable that can be passed as |
|
|
Determines when a definition list should use a row separator. |
|
Inserts a row separator between the rows of a definition list only if a condition is satisfied. |
|
Returns a function that generates an horizontal line of a given length. |
Functions¶
|
Return the total width of a definition list (or, more generally, a table). |
|
|
|
Return a |
Attributes¶
Return a line like |
|
Return a line like |
|
Return a line like |
|
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
, thiswidth
corresponds toHelpFormatter.available_width
, i.e. the line width excluding the current indentation width.Note: the length of the returned separator may differ from
width
.
-
class
cloup.formatting.sep.
RowSepPolicy
[source]¶ A callable that can be passed as
row_sep
toHelpFormatter
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]]
.
-
class
cloup.formatting.sep.
RowSepCondition
[source]¶ Bases:
Protocol
Determines when a definition list should use a row separator.
-
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
condition (cloup.formatting.sep.RowSepCondition) – a
RowSepCondition
that determines when to add the (extra) row separator.sep (Union[str, cloup.formatting.sep.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.
-
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.
-
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
-
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
andHline.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¶
-
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
┄┄┄┄┄┄┄┄
.