Skip to content

Text

Bases: Text

A rich text class that supports gradient colors and styles.

Source code in src/rich_gradient/text.py 
 22
 23
 24
 25
 26
 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
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
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
class Text(RichText):
    """A rich text class that supports gradient colors and styles."""

    def __init__(
        self,
        text: TextType = "",
        colors: Optional[Sequence[ColorType]] = None,
        *,
        rainbow: bool = False,
        hues: int = 5,
        style: StyleType = "",
        justify: JustifyMethod = "default",
        overflow: OverflowMethod = "fold",
        no_wrap: bool = False,
        end: str = "\n",
        tab_size: int = 4,
        bgcolors: Optional[Sequence[ColorType]] = None,
        markup: bool = True,
        spans: Optional[Sequence[Span]] = None,
    ):
        """Initialize the Text with gradient colors and styles.
        Args:
            text (TextType): The text content.
            colors (Optional[List[ColorType]]): A list of colors as Color instances or strings.
            rainbow (bool): If True, generate a rainbow spectrum.
            hues (int): The number of hues to generate if colors are not provided.
            style (StyleType): The style of the text.
            justify (JustifyMethod): Justification method for the text.
            overflow (OverflowMethod): Overflow method for the text.
            no_wrap (bool): If True, disable wrapping of the text.
            end (str): The string to append at the end of the text. Default is a newline.
            tab_size (int): The number of spaces for a tab character.
            bgcolors (Optional[List[ColorType]]): A list of background colors as Color instances
            markup (bool): If True, parse Rich markup tags in the input text.
            spans (Optional[Sequence[Span]]): A list of spans to apply to the text.
        """
        if markup:
            parsed_text = RichText.from_markup(
                text=str(text), style=style, justify=justify, overflow=overflow
            )
        else:
            parsed_text = RichText(
                strip_control_codes(str(text)),
                style=style,
                justify=justify,
                overflow=overflow,
            )
        plain = parsed_text.plain
        parsed_justify = parsed_text.justify
        parsed_overflow = parsed_text.overflow
        parsed_spans = parsed_text._spans

        super().__init__(
            plain,
            style=style,
            justify=parsed_justify,
            overflow=parsed_overflow,
            no_wrap=no_wrap,
            end=end,
            tab_size=tab_size,
            spans=parsed_spans,
        )
        self.colors = self.parse_colors(colors, hues, rainbow)
        self.bgcolors = self.parse_bgcolors(bgcolors, hues)

        # Handle the single-color and single-background case: apply style directly and return early
        if len(self.colors) == 1 and len(self.bgcolors) == 1:
            # Apply the single color style directly
            style_with_color = Style(
                color=self.colors[0], bgcolor=self.bgcolors[0]
            ) + Style.parse(style)
            for index in range(len(self.plain)):
                self.stylize(style_with_color, index, index + 1)
            return

        # Apply the gradient coloring
        self.apply_gradient()

    @property
    def colors(self) -> list[Color]:
        """Return the list of colors in the gradient."""
        return list(self._colors) if self._colors else []

    @colors.setter
    def colors(self, value: Optional[Sequence[Color]]) -> None:
        """Set the list of colors in the gradient."""
        self._colors = list(value) if value else []

    @property
    def bgcolors(self) -> list[Color]:
        """Return the list of background colors in the gradient."""
        return list(self._bgcolors) if self._bgcolors else []

    @bgcolors.setter
    def bgcolors(self, value: Optional[Sequence[Color]]) -> None:
        """Set the list of background colors in the gradient."""
        self._bgcolors = list(value) if value else []

    @staticmethod
    def parse_colors(
        colors: Optional[Sequence[ColorType]] = None,
        hues: int = 5,
        rainbow: bool = False,
    ) -> List[Color]:
        """Parse and return a list of colors for the gradient.
        Supports 3-digit hex colors (e.g., '#f00', '#F90'), 6-digit hex, CSS names, and Color objects.
        Args:
            colors (Optional[Sequence[ColorType | Color]]): A list of colors as Color instances or strings.
            hues (int): The number of hues to generate if colors are not provided.
            rainbow (bool): If True, generate a rainbow spectrum.
        Returns:
            List[Color]: A list of Color objects.
        """
        if rainbow:
            return Spectrum(hues=18).colors
        if colors is None or len(colors) == 0:
            return Spectrum(hues).colors
        # Support 3-digit hex colors and all string representations via Color.parse
        return [c if isinstance(c, Color) else Color.parse(c) for c in colors]

    def parse_bgcolors(
        self, bgcolors: Optional[Sequence[ColorType]] = None, hues: int = 5
    ) -> List[Color]:
        """Parse and return a list of background colors for the gradient.
        Supports 3-digit hex colors (e.g., '#f00', '#F90'), 6-digit hex, CSS names, and Color objects.
        Args:
            bgcolors (Optional[Sequence[ColorType | Color]]): A list of background colors as Color instances or strings.
            hues (int): The number of hues to generate if bgcolors are not provided.
        Returns:
            List[Color]: A list of Color objects for background colors.
        """
        if bgcolors is None or len(bgcolors) == 0:
            self._interpolate_bgcolors = False
            return [Color.parse("default")] * len(self.colors)

        if len(bgcolors) == 1:
            # If only one background color is provided, repeat it for each character
            self._interpolate_bgcolors = False
            return [Color.parse(bgcolors[0])] * len(self.colors)
        # Support 3-digit hex colors and all string representations via Color.parse
        self._interpolate_bgcolors = True
        return [c if isinstance(c, Color) else Color.parse(c) for c in bgcolors]

    def interpolate_colors(
        self, colors: Optional[Sequence[Color]] = None
    ) -> list[Color]:
        """Interpolate colors in the gradient."""
        colors = list(colors) if colors is not None else self.colors
        if not colors:
            raise ValueError("No colors to interpolate")
        # Prepare the text and handle edge cases

        text = self.plain
        length = len(text)
        if length == 0:
            return []
        num_colors = len(colors)
        if num_colors == 1:
            return [colors[0]] * length

        # Compute number of segments between colors
        segments = num_colors - 1
        result: List[Color] = []

        # For each character, determine its position and blend accordingly
        for i in range(length):
            # Normalized position along the entire text
            pos = i / (length - 1) if length > 1 else 0.0
            # Determine which two colors to blend between
            float_index = pos * segments
            index = int(float_index)
            # Clamp to valid segment range
            if index >= segments:
                index = segments - 1
                t = 1.0
            else:
                t = float_index - index

            start = colors[index]
            end = colors[index + 1]
            triplet1 = start.get_truecolor()
            triplet2 = end.get_truecolor()

            # Interpolate each RGB component
            r = int(triplet1.red + (triplet2.red - triplet1.red) * t)
            g = int(triplet1.green + (triplet2.green - triplet1.green) * t)
            b = int(triplet1.blue + (triplet2.blue - triplet1.blue) * t)

            result.append(Color.from_rgb(r, g, b))

        return result

    def apply_gradient(self) -> None:
        """Apply interpolated colors as spans to each character in the text."""
        # Generate a color for each character
        colors = self.interpolate_colors(self.colors)
        if self._interpolate_bgcolors:
            # Generate a background color for each character if bgcolors are interpolated
            bgcolors = self.interpolate_colors(self.bgcolors)
        else:
            # If not interpolating background colors, use the first bgcolor for all characters
            bgcolors = [self.bgcolors[0]] * len(colors)
        # Apply a style span for each character with its corresponding color
        for index, (color, bgcolor) in enumerate(zip(colors, bgcolors)):
            # Build a style with the interpolated color
            span_style = Style(color=color, bgcolor=bgcolor)
            # Stylize the single character range
            self.stylize(span_style, index, index + 1)

