Skip to content

Fireworks

Demo

Quick Start

fireworks.py
from terminaltexteffects.effects.effect_fireworks import Fireworks

effect = Fireworks("YourTextHere")
with effect.terminal_output() as terminal:
    for frame in effect:
        terminal.print(frame)

Launches characters up the screen where they explode like fireworks and fall into place.

Classes:

Name Description
Fireworks

Characters explode like fireworks and fall into place.
FireworksConfig

Configuration for the Fireworks effect.
FireworksIterator

Iterates over the effect. Does not normally need to be called directly.

Fireworks

Bases: BaseEffect[FireworksConfig]

Launches characters up the screen where they explode like fireworks and fall into place.

Attributes:

Name Type Description
effect_config FireworksConfig

Configuration for the effect.
terminal_config TerminalConfig

Configuration for the terminal.
Source code in terminaltexteffects/effects/effect_fireworks.py 
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
class Fireworks(BaseEffect[FireworksConfig]):
    """Launches characters up the screen where they explode like fireworks and fall into place.

    Attributes:
        effect_config (FireworksConfig): Configuration for the effect.
        terminal_config (TerminalConfig): Configuration for the terminal.

    """

    _config_cls = FireworksConfig
    _iterator_cls = FireworksIterator

    def __init__(self, input_data: str):
        """Initialize the effect with the provided input data.

        Args:
            input_data (str): The input data to use for the effect."""
        super().__init__(input_data)

__init__(input_data)

Initialize the effect with the provided input data.

Parameters:

Name Type Description Default
input_data str

The input data to use for the effect.

 required
Source code in terminaltexteffects/effects/effect_fireworks.py 
267
268
269
270
271
272
def __init__(self, input_data: str):
    """Initialize the effect with the provided input data.

    Args:
        input_data (str): The input data to use for the effect."""
    super().__init__(input_data)

FireworksConfig dataclass

Bases: ArgsDataClass

Configuration for the Fireworks effect.

Attributes:

Name Type Description
explode_anywhere bool

If set, fireworks explode anywhere in the canvas. Otherwise, fireworks explode above highest settled row of text.
firework_colors tuple[Color, ...]

Tuple of colors from which firework colors will be randomly selected.
firework_symbol str

Symbol to use for the firework shell.
firework_volume float

Percent of total characters in each firework shell. Valid values are 0 < n <= 1.
final_gradient_stops tuple[Color, ...]

Tuple of colors for the final color gradient. If only one color is provided, the characters will be displayed in that color.
final_gradient_steps tuple[int, ...] | int

Tuple of the number of gradient steps to use. More steps will create a smoother and longer gradient animation. Valid values are n > 0.
final_gradient_direction Direction

Direction of the final gradient.
launch_delay int

Number of frames to wait between launching each firework shell. +/- 0-50 percent randomness is applied to this value. Valid values are n >= 0.
explode_distance float

Maximum distance from the firework shell origin to the explode waypoint as a percentage of the total canvas width. Valid values are 0 < n <= 1.
Source code in terminaltexteffects/effects/effect_fireworks.py 
 27
 28
 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
 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
