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 (Optional[Callable[[str], str]]) – 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)[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 (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

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__(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#