bgcolors property writable

Return the list of background colors in the gradient.

colors property writable

Return the list of colors in the gradient.

__init__(text='', colors=None, *, rainbow=False, hues=5, style='', justify='default', overflow='fold', no_wrap=False, end='\n', tab_size=4, bgcolors=None, markup=True, spans=None)

Initialize the Text with gradient colors and styles. Args: text (TextType): The text content. colors (Optional[List[ColorType]]): A list of colors as Color instances or strings. rainbow (bool): If True, generate a rainbow spectrum. hues (int): The number of hues to generate if colors are not provided. style (StyleType): The style of the text. justify (JustifyMethod): Justification method for the text. overflow (OverflowMethod): Overflow method for the text. no_wrap (bool): If True, disable wrapping of the text. end (str): The string to append at the end of the text. Default is a newline. tab_size (int): The number of spaces for a tab character. bgcolors (Optional[List[ColorType]]): A list of background colors as Color instances markup (bool): If True, parse Rich markup tags in the input text. spans (Optional[Sequence[Span]]): A list of spans to apply to the text.

Source code in src/rich_gradient/text.py 
25
26
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
def __init__(
    self,
    text: TextType = "",
    colors: Optional[Sequence[ColorType]] = None,
    *,
    rainbow: bool = False,
    hues: int = 5,
    style: StyleType = "",
    justify: JustifyMethod = "default",
    overflow: OverflowMethod = "fold",
    no_wrap: bool = False,
    end: str = "\n",
    tab_size: int = 4,
    bgcolors: Optional[Sequence[ColorType]] = None,
    markup: bool = True,
    spans: Optional[Sequence[Span]] = None,
):
    """Initialize the Text with gradient colors and styles.
    Args:
        text (TextType): The text content.
        colors (Optional[List[ColorType]]): A list of colors as Color instances or strings.
        rainbow (bool): If True, generate a rainbow spectrum.
        hues (int): The number of hues to generate if colors are not provided.
        style (StyleType): The style of the text.
        justify (JustifyMethod): Justification method for the text.
        overflow (OverflowMethod): Overflow method for the text.
        no_wrap (bool): If True, disable wrapping of the text.
        end (str): The string to append at the end of the text. Default is a newline.
        tab_size (int): The number of spaces for a tab character.
        bgcolors (Optional[List[ColorType]]): A list of background colors as Color instances
        markup (bool): If True, parse Rich markup tags in the input text.
        spans (Optional[Sequence[Span]]): A list of spans to apply to the text.
    """
    if markup:
        parsed_text = RichText.from_markup(
            text=str(text), style=style, justify=justify, overflow=overflow
        )
    else:
        parsed_text = RichText(
            strip_control_codes(str(text)),
            style=style,
            justify=justify,
            overflow=overflow,
        )
    plain = parsed_text.plain
    parsed_justify = parsed_text.justify
    parsed_overflow = parsed_text.overflow
    parsed_spans = parsed_text._spans

    super().__init__(
        plain,
        style=style,
        justify=parsed_justify,
        overflow=parsed_overflow,
        no_wrap=no_wrap,
        end=end,
        tab_size=tab_size,
        spans=parsed_spans,
    )
    self.colors = self.parse_colors(colors, hues, rainbow)
    self.bgcolors = self.parse_bgcolors(bgcolors, hues)

    # Handle the single-color and single-background case: apply style directly and return early
    if len(self.colors) == 1 and len(self.bgcolors) == 1:
        # Apply the single color style directly
        style_with_color = Style(
            color=self.colors[0], bgcolor=self.bgcolors[0]
        ) + Style.parse(style)
        for index in range(len(self.plain)):
            self.stylize(style_with_color, index, index + 1)
        return

    # Apply the gradient coloring
    self.apply_gradient()

