Styling

Control the appearance and colors of your CLI help output.

ColorChoice

clap.styling.ColorChoice

Bases: Enum

Represents the color preferences for help output.

Attributes:

• Always –

  Enables colored output regardless of whether or not the output is going to a terminal/TTY.

• Auto –

  Enables colored output only when the output is going to a terminal or TTY.

• Never –

  Disables colored output no matter if the output is going to a terminal/TTY, or not.

Always class-attribute instance-attribute

Always = auto()

Enables colored output regardless of whether or not the output is going to a terminal/TTY.

Example:

import clap
from clap import ColorChoice

@clap.command(color=ColorChoice.Always)
class Cli:
    ...

Auto class-attribute instance-attribute

Auto = auto()

Enables colored output only when the output is going to a terminal or TTY.

Example:

import clap
from clap import ColorChoice

@clap.command(color=ColorChoice.Auto)
class Cli:
    ...

Never class-attribute instance-attribute

Never = auto()

Disables colored output no matter if the output is going to a terminal/TTY, or not.

Example:

import clap
from clap import ColorChoice

@clap.command(color=ColorChoice.Never)
class Cli:
    ...

AnsiColor

clap.styling.AnsiColor

Bases: IntEnum

Available 4-bit ANSI color palette codes.

The user's terminal defines the meaning of the each palette code.

TODO

Background colors not implemented. Enum values will be changed when that is implemented.

Attributes:

• Black –

  Black: #0 (foreground code 30, background code 40).

• Blue –

  Blue: #4 (foreground code 34, background code 44).

• BrightBlack –

  Bright black: #0 (foreground code 90, background code 100).

• BrightBlue –

  Bright blue: #4 (foreground code 94, background code 104).

• BrightCyan –

  Bright cyan: #6 (foreground code 96, background code 106).

• BrightGreen –

  Bright green: #2 (foreground code 92, background code 102).

• BrightMagenta –

  Bright magenta: #5 (foreground code 95, background code 105).

• BrightRed –

  Bright red: #1 (foreground code 91, background code 101).

• BrightWhite –

  Bright white: #7 (foreground code 97, background code 107).

• BrightYellow –

  Bright yellow: #3 (foreground code 93, background code 103).

• Cyan –

  Cyan: #6 (foreground code 36, background code 46).

• Green –

  Green: #2 (foreground code 32, background code 42).

• Magenta –

  Magenta: #5 (foreground code 35, background code 45).

• Red –

  Red: #1 (foreground code 31, background code 41).

• White –

  White: #7 (foreground code 37, background code 47).

• Yellow –

  Yellow: #3 (foreground code 33, background code 43).

Black class-attribute instance-attribute

Black = 30

Black: #0 (foreground code 30, background code 40).

Blue class-attribute instance-attribute

Blue = 34

Blue: #4 (foreground code 34, background code 44).

BrightBlack class-attribute instance-attribute

BrightBlack = 90

Bright black: #0 (foreground code 90, background code 100).

BrightBlue class-attribute instance-attribute

BrightBlue = 94

Bright blue: #4 (foreground code 94, background code 104).

BrightCyan class-attribute instance-attribute

BrightCyan = 96

Bright cyan: #6 (foreground code 96, background code 106).

BrightGreen class-attribute instance-attribute

BrightGreen = 92

Bright green: #2 (foreground code 92, background code 102).

BrightMagenta class-attribute instance-attribute

BrightMagenta = 95

Bright magenta: #5 (foreground code 95, background code 105).

BrightRed class-attribute instance-attribute

BrightRed = 91

Bright red: #1 (foreground code 91, background code 101).

BrightWhite class-attribute instance-attribute

BrightWhite = 97

Bright white: #7 (foreground code 97, background code 107).

BrightYellow class-attribute instance-attribute

BrightYellow = 93

Bright yellow: #3 (foreground code 93, background code 103).

Cyan class-attribute instance-attribute

Cyan = 36

Cyan: #6 (foreground code 36, background code 46).

Green class-attribute instance-attribute

Green = 32

Green: #2 (foreground code 32, background code 42).

Magenta class-attribute instance-attribute

Magenta = 35

Magenta: #5 (foreground code 35, background code 45).

Red class-attribute instance-attribute

Red = 31

Red: #1 (foreground code 31, background code 41).

White class-attribute instance-attribute

