cloup.styling

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

Classes

HelpTheme

A collection of styles for several elements of the help page.

Style

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 – Style of the invoked command name (in Usage).

  • command_help – Style of the invoked command description (below Usage).

  • heading – Style of help section headings.

  • constraint – Style of an option group constraint description.

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

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

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

  • epilog – Style of the epilog.

  • alias – Style of subcommand aliases in a definition lists.

  • alias_secondary – 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, **kwargs)[source]

Return a theme of the same type with the supplied fields replaced.

Additional keyword arguments are passed to dataclasses.replace() to support fields added by subclasses.

Parameters:

  • invoked_command (IStyle | None)

  • command_help (IStyle | None)

  • heading (IStyle | None)

  • constraint (IStyle | None)

  • section_help (IStyle | None)

  • col1 (IStyle | None)

  • col2 (IStyle | None)

  • alias (IStyle | None)

  • alias_secondary (cloup.typing.Possibly[IStyle | None])

  • epilog (IStyle | None)

  • kwargs (object)

Return type:

Self

classmethod dark()[source]

A theme assuming a dark terminal background color.

Return type:

Self

classmethod light()[source]

A theme assuming a light terminal background color.

Return type:

Self

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 – foreground color

  • bg – background color

  • bold

  • dim

  • underline

  • overline

  • italic

  • blink

  • reverse

  • strikethrough

  • text_transform – a generic string transformation; useful to apply functions like str.upper

Added in version 0.8.0.

fg: int | tuple[int, int, int] | str | None = None
bg: int | tuple[int, int, int] | 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