:mod:`cloup.formatting` ======================= .. py:module:: cloup.formatting Submodules ---------- .. toctree:: :titlesonly: :maxdepth: 1 sep Classes ------- .. autosummary:: ~cloup.formatting.HelpFormatter ~cloup.formatting.HelpSection Functions --------- .. autosummary:: ~cloup.formatting.ensure_is_cloup_formatter ~cloup.formatting.unstyled_len Contents -------- .. py:class:: HelpFormatter(indent_increment = 2, width = None, max_width = None, col1_max_width = 30, col2_min_width = 35, col_spacing = 2, row_sep = None, 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). .. versionchanged:: 0.9.0 the ``row_sep`` parameter now: - is set to ``None`` by default and ``row_sep=""`` corresponds to an empty line between rows - must not ends with ``\n``; the formatter writes a newline just after it (when it's not ``None``), so a newline at the end is always enforced - accepts instances of :class:`~cloup.formatting.sep.SepGenerator` and :class:`~cloup.formatting.sep.RowSepPolicy`. .. versionadded:: 0.8.0 :param indent_increment: width of each indentation increment. :param width: content line width, excluding the newline character; 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: an "extra" separator to insert between the rows of a definition list (in addition to the normal newline between definitions). If you want an empty line between rows, pass ``row_sep=""``. Read :ref:`Row separators ` for more. :param theme: an :class:`~cloup.HelpTheme` instance specifying how to style the various elements of the help page. .. py:method:: settings(width = MISSING, max_width = MISSING, indent_increment = MISSING, col1_max_width = MISSING, col2_min_width = MISSING, col_spacing = MISSING, row_sep = MISSING, theme = MISSING) :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 described in :class:`HelpFormatter`. .. py:method:: available_width(self) :property: .. py:method:: write(self, *strings) Writes a unicode string into the internal buffer. .. py:method:: write_usage(self, prog, args = '', prefix = None) 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: "``. .. py:method:: write_aliases(self, aliases) .. py:method:: write_command_help_text(self, cmd) .. py:method:: write_heading(self, heading, newline = True) Writes a heading into the buffer. .. py:method:: write_many_sections(self, sections, aligned = True) .. py:method:: write_aligned_sections(self, sections) Write multiple aligned definition lists. .. py:method:: write_section(self, s, col1_width = None) .. py:method:: write_text(self, text, style = identity) Writes re-indented text into the buffer. This rewraps and preserves paragraphs. .. py:method:: compute_col1_width(self, rows, max_width) .. py:method:: write_dl(self, rows, col_max = None, col_spacing = None, col1_width = None) Write 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. .. py:method:: write_tabular_dl(self, rows, col1_width, col_spacing, col2_width) Format 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. .. py:method:: write_linear_dl(self, dl) Format 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``. .. py:method:: write_epilog(self, epilog) .. py:method:: __repr__(self) Return repr(self). .. py:class:: HelpSection A container for a help section data. .. py:attribute:: heading :annotation: :str Help section title. .. py: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. .. py:attribute:: help :annotation: :Optional[str] (Optional) long description of the section. .. py:attribute:: constraint :annotation: :Optional[str] (Optional) option group constraint description. .. py:function:: ensure_is_cloup_formatter(formatter) .. py:function:: unstyled_len(string)