White = 37

White: #7 (foreground code 37, background code 47).

Yellow class-attribute instance-attribute

Yellow = 33

Yellow: #3 (foreground code 33, background code 43).

Style

clap.styling.Style dataclass

Style(
    color: Optional[AnsiColor] = None,
    is_bold: bool = False,
    is_dimmed: bool = False,
    is_italic: bool = False,
    is_underline: bool = False,
)

ANSI Text styling.

You can print a Style to render the corresponding ANSI code. Using the alternate flag # will render the ANSI reset code, if needed. Together, this makes it convenient to render styles using inline format arguments.

Example:

style = Style().bold()
value = 42
print(f"{style}value{style:#}")

Methods:

• bold –

  Apply bold effect.

• dimmed –

  Apply dimmed effect.

• fg_color –

  Set foreground color.

• italic –

  Apply italic effect.

• underline –

  Apply underline effect.

bold

bold() -> Style

Apply bold effect.

Source code in clap/styling.py

def bold(self) -> "Style":
    """Apply `bold` effect."""
    self.is_bold = True
    return self

dimmed

dimmed() -> Style

Apply dimmed effect.

Source code in clap/styling.py

def dimmed(self) -> "Style":
    """Apply `dimmed` effect."""
    self.is_dimmed = True
    return self

fg_color

fg_color(color: Optional[AnsiColor] = None) -> Style

Set foreground color.

Source code in clap/styling.py

def fg_color(self, color: Optional[AnsiColor] = None) -> "Style":
    """Set foreground color."""
    self.color = color
    return self

italic

italic() -> Style

Apply italic effect.

Source code in clap/styling.py

def italic(self) -> "Style":
    """Apply `italic` effect."""
    self.is_italic = True
    return self

underline

underline() -> Style

Apply underline effect.

Source code in clap/styling.py

def underline(self) -> "Style":
    """Apply `underline` effect."""
    self.is_underline = True
    return self

Styles

clap.styling.Styles

Styles()

Terminal styling definitions.

Example:

from clap import AnsiColor, Style, Styles

styles = (Styles().header(Style().bold().underline())
              .literal(Style().fg_color(AnsiColor.Green).bold()))

Methods:

• header –

  General heading style, e.g., Commands.

• literal –

  Literal command-line syntax, e.g., --help.

• placeholder –

  Descriptions within command-line syntax, e.g., value_name.

• styled –

  Default terminal styling.

• usage –

  Usage heading.

Source code in clap/styling.py

def __init__(self):
    self.header_style = Style()
    self.literal_style = Style()
    self.usage_style = Style()
    self.placeholder_style = Style()

header

header(style: Style) -> Styles

General heading style, e.g., Commands.

Source code in clap/styling.py

def header(self, style: Style) -> "Styles":
    """General heading style, e.g., `Commands`."""
    self.header_style = style
    return self

literal

literal(style: Style) -> Styles

Literal command-line syntax, e.g., --help.

Source code in clap/styling.py

def literal(self, style: Style) -> "Styles":
    """Literal command-line syntax, e.g., `--help`."""
    self.literal_style = style
    return self

placeholder

placeholder(style: Style) -> Styles

Descriptions within command-line syntax, e.g., value_name.

Source code in clap/styling.py

def placeholder(self, style: Style) -> "Styles":
    """Descriptions within command-line syntax, e.g., `value_name`."""
    self.placeholder_style = style
    return self

styled classmethod

styled() -> Styles

Default terminal styling.

Source code in clap/styling.py

@classmethod
def styled(cls) -> "Styles":
    """Default terminal styling."""
    return (Styles().header(Style().bold().underline())
                .literal(Style().bold())
                .usage(Style().bold().underline())
                .placeholder(Style()))

usage

usage(style: Style) -> Styles

Usage heading.

Source code in clap/styling.py

def usage(self, style: Style) -> "Styles":
    """Usage heading."""
    self.usage_style = style
    return self

Functions

clap.styling.determine_color_usage

determine_color_usage(color_choice: ColorChoice) -> bool

Source code in clap/styling.py

def determine_color_usage(color_choice: ColorChoice) -> bool:
    match color_choice:
        case ColorChoice.Never:
            return False
        case ColorChoice.Always:
            return True
        case ColorChoice.Auto:
            return sys.stdout.isatty()