:mod:`cloup.styling`
====================

.. py:module:: cloup.styling

.. autoapi-nested-parse::

   This module defines the classes that support the styling and theming of commands
   help page.





                              
Classes
-------

.. autosummary::

   ~cloup.styling.HelpTheme
   ~cloup.styling.Style
   ~cloup.styling.Color


Attributes
----------

.. autoapisummary::

   cloup.styling.IStyle

                                           
Contents
--------
.. data:: IStyle
   

   A callable that takes a string and returns a styled version of it.


.. class:: HelpTheme

   Bases: :py:obj:`NamedTuple`

   A collection of styles for several elements of the help page.

   A "style" is just a function or a callable that takes a string and returns
   a styled version of it. This means you can use your favorite styling/color
   library (like rich, colorful etc). Nonetheless, given that Click has some
   basic styling functionality built-in, Cloup provides the :class:`Style`
   class, which is a wrapper of the ``click.style`` function.

   :param invoked_command:
       Style of the invoked command name (in Usage).
   :param command_help:
       Style of the invoked command description (below Usage).
   :param heading:
       Style of help section headings.
   :param constraint:
       Style of an option group constraint description.
   :param section_help:
       Style of the help text of a section (the optional paragraph below the heading).
   :param col1:
       Style of the first column of a definition list (options and command names).
   :param col2:
       Style of the second column of a definition list (help text).
   :param epilog:
       Style of the epilog.

   .. attribute:: invoked_command
      :annotation: :IStyle

      Style of the invoked command name (in Usage).


   .. attribute:: command_help
      :annotation: :IStyle

      Style of the invoked command description (below Usage).


   .. attribute:: heading
      :annotation: :IStyle

      Style of help section headings.


   .. attribute:: constraint
      :annotation: :IStyle

      Style of an option group constraint description.


   .. attribute:: section_help
      :annotation: :IStyle

      Style of the help text of a section (the optional paragraph below the heading).


   .. attribute:: col1
      :annotation: :IStyle

      Style of the first column of a definition list (options and command names).


   .. attribute:: col2
      :annotation: :IStyle

      Style of the second column of a definition list (help text).


   .. attribute:: epilog
      :annotation: :IStyle

      Style of the epilog.


   .. method:: with_(self, invoked_command = None, command_help = None, heading = None, constraint = None, section_help = None, col1 = None, col2 = None, epilog = None)


   .. method:: dark()
      :staticmethod:

      A theme assuming a dark terminal background color.


   .. method:: light()
      :staticmethod:

      A theme assuming a light terminal background color.



.. class:: Style

   Wraps :func:`click.style` for a better integration with :class:`HelpTheme`.

   Available colors are defined as static constants in :class:`Color`.

   Arguments are set to ``None`` by default. Passing ``False`` to boolean args
   or ``Color.reset`` as color causes a reset code to be inserted.

   With respect to :func:`click.style`, this class:

   - has an argument less, ``reset``, which is always ``True``
   - add the ``text_transform``.

   .. warning::
       The arguments ``overline``, ``italic`` and ``strikethrough`` are only
       supported in Click 8 and will be ignored if you are using Click 7.

   :param fg: foreground color
   :param bg: background color
   :param bold:
   :param dim:
   :param underline:
   :param overline:
   :param italic:
   :param blink:
   :param reverse:
   :param strikethrough:
   :param text_transform:
       a generic string transformation; useful to apply functions like ``str.upper``

   .. versionadded:: 0.8.0

   .. attribute:: fg
      :annotation: :Optional[str]

      

   .. attribute:: bg
      :annotation: :Optional[str]

      

   .. attribute:: bold
      :annotation: :Optional[bool]

      

   .. attribute:: dim
      :annotation: :Optional[bool]

      

   .. attribute:: underline
      :annotation: :Optional[bool]

      

   .. attribute:: overline
      :annotation: :Optional[bool]

      

   .. attribute:: italic
      :annotation: :Optional[bool]

      

   .. attribute:: blink
      :annotation: :Optional[bool]

      

   .. attribute:: reverse
      :annotation: :Optional[bool]

      

   .. attribute:: strikethrough
      :annotation: :Optional[bool]

      

   .. attribute:: text_transform
      :annotation: :Optional[IStyle]

      

   .. method:: __call__(self, text)



.. class:: Color


   Bases: :py:obj:`cloup._util.FrozenSpace`

   Colors accepted by :class:`Style` and :func:`click.style`.

   .. attribute:: black
      :annotation: = black

      

   .. attribute:: red
      :annotation: = red

      

   .. attribute:: green
      :annotation: = green

      

   .. attribute:: yellow
      :annotation: = yellow

      

   .. attribute:: blue
      :annotation: = blue

      

   .. attribute:: magenta
      :annotation: = magenta

      

   .. attribute:: cyan
      :annotation: = cyan

      

   .. attribute:: white
      :annotation: = white

      

   .. attribute:: reset
      :annotation: = reset

      

   .. attribute:: bright_black
      :annotation: = bright_black

      

   .. attribute:: bright_red
      :annotation: = bright_red

      

   .. attribute:: bright_green
      :annotation: = bright_green

      

   .. attribute:: bright_yellow
      :annotation: = bright_yellow

      

   .. attribute:: bright_blue
      :annotation: = bright_blue

      

   .. attribute:: bright_magenta
      :annotation: = bright_magenta

      

   .. attribute:: bright_cyan
      :annotation: = bright_cyan

      

   .. attribute:: bright_white
      :annotation: = bright_white