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

.. py:module:: cloup.formatting.sep

.. autoapi-nested-parse::

   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
-------

.. autosummary::

   ~cloup.formatting.sep.SepGenerator
   ~cloup.formatting.sep.RowSepPolicy
   ~cloup.formatting.sep.RowSepCondition
   ~cloup.formatting.sep.RowSepIf
   ~cloup.formatting.sep.Hline

Functions
---------

.. autosummary::

   ~cloup.formatting.sep.get_total_width
   ~cloup.formatting.sep.count_multiline_rows
   ~cloup.formatting.sep.multiline_rows_are_at_least

Attributes
----------

.. autoapisummary::

   cloup.formatting.sep.SepType
   cloup.formatting.sep.solid
   cloup.formatting.sep.dashed
   cloup.formatting.sep.densely_dashed
   cloup.formatting.sep.dotted

                                           
Contents
--------
.. py:data:: SepType
   

   

.. py:class:: SepGenerator

   Bases: :py:obj:`Protocol`

   Generate a separator given a width. When used as ``row_sep``, this ``width``
   corresponds to ``HelpFormatter.available_width``, i.e. the line width excluding
   the current indentation width.

   Note: the length of the returned separator may differ from ``width``.

   .. py:method:: __call__(self, width)



.. py:class:: RowSepPolicy

   A callable that can be passed as ``row_sep`` to  :class:`HelpFormatter` 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 :class:`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]]``.

   .. py:method:: __call__(self, rows, col_widths, col_spacing)
      :abstractmethod:

      Decide which row separator to use (eventually none) in the given
      definition list.



.. py:class:: RowSepCondition

   Bases: :py:obj:`Protocol`

   Determines when a definition list should use a row separator.

   .. py:method:: __call__(self, rows, col_widths, col_spacing)

      Return ``True`` if the input definition list should use a row
      separator (in addition to the usual ``\n``).



.. py:class:: RowSepIf(condition, sep = '')

   Bases: :py:obj:`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
       :data:`RowSepCondition`) without worrying about the generation part,
       which is always the same.

   :param condition:
       a :class:`RowSepCondition` that determines when to add the (extra)
       row separator.
   :param sep:
       either a string or a ``SepGenerator``,
       i.e. a function ``(width: int) -> str`` (e.g. :class:`Hline`).
       The empty string corresponds to an empty line separator.

   .. py:method:: __call__(self, rows, col_widths, col_spacing)

      Decide which row separator to use (eventually none) in the given
      definition list.



.. py:function:: get_total_width(col_widths, col_spacing)

   Return the total width of a definition list (or, more generally, a table).
   Useful when implementing a RowSepStrategy.


.. py:function:: count_multiline_rows(rows, col_widths)


.. py:function:: multiline_rows_are_at_least(count_or_percentage)

   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.

   :param count_or_percentage:
       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).


.. py:class:: Hline(pattern)

   Bases: :py:obj:`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``
   and  ``Hline.dotted``.

   :param pattern:
       a string (usually a single character) that is repeated to generate
       the line.

   .. py:attribute:: solid
      :annotation: :Hline

      

   .. py:attribute:: dashed
      :annotation: :Hline

      

   .. py:attribute:: densely_dashed
      :annotation: :Hline

      

   .. py:attribute:: dotted
      :annotation: :Hline

      

   .. py:method:: __call__(self, width)



.. py:data:: solid
   

   Return a line like ``────────``.


.. py:data:: dashed
   

   Return a line like ``--------``.


.. py:data:: densely_dashed
   

   Return a line like ``╌╌╌╌╌╌╌╌``.


.. py:data:: dotted
   

   Return a line like ``┄┄┄┄┄┄┄┄``.