Skip to content

TerminalConfig

Module: terminaltexteffects.engine.terminal

Bases: BaseConfig

Configuration for the terminal.

Attributes:

Name Type Description
tab_width int

Number of spaces to use for a tab character.
xterm_colors bool

Convert any colors specified in RGB hex to the closest XTerm-256 color.
no_color bool

Disable all colors in the effect.
terminal_background_color Color

Background color of the terminal used by effects that depend on it.
existing_color_handling Literal['always', 'dynamic', 'ignore']

Specify handling of existing ANSI SGR color sequences in the input data. Supported input colors include 3-bit, 4-bit, 8-bit, and 24-bit foreground/background sequences. 'always' will always use the input colors, ignoring any effect specific colors. 'dynamic' will leave it to the effect implementation to apply input colors. 'ignore' will ignore the colors in the input data. Default is 'ignore'.
wrap_text bool

Wrap text wider than the canvas width.
frame_rate int

Target frame rate for the animation in frames per second. Set to 0 to disable frame rate limiting.
canvas_width int

Canvas width, set to an integer > 0 to use a specific dimension, if set to 0 the canvas width is detected automatically based on the terminal device, if set to -1 the canvas width is based on the input data width.
canvas_height int

Canvas height, set to an integer > 0 to use a specific dimension, if set to 0 the canvas height is detected automatically based on the terminal device, if set to -1 the canvas height is based on the input data height.
anchor_canvas Literal['sw', 's', 'se', 'e', 'ne', 'n', 'nw', 'w', 'c']

Anchor point for the Canvas. The Canvas will be anchored in the terminal to the location corresponding to the cardinal/diagonal direction. Defaults to 'sw'.
anchor_text Literal['n', 'ne', 'e', 'se', 's', 'sw', 'w', 'nw', 'c']

Anchor point for the text within the Canvas. Input text will be anchored in the Canvas to the location corresponding to the cardinal/diagonal direction. Defaults to 'sw'.
ignore_terminal_dimensions bool

Ignore the terminal dimensions and utilize the full Canvas beyond the extents of the terminal. Useful for sending frames to another output handler.
reuse_canvas bool

Do not create new rows at the start of the effect. The cursor will be restored to the position of the previous canvas.
no_eol bool

Suppress the trailing newline emitted when an effect animation completes.
no_restore_cursor bool

