Skip to content

Color

Module: terminaltexteffects.utils.graphics

Basic Usage

Color objects are used to represent colors throughout TTE. However, they can be instantiated and printed directly.

Supports Multiple Specification Formats

from terminaltexteffects.utils.graphics import Color

red = Color('ff0000')
xterm_red = Color(9)
rgb_red_again = Color('#ff0000')

Printing Colors

Colors can be printed to show the code and resulting color appearance.

from terminaltexteffects.utils.graphics import Color

red = Color("#ff0000")
print(red)

t

Using Colors to build a Gradient

from terminaltexteffects.utils.graphics import Gradient, Color

rgb = Gradient(Color("#ff0000"), Color("#00ff00"), Color("#0000ff"), steps=5)
for color in rgb:
    # color is a hex string
    ...

Passing Colors to effect configurations

text = ("EXAMPLE" * 10 + "\n") * 10
red = Color("#ff0000")
green = Color("#00ff00")
blue = Color("#0000ff")
effect = ColorShift(text)
effect.effect_config.gradient_stops = (red, green, blue)
with effect.terminal_output() as terminal:
    for frame in effect:
        terminal.print(frame)

Color Reference

Represents a color in the RGB color space.

The color can be initialized with an XTerm-256 color code or an RGB hex color string. Can be printed to display the color code and appearance as a color block.

Attributes:

Name Type Description
color_arg int | str

The color value as an XTerm-256 color code or an RGB hex color string.
xterm_color int | None

The XTerm-256 color code. None if the color is an RGB hex color string.
rgb_color str

The RGB hex color string.
Properties

rgb_ints (tuple[int, int, int]): Returns the RGB values as a tuple of integers.

Raises:

Type Description
ValueError

If the color value is not a valid XTerm-256 color code or an RGB hex color string.
Source code in terminaltexteffects/utils/graphics.py 
 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
class Color:
    """Represents a color in the RGB color space.

    The color can be initialized with an XTerm-256 color code or an RGB hex color string. Can be printed
    to display the color code and appearance as a color block.

    Attributes:
        color_arg (int | str): The color value as an XTerm-256 color code or an RGB hex color string.
        xterm_color (int | None): The XTerm-256 color code. None if the color is an RGB hex color string.
        rgb_color (str): The RGB hex color string.

    Properties:
        rgb_ints (tuple[int, int, int]): Returns the RGB values as a tuple of integers.

    Raises:
        ValueError: If the color value is not a valid XTerm-256 color code or an RGB hex color string.

    """

    def __init__(self, color_value: int | str) -> None:
        """Initialize a Color object.

        Args:
            color_value (int | str): The color value as an XTerm-256 color code or an RGB hex color string.
                Example: 255 or 'ffffff' or '#ffffff'

        Raises:
            ValueError: If the color value is not a valid XTerm-256 color code or an RGB hex color string.

        """
        if isinstance(color_value, str):
            color_value = color_value.strip("#")
        self.color_arg = color_value
        self.xterm_color: int | None = None
        if hexterm.is_valid_color(color_value):
            if isinstance(color_value, int):
                self.xterm_color = color_value
                self.rgb_color = hexterm.xterm_to_hex(color_value)
            else:
                self.rgb_color = color_value
                self.xterm_color = None
        else:
            msg = (
                "Invalid color value. Color must be an XTerm-256 color code or an RGB hex color string. "
                "Example: 255 or 'ffffff' or '#ffffff'"
            )
            raise ValueError(
                msg,
            )

    @property
    def rgb_ints(self) -> tuple[int, int, int]:
        """Returns the RGB values as a tuple of integers.

        Returns:
            tuple[int, int, int]: The RGB values as a tuple of integers.

        """
        return colorterm._hex_to_int(self.rgb_color)

    def __repr__(self) -> str:
        """Return a string representation of the Color object."""
        return f"Color('{self.color_arg}')"

    def __str__(self) -> str:
        """Return a string representation of the Color object."""
        color_block = f"{colorterm.fg(self.rgb_color)}█████{ansitools.reset_all()}"
        xterm_display = f" | XTerm Color: {self.xterm_color}" if self.xterm_color is not None else ""
        return (
            f"Color Code: {self.rgb_color}{xterm_display}"
            f"\nColor Appearance: {color_block}"
        )

    def __eq__(self, other: object) -> bool:
        """Return whether this color is equal to another `Color`.

        Returns `NotImplemented` when `other` is not a `Color`.
        """
        if not isinstance(other, Color):
            return NotImplemented
        return self.color_arg == other.color_arg

    def __ne__(self, other: object) -> bool:
        """Return whether this color is not equal to another `Color`.

        Returns `NotImplemented` when `other` is not a `Color`.
        """
        if not isinstance(other, Color):
            return NotImplemented
        return self.color_arg != other.color_arg

    def __hash__(self) -> int:
        """Return the hash value of the Color object."""
        return hash(self.color_arg)

    def __iter__(self) -> Iterator[Color]:
        """Return an iterator yielding this `Color` instance once."""
        return iter((self,))