@argclass(
    name="fireworks",
    help="Characters launch and explode like fireworks and fall into place.",
    description="fireworks | Characters explode like fireworks and fall into place.",
    epilog="""Example: terminaltexteffects fireworks --firework-colors 88F7E2 44D492 F5EB67 FFA15C FA233E --firework-symbol o --firework-volume 0.02 --final-gradient-stops 8A008A 00D1FF FFFFFF --final-gradient-steps 12 --launch-delay 60 --explode-distance 0.1 --explode-anywhere""",
)
@dataclass
class FireworksConfig(ArgsDataClass):
    """Configuration for the Fireworks effect.

    Attributes:
        explode_anywhere (bool): If set, fireworks explode anywhere in the canvas. Otherwise, fireworks explode above highest settled row of text.
        firework_colors (tuple[Color, ...]): Tuple of colors from which firework colors will be randomly selected.
        firework_symbol (str): Symbol to use for the firework shell.
        firework_volume (float): Percent of total characters in each firework shell. Valid values are 0 < n <= 1.
        final_gradient_stops (tuple[Color, ...]): Tuple of colors for the final color gradient. If only one color is provided, the characters will be displayed in that color.
        final_gradient_steps (tuple[int, ...] | int): Tuple of the number of gradient steps to use. More steps will create a smoother and longer gradient animation. Valid values are n > 0.
        final_gradient_direction (Gradient.Direction): Direction of the final gradient.
        launch_delay (int): Number of frames to wait between launching each firework shell. +/- 0-50 percent randomness is applied to this value. Valid values are n >= 0.
        explode_distance (float): Maximum distance from the firework shell origin to the explode waypoint as a percentage of the total canvas width. Valid values are 0 < n <= 1."""

    explode_anywhere: bool = ArgField(
        cmd_name="--explode-anywhere",
        action="store_true",
        default=False,
        help="If set, fireworks explode anywhere in the canvas. Otherwise, fireworks explode above highest settled row of text.",
    )  # type: ignore[assignment]
    "bool : If set, fireworks explode anywhere in the canvas. Otherwise, fireworks explode above highest settled row of text."

    firework_colors: tuple[Color, ...] = ArgField(
        cmd_name="--firework-colors",
        type_parser=argvalidators.ColorArg.type_parser,
        nargs="+",
        default=(Color("88F7E2"), Color("44D492"), Color("F5EB67"), Color("FFA15C"), Color("FA233E")),
        metavar=argvalidators.ColorArg.METAVAR,
        help="Space separated list of colors from which firework colors will be randomly selected.",
    )  # type: ignore[assignment]
    "tuple[Color, ...] : Tuple of colors from which firework colors will be randomly selected."

    firework_symbol: str = ArgField(
        cmd_name="--firework-symbol",
        type_parser=argvalidators.Symbol.type_parser,
        default="o",
        metavar=argvalidators.Symbol.METAVAR,
        help="Symbol to use for the firework shell.",
    )  # type: ignore[assignment]
    "str : Symbol to use for the firework shell."

    firework_volume: float = ArgField(
        cmd_name="--firework-volume",
        type_parser=argvalidators.Ratio.type_parser,
        default=0.02,
        metavar=argvalidators.Ratio.METAVAR,
        help="Percent of total characters in each firework shell.",
    )  # type: ignore[assignment]
    "float : Percent of total characters in each firework shell."

    final_gradient_stops: tuple[Color, ...] = ArgField(
        cmd_name="--final-gradient-stops",
        type_parser=argvalidators.ColorArg.type_parser,
        nargs="+",
        default=(Color("8A008A"), Color("00D1FF"), Color("FFFFFF")),
        metavar=argvalidators.ColorArg.METAVAR,
        help="Space separated, unquoted, list of colors for the character gradient (applied from bottom to top). If only one color is provided, the characters will be displayed in that color.",
    )  # type: ignore[assignment]
    "tuple[Color, ...] : Tuple of colors for the final color gradient. If only one color is provided, the characters will be displayed in that color."

    final_gradient_steps: tuple[int, ...] | int = ArgField(
        cmd_name="--final-gradient-steps",
        type_parser=argvalidators.PositiveInt.type_parser,
        nargs="+",
        default=12,
        metavar=argvalidators.PositiveInt.METAVAR,
        help="Space separated, unquoted, list of the number of gradient steps to use. More steps will create a smoother and longer gradient animation.",
    )  # type: ignore[assignment]
    "tuple[int, ...] | int : Int or Tuple of ints for the number of gradient steps to use. More steps will create a smoother and longer gradient animation."

    final_gradient_direction: Gradient.Direction = ArgField(
        cmd_name="--final-gradient-direction",
        type_parser=argvalidators.GradientDirection.type_parser,
        default=Gradient.Direction.HORIZONTAL,
        metavar=argvalidators.GradientDirection.METAVAR,
        help="Direction of the final gradient.",
    )  # type: ignore[assignment]
    "Gradient.Direction : Direction of the final gradient."

    launch_delay: int = ArgField(
        cmd_name="--launch-delay",
        type_parser=argvalidators.NonNegativeInt.type_parser,
        default=60,
        metavar=argvalidators.NonNegativeInt.METAVAR,
        help="Number of frames to wait between launching each firework shell. +/- 0-50 percent randomness is applied to this value.",
    )  # type: ignore[assignment]
    "int : Number of frames to wait between launching each firework shell. +/- 0-50 percent randomness is applied to this value."

    explode_distance: float = ArgField(
        cmd_name="--explode-distance",
        default=0.1,
        type_parser=argvalidators.Ratio.type_parser,
        metavar=argvalidators.Ratio.METAVAR,
        help="Maximum distance from the firework shell origin to the explode waypoint as a percentage of the total canvas width.",
    )  # type: ignore[assignment]
    "float : Maximum distance from the firework shell origin to the explode waypoint as a percentage of the total canvas width."

    @classmethod
    def get_effect_class(cls):
        return Fireworks