Do not restore cursor visibility when an effect animation completes.
Source code in terminaltexteffects/engine/terminal.py 
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 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
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
@dataclass
class TerminalConfig(BaseConfig):
    """Configuration for the terminal.

    Attributes:
        tab_width (int): Number of spaces to use for a tab character.
        xterm_colors (bool): Convert any colors specified in RGB hex to the closest XTerm-256 color.
        no_color (bool): Disable all colors in the effect.
        terminal_background_color (Color): Background color of the terminal used by effects that depend on it.
        existing_color_handling (Literal['always','dynamic','ignore']): Specify handling of existing ANSI SGR color
            sequences in the input data. Supported input colors include 3-bit, 4-bit, 8-bit, and 24-bit
            foreground/background sequences. 'always' will always use the input colors, ignoring any effect specific
            colors. 'dynamic' will leave it to the effect implementation to apply input colors. 'ignore' will ignore
            the colors in the input data. Default is 'ignore'.
        wrap_text (bool): Wrap text wider than the canvas width.
        frame_rate (int): Target frame rate for the animation in frames per second. Set to 0 to disable frame
            rate limiting.
        canvas_width (int): Canvas width, set to an integer > 0 to use a specific dimension, if set to 0 the canvas
            width is detected automatically based on the terminal device, if set to -1 the canvas width is based on
            the input data width.
        canvas_height (int): Canvas height, set to an integer > 0 to use a specific dimension, if set to 0 the canvas
            height is detected automatically based on the terminal device, if set to -1 the canvas height is
            based on the input data height.
        anchor_canvas (Literal['sw','s','se','e','ne','n','nw','w','c']): Anchor point for the Canvas. The Canvas will
            be anchored in the terminal to the location corresponding to the cardinal/diagonal direction.
            Defaults to 'sw'.
        anchor_text (Literal['n','ne','e','se','s','sw','w','nw','c']): Anchor point for the text within the Canvas.
            Input text will be anchored in the Canvas to the location corresponding to the cardinal/diagonal
            direction. Defaults to 'sw'.
        ignore_terminal_dimensions (bool): Ignore the terminal dimensions and utilize the full Canvas beyond the extents
            of the terminal. Useful for sending frames to another output handler.
        reuse_canvas (bool): Do not create new rows at the start of the effect. The cursor will be restored to the
            position of the previous canvas.
        no_eol (bool): Suppress the trailing newline emitted when an effect animation completes.
        no_restore_cursor (bool): Do not restore cursor visibility when an effect animation completes.

    """

    tab_width: int = argutils.ArgSpec(
        name="--tab-width",
        type=argutils.PositiveInt.type_parser,
        metavar=argutils.PositiveInt.METAVAR,
        default=4,
        help="Number of spaces to use for a tab character.",
    )  # pyright: ignore[reportAssignmentType]
    "int : Number of spaces to use for a tab character."

    xterm_colors: bool = argutils.ArgSpec(
        name="--xterm-colors",
        default=False,
        action="store_true",
        help="Convert any colors specified in 24-bit RGB hex to the closest 8-bit XTerm-256 color.",
    )  # pyright: ignore[reportAssignmentType]
    "bool : Convert any colors specified in 24-bit RGB hex to the closest 8-bit XTerm-256 color."

    no_color: bool = argutils.ArgSpec(
        name="--no-color",
        default=False,
        action="store_true",
        help="Disable all colors in the effect.",
    )  # pyright: ignore[reportAssignmentType]
    "bool : Disable all colors in the effect."

    terminal_background_color: Color = argutils.ArgSpec(
        name="--terminal-background-color",
        type=argutils.ColorArg.type_parser,
        default=Color("#000000"),
        metavar=argutils.ColorArg.METAVAR,
        help=(
            "The background color of your terminal. "
            "Used to determine the appropriate color for fade-in/out within effects."
        ),
    )  # type: ignore[assignment]
    "Color: User-defined background color of the terminal."

    existing_color_handling: Literal["always", "dynamic", "ignore"] = argutils.ArgSpec(
        name="--existing-color-handling",
        default="ignore",
        choices=["always", "dynamic", "ignore"],
        help=(
            "Specify handling of existing ANSI SGR color sequences in the input data. Supported input colors include "
            "3-bit, 4-bit, 8-bit, and 24-bit foreground/background sequences. 'always' will always use the input "
            "colors, ignoring any effect specific colors. 'dynamic' will leave it to the effect implementation to "
            "apply input colors. 'ignore' will ignore the colors in the input data. Default is 'ignore'."
        ),
    )  # pyright: ignore[reportAssignmentType]
    (
        "Literal['always','dynamic','ignore'] : Specify handling of existing ANSI SGR color sequences in the input "
        "data. Supported input colors include 3-bit, 4-bit, 8-bit, and 24-bit foreground/background sequences. "
        "'always' will always use the input colors, ignoring any effect specific colors. 'dynamic' will leave it to "
        "the effect implementation to apply input colors. 'ignore' will ignore the colors in the input data. "
        "Default is 'ignore'."
    )

    wrap_text: bool = argutils.ArgSpec(
        name="--wrap-text",
        default=False,
        action="store_true",
        help="Wrap text wider than the canvas width.",
    )  # pyright: ignore[reportAssignmentType]
    "bool : Wrap text wider than the canvas width."

    frame_rate: int = argutils.ArgSpec(
        name="--frame-rate",
        type=argutils.NonNegativeInt.type_parser,
        default=60,
        help=(
            "Target frame rate for the animation in frames per second. Set to 0 to disable frame rate limiting. "
            "Defaults to 60."
        ),
    )  # type: ignore[assignment]

    "int : Target frame rate for the animation in frames per second. Set to 0 to disable frame rate limiting."

    canvas_width: int = argutils.ArgSpec(
        name="--canvas-width",
        metavar=argutils.CanvasDimension.METAVAR,
        type=argutils.CanvasDimension.type_parser,
        default=-1,
        help=(
            "Canvas width, set to an integer > 0 to use a specific dimension, use 0 to match the terminal width, "
            "or use -1 to match the input text width. Defaults to -1."
        ),
    )  # pyright: ignore[reportAssignmentType]
    (
        "int : Canvas width, set to an integer > 0 to use a specific dimension, if set to 0 the canvas width is "
        "detected automatically based on the terminal device, if set to -1 the canvas width is based on "
        "the input data width. Defaults to -1."
    )

    canvas_height: int = argutils.ArgSpec(
        name="--canvas-height",
        metavar=argutils.CanvasDimension.METAVAR,
        type=argutils.CanvasDimension.type_parser,
        default=-1,
        help=(
            "Canvas height, set to an integer > 0 to use a specific dimension, use 0 to match the terminal "
            "height, or use -1 to match the input text height. Defaults to -1."
        ),
    )  # pyright: ignore[reportAssignmentType]
    (
        "int : Canvas height, set to an integer > 0 to use a specific dimension, if set to 0 the canvas height "
        "is detected automatically based on the terminal device, if set to -1 the canvas height is "
        "based on the input data height. Defaults to -1."
    )

    anchor_canvas: Literal["sw", "s", "se", "e", "ne", "n", "nw", "w", "c"] = argutils.ArgSpec(
        name="--anchor-canvas",
        choices=["sw", "s", "se", "e", "ne", "n", "nw", "w", "c"],
        default="sw",
        help=(
            "Anchor point for the canvas. The canvas will be anchored in the terminal to the location "
            "corresponding to the cardinal/diagonal direction. Defaults to 'sw'."
        ),
    )  # pyright: ignore[reportAssignmentType]
    (
        "Literal['sw','s','se','e','ne','n','nw','w','c'] : Anchor point for the canvas. The canvas will be "
        "anchored in the terminal to the location corresponding to the cardinal/diagonal direction. Defaults to 'sw'."
    )

    anchor_text: Literal["n", "ne", "e", "se", "s", "sw", "w", "nw", "c"] = argutils.ArgSpec(
        name="--anchor-text",
        choices=["n", "ne", "e", "se", "s", "sw", "w", "nw", "c"],
        default="sw",
        help=(
            "Anchor point for the text within the Canvas. Input text will be anchored in the Canvas to "
            "the location corresponding to the cardinal/diagonal direction. Defaults to 'sw'."
        ),
    )  # pyright: ignore[reportAssignmentType]
    (
        "Literal['n','ne','e','se','s','sw','w','nw','c'] : Anchor point for the text within the Canvas. "
        "Input text will be anchored in the Canvas to the location corresponding to the cardinal/diagonal direction. "
        "Defaults to 'sw'."
    )

    ignore_terminal_dimensions: bool = argutils.ArgSpec(
        name="--ignore-terminal-dimensions",
        default=False,
        action="store_true",
        help=(
            "Ignore the terminal dimensions and utilize the full Canvas beyond the extents of the terminal. "
            "Useful for sending frames to another output handler."
        ),
    )  # pyright: ignore[reportAssignmentType]
    (
        "bool : Ignore the terminal dimensions and utilize the full Canvas beyond the extents of the terminal. "
        "Useful for sending frames to another output handler."
    )

    reuse_canvas: bool = argutils.ArgSpec(
        name="--reuse-canvas",
        default=False,
        action="store_true",
        help=(
            "Do not create new rows at the start of the effect. The cursor will be moved up the number of rows "
            "present in the input text in an attempt to re-use the canvas. This option works best when used in "
            "a shell script. If used interactively with prompts between runs, the result is unpredictable."
        ),
    )  # pyright: ignore[reportAssignmentType]
    (
        "bool: Do not create new rows at the start of the effect. The cursor will be moved up the number of rows "
        "present in the input text in an attempt to re-use the canvas. This option works best when used in "
        "a shell script. If used interactively with prompts between runs, the result is unpredictable."
    )

    no_eol: bool = argutils.ArgSpec(
        name="--no-eol",
        default=False,
        action="store_true",
        help=("Suppress the trailing newline emitted when an effect animation completes."),
    )  # pyright: ignore[reportAssignmentType]
    ("bool : Suppress the trailing newline emitted when an effect animation completes. ")

    no_restore_cursor: bool = argutils.ArgSpec(
        name="--no-restore-cursor",
        default=False,
        action="store_true",
        help=("Do not restore cursor visibility after the effect."),
    )  # pyright: ignore[reportAssignmentType]
    ("bool : Do not restore cursor visibility after the effect.")

