Skip to content

Pour

Demo

Quick Start

pour.py
from terminaltexteffects.effects.effect_pour import Pour

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

Pours the characters back and forth from the top, bottom, left, or right.

Classes:

Name Description
Pour

Pours the characters back and forth from the top, bottom, left, or right.
PourConfig

Configuration for the Pour effect.
PourIterator

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

Pour

Bases: BaseEffect[PourConfig]

Pours the characters back and forth from the top, bottom, left, or right.

Attributes:

Name Type Description
effect_config PourConfig

Configuration for the effect.
terminal_config TerminalConfig

Configuration for the terminal.
Source code in terminaltexteffects/effects/effect_pour.py 
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
class Pour(BaseEffect[PourConfig]):
    """Pours the characters back and forth from the top, bottom, left, or right.

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

    _config_cls = PourConfig
    _iterator_cls = PourIterator

    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_pour.py 
246
247
248
249
250
251
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)

PourConfig dataclass

Bases: ArgsDataClass

Configuration for the Pour effect.

Attributes:

Name Type Description
pour_direction str

Direction the text will pour. Valid values are "up", "down", "left", and "right".
pour_speed int

Number of characters poured in per tick. Increase to speed up the effect. Valid values are n > 0.
movement_speed float

Movement speed of the characters. Valid values are n > 0.
gap int

Number of frames to wait between each character in the pour effect. Increase to slow down effect and create a more defined back and forth motion. Valid values are n >= 0.
starting_color Color

Color of the characters before the gradient starts.
final_gradient_stops tuple[Color, ...]

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

Number of gradient steps to use. More steps will create a smoother and longer gradient animation.
final_gradient_frames int

Number of frames to display each gradient step. Increase to slow down the gradient animation.
final_gradient_direction Direction

Direction of the final gradient.
easing EasingFunction

Easing function to use for character movement.
Source code in terminaltexteffects/effects/effect_pour.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
@argclass(
    name="pour",
    help="Pours the characters into position from the given direction.",
    description="pour | Pours the characters into position from the given direction.",
    epilog=f"""{argvalidators.EASING_EPILOG}
