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 = 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

Added in version 0.8.0.

fg: str | None = None
bg: str | None = None
bold: bool | None = None
dim: bool | None = None
underline: bool | None = None
overline: bool | None = None
italic: bool | None = None
reverse: bool | None = None
strikethrough: bool | None = None
text_transform: IStyle | None = 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