
:mod:`cloup.formatting`
=======================

.. py:module:: cloup.formatting



Submodules
----------
.. toctree::
   :titlesonly:
   :maxdepth: 1

   sep <sep/index.rst>


                              
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 <row-separators>` for more.
   :param theme:
       an :class:`~cloup.HelpTheme` instance specifying how to style the various
       elements of the help page.


   .. py:attribute:: width
      :type:  int


   .. py:attribute:: col1_max_width
      :value: 30



   .. py:attribute:: col2_min_width
      :value: 35



   .. py:attribute:: col_spacing
      :value: 2



   .. py:attribute:: theme


   .. py:attribute:: row_sep
      :value: None



   .. 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:property:: available_width
      :type: int



   .. py:method:: write(*strings)

      Writes a unicode string into the internal buffer.



   .. py:method:: write_usage(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(aliases)


   .. py:method:: write_command_help_text(cmd)


   .. py:method:: write_heading(heading, newline = True)

      Writes a heading into the buffer.



   .. py:method:: write_many_sections(sections, aligned = True)


   .. py:method:: write_aligned_sections(sections)

      Write multiple aligned definition lists.



   .. py:method:: write_section(s, col1_width = None)


   .. py:method:: write_text(text, style = identity)

      Writes re-indented text into the buffer.  This rewraps and
      preserves paragraphs.



   .. py:method:: compute_col1_width(rows, max_width)


   .. py:method:: write_dl(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(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(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(epilog)


   .. py:method:: __repr__()


.. py:class:: HelpSection

   A container for a help section data.


   .. py:attribute:: heading
      :type:  str

      Help section title.



   .. py:attribute:: definitions
      :type:  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
      :type:  Optional[str]
      :value: None


      (Optional) long description of the section.



   .. py:attribute:: constraint
      :type:  Optional[str]
      :value: None


      (Optional) option group constraint description.



.. py:function:: ensure_is_cloup_formatter(formatter)

.. py:function:: unstyled_len(string)


                                         