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

.. py:module:: cloup.styling

.. autoapi-nested-parse::

   This module contains components that specifically address the styling and theming
   of the ``--help`` output.





                              
Classes
-------

.. autosummary::

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


Attributes
----------

.. autoapisummary::

   cloup.styling.IStyle
   cloup.styling.DEFAULT_THEME

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

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


.. py:class:: HelpTheme

   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.
   :param alias:
       Style of subcommand aliases in a definition lists.
   :param alias_secondary:
       Style of separator and eventual parenthesis/brackets in subcommand alias lists.
       If not provided, the ``alias`` style will be used.


   .. py:attribute:: invoked_command
      :type:  IStyle

      Style of the invoked command name (in Usage).



   .. py:attribute:: command_help
      :type:  IStyle

      Style of the invoked command description (below Usage).



   .. py:attribute:: heading
      :type:  IStyle

      Style of help section headings.



   .. py:attribute:: constraint
      :type:  IStyle

      Style of an option group constraint description.



   .. py:attribute:: section_help
      :type:  IStyle

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



   .. py:attribute:: col1
      :type:  IStyle

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



   .. py:attribute:: col2
      :type:  IStyle

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



   .. py:attribute:: alias
      :type:  IStyle

      Style of subcommand aliases in a definition lists.



   .. py:attribute:: alias_secondary
      :type:  Optional[IStyle]
      :value: None


      Style of separator and eventual parenthesis/brackets in subcommand alias lists.
      If not provided, the ``alias`` style will be used.



   .. py:attribute:: epilog
      :type:  IStyle

      Style of the epilog.



   .. py:method:: with_(invoked_command = None, command_help = None, heading = None, constraint = None, section_help = None, col1 = None, col2 = None, alias = None, alias_secondary = MISSING, epilog = None)


   .. py:method:: dark()
      :staticmethod:


      A theme assuming a dark terminal background color.



   .. py:method:: light()
      :staticmethod:


      A theme assuming a light terminal background color.



.. py: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


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



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



   .. py:attribute:: bold
      :type:  Optional[bool]
      :value: None



   .. py:attribute:: dim
      :type:  Optional[bool]
      :value: None



   .. py:attribute:: underline
      :type:  Optional[bool]
      :value: None



   .. py:attribute:: overline
      :type:  Optional[bool]
      :value: None



   .. py:attribute:: italic
      :type:  Optional[bool]
      :value: None



   .. py:attribute:: blink
      :type:  Optional[bool]
      :value: None



   .. py:attribute:: reverse
      :type:  Optional[bool]
      :value: None



   .. py:attribute:: strikethrough
      :type:  Optional[bool]
      :value: None



   .. py:attribute:: text_transform
      :type:  Optional[IStyle]
      :value: None



   .. py:method:: __call__(text)


.. py:class:: Color

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


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


   .. py:attribute:: black
      :value: 'black'



   .. py:attribute:: red
      :value: 'red'



   .. py:attribute:: green
      :value: 'green'



   .. py:attribute:: yellow
      :value: 'yellow'



   .. py:attribute:: blue
      :value: 'blue'



   .. py:attribute:: magenta
      :value: 'magenta'



   .. py:attribute:: cyan
      :value: 'cyan'



   .. py:attribute:: white
      :value: 'white'



   .. py:attribute:: reset
      :value: 'reset'



   .. py:attribute:: bright_black
      :value: 'bright_black'



   .. py:attribute:: bright_red
      :value: 'bright_red'



   .. py:attribute:: bright_green
      :value: 'bright_green'



   .. py:attribute:: bright_yellow
      :value: 'bright_yellow'



   .. py:attribute:: bright_blue
      :value: 'bright_blue'



   .. py:attribute:: bright_magenta
      :value: 'bright_magenta'



   .. py:attribute:: bright_cyan
      :value: 'bright_cyan'



   .. py:attribute:: bright_white
      :value: 'bright_white'



.. py:data:: DEFAULT_THEME


                                         