Skip to content

ColorTerm

Module: terminaltexteffects.utils.colorterm

New in 0.16.0

reset_fg() and reset_bg() are available on development main and are not in the published 0.15.0 package.

Use reset_fg() to restore the terminal's default foreground color, or reset_bg() to restore its default background color. Each emits a selective SGR reset and leaves the other color and text attributes in effect. Use ansitools.reset_all() to clear all formatting.

Convert XTerm 256 color codes and RGB hex colors into ANSI escape sequences.

Functions:

Name Description
`fg`

Set the foreground color using an XTerm code or RGB hex string.
`bg`

Set the background color using an XTerm code or RGB hex string.
`reset_fg`

Restore the default foreground color without clearing other formatting.
`reset_bg`

Restore the default background color without clearing other formatting.

bg(color_code)

Set the background color of the terminal text.

Parameters:

Name Type Description Default
color_code str | int

The background color as an XTerm 256 color code or an RGB hex string, with or without a leading #.

 required

Returns:

Name Type Description
str str

The ANSI escape sequence to set the background color.

Raises:

Type Description
TypeError

If color_code is not a string or non-boolean integer.
ValueError

If color_code is not exactly six hexadecimal digits with at most one leading #, or an integer from 0 through 255.
Source code in terminaltexteffects/utils/colorterm.py 
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
def bg(color_code: str | int) -> str:
    """Set the background color of the terminal text.

    Args:
        color_code (str | int): The background color as an XTerm 256 color code
            or an RGB hex string, with or without a leading `#`.

    Returns:
        str: The ANSI escape sequence to set the background color.

    Raises:
        TypeError: If `color_code` is not a string or non-boolean integer.
        ValueError: If `color_code` is not exactly six hexadecimal digits with at most one leading `#`, or an integer
            from 0 through 255.

    """
    return _color(color_code, 48)

fg(color_code)

Set the foreground color of the terminal text.

Parameters:

Name Type Description Default
color_code str | int

The foreground color as an XTerm 256 color code or an RGB hex string, with or without a leading #.

 required

Returns:

Name Type Description
str str

The ANSI escape sequence to set the foreground color.

Raises:

Type Description
TypeError

If color_code is not a string or non-boolean integer.
ValueError

If color_code is not exactly six hexadecimal digits with at most one leading #, or an integer from 0 through 255.
Source code in terminaltexteffects/utils/colorterm.py 
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
def fg(color_code: str | int) -> str:
    """Set the foreground color of the terminal text.

    Args:
        color_code (str | int): The foreground color as an XTerm 256 color code
            or an RGB hex string, with or without a leading `#`.

    Returns:
        str: The ANSI escape sequence to set the foreground color.

    Raises:
        TypeError: If `color_code` is not a string or non-boolean integer.
        ValueError: If `color_code` is not exactly six hexadecimal digits with at most one leading `#`, or an integer
            from 0 through 255.

    """
    return _color(color_code, 38)

reset_bg()

Restore the terminal's default background color without clearing other SGR attributes.

Source code in terminaltexteffects/utils/colorterm.py 
136
137
138
def reset_bg() -> str:
    """Restore the terminal's default background color without clearing other SGR attributes."""
    return "\x1b[49m"

reset_fg()

Restore the terminal's default foreground color without clearing other SGR attributes.

Source code in terminaltexteffects/utils/colorterm.py 
131
132
133
def reset_fg() -> str:
    """Restore the terminal's default foreground color without clearing other SGR attributes."""
    return "\x1b[39m"