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.

Contents

cloup.styling.IStyle

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

class cloup.styling.HelpTheme[source]

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

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

epilog :IStyle

Style of the epilog.

with_(self, invoked_command=None, command_help=None, heading=None, constraint=None, section_help=None, col1=None, col2=None, epilog=None)[source]
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]) –

  • epilog (Optional[IStyle]) –

Return type

HelpTheme

static dark()[source]

A theme assuming a dark terminal background color.

Return type

HelpTheme

static light()[source]

A theme assuming a light terminal background color.

Return type

HelpTheme

class cloup.styling.Style[source]

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 (Optional[str]) – foreground color

  • bg (Optional[str]) – background color

  • 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[Callable[[str], str]]) – a generic string transformation; useful to apply functions like str.upper

Return type

None

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]
reverse :Optional[bool]
strikethrough :Optional[bool]
text_transform :Optional[IStyle]
__call__(self, text)[source]
Parameters

text (str) –

Return type

str

class cloup.styling.Color[source]

Bases: cloup._util.FrozenSpace

Colors accepted by Style and click.style().

Return type

None

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