Skip to content

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.

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 = auto()

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

Blue class-attribute instance-attribute 

Blue = auto()

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

BrightBlack class-attribute instance-attribute 

BrightBlack = auto()

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

BrightBlue class-attribute instance-attribute 

BrightBlue = auto()

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

BrightCyan class-attribute instance-attribute 

BrightCyan = auto()

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

BrightGreen class-attribute instance-attribute 

BrightGreen = auto()

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

BrightMagenta class-attribute instance-attribute 

BrightMagenta = auto()

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

BrightRed class-attribute instance-attribute 

BrightRed = auto()

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

BrightWhite class-attribute instance-attribute 

BrightWhite = auto()

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

BrightYellow class-attribute instance-attribute 

BrightYellow = auto()

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

Cyan class-attribute instance-attribute 

Cyan = auto()

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

Green class-attribute instance-attribute 

Green = auto()

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

Magenta class-attribute instance-attribute 

Magenta = auto()

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

Red class-attribute instance-attribute 

Red = auto()

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

White class-attribute instance-attribute 

White = auto()

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

Yellow class-attribute instance-attribute 

Yellow = auto()

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

Style

clap.styling.Style dataclass 

Style(
    color_fg: Optional[AnsiColor] = None,
    color_bg: 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:

  • bg_color –

    Set background color.

  • bold –

    Apply bold effect.

  • dimmed –

    Apply dimmed effect.

  • fg_color –

    Set foreground color.

  • italic –

    Apply italic effect.

  • render_bg –

    Render the ANSI code for a background color.

  • render_fg –

    Render the ANSI code for a foreground color.

  • render_reset –

    Renders the ANSI reset code.

  • underline –

    Apply underline effect.

bg_color 

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

Set background color.

Source code in clap/styling.py 
137
138
139
140
def bg_color(self, color: Optional[AnsiColor] = None) -> "Style":
    """Set background color."""
    self.color_bg = color
    return self

bold 

bold() -> Style

Apply bold effect.

Source code in clap/styling.py 
112
113
114
115
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 
117
118
119
120
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 
132
133
134
135
def fg_color(self, color: Optional[AnsiColor] = None) -> "Style":
    """Set foreground color."""
    self.color_fg = color
    return self

italic 

italic() -> Style

Apply italic effect.

Source code in clap/styling.py 
122
123
124
125
def italic(self) -> "Style":
    """Apply `italic` effect."""
    self.is_italic = True
    return self

render_bg 

render_bg() -> str

Render the ANSI code for a background color.

Source code in clap/styling.py 
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
def render_bg(self) -> str:
    """Render the ANSI code for a background color."""
    match self.color_bg:
        case None: return ""
        case AnsiColor.Black: return "40"
        case AnsiColor.Red: return "41"
        case AnsiColor.Green: return "42"
        case AnsiColor.Yellow: return "43"
        case AnsiColor.Blue: return "44"
        case AnsiColor.Magenta: return "45"
        case AnsiColor.Cyan: return "46"
        case AnsiColor.White: return "47"
        case AnsiColor.BrightBlack: return "100"
        case AnsiColor.BrightRed: return "101"
        case AnsiColor.BrightGreen: return "102"
        case AnsiColor.BrightYellow: return "103"
        case AnsiColor.BrightBlue: return "104"
        case AnsiColor.BrightMagenta: return "105"
        case AnsiColor.BrightCyan: return "106"
        case AnsiColor.BrightWhite: return "107"

render_fg 

render_fg() -> str

Render the ANSI code for a foreground color.

Source code in clap/styling.py 
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
def render_fg(self) -> str:
    """Render the ANSI code for a foreground color."""
    match self.color_fg:
        case None: return ""
        case AnsiColor.Black: return "30"
        case AnsiColor.Red: return "31"
        case AnsiColor.Green: return "32"
        case AnsiColor.Yellow: return "33"
        case AnsiColor.Blue: return "34"
        case AnsiColor.Magenta: return "35"
        case AnsiColor.Cyan: return "36"
        case AnsiColor.White: return "37"
        case AnsiColor.BrightBlack: return "90"
        case AnsiColor.BrightRed: return "91"
        case AnsiColor.BrightGreen: return "92"
        case AnsiColor.BrightYellow: return "93"
        case AnsiColor.BrightBlue: return "94"
        case AnsiColor.BrightMagenta: return "95"
        case AnsiColor.BrightCyan: return "96"
        case AnsiColor.BrightWhite: return "97"

render_reset 

render_reset() -> str

Renders the ANSI reset code.

Ellides the code if there is nothing to reset.

Source code in clap/styling.py 
184
185
186
187
188
189
190
191
def render_reset(self) -> str:
    """Renders the ANSI reset code.

    Ellides the code if there is nothing to reset.
    """
    if self != Style():
        return "\033[0m"
    return ""

underline 

underline() -> Style

Apply underline effect.

Source code in clap/styling.py 
127
128
129
130
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 
230
231
232
233
234
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 
244
245
246
247
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 
249
250
251
252
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 
259
260
261
262
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 
236
237
238
239
240
241
242
@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 
254
255
256
257
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 
265
266
267
268
269
270
271
272
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()