rgb_ints property

Returns the RGB values as a tuple of integers.

Returns:

Type Description
tuple[int, int, int]

tuple[int, int, int]: The RGB values as a tuple of integers.

__eq__(other)

Return whether this color is equal to another Color.

Returns NotImplemented when other is not a Color.

Source code in terminaltexteffects/utils/graphics.py 
 99
100
101
102
103
104
105
106
def __eq__(self, other: object) -> bool:
    """Return whether this color is equal to another `Color`.

    Returns `NotImplemented` when `other` is not a `Color`.
    """
    if not isinstance(other, Color):
        return NotImplemented
    return self.color_arg == other.color_arg

__hash__()

Return the hash value of the Color object.

Source code in terminaltexteffects/utils/graphics.py 
117
118
119
def __hash__(self) -> int:
    """Return the hash value of the Color object."""
    return hash(self.color_arg)

__init__(color_value)

Initialize a Color object.

Parameters:

Name Type Description Default
color_value int | str

The color value as an XTerm-256 color code or an RGB hex color string. Example: 255 or 'ffffff' or '#ffffff'

 required

Raises:

Type Description
ValueError

If the color value is not a valid XTerm-256 color code or an RGB hex color string.
Source code in terminaltexteffects/utils/graphics.py 
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
def __init__(self, color_value: int | str) -> None:
    """Initialize a Color object.

    Args:
        color_value (int | str): The color value as an XTerm-256 color code or an RGB hex color string.
            Example: 255 or 'ffffff' or '#ffffff'

    Raises:
        ValueError: If the color value is not a valid XTerm-256 color code or an RGB hex color string.

    """
    if isinstance(color_value, str):
        color_value = color_value.strip("#")
    self.color_arg = color_value
    self.xterm_color: int | None = None
    if hexterm.is_valid_color(color_value):
        if isinstance(color_value, int):
            self.xterm_color = color_value
            self.rgb_color = hexterm.xterm_to_hex(color_value)
        else:
            self.rgb_color = color_value
            self.xterm_color = None
    else:
        msg = (
            "Invalid color value. Color must be an XTerm-256 color code or an RGB hex color string. "
            "Example: 255 or 'ffffff' or '#ffffff'"
        )
        raise ValueError(
            msg,
        )

__iter__()

Return an iterator yielding this Color instance once.

Source code in terminaltexteffects/utils/graphics.py 
121
122
123
def __iter__(self) -> Iterator[Color]:
    """Return an iterator yielding this `Color` instance once."""
    return iter((self,))

__ne__(other)

Return whether this color is not equal to another Color.

Returns NotImplemented when other is not a Color.

Source code in terminaltexteffects/utils/graphics.py 
108
109
110
111
112
113
114
115
def __ne__(self, other: object) -> bool:
    """Return whether this color is not equal to another `Color`.

    Returns `NotImplemented` when `other` is not a `Color`.
    """
    if not isinstance(other, Color):
        return NotImplemented
    return self.color_arg != other.color_arg

__repr__()

Return a string representation of the Color object.

Source code in terminaltexteffects/utils/graphics.py 
86
87
88
def __repr__(self) -> str:
    """Return a string representation of the Color object."""
    return f"Color('{self.color_arg}')"

__str__()

Return a string representation of the Color object.

Source code in terminaltexteffects/utils/graphics.py 
90
91
92
93
94
95
96
97
def __str__(self) -> str:
    """Return a string representation of the Color object."""
    color_block = f"{colorterm.fg(self.rgb_color)}█████{ansitools.reset_all()}"
    xterm_display = f" | XTerm Color: {self.xterm_color}" if self.xterm_color is not None else ""
    return (
        f"Color Code: {self.rgb_color}{xterm_display}"
        f"\nColor Appearance: {color_block}"
    )