apply_gradient()

Apply interpolated colors as spans to each character in the text.

Source code in src/rich_gradient/text.py 
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
def apply_gradient(self) -> None:
    """Apply interpolated colors as spans to each character in the text."""
    # Generate a color for each character
    colors = self.interpolate_colors(self.colors)
    if self._interpolate_bgcolors:
        # Generate a background color for each character if bgcolors are interpolated
        bgcolors = self.interpolate_colors(self.bgcolors)
    else:
        # If not interpolating background colors, use the first bgcolor for all characters
        bgcolors = [self.bgcolors[0]] * len(colors)
    # Apply a style span for each character with its corresponding color
    for index, (color, bgcolor) in enumerate(zip(colors, bgcolors)):
        # Build a style with the interpolated color
        span_style = Style(color=color, bgcolor=bgcolor)
        # Stylize the single character range
        self.stylize(span_style, index, index + 1)

interpolate_colors(colors=None)

Interpolate colors in the gradient.

Source code in src/rich_gradient/text.py 
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
207
208
209
210
211
212
def interpolate_colors(
    self, colors: Optional[Sequence[Color]] = None
) -> list[Color]:
    """Interpolate colors in the gradient."""
    colors = list(colors) if colors is not None else self.colors
    if not colors:
        raise ValueError("No colors to interpolate")
    # Prepare the text and handle edge cases

    text = self.plain
    length = len(text)
    if length == 0:
        return []
    num_colors = len(colors)
    if num_colors == 1:
        return [colors[0]] * length

    # Compute number of segments between colors
    segments = num_colors - 1
    result: List[Color] = []

    # For each character, determine its position and blend accordingly
    for i in range(length):
        # Normalized position along the entire text
        pos = i / (length - 1) if length > 1 else 0.0
        # Determine which two colors to blend between
        float_index = pos * segments
        index = int(float_index)
        # Clamp to valid segment range
        if index >= segments:
            index = segments - 1
            t = 1.0
        else:
            t = float_index - index

        start = colors[index]
        end = colors[index + 1]
        triplet1 = start.get_truecolor()
        triplet2 = end.get_truecolor()

        # Interpolate each RGB component
        r = int(triplet1.red + (triplet2.red - triplet1.red) * t)
        g = int(triplet1.green + (triplet2.green - triplet1.green) * t)
        b = int(triplet1.blue + (triplet2.blue - triplet1.blue) * t)

        result.append(Color.from_rgb(r, g, b))

    return result

