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[source]#

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: IStyle | None#

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)[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]) –

  • alias (Optional[IStyle]) –

  • alias_secondary (cloup.typing.Possibly[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 (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: str | None#
bg: str | None#
bold: bool | None#
dim: bool | None#
underline: bool | None#
overline: bool | None#
italic: bool | None#
reverse: bool | None#
strikethrough: bool | None#
text_transform: IStyle | None#
__call__(text)[source]#
Parameters:

text (str) –

Return type:

str

class cloup.styling.Color[source]#

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#