Skip to content

TerminalConfig

Module: terminaltexteffects.engine.terminal

Bases: ArgsDataClass

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 RBG hex to the closest XTerm-256 color.
no_color bool

Disable all colors in the effect.
wrap_text bool

Wrap text wider than the canvas width.
frame_rate float

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 is detected automatically based on the terminal device, if set to -1 the canvas width 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_effect Literal['sw', 's', 'se', 'e', 'ne', 'n', 'nw', 'w', 'c']

Anchor point for the effect within the Canvas. Effect text will 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.
existing_color_handling Literal['always', 'dynamic', 'ignore']

Specify handling of existing ANSI color sequences in the input data. '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'.
Source code in terminaltexteffects/engine/terminal.py 
 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
 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
@dataclass
class TerminalConfig(ArgsDataClass):
    """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 RBG hex to the closest XTerm-256 color.
        no_color (bool): Disable all colors in the effect.
        wrap_text (bool): Wrap text wider than the canvas width.
        frame_rate (float): 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 is detected automatically based on the terminal device, if set to -1 the canvas width 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_effect (Literal['sw','s','se','e','ne','n','nw','w','c']): Anchor point for the effect within the Canvas.
            Effect text will 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.
        existing_color_handling (Literal['always','dynamic','ignore']): Specify handling of existing ANSI color
            sequences in the input data. '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'.

    """

    tab_width: int = ArgField(
        cmd_name=["--tab-width"],
        type_parser=argvalidators.PositiveInt.type_parser,
        metavar=argvalidators.PositiveInt.METAVAR,
        default=4,
        help="Number of spaces to use for a tab character.",
    )  # type: ignore[assignment]

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

    xterm_colors: bool = ArgField(
        cmd_name=["--xterm-colors"],
        default=False,
        action="store_true",
        help="Convert any colors specified in 24-bit RBG hex to the closest 8-bit XTerm-256 color.",
    )  # type: ignore[assignment]

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

    no_color: bool = ArgField(
        cmd_name=["--no-color"],
        default=False,
        action="store_true",
        help="Disable all colors in the effect.",
    )  # type: ignore[assignment]

    "bool : Disable all colors in the effect."

    existing_color_handling: Literal["always", "dynamic", "ignore"] = ArgField(
        cmd_name=["--existing-color-handling"],
        default="ignore",
        choices=["always", "dynamic", "ignore"],
        help=(
            "Specify handling of existing 8-bit and 24-bit ANSI color sequences in the input data. 3-bit and 4-bit "
            "sequences are not supported. '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'."
        ),
    )  # type: ignore[assignment]

    (
        "Literal['always','dynamic','ignore'] : Specify handling of existing ANSI color sequences in the input data. "
        "'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: int = ArgField(
        cmd_name="--wrap-text",
        default=False,
        action="store_true",
        help="Wrap text wider than the canvas width.",
    )  # type: ignore[assignment]
    "bool : Wrap text wider than the canvas width."

    frame_rate: int = ArgField(
        cmd_name="--frame-rate",
        type_parser=argvalidators.NonNegativeInt.type_parser,
        default=100,
        help="""Target frame rate for the animation in frames per second. Set to 0 to disable frame rate limiting.""",
    )  # 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 = ArgField(
        cmd_name=["--canvas-width"],
        metavar=argvalidators.CanvasDimension.METAVAR,
        type_parser=argvalidators.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."
        ),
    )  # type: ignore[assignment]

    (
        "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 = ArgField(
        cmd_name=["--canvas-height"],
        metavar=argvalidators.CanvasDimension.METAVAR,
        type_parser=argvalidators.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."
        ),
    )  # type: ignore[assignment]

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

    anchor_canvas: Literal["sw", "s", "se", "e", "ne", "n", "nw", "w", "c"] = ArgField(
        cmd_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."
        ),
    )  # type: ignore[assignment]

    (
        "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."
    )

    anchor_text: Literal["n", "ne", "e", "se", "s", "sw", "w", "nw", "c"] = ArgField(
        cmd_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 anchored in the Canvas to "
            "the location corresponding to the cardinal/diagonal direction."
        ),
    )  # type: ignore[assignment]

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

    ignore_terminal_dimensions: bool = ArgField(
        cmd_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."
        ),
    )  # type: ignore[assignment]
    (
        "bool : Ignore the terminal dimensions and utilize the full Canvas beyond the extents of the terminal. "
        "Useful for sending frames to another output handler."
    )

anchor_canvas = ArgField(cmd_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.') 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.

anchor_text = ArgField(cmd_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 anchored in the Canvas to the location corresponding to the cardinal/diagonal direction.') 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 anchored in the Canvas to the location corresponding to the cardinal/diagonal direction.

canvas_height = ArgField(cmd_name=['--canvas-height'], metavar=argvalidators.CanvasDimension.METAVAR, type_parser=argvalidators.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.') 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 is detected automatically based on the terminal device, if set to -1 the canvas width is based on the input data height.

canvas_width = ArgField(cmd_name=['--canvas-width'], metavar=argvalidators.CanvasDimension.METAVAR, type_parser=argvalidators.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.') 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.

existing_color_handling = ArgField(cmd_name=['--existing-color-handling'], default='ignore', choices=['always', 'dynamic', 'ignore'], help="Specify handling of existing 8-bit and 24-bit ANSI color sequences in the input data. 3-bit and 4-bit sequences are not supported. '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 color sequences in the input data. '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 = ArgField(cmd_name='--frame-rate', type_parser=argvalidators.NonNegativeInt.type_parser, default=100, help='Target frame rate for the animation in frames per second. Set to 0 to disable frame rate limiting.') 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 = ArgField(cmd_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 = ArgField(cmd_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.

tab_width = ArgField(cmd_name=['--tab-width'], type_parser=argvalidators.PositiveInt.type_parser, metavar=argvalidators.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.

wrap_text = ArgField(cmd_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 = ArgField(cmd_name=['--xterm-colors'], default=False, action='store_true', help='Convert any colors specified in 24-bit RBG hex to the closest 8-bit XTerm-256 color.') class-attribute instance-attribute

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