explode_anywhere: bool = ArgField(cmd_name='--explode-anywhere', action='store_true', default=False, help='If set, fireworks explode anywhere in the canvas. Otherwise, fireworks explode above highest settled row of text.') class-attribute instance-attribute

bool : If set, fireworks explode anywhere in the canvas. Otherwise, fireworks explode above highest settled row of text.

explode_distance: float = ArgField(cmd_name='--explode-distance', default=0.1, type_parser=argvalidators.Ratio.type_parser, metavar=argvalidators.Ratio.METAVAR, help='Maximum distance from the firework shell origin to the explode waypoint as a percentage of the total canvas width.') class-attribute instance-attribute

float : Maximum distance from the firework shell origin to the explode waypoint as a percentage of the total canvas width.

final_gradient_direction: Gradient.Direction = ArgField(cmd_name='--final-gradient-direction', type_parser=argvalidators.GradientDirection.type_parser, default=Gradient.Direction.HORIZONTAL, metavar=argvalidators.GradientDirection.METAVAR, help='Direction of the final gradient.') class-attribute instance-attribute

Gradient.Direction : Direction of the final gradient.

final_gradient_steps: tuple[int, ...] | int = ArgField(cmd_name='--final-gradient-steps', type_parser=argvalidators.PositiveInt.type_parser, nargs='+', default=12, metavar=argvalidators.PositiveInt.METAVAR, help='Space separated, unquoted, list of the number of gradient steps to use. More steps will create a smoother and longer gradient animation.') class-attribute instance-attribute

tuple[int, ...] | int : Int or Tuple of ints for the number of gradient steps to use. More steps will create a smoother and longer gradient animation.

final_gradient_stops: tuple[Color, ...] = ArgField(cmd_name='--final-gradient-stops', type_parser=argvalidators.ColorArg.type_parser, nargs='+', default=(Color('8A008A'), Color('00D1FF'), Color('FFFFFF')), metavar=argvalidators.ColorArg.METAVAR, help='Space separated, unquoted, list of colors for the character gradient (applied from bottom to top). If only one color is provided, the characters will be displayed in that color.') class-attribute instance-attribute

tuple[Color, ...] : Tuple of colors for the final color gradient. If only one color is provided, the characters will be displayed in that color.

firework_colors: tuple[Color, ...] = ArgField(cmd_name='--firework-colors', type_parser=argvalidators.ColorArg.type_parser, nargs='+', default=(Color('88F7E2'), Color('44D492'), Color('F5EB67'), Color('FFA15C'), Color('FA233E')), metavar=argvalidators.ColorArg.METAVAR, help='Space separated list of colors from which firework colors will be randomly selected.') class-attribute instance-attribute

tuple[Color, ...] : Tuple of colors from which firework colors will be randomly selected.

firework_symbol: str = ArgField(cmd_name='--firework-symbol', type_parser=argvalidators.Symbol.type_parser, default='o', metavar=argvalidators.Symbol.METAVAR, help='Symbol to use for the firework shell.') class-attribute instance-attribute

str : Symbol to use for the firework shell.

firework_volume: float = ArgField(cmd_name='--firework-volume', type_parser=argvalidators.Ratio.type_parser, default=0.02, metavar=argvalidators.Ratio.METAVAR, help='Percent of total characters in each firework shell.') class-attribute instance-attribute

float : Percent of total characters in each firework shell.

launch_delay: int = ArgField(cmd_name='--launch-delay', type_parser=argvalidators.NonNegativeInt.type_parser, default=60, metavar=argvalidators.NonNegativeInt.METAVAR, help='Number of frames to wait between launching each firework shell. +/- 0-50 percent randomness is applied to this value.') class-attribute instance-attribute

int : Number of frames to wait between launching each firework shell. +/- 0-50 percent randomness is applied to this value.