Skip to content

Bubbles

Demo

Quick Start

bubbles.py
from terminaltexteffects.effects.effect_bubbles import Bubbles

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

Forms bubbles with the characters. Bubbles float down and pop.

Classes:

Name Description
Bubbles

Forms bubbles with the characters. Bubbles float down and pop.
BubblesConfig

Configuration for the Bubbles effect.
BubblesIterator

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

Bubbles

Bases: BaseEffect[BubblesConfig]

Forms bubbles with the characters. Bubbles float down and pop.

Attributes:

Name Type Description
effect_config BubblesConfig

Configuration for the effect.
terminal_config TerminalConfig

Configuration for the terminal.
Source code in terminaltexteffects/effects/effect_bubbles.py 
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
class Bubbles(BaseEffect[BubblesConfig]):
    """Forms bubbles with the characters. Bubbles float down and pop.

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

    _config_cls = BubblesConfig
    _iterator_cls = BubblesIterator

    def __init__(self, input_data: str) -> None:
        """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_bubbles.py 
353
354
355
356
357
358
def __init__(self, input_data: str) -> None:
    """Initialize the effect with the provided input data.

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

BubblesConfig dataclass

Bases: ArgsDataClass

Configuration for the Bubbles effect.

Attributes:

Name Type Description
rainbow bool

If set, the bubbles will be colored with a rotating rainbow gradient.
bubble_colors tuple[Color, ...]

Tuple of colors for the bubbles. Ignored if --no-rainbow is left as default False.
pop_color Color

Color for the spray emitted when a bubble pops.
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.
bubble_speed float

Speed of the floating bubbles. Valid values are n > 0.
bubble_delay int

Number of frames between bubbles. Valid values are n >= 0.
pop_condition Literal['row', 'bottom', 'anywhere']

Condition for a bubble to pop. 'row' will pop the bubble when it reaches the the lowest row for which a character in the bubble originates. 'bottom' will pop the bubble at the bottom row of the terminal. 'anywhere' will pop the bubble randomly, or at the bottom of the terminal.
easing EasingFunction

Easing function to use for character movement after a bubble pops.
Source code in terminaltexteffects/effects/effect_bubbles.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
 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
@argclass(
    name="bubbles",
    help="Characters are formed into bubbles that float down and pop.",
    description="bubbles | Characters are formed into bubbles that float down and pop.",
    epilog=f"""{argvalidators.EASING_EPILOG}

