Hide navigation sidebar
Hide table of contents sidebar
Back to top
Toggle table of contents sidebar

# `cloup.styling`

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

## Classes

`HelpTheme`([invoked_command, command_help, ...]) | A collection of styles for several elements of the help page.
`Style`([fg, bg, bold, dim, underline, ...]) | Wraps `click.style()` for a better integration with `HelpTheme`.
`Color`() | Colors accepted by `Style` and `click.style()`.

## Attributes

`IStyle` | A callable that takes a string and returns a styled version of it.
`DEFAULT_THEME` |

## Contents

cloup.styling.IStyle

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

class cloup.styling.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 `Style` class, which is a wrapper of the `click.style` function.

  Parameters:

    - invoked_command (Callable[[str], str]) – Style of the invoked command name (in Usage).

    - command_help (Callable[[str], str]) – Style of the invoked command description (below Usage).

    - heading (Callable[[str], str]) – Style of help section headings.

    - constraint (Callable[[str], str]) – Style of an option group constraint description.

    - section_help (Callable[[str], str]) – Style of the help text of a section (the optional paragraph below the heading).

    - col1 (Callable[[str], str]) – Style of the first column of a definition list (options and command names).

    - col2 (Callable[[str], str]) – Style of the second column of a definition list (help text).

    - epilog (Callable[[str], str]) – Style of the epilog.

    - alias (Callable[[str], str]) – Style of subcommand aliases in a definition lists.

    - alias_secondary (Callable[[str], str] | None) – Style of separator and eventual parenthesis/brackets in subcommand alias lists. If not provided, the `alias` style will be used.

  invoked_command :IStyle

    Style of the invoked command name (in Usage).

  command_help :IStyle

    Style of the invoked command description (below Usage).

  heading :IStyle

    Style of help section headings.

  constraint :IStyle

    Style of an option group constraint description.

  section_help :IStyle

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

  col1 :IStyle

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

  col2 :IStyle

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

  alias :IStyle

    Style of subcommand aliases in a definition lists.

  alias_secondary :Optional[IStyle]

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

  epilog :IStyle

    Style of the epilog.

  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)
    Parameters:

      - invoked_command (Optional[IStyle]) –

      - command_help (Optional[IStyle]) –

      - heading (Optional[IStyle]) –

      - constraint (Optional[IStyle]) –

      - section_help (Optional[IStyle]) –

      - col1 (Optional[IStyle]) –

      - col2 (Optional[IStyle]) –

      - alias (Optional[IStyle]) –

      - alias_secondary (cloup.typing.Possibly[Optional[IStyle]]) –

      - epilog (Optional[IStyle]) –

    Return type:

      HelpTheme

  static dark()

    A theme assuming a dark terminal background color.

    Return type:

      HelpTheme

  static light()

    A theme assuming a light terminal background color.

    Return type:

      HelpTheme

class cloup.styling.Style

  Wraps `click.style()` for a better integration with `HelpTheme`.

  Available colors are defined as static constants in `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 `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.

  Parameters:

    - fg (str | None) – foreground color

    - bg (str | None) – background color

    - bold (bool | None) –

    - dim (bool | None) –

    - underline (bool | None) –

    - overline (bool | None) –

    - italic (bool | None) –

    - blink (bool | None) –

    - reverse (bool | None) –

    - strikethrough (bool | None) –

    - text_transform (Callable[[str], str] | None) – a generic string transformation; useful to apply functions like `str.upper`

  New in version 0.8.0.

  fg :Optional[str]
  bg :Optional[str]
  bold :Optional[bool]
  dim :Optional[bool]
  underline :Optional[bool]
  overline :Optional[bool]
  italic :Optional[bool]
  blink :Optional[bool]
  reverse :Optional[bool]
  strikethrough :Optional[bool]
  text_transform :Optional[IStyle]
  __call__(text)
    Parameters:

      text (str) –

    Return type:

      str

class cloup.styling.Color

  Bases: `cloup._util.FrozenSpace`

  Colors accepted by `Style` and `click.style()`.

  black = black
  red = red
  green = green
  yellow = yellow
  blue = blue
  magenta = magenta
  cyan = cyan
  white = white
  reset = reset
  bright_black = bright_black
  bright_red = bright_red
  bright_green = bright_green
  bright_yellow = bright_yellow
  bright_blue = bright_blue
  bright_magenta = bright_magenta
  bright_cyan = bright_cyan
  bright_white = bright_white

cloup.styling.DEFAULT_THEME