parse_bgcolors(bgcolors=None, hues=5)

Parse and return a list of background colors for the gradient. Supports 3-digit hex colors (e.g., '#f00', '#F90'), 6-digit hex, CSS names, and Color objects. Args: bgcolors (Optional[Sequence[ColorType | Color]]): A list of background colors as Color instances or strings. hues (int): The number of hues to generate if bgcolors are not provided. Returns: List[Color]: A list of Color objects for background colors.

Source code in src/rich_gradient/text.py 
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
def parse_bgcolors(
    self, bgcolors: Optional[Sequence[ColorType]] = None, hues: int = 5
) -> List[Color]:
    """Parse and return a list of background colors for the gradient.
    Supports 3-digit hex colors (e.g., '#f00', '#F90'), 6-digit hex, CSS names, and Color objects.
    Args:
        bgcolors (Optional[Sequence[ColorType | Color]]): A list of background colors as Color instances or strings.
        hues (int): The number of hues to generate if bgcolors are not provided.
    Returns:
        List[Color]: A list of Color objects for background colors.
    """
    if bgcolors is None or len(bgcolors) == 0:
        self._interpolate_bgcolors = False
        return [Color.parse("default")] * len(self.colors)

    if len(bgcolors) == 1:
        # If only one background color is provided, repeat it for each character
        self._interpolate_bgcolors = False
        return [Color.parse(bgcolors[0])] * len(self.colors)
    # Support 3-digit hex colors and all string representations via Color.parse
    self._interpolate_bgcolors = True
    return [c if isinstance(c, Color) else Color.parse(c) for c in bgcolors]

parse_colors(colors=None, hues=5, rainbow=False) staticmethod

Parse and return a list of colors for the gradient. Supports 3-digit hex colors (e.g., '#f00', '#F90'), 6-digit hex, CSS names, and Color objects. Args: colors (Optional[Sequence[ColorType | Color]]): A list of colors as Color instances or strings. hues (int): The number of hues to generate if colors are not provided. rainbow (bool): If True, generate a rainbow spectrum. Returns: List[Color]: A list of Color objects.

Source code in src/rich_gradient/text.py 
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
@staticmethod
def parse_colors(
    colors: Optional[Sequence[ColorType]] = None,
    hues: int = 5,
    rainbow: bool = False,
) -> List[Color]:
    """Parse and return a list of colors for the gradient.
    Supports 3-digit hex colors (e.g., '#f00', '#F90'), 6-digit hex, CSS names, and Color objects.
    Args:
        colors (Optional[Sequence[ColorType | Color]]): A list of colors as Color instances or strings.
        hues (int): The number of hues to generate if colors are not provided.
        rainbow (bool): If True, generate a rainbow spectrum.
    Returns:
        List[Color]: A list of Color objects.
    """
    if rainbow:
        return Spectrum(hues=18).colors
    if colors is None or len(colors) == 0:
        return Spectrum(hues).colors
    # Support 3-digit hex colors and all string representations via Color.parse
    return [c if isinstance(c, Color) else Color.parse(c) for c in colors]