Skip to content

ANSItools

Module: terminaltexteffects.utils.ansitools

Collection of functions that generate ANSI escape codes for various terminal formatting effects.

These escape codes can be used to modify the appearance of text in a terminal.

Functions:

Name Description
parse_ansi_color_sequence

str) -> int | str: Parse an 8-bit or 24-bit ANSI color sequence.
dec_save_cursor_position

Save the cursor position using DEC sequence.
dec_restore_cursor_position

Restore the cursor position using DEC sequence.
hide_cursor

Hide the cursor.
show_cursor

Show the cursor.
move_cursor_up

int) -> str: Move the cursor up y lines.
move_cursor_to_column

int) -> str: Move the cursor to the specified column.
reset_all

Reset all formatting.
apply_bold

Apply bold formatting.
apply_dim

Apply dim formatting.
apply_italic

Apply italic formatting.
apply_underline

Apply underline formatting.
apply_blink

Apply blink formatting.
apply_reverse

Apply reverse formatting.
apply_hidden

Apply hidden formatting.
apply_strikethrough

Apply strikethrough formatting.

Apply blink formatting.

Returns:

Name Type Description
str str

ANSI escape code
Source code in terminaltexteffects/utils/ansitools.py 
177
178
179
180
181
182
183
184
def apply_blink() -> str:
    """Apply blink formatting.

    Returns:
        str: ANSI escape code

    """
    return "\033[5m"

apply_bold()

Apply bold formatting.

Returns:

Name Type Description
str str

ANSI escape code
Source code in terminaltexteffects/utils/ansitools.py 
137
138
139
140
141
142
143
144
def apply_bold() -> str:
    """Apply bold formatting.

    Returns:
        str: ANSI escape code

    """
    return "\033[1m"

apply_dim()

Apply dim formatting.

Returns:

Name Type Description
str str

ANSI escape code
Source code in terminaltexteffects/utils/ansitools.py 
147
148
149
150
151
152
153
154
def apply_dim() -> str:
    """Apply dim formatting.

    Returns:
        str: ANSI escape code

    """
    return "\033[2m"

apply_hidden()

Apply hidden formatting.

Returns:

Name Type Description
str str

ANSI escape code
Source code in terminaltexteffects/utils/ansitools.py 
197
198
199
200
201
202
203
204
def apply_hidden() -> str:
    """Apply hidden formatting.

    Returns:
        str: ANSI escape code

    """
    return "\033[8m"

apply_italic()

Apply italic formatting.

Returns:

Name Type Description
str str

ANSI escape code
Source code in terminaltexteffects/utils/ansitools.py 
157
158
159
160
161
162
163
164
def apply_italic() -> str:
    """Apply italic formatting.

    Returns:
        str: ANSI escape code

    """
    return "\033[3m"

apply_reverse()

Apply reverse formatting.

Returns:

Name Type Description
str str

ANSI escape code
Source code in terminaltexteffects/utils/ansitools.py 
187
188
189
190
191
192
193
194
def apply_reverse() -> str:
    """Apply reverse formatting.

    Returns:
        str: ANSI escape code

    """
    return "\033[7m"

apply_strikethrough()

Apply strikethrough formatting.

Returns:

Name Type Description
str str

ANSI escape code
Source code in terminaltexteffects/utils/ansitools.py 
207
208
209
210
211
212
213
214
def apply_strikethrough() -> str:
    """Apply strikethrough formatting.

    Returns:
        str: ANSI escape code

    """
    return "\033[9m"

apply_underline()

Apply underline formatting.

Returns:

Name Type Description
str str

ANSI escape code
Source code in terminaltexteffects/utils/ansitools.py 
167
168
169
170
171
172
173
174
def apply_underline() -> str:
    """Apply underline formatting.

    Returns:
        str: ANSI escape code

    """
    return "\033[4m"

dec_restore_cursor_position()

Restore the cursor position using DEC sequence.

Returns:

Name Type Description
str str

ANSI escape code
Source code in terminaltexteffects/utils/ansitools.py 
71
72
73
74
75
76
77
78
def dec_restore_cursor_position() -> str:
    """Restore the cursor position using DEC sequence.

    Returns:
        str: ANSI escape code

    """
    return "\0338"