Example: terminaltexteffects bubbles --bubble-colors d33aff 7395c4 43c2a7 02ff7f --pop-color ffffff --final-gradient-stops d33aff 02ff7f --final-gradient-steps 12 --final-gradient-direction diagonal --bubble-speed 0.1 --bubble-delay 50 --pop-condition row --easing IN_OUT_SINE""",
)
@dataclass
class BubblesConfig(ArgsDataClass):
    """Configuration for the Bubbles effect.

    Attributes:
        rainbow (bool): If set, the bubbles will be colored with a rotating rainbow gradient.
        bubble_colors (tuple[Color, ...]): Tuple of colors for the bubbles. Ignored if --no-rainbow is left as default False.
        pop_color (Color): Color for the spray emitted when a bubble pops.
        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.
        bubble_speed (float): Speed of the floating bubbles. Valid values are n > 0.
        bubble_delay (int): Number of frames between bubbles. Valid values are n >= 0.
        pop_condition (typing.Literal["row", "bottom", "anywhere"]): Condition for a bubble to pop. 'row' will pop the bubble when it reaches the the lowest row for which a character in the bubble originates. 'bottom' will pop the bubble at the bottom row of the terminal. 'anywhere' will pop the bubble randomly, or at the bottom of the terminal.
        easing (easing.EasingFunction): Easing function to use for character movement after a bubble pops.
    """

    rainbow: bool = ArgField(
        cmd_name="--rainbow",
        action="store_true",
        default=False,
        help="If set, the bubbles will be colored with a rotating rainbow gradient.",
    )  # type: ignore[assignment]
    "bool : If set, the bubbles will be colored with a rotating rainbow gradient."

    bubble_colors: tuple[Color, ...] = ArgField(
        cmd_name="--bubble-colors",
        type_parser=argvalidators.ColorArg.type_parser,
        nargs="+",
        default=(Color("d33aff"), Color("7395c4"), Color("43c2a7"), Color("02ff7f")),
        metavar=argvalidators.ColorArg.METAVAR,
        help="Space separated, unquoted, list of colors for the bubbles. Ignored if --no-rainbow is left as default False.",
    )  # type: ignore[assignment]
    "tuple[Color, ...] : Tuple of colors for the bubbles. Ignored if --no-rainbow is left as default False."

    pop_color: Color = ArgField(
        cmd_name="--pop-color",
        type_parser=argvalidators.ColorArg.type_parser,
        default=Color("ffffff"),
        metavar=argvalidators.ColorArg.METAVAR,
        help="Color for the spray emitted when a bubble pops.",
    )  # type: ignore[assignment]
    "Color : Color for the spray emitted when a bubble pops."

    final_gradient_stops: tuple[Color, ...] = ArgField(
        cmd_name=["--final-gradient-stops"],
        type_parser=argvalidators.ColorArg.type_parser,
        nargs="+",
        default=(Color("d33aff"), Color("02ff7f")),
        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.DIAGONAL,
        metavar=argvalidators.GradientDirection.METAVAR,
        help="Direction of the final gradient.",
    )  # type: ignore[assignment]
    "Gradient.Direction : Direction of the final gradient."

    bubble_speed: float = ArgField(
        cmd_name="--bubble-speed",
        type_parser=argvalidators.PositiveFloat.type_parser,
        default=0.1,
        metavar=argvalidators.PositiveFloat.METAVAR,
        help="Speed of the floating bubbles. ",
    )  # type: ignore[assignment]
    "float : Speed of the floating bubbles. "

    bubble_delay: int = ArgField(
        cmd_name="--bubble-delay",
        type_parser=argvalidators.PositiveInt.type_parser,
        default=50,
        metavar=argvalidators.PositiveInt.METAVAR,
        help="Number of frames between bubbles.",
    )  # type: ignore[assignment]
    "int : Number of frames between bubbles."

    pop_condition: typing.Literal["row", "bottom", "anywhere"] = ArgField(
        cmd_name="--pop-condition",
        default="row",
        choices=["row", "bottom", "anywhere"],
        help="Condition for a bubble to pop. 'row' will pop the bubble when it reaches the the lowest row for which a character in the bubble originates. 'bottom' will pop the bubble at the bottom row of the terminal. 'anywhere' will pop the bubble randomly, or at the bottom of the terminal.",
    )  # type: ignore[assignment]
    "typing.Literal['row', 'bottom', 'anywhere'] : Condition for a bubble to pop. 'row' will pop the bubble when it reaches the the lowest row for which a character in the bubble originates. 'bottom' will pop the bubble at the bottom row of the terminal. 'anywhere' will pop the bubble randomly, or at the bottom of the terminal."

    movement_easing: easing.EasingFunction = ArgField(
        cmd_name=["--movement-easing"],
        default=easing.in_out_sine,
        type_parser=argvalidators.Ease.type_parser,
        metavar=argvalidators.Ease.METAVAR,
        help="Easing function to use for character movement after a bubble pops.",
    )  # type: ignore[assignment]
    "easing.EasingFunction : Easing function to use for character movement after a bubble pops."

    @classmethod
    def get_effect_class(cls):
        return Bubbles

bubble_colors: tuple[Color, ...] = ArgField(cmd_name='--bubble-colors', type_parser=argvalidators.ColorArg.type_parser, nargs='+', default=(Color('d33aff'), Color('7395c4'), Color('43c2a7'), Color('02ff7f')), metavar=argvalidators.ColorArg.METAVAR, help='Space separated, unquoted, list of colors for the bubbles. Ignored if --no-rainbow is left as default False.') class-attribute instance-attribute

tuple[Color, ...] : Tuple of colors for the bubbles. Ignored if --no-rainbow is left as default False.

bubble_delay: int = ArgField(cmd_name='--bubble-delay', type_parser=argvalidators.PositiveInt.type_parser, default=50, metavar=argvalidators.PositiveInt.METAVAR, help='Number of frames between bubbles.') class-attribute instance-attribute

int : Number of frames between bubbles.

bubble_speed: float = ArgField(cmd_name='--bubble-speed', type_parser=argvalidators.PositiveFloat.type_parser, default=0.1, metavar=argvalidators.PositiveFloat.METAVAR, help='Speed of the floating bubbles. ') class-attribute instance-attribute

float : Speed of the floating bubbles.

final_gradient_direction: Gradient.Direction = ArgField(cmd_name='--final-gradient-direction', type_parser=argvalidators.GradientDirection.type_parser, default=Gradient.Direction.DIAGONAL, 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('d33aff'), Color('02ff7f')), 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.

movement_easing: easing.EasingFunction = ArgField(cmd_name=['--movement-easing'], default=easing.in_out_sine, type_parser=argvalidators.Ease.type_parser, metavar=argvalidators.Ease.METAVAR, help='Easing function to use for character movement after a bubble pops.') class-attribute instance-attribute

easing.EasingFunction : Easing function to use for character movement after a bubble pops.

pop_color: Color = ArgField(cmd_name='--pop-color', type_parser=argvalidators.ColorArg.type_parser, default=Color('ffffff'), metavar=argvalidators.ColorArg.METAVAR, help='Color for the spray emitted when a bubble pops.') class-attribute instance-attribute

Color : Color for the spray emitted when a bubble pops.

pop_condition: typing.Literal['row', 'bottom', 'anywhere'] = ArgField(cmd_name='--pop-condition', default='row', choices=['row', 'bottom', 'anywhere'], help="Condition for a bubble to pop. 'row' will pop the bubble when it reaches the the lowest row for which a character in the bubble originates. 'bottom' will pop the bubble at the bottom row of the terminal. 'anywhere' will pop the bubble randomly, or at the bottom of the terminal.") class-attribute instance-attribute

typing.Literal['row', 'bottom', 'anywhere'] : Condition for a bubble to pop. 'row' will pop the bubble when it reaches the the lowest row for which a character in the bubble originates. 'bottom' will pop the bubble at the bottom row of the terminal. 'anywhere' will pop the bubble randomly, or at the bottom of the terminal.

rainbow: bool = ArgField(cmd_name='--rainbow', action='store_true', default=False, help='If set, the bubbles will be colored with a rotating rainbow gradient.') class-attribute instance-attribute

bool : If set, the bubbles will be colored with a rotating rainbow gradient.