:mod:`cloup.formatting` ======================= .. py:module:: cloup.formatting Classes ------- .. autosummary:: ~cloup.formatting.HelpSection ~cloup.formatting.HelpFormatter Functions --------- .. autosummary:: ~cloup.formatting.ensure_is_cloup_formatter ~cloup.formatting.unstyled_len ~cloup.formatting.iter_defs Attributes ---------- .. autoapisummary:: cloup.formatting.FORMATTER_TYPE_ERROR cloup.formatting.Definition Contents -------- .. data:: FORMATTER_TYPE_ERROR :annotation: = Multiline-String .. raw:: html
Show Value .. code-block:: text :linenos: 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. .. raw:: html
.. function:: ensure_is_cloup_formatter(formatter) .. function:: unstyled_len(string) .. data:: Definition .. class:: HelpSection A container for a help section data. .. attribute:: heading :annotation: :str Help section title. .. attribute:: definitions :annotation: :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. .. attribute:: help :annotation: :Optional[str] (Optional) long description of the section. .. attribute:: constraint :annotation: :Optional[str] (Optional) option group constraint description. .. class:: HelpFormatter(indent_increment = 2, width = None, max_width = None, col1_max_width = 30, col2_min_width = 35, col_spacing = 2, row_sep = '', theme = HelpTheme()) Bases: :py:obj:`click.HelpFormatter` A custom help formatter. Features include: - more attributes for controlling the output of the formatter - a ``col1_width`` parameter in :meth:`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). .. versionadded:: 0.8.0 :param indent_increment: width of each indentation increment. :param width: content line width; by default it's initialized to ``min(terminal_width - 1, max_width)`` where ``max_width`` is another argument. :param max_width: maximum content line width (equivalent to ``Context.max_content_width``). Used to compute ``width`` when it is not provided, ignored otherwise. :param col1_max_width: 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. :param col2_min_width: 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. :param col_spacing: the number of spaces between the column boundaries of a definition list. :param row_sep: a string printed after each row of a definition list (including the last). :param theme: an :class:`~cloup.HelpTheme` instance specifying how to style the various elements of the help page. .. method:: 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) :staticmethod: 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 :class:`HelpFormatter` in case of doubts. .. method:: available_width(self) :property: .. method:: write(self, *strings) Writes a unicode string into the internal buffer. .. method:: write_usage(self, prog, args = '', prefix = 'Usage:') Writes a usage line into the buffer. :param prog: the program name. :param args: whitespace separated list of arguments. :param prefix: The prefix for the first line. Defaults to ``"Usage: "``. .. method:: write_command_help_text(self, cmd) .. method:: write_heading(self, heading, newline = True) Writes a heading into the buffer. .. method:: write_many_sections(self, sections, aligned = True) .. method:: write_aligned_sections(self, sections) Writes multiple aligned definition lists. .. method:: write_section(self, s, col1_width = None) .. method:: write_text(self, text, style = identity) Writes re-indented text into the buffer. This rewraps and preserves paragraphs. .. method:: compute_col1_width(self, rows, max_width) .. method:: write_dl(self, rows, col_max = None, col_spacing = None, col1_width = None) 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 one ``indent_increment`` if that's greater than 3). :param rows: a list of two item tuples for the terms and values. :param col_max: 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``. :param col_spacing: 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``. :param col1_width: 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. .. method:: write_tabular_dl(self, rows, col1_width, col_spacing, col2_width) 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. .. method:: write_linear_dl(self, dl) Formats 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``. .. method:: write_epilog(self, epilog) .. method:: __repr__(self) Return repr(self). .. function:: iter_defs(rows, col2_width)