dec_save_cursor_position()

Save the cursor position using DEC sequence.

Returns:

Name Type Description
str str

ANSI escape code
Source code in terminaltexteffects/utils/ansitools.py 
61
62
63
64
65
66
67
68
def dec_save_cursor_position() -> str:
    """Save the cursor position using DEC sequence.

    Returns:
        str: ANSI escape code

    """
    return "\0337"

hide_cursor()

Hide the cursor.

Returns:

Name Type Description
str str

ANSI escape code
Source code in terminaltexteffects/utils/ansitools.py 
81
82
83
84
85
86
87
88
def hide_cursor() -> str:
    """Hide the cursor.

    Returns:
        str: ANSI escape code

    """
    return "\033[?25l"

move_cursor_to_column(x)

Move the cursor to the specified column.

Parameters:

Name Type Description Default
x int

column number

 required

Returns:

Name Type Description
str str

ANSI escape code
Source code in terminaltexteffects/utils/ansitools.py 
114
115
116
117
118
119
120
121
122
123
124
def move_cursor_to_column(x: int) -> str:
    """Move the cursor to the specified column.

    Args:
        x (int): column number

    Returns:
        str: ANSI escape code

    """
    return f"\033[{x}G"

move_cursor_up(y)

Move the cursor up y lines.

Parameters:

Name Type Description Default
y int

number of lines to move up

 required

Returns:

Name Type Description
str str

ANSI escape code
Source code in terminaltexteffects/utils/ansitools.py 
101
102
103
104
105
106
107
108
109
110
111
def move_cursor_up(y: int) -> str:
    """Move the cursor up y lines.

    Args:
        y (int): number of lines to move up

    Returns:
        str: ANSI escape code

    """
    return f"\033[{y}A"

parse_ansi_color_sequence(sequence)

Parse an 8-bit or 24-bit ANSI color sequence.

Returns the color code as an integer, in the case of 8-bit, or a hex string in the case of 24-bit.

Parameters:

Name Type Description Default
sequence str

ANSI color sequence

 required

Returns:

Type Description
int | str

int | str: 8-bit color int or 24-bit color str
Source code in terminaltexteffects/utils/ansitools.py 
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
def parse_ansi_color_sequence(sequence: str) -> int | str:
    """Parse an 8-bit or 24-bit ANSI color sequence.

    Returns the color code as an integer, in the case of 8-bit, or a hex string in the case of 24-bit.

    Args:
        sequence (str): ANSI color sequence

    Returns:
        int | str: 8-bit color int or 24-bit color str

    """
    # Remove escape characters
    sequence = re.sub(r"(\033\[|\x1b\[)", "", sequence).strip("m")
    # detect 24-bit colors
    if re.match(r"^(38;2|48;2)", sequence):
        sequence = re.sub(r"^(38;2;|48;2;)", "", sequence)
        colors = []
        for color in sequence.split(";"):
            if color:
                colors.append(int(color))
            else:
                colors.append(0)  # default to 0 if no value in field (e.g. 38;2;;0m)
        return "".join(f"{color:02X}" for color in colors)
    # detect 8-bit colors
    if re.match(r"^(38;5|48;5)", sequence):
        sequence = re.sub(r"^(38;5;|48;5;)", "", sequence)
        return int(sequence)
    msg = "Invalid ANSI color sequence"
    raise ValueError(msg)

reset_all()

Reset all formatting.

Returns:

Name Type Description
str str

ANSI escape code
Source code in terminaltexteffects/utils/ansitools.py 
127
128
129
130
131
132
133
134
def reset_all() -> str:
    """Reset all formatting.

    Returns:
        str: ANSI escape code

    """
    return "\033[0m"

show_cursor()

Show the cursor.

Returns:

Name Type Description
str str

ANSI escape code
Source code in terminaltexteffects/utils/ansitools.py 
91
92
93
94
95
96
97
98
def show_cursor() -> str:
    """Show the cursor.

    Returns:
        str: ANSI escape code

    """
    return "\033[?25h"