Example: terminaltexteffects pour --pour-direction down --movement-speed 0.2 --gap 1 --starting-color FFFFFF --final-gradient-stops 8A008A 00D1FF FFFFFF --easing IN_QUAD""",
)
@dataclass
class PourConfig(ArgsDataClass):
    """Configuration for the Pour effect.

    Attributes:
        pour_direction (str): Direction the text will pour. Valid values are "up", "down", "left", and "right".
        pour_speed (int): Number of characters poured in per tick. Increase to speed up the effect. Valid values are n > 0.
        movement_speed (float): Movement speed of the characters. Valid values are n > 0.
        gap (int): Number of frames to wait between each character in the pour effect. Increase to slow down effect and create a more defined back and forth motion. Valid values are n >= 0.
        starting_color (Color): Color of the characters before the gradient starts.
        final_gradient_stops (tuple[Color, ...]): Tuple of colors for the character gradient. If only one color is provided, the characters will be displayed in that color.
        final_gradient_steps (tuple[int, ...] | int): Number of gradient steps to use. More steps will create a smoother and longer gradient animation.
        final_gradient_frames (int): Number of frames to display each gradient step. Increase to slow down the gradient animation.
        final_gradient_direction (Gradient.Direction): Direction of the final gradient.
        easing (easing.EasingFunction): Easing function to use for character movement."""

    pour_direction: typing.Literal["up", "down", "left", "right"] = ArgField(
        cmd_name=["--pour-direction"],
        default="down",
        choices=["up", "down", "left", "right"],
        help="Direction the text will pour.",
    )  # type: ignore[assignment]
    "typing.Literal['up', 'down', 'left', 'right'] : Direction the text will pour."

    pour_speed: int = ArgField(
        cmd_name="--pour-speed",
        type_parser=argvalidators.PositiveInt.type_parser,
        default=1,
        metavar=argvalidators.PositiveInt.METAVAR,
        help="Number of characters poured in per tick. Increase to speed up the effect.",
    )  # type: ignore[assignment]
    "int : Number of characters poured in per tick. Increase to speed up the effect."

    movement_speed: float = ArgField(
        cmd_name="--movement-speed",
        type_parser=argvalidators.PositiveFloat.type_parser,
        default=0.2,
        metavar=argvalidators.PositiveFloat.METAVAR,
        help="Movement speed of the characters. ",
    )  # type: ignore[assignment]
    "float : Movement speed of the characters."

    gap: int = ArgField(
        cmd_name="--gap",
        type_parser=argvalidators.NonNegativeInt.type_parser,
        default=1,
        metavar=argvalidators.NonNegativeInt.METAVAR,
        help="Number of frames to wait between each character in the pour effect. Increase to slow down effect and create a more defined back and forth motion.",
    )  # type: ignore[assignment]
    "int : Number of frames to wait between each character in the pour effect."

    starting_color: Color = ArgField(
        cmd_name=["--starting-color"],
        type_parser=argvalidators.ColorArg.type_parser,
        default=Color("ffffff"),
        metavar=argvalidators.ColorArg.METAVAR,
        help="Color of the characters before the gradient starts.",
    )  # type: ignore[assignment]
    "Color : Color of the characters before the gradient starts."

    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. If only one color is provided, the characters will be displayed in that color.",
    )  # type: ignore[assignment]
    "tuple[Color, ...] : Tuple of colors for the character gradient."

    final_gradient_steps: tuple[int, ...] | int = ArgField(
        cmd_name=["--final-gradient-steps"],
        type_parser=argvalidators.PositiveInt.type_parser,
        default=12,
        metavar=argvalidators.PositiveInt.METAVAR,
        help="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."

    final_gradient_frames: int = ArgField(
        cmd_name=["--final-gradient-frames"],
        type_parser=argvalidators.PositiveInt.type_parser,
        default=10,
        metavar=argvalidators.PositiveInt.METAVAR,
        help="Number of frames to display each gradient step. Increase to slow down the gradient animation.",
    )  # type: ignore[assignment]
    "int : Number of frames to display each gradient step. Increase to slow down the gradient animation."

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

    movement_easing: easing.EasingFunction = ArgField(
        cmd_name="--movement-easing",
        default=easing.in_quad,
        type_parser=argvalidators.Ease.type_parser,
        help="Easing function to use for character movement.",
    )  # type: ignore[assignment]
    "easing.EasingFunction : Easing function to use for character movement."

    @classmethod
    def get_effect_class(cls):
        return Pour

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

Gradient.Direction : Direction of the final gradient.

final_gradient_frames: int = ArgField(cmd_name=['--final-gradient-frames'], type_parser=argvalidators.PositiveInt.type_parser, default=10, metavar=argvalidators.PositiveInt.METAVAR, help='Number of frames to display each gradient step. Increase to slow down the gradient animation.') class-attribute instance-attribute

int : Number of frames to display each gradient step. Increase to slow down the gradient animation.

final_gradient_steps: tuple[int, ...] | int = ArgField(cmd_name=['--final-gradient-steps'], type_parser=argvalidators.PositiveInt.type_parser, default=12, metavar=argvalidators.PositiveInt.METAVAR, help='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.

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. 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 character gradient.

gap: int = ArgField(cmd_name='--gap', type_parser=argvalidators.NonNegativeInt.type_parser, default=1, metavar=argvalidators.NonNegativeInt.METAVAR, help='Number of frames to wait between each character in the pour effect. Increase to slow down effect and create a more defined back and forth motion.') class-attribute instance-attribute

int : Number of frames to wait between each character in the pour effect.

movement_easing: easing.EasingFunction = ArgField(cmd_name='--movement-easing', default=easing.in_quad, type_parser=argvalidators.Ease.type_parser, help='Easing function to use for character movement.') class-attribute instance-attribute

easing.EasingFunction : Easing function to use for character movement.

movement_speed: float = ArgField(cmd_name='--movement-speed', type_parser=argvalidators.PositiveFloat.type_parser, default=0.2, metavar=argvalidators.PositiveFloat.METAVAR, help='Movement speed of the characters. ') class-attribute instance-attribute

float : Movement speed of the characters.

pour_direction: typing.Literal['up', 'down', 'left', 'right'] = ArgField(cmd_name=['--pour-direction'], default='down', choices=['up', 'down', 'left', 'right'], help='Direction the text will pour.') class-attribute instance-attribute

typing.Literal['up', 'down', 'left', 'right'] : Direction the text will pour.

pour_speed: int = ArgField(cmd_name='--pour-speed', type_parser=argvalidators.PositiveInt.type_parser, default=1, metavar=argvalidators.PositiveInt.METAVAR, help='Number of characters poured in per tick. Increase to speed up the effect.') class-attribute instance-attribute

int : Number of characters poured in per tick. Increase to speed up the effect.

starting_color: Color = ArgField(cmd_name=['--starting-color'], type_parser=argvalidators.ColorArg.type_parser, default=Color('ffffff'), metavar=argvalidators.ColorArg.METAVAR, help='Color of the characters before the gradient starts.') class-attribute instance-attribute

Color : Color of the characters before the gradient starts.