cloup.formatting
¶
Classes¶
|
A container for a help section data. |
|
A custom help formatter. |
Functions¶
|
|
|
|
|
Attributes¶
Contents¶
-
cloup.formatting.
FORMATTER_TYPE_ERROR
= Multiline-String¶ Show Value
1 2 3 4 5 6 7
since cloup v0.8.0, this class relies on cloup.HelpFormatter to align help sections. So, you need to make sure your command class uses cloup.HelpFormatter as formatter class. If you have your own custom HelpFormatter, know that cloup.HelpFormatter is more easily customizable then Click's one, so consider extending it instead of extending click.HelpFormatter.
-
cloup.formatting.
ensure_is_cloup_formatter
(formatter)[source]¶ - Parameters
formatter (click.formatting.HelpFormatter) –
- Return type
-
cloup.formatting.
Definition
¶
-
class
cloup.formatting.
HelpSection
[source]¶ A container for a help section data.
- Parameters
- Return type
-
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.
HelpFormatter
(indent_increment=2, width=None, max_width=None, col1_max_width=30, col2_min_width=35, col_spacing=2, row_sep='', 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 inwrite_dl()
that allows Cloup to align multiple definition lists without resorting to hacksa “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 exceedcol1_max_width
(calledcol_max
inwrite_dl
for compatibility with Click).
New in version 0.8.0.
- Parameters
indent_increment (int) – width of each indentation increment.
width (Optional[int]) – content line width; by default it’s initialized to
min(terminal_width - 1, max_width)
wheremax_width
is another argument.max_width (Optional[int]) – maximum content line width (equivalent to
Context.max_content_width
). Used to computewidth
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 (str) – a string printed after each row of a definition list (including the last).
theme (cloup.styling.HelpTheme) – an
HelpTheme
instance specifying how to style the various elements of the help page.
-
static
settings
(*, width=None, max_width=None, indent_increment=None, col1_max_width=None, col2_min_width=None, col_spacing=None, row_sep=None, theme=None)[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 pretty self-explanatory. Refer to
HelpFormatter
in case of doubts.
-
write_command_help_text
(self, cmd)[source]¶ - Parameters
cmd (click.Command) –
- Return type
-
write_many_sections
(self, sections, aligned=True)[source]¶ - Parameters
sections (Sequence[HelpSection]) –
aligned (bool) –
- Return type
-
write_aligned_sections
(self, sections)[source]¶ Writes multiple aligned definition lists.
- Parameters
sections (Sequence[HelpSection]) –
- Return type
-
write_section
(self, s, col1_width=None)[source]¶ - Parameters
s (HelpSection) –
col1_width (Optional[int]) –
- Return type
-
write_text
(self, text, style=identity)[source]¶ Writes re-indented text into the buffer. This rewraps and preserves paragraphs.
-
write_dl
(self, rows, col_max=None, col_spacing=None, col1_width=None)[source]¶ Writes 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 oneindent_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
-
write_tabular_dl
(self, rows, col1_width, col_spacing, col2_width)[source]¶ Formats 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.