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
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.
enter_alternate_screen

Switch to a cleared alternate screen with the cursor at the top-left.
exit_alternate_screen

Return from the alternate screen to the original screen.
move_cursor_up

int) -> str: Move the cursor up y lines.
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 
166
167
168
169
170
171
172
173
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 
126
127
128
129
130
131
132
133
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 
136
137
138
139
140
141
142
143
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 
186
187
188
189
190
191
192
193
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 
146
147
148
149
150
151
152
153
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 
176
177
178
179
180
181
182
183
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 
196
197
198
199
200
201
202
203
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 
156
157
158
159
160
161
162
163
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 
37
38
39
40
41
42
43
44
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 
27
28
29
30
31
32
33
34
def dec_save_cursor_position() -> str:
    """Save the cursor position using DEC sequence.

    Returns:
        str: ANSI escape code

    """
    return "\0337"

enter_alternate_screen()

Switch to the alternate screen buffer, clear it, and move the cursor to the top-left.

The original screen contents and cursor position are restored by exit_alternate_screen().

Returns:

Name Type Description
str str

ANSI escape code
Source code in terminaltexteffects/utils/ansitools.py 
67
68
69
70
71
72
73
74
75
76
def enter_alternate_screen() -> str:
    """Switch to the alternate screen buffer, clear it, and move the cursor to the top-left.

    The original screen contents and cursor position are restored by `exit_alternate_screen()`.

    Returns:
        str: ANSI escape code

    """
    return "\033[?1049h\033[H"

exit_alternate_screen()

Return from the alternate screen buffer to the original screen.

Returns:

Name Type Description
str str

ANSI escape code
Source code in terminaltexteffects/utils/ansitools.py 
79
80
81
82
83
84
85
86
def exit_alternate_screen() -> str:
    """Return from the alternate screen buffer to the original screen.

    Returns:
        str: ANSI escape code

    """
    return "\033[?1049l"

hide_cursor()

Hide the cursor.

Returns:

Name Type Description
str str

ANSI escape code
Source code in terminaltexteffects/utils/ansitools.py 
47
48
49
50
51
52
53
54
def hide_cursor() -> str:
    """Hide the cursor.

    Returns:
        str: ANSI escape code

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

move_cursor_up(y)

Move the cursor up by a relative number of rows.

A distance of 0 is a no-op and returns an empty string.

Parameters:

Name Type Description Default
y int

Number of rows to move upward from the current cursor position.

 required

Returns:

Name Type Description
str str

ANSI escape code

Raises:

Type Description
TypeError

If y is not a non-boolean integer.
ValueError

If y is negative.
Source code in terminaltexteffects/utils/ansitools.py 
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
def move_cursor_up(y: int) -> str:
    """Move the cursor up by a relative number of rows.

    A distance of `0` is a no-op and returns an empty string.

    Args:
        y (int): Number of rows to move upward from the current cursor position.

    Returns:
        str: ANSI escape code

    Raises:
        TypeError: If `y` is not a non-boolean integer.
        ValueError: If `y` is negative.

    """
    if isinstance(y, bool) or not isinstance(y, int):
        msg = "y must be a non-boolean integer"
        raise TypeError(msg)
    if y < 0:
        msg = "y must be non-negative"
        raise ValueError(msg)
    if y == 0:
        return ""
    return f"\033[{y}A"

reset_all()

Reset all formatting.

Returns:

Name Type Description
str str

ANSI escape code
Source code in terminaltexteffects/utils/ansitools.py 
116
117
118
119
120
121
122
123
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 
57
58
59
60
61
62
63
64
def show_cursor() -> str:
    """Show the cursor.

    Returns:
        str: ANSI escape code

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