Skip to content

Rings

Demo

Quick Start

rings.py
from terminaltexteffects.effects.effect_rings import Rings

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

Characters are dispersed and form into spinning rings.

Classes:

Name Description
Rings

Characters are dispersed and form into spinning rings.
RingsConfig

Configuration for the Rings effect.
RingsIterator

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

Rings

Bases: BaseEffect[RingsConfig]

Characters are dispersed and form into spinning rings.

Attributes:

Name Type Description
effect_config RingsConfig

Configuration for the effect.
terminal_config TerminalConfig

Configuration for the terminal.
Source code in terminaltexteffects/effects/effect_rings.py 
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
class Rings(BaseEffect[RingsConfig]):
    """Characters are dispersed and form into spinning rings.

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

    _config_cls = RingsConfig
    _iterator_cls = RingsIterator

    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_rings.py 
391
392
393
394
395
396
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)

RingsConfig dataclass

Bases: ArgsDataClass

Configurations for the RingsEffect.

Attributes:

Name Type Description
ring_colors tuple[Color, ...]

Tuple of colors for the rings.
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

Number of gradient steps to use. More steps will create a smoother and longer gradient animation.
final_gradient_direction Direction

Direction of the final gradient.
ring_gap float

Distance between rings as a percent of the smallest canvas dimension. Valid values are 0 < n <= 1.
spin_duration int

Number of frames for each cycle of the spin phase. Valid values are n >= 0.
spin_speed tuple[float, float]

Range of speeds for the rotation of the rings. The speed is randomly selected from this range for each ring. Valid values are n > 0.
disperse_duration int

Number of frames spent in the dispersed state between spinning cycles. Valid values are n >= 0.
spin_disperse_cycles int

Number of times the animation will cycle between spinning rings and dispersed characters. Valid values are n > 0.
Source code in terminaltexteffects/effects/effect_rings.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
@argclass(
    name="rings",
    help="Characters are dispersed and form into spinning rings.",
    description="rings | Characters are dispersed and form into spinning rings.",
    epilog="""Example: terminaltexteffects rings --ring-colors ab48ff e7b2b2 fffebd --final-gradient-stops ab48ff e7b2b2 fffebd --final-gradient-steps 12 --ring-gap 0.1 --spin-duration 200 --spin-speed 0.25-1.0 --disperse-duration 200 --spin-disperse-cycles 3""",
)
@dataclass
class RingsConfig(ArgsDataClass):
    """Configurations for the RingsEffect.

    Attributes:
        ring_colors (tuple[Color, ...]): Tuple of colors for the rings.
        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): Number of gradient steps to use. More steps will create a smoother and longer gradient animation.
        final_gradient_direction (Gradient.Direction): Direction of the final gradient.
        ring_gap (float): Distance between rings as a percent of the smallest canvas dimension. Valid values are 0 < n <= 1.
        spin_duration (int): Number of frames for each cycle of the spin phase. Valid values are n >= 0.
        spin_speed (tuple[float, float]): Range of speeds for the rotation of the rings. The speed is randomly selected from this range for each ring. Valid values are n > 0.
        disperse_duration (int): Number of frames spent in the dispersed state between spinning cycles. Valid values are n >= 0.
        spin_disperse_cycles (int): Number of times the animation will cycle between spinning rings and dispersed characters. Valid values are n > 0.
    """

    ring_colors: tuple[Color, ...] = ArgField(
        cmd_name=["--ring-colors"],
        type_parser=argvalidators.ColorArg.type_parser,
        nargs="+",
        default=(Color("ab48ff"), Color("e7b2b2"), Color("fffebd")),
        metavar=argvalidators.ColorArg.METAVAR,
        help="Space separated, unquoted, list of colors for the rings.",
    )  # type: ignore[assignment]

    "tuple[Color] : Tuple of colors for the rings."

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

    "Gradient.Direction : Direction of the final gradient."

    ring_gap: float = ArgField(
        cmd_name=["--ring-gap"],
        type_parser=argvalidators.PositiveFloat.type_parser,
        default=0.1,
        help="Distance between rings as a percent of the smallest canvas dimension.",
    )  # type: ignore[assignment]

    "float : Distance between rings as a percent of the smallest canvas dimension."
    spin_duration: int = ArgField(
        cmd_name=["--spin-duration"],
        type_parser=argvalidators.PositiveInt.type_parser,
        default=200,
        help="Number of frames for each cycle of the spin phase.",
    )  # type: ignore[assignment]

    "int : Number of frames for each cycle of the spin phase."

    spin_speed: tuple[float, float] = ArgField(
        cmd_name=["--spin-speed"],
        type_parser=argvalidators.PositiveFloatRange.type_parser,
        default=(0.25, 1.0),
        metavar=argvalidators.PositiveFloatRange.METAVAR,
        help="Range of speeds for the rotation of the rings. The speed is randomly selected from this range for each ring.",
    )  # type: ignore[assignment]

    "tuple[float, float] : Range of speeds for the rotation of the rings. The speed is randomly selected from this range for each ring."

    disperse_duration: int = ArgField(
        cmd_name=["--disperse-duration"],
        type_parser=argvalidators.PositiveInt.type_parser,
        default=200,
        help="Number of frames spent in the dispersed state between spinning cycles.",
    )  # type: ignore[assignment]

    "int : Number of frames spent in the dispersed state between spinning cycles."

    spin_disperse_cycles: int = ArgField(
        cmd_name=["--spin-disperse-cycles"],
        type_parser=argvalidators.PositiveInt.type_parser,
        default=3,
        help="Number of times the animation will cycles between spinning rings and dispersed characters.",
    )  # type: ignore[assignment]

    "int : Number of times the animation will cycles between spinning rings and dispersed characters."

    @classmethod
    def get_effect_class(cls):
        return Rings

disperse_duration: int = ArgField(cmd_name=['--disperse-duration'], type_parser=argvalidators.PositiveInt.type_parser, default=200, help='Number of frames spent in the dispersed state between spinning cycles.') class-attribute instance-attribute

int : Number of frames spent in the dispersed state between spinning cycles.

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_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 : 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('ab48ff'), Color('e7b2b2'), Color('fffebd')), 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.

ring_colors: tuple[Color, ...] = ArgField(cmd_name=['--ring-colors'], type_parser=argvalidators.ColorArg.type_parser, nargs='+', default=(Color('ab48ff'), Color('e7b2b2'), Color('fffebd')), metavar=argvalidators.ColorArg.METAVAR, help='Space separated, unquoted, list of colors for the rings.') class-attribute instance-attribute

tuple[Color] : Tuple of colors for the rings.

ring_gap: float = ArgField(cmd_name=['--ring-gap'], type_parser=argvalidators.PositiveFloat.type_parser, default=0.1, help='Distance between rings as a percent of the smallest canvas dimension.') class-attribute instance-attribute

float : Distance between rings as a percent of the smallest canvas dimension.

spin_disperse_cycles: int = ArgField(cmd_name=['--spin-disperse-cycles'], type_parser=argvalidators.PositiveInt.type_parser, default=3, help='Number of times the animation will cycles between spinning rings and dispersed characters.') class-attribute instance-attribute

int : Number of times the animation will cycles between spinning rings and dispersed characters.

spin_duration: int = ArgField(cmd_name=['--spin-duration'], type_parser=argvalidators.PositiveInt.type_parser, default=200, help='Number of frames for each cycle of the spin phase.') class-attribute instance-attribute

int : Number of frames for each cycle of the spin phase.

spin_speed: tuple[float, float] = ArgField(cmd_name=['--spin-speed'], type_parser=argvalidators.PositiveFloatRange.type_parser, default=(0.25, 1.0), metavar=argvalidators.PositiveFloatRange.METAVAR, help='Range of speeds for the rotation of the rings. The speed is randomly selected from this range for each ring.') class-attribute instance-attribute

tuple[float, float] : Range of speeds for the rotation of the rings. The speed is randomly selected from this range for each ring.