anchor_canvas = argutils.ArgSpec(name='--anchor-canvas', choices=['sw', 's', 'se', 'e', 'ne', 'n', 'nw', 'w', 'c'], default='sw', help="Anchor point for the canvas. The canvas will be anchored in the terminal to the location corresponding to the cardinal/diagonal direction. Defaults to 'sw'.") class-attribute instance-attribute

Literal['sw','s','se','e','ne','n','nw','w','c'] : Anchor point for the canvas. The canvas will be anchored in the terminal to the location corresponding to the cardinal/diagonal direction. Defaults to 'sw'.

anchor_text = argutils.ArgSpec(name='--anchor-text', choices=['n', 'ne', 'e', 'se', 's', 'sw', 'w', 'nw', 'c'], default='sw', help="Anchor point for the text within the Canvas. Input text will be anchored in the Canvas to the location corresponding to the cardinal/diagonal direction. Defaults to 'sw'.") class-attribute instance-attribute

Literal['n','ne','e','se','s','sw','w','nw','c'] : Anchor point for the text within the Canvas. Input text will be anchored in the Canvas to the location corresponding to the cardinal/diagonal direction. Defaults to 'sw'.

canvas_height = argutils.ArgSpec(name='--canvas-height', metavar=(argutils.CanvasDimension.METAVAR), type=(argutils.CanvasDimension.type_parser), default=(-1), help='Canvas height, set to an integer > 0 to use a specific dimension, use 0 to match the terminal height, or use -1 to match the input text height. Defaults to -1.') class-attribute instance-attribute

int : Canvas height, set to an integer > 0 to use a specific dimension, if set to 0 the canvas height is detected automatically based on the terminal device, if set to -1 the canvas height is based on the input data height. Defaults to -1.

canvas_width = argutils.ArgSpec(name='--canvas-width', metavar=(argutils.CanvasDimension.METAVAR), type=(argutils.CanvasDimension.type_parser), default=(-1), help='Canvas width, set to an integer > 0 to use a specific dimension, use 0 to match the terminal width, or use -1 to match the input text width. Defaults to -1.') class-attribute instance-attribute

int : Canvas width, set to an integer > 0 to use a specific dimension, if set to 0 the canvas width is detected automatically based on the terminal device, if set to -1 the canvas width is based on the input data width. Defaults to -1.

existing_color_handling = argutils.ArgSpec(name='--existing-color-handling', default='ignore', choices=['always', 'dynamic', 'ignore'], help="Specify handling of existing ANSI SGR color sequences in the input data. Supported input colors include 3-bit, 4-bit, 8-bit, and 24-bit foreground/background sequences. 'always' will always use the input colors, ignoring any effect specific colors. 'dynamic' will leave it to the effect implementation to apply input colors. 'ignore' will ignore the colors in the input data. Default is 'ignore'.") class-attribute instance-attribute

Literal['always','dynamic','ignore'] : Specify handling of existing ANSI SGR color sequences in the input data. Supported input colors include 3-bit, 4-bit, 8-bit, and 24-bit foreground/background sequences. 'always' will always use the input colors, ignoring any effect specific colors. 'dynamic' will leave it to the effect implementation to apply input colors. 'ignore' will ignore the colors in the input data. Default is 'ignore'.

frame_rate = argutils.ArgSpec(name='--frame-rate', type=(argutils.NonNegativeInt.type_parser), default=60, help='Target frame rate for the animation in frames per second. Set to 0 to disable frame rate limiting. Defaults to 60.') class-attribute instance-attribute

int : Target frame rate for the animation in frames per second. Set to 0 to disable frame rate limiting.

ignore_terminal_dimensions = argutils.ArgSpec(name='--ignore-terminal-dimensions', default=False, action='store_true', help='Ignore the terminal dimensions and utilize the full Canvas beyond the extents of the terminal. Useful for sending frames to another output handler.') class-attribute instance-attribute

bool : Ignore the terminal dimensions and utilize the full Canvas beyond the extents of the terminal. Useful for sending frames to another output handler.

no_color = argutils.ArgSpec(name='--no-color', default=False, action='store_true', help='Disable all colors in the effect.') class-attribute instance-attribute

bool : Disable all colors in the effect.

no_eol = argutils.ArgSpec(name='--no-eol', default=False, action='store_true', help='Suppress the trailing newline emitted when an effect animation completes.') class-attribute instance-attribute

bool : Suppress the trailing newline emitted when an effect animation completes.

no_restore_cursor = argutils.ArgSpec(name='--no-restore-cursor', default=False, action='store_true', help='Do not restore cursor visibility after the effect.') class-attribute instance-attribute

bool : Do not restore cursor visibility after the effect.

reuse_canvas = argutils.ArgSpec(name='--reuse-canvas', default=False, action='store_true', help='Do not create new rows at the start of the effect. The cursor will be moved up the number of rows present in the input text in an attempt to re-use the canvas. This option works best when used in a shell script. If used interactively with prompts between runs, the result is unpredictable.') class-attribute instance-attribute

bool: Do not create new rows at the start of the effect. The cursor will be moved up the number of rows present in the input text in an attempt to re-use the canvas. This option works best when used in a shell script. If used interactively with prompts between runs, the result is unpredictable.

tab_width = argutils.ArgSpec(name='--tab-width', type=(argutils.PositiveInt.type_parser), metavar=(argutils.PositiveInt.METAVAR), default=4, help='Number of spaces to use for a tab character.') class-attribute instance-attribute

int : Number of spaces to use for a tab character.

terminal_background_color = argutils.ArgSpec(name='--terminal-background-color', type=(argutils.ColorArg.type_parser), default=(Color('#000000')), metavar=(argutils.ColorArg.METAVAR), help='The background color of your terminal. Used to determine the appropriate color for fade-in/out within effects.') class-attribute instance-attribute

Color: User-defined background color of the terminal.

wrap_text = argutils.ArgSpec(name='--wrap-text', default=False, action='store_true', help='Wrap text wider than the canvas width.') class-attribute instance-attribute

bool : Wrap text wider than the canvas width.

xterm_colors = argutils.ArgSpec(name='--xterm-colors', default=False, action='store_true', help='Convert any colors specified in 24-bit RGB hex to the closest 8-bit XTerm-256 color.') class-attribute instance-attribute

bool : Convert any colors specified in 24-bit RGB hex to the closest 8-bit XTerm-256 color.