This module contains a powerful Color class which Textual uses to manipulate colors.
Named colors
The following named colors are used by the parse method.
colors
┏━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┓
┃ Name ┃ hex ┃ RGB ┃ Color ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━┩
│ "aliceblue" │ #F0F8FF │ rgb ( 240 , 248 , 255 ) │ │
│ "ansi_black" │ #000000 │ rgb ( 0 , 0 , 0 ) │ │
│ "ansi_blue" │ #000080 │ rgb ( 0 , 0 , 128 ) │ │
│ "ansi_bright_black" │ #808080 │ rgb ( 128 , 128 , 128 ) │ │
│ "ansi_bright_blue" │ #0000FF │ rgb ( 0 , 0 , 255 ) │ │
│ "ansi_bright_cyan" │ #00FFFF │ rgb ( 0 , 255 , 255 ) │ │
│ "ansi_bright_green" │ #00FF00 │ rgb ( 0 , 255 , 0 ) │ │
│ "ansi_bright_magenta" │ #FF00FF │ rgb ( 255 , 0 , 255 ) │ │
│ "ansi_bright_red" │ #FF0000 │ rgb ( 255 , 0 , 0 ) │ │
│ "ansi_bright_white" │ #FFFFFF │ rgb ( 255 , 255 , 255 ) │ │
│ "ansi_bright_yellow" │ #FFFF00 │ rgb ( 255 , 255 , 0 ) │ │
│ "ansi_cyan" │ #008080 │ rgb ( 0 , 128 , 128 ) │ │
│ "ansi_green" │ #008000 │ rgb ( 0 , 128 , 0 ) │ │
│ "ansi_magenta" │ #800080 │ rgb ( 128 , 0 , 128 ) │ │
│ "ansi_red" │ #800000 │ rgb ( 128 , 0 , 0 ) │ │
│ "ansi_white" │ #C0C0C0 │ rgb ( 192 , 192 , 192 ) │ │
│ "ansi_yellow" │ #808000 │ rgb ( 128 , 128 , 0 ) │ │
│ "antiquewhite" │ #FAEBD7 │ rgb ( 250 , 235 , 215 ) │ │
│ "aqua" │ #00FFFF │ rgb ( 0 , 255 , 255 ) │ │
│ "aquamarine" │ #7FFFD4 │ rgb ( 127 , 255 , 212 ) │ │
│ "azure" │ #F0FFFF │ rgb ( 240 , 255 , 255 ) │ │
│ "beige" │ #F5F5DC │ rgb ( 245 , 245 , 220 ) │ │
│ "bisque" │ #FFE4C4 │ rgb ( 255 , 228 , 196 ) │ │
│ "black" │ #000000 │ rgb ( 0 , 0 , 0 ) │ │
│ "blanchedalmond" │ #FFEBCD │ rgb ( 255 , 235 , 205 ) │ │
│ "blue" │ #0000FF │ rgb ( 0 , 0 , 255 ) │ │
│ "blueviolet" │ #8A2BE2 │ rgb ( 138 , 43 , 226 ) │ │
│ "brown" │ #A52A2A │ rgb ( 165 , 42 , 42 ) │ │
│ "burlywood" │ #DEB887 │ rgb ( 222 , 184 , 135 ) │ │
│ "cadetblue" │ #5F9EA0 │ rgb ( 95 , 158 , 160 ) │ │
│ "chartreuse" │ #7FFF00 │ rgb ( 127 , 255 , 0 ) │ │
│ "chocolate" │ #D2691E │ rgb ( 210 , 105 , 30 ) │ │
│ "coral" │ #FF7F50 │ rgb ( 255 , 127 , 80 ) │ │
│ "cornflowerblue" │ #6495ED │ rgb ( 100 , 149 , 237 ) │ │
│ "cornsilk" │ #FFF8DC │ rgb ( 255 , 248 , 220 ) │ │
│ "crimson" │ #DC143C │ rgb ( 220 , 20 , 60 ) │ │
│ "cyan" │ #00FFFF │ rgb ( 0 , 255 , 255 ) │ │
│ "darkblue" │ #00008B │ rgb ( 0 , 0 , 139 ) │ │
│ "darkcyan" │ #008B8B │ rgb ( 0 , 139 , 139 ) │ │
│ "darkgoldenrod" │ #B8860B │ rgb ( 184 , 134 , 11 ) │ │
│ "darkgray" │ #A9A9A9 │ rgb ( 169 , 169 , 169 ) │ │
│ "darkgreen" │ #006400 │ rgb ( 0 , 100 , 0 ) │ │
│ "darkgrey" │ #A9A9A9 │ rgb ( 169 , 169 , 169 ) │ │
│ "darkkhaki" │ #BDB76B │ rgb ( 189 , 183 , 107 ) │ │
│ "darkmagenta" │ #8B008B │ rgb ( 139 , 0 , 139 ) │ │
│ "darkolivegreen" │ #556B2F │ rgb ( 85 , 107 , 47 ) │ │
│ "darkorange" │ #FF8C00 │ rgb ( 255 , 140 , 0 ) │ │
│ "darkorchid" │ #9932CC │ rgb ( 153 , 50 , 204 ) │ │
│ "darkred" │ #8B0000 │ rgb ( 139 , 0 , 0 ) │ │
│ "darksalmon" │ #E9967A │ rgb ( 233 , 150 , 122 ) │ │
│ "darkseagreen" │ #8FBC8F │ rgb ( 143 , 188 , 143 ) │ │
│ "darkslateblue" │ #483D8B │ rgb ( 72 , 61 , 139 ) │ │
│ "darkslategray" │ #2F4F4F │ rgb ( 47 , 79 , 79 ) │ │
│ "darkslategrey" │ #2F4F4F │ rgb ( 47 , 79 , 79 ) │ │
│ "darkturquoise" │ #00CED1 │ rgb ( 0 , 206 , 209 ) │ │
│ "darkviolet" │ #9400D3 │ rgb ( 148 , 0 , 211 ) │ │
│ "deeppink" │ #FF1493 │ rgb ( 255 , 20 , 147 ) │ │
│ "deepskyblue" │ #00BFFF │ rgb ( 0 , 191 , 255 ) │ │
│ "dimgray" │ #696969 │ rgb ( 105 , 105 , 105 ) │ │
│ "dimgrey" │ #696969 │ rgb ( 105 , 105 , 105 ) │ │
│ "dodgerblue" │ #1E90FF │ rgb ( 30 , 144 , 255 ) │ │
│ "firebrick" │ #B22222 │ rgb ( 178 , 34 , 34 ) │ │
│ "floralwhite" │ #FFFAF0 │ rgb ( 255 , 250 , 240 ) │ │
│ "forestgreen" │ #228B22 │ rgb ( 34 , 139 , 34 ) │ │
│ "fuchsia" │ #FF00FF │ rgb ( 255 , 0 , 255 ) │ │
│ "gainsboro" │ #DCDCDC │ rgb ( 220 , 220 , 220 ) │ │
│ "ghostwhite" │ #F8F8FF │ rgb ( 248 , 248 , 255 ) │ │
│ "gold" │ #FFD700 │ rgb ( 255 , 215 , 0 ) │ │
│ "goldenrod" │ #DAA520 │ rgb ( 218 , 165 , 32 ) │ │
│ "gray" │ #808080 │ rgb ( 128 , 128 , 128 ) │ │
│ "green" │ #008000 │ rgb ( 0 , 128 , 0 ) │ │
│ "greenyellow" │ #ADFF2F │ rgb ( 173 , 255 , 47 ) │ │
│ "grey" │ #808080 │ rgb ( 128 , 128 , 128 ) │ │
│ "honeydew" │ #F0FFF0 │ rgb ( 240 , 255 , 240 ) │ │
│ "hotpink" │ #FF69B4 │ rgb ( 255 , 105 , 180 ) │ │
│ "indianred" │ #CD5C5C │ rgb ( 205 , 92 , 92 ) │ │
│ "indigo" │ #4B0082 │ rgb ( 75 , 0 , 130 ) │ │
│ "ivory" │ #FFFFF0 │ rgb ( 255 , 255 , 240 ) │ │
│ "khaki" │ #F0E68C │ rgb ( 240 , 230 , 140 ) │ │
│ "lavender" │ #E6E6FA │ rgb ( 230 , 230 , 250 ) │ │
│ "lavenderblush" │ #FFF0F5 │ rgb ( 255 , 240 , 245 ) │ │
│ "lawngreen" │ #7CFC00 │ rgb ( 124 , 252 , 0 ) │ │
│ "lemonchiffon" │ #FFFACD │ rgb ( 255 , 250 , 205 ) │ │
│ "lightblue" │ #ADD8E6 │ rgb ( 173 , 216 , 230 ) │ │
│ "lightcoral" │ #F08080 │ rgb ( 240 , 128 , 128 ) │ │
│ "lightcyan" │ #E0FFFF │ rgb ( 224 , 255 , 255 ) │ │
│ "lightgoldenrodyellow" │ #FAFAD2 │ rgb ( 250 , 250 , 210 ) │ │
│ "lightgray" │ #D3D3D3 │ rgb ( 211 , 211 , 211 ) │ │
│ "lightgreen" │ #90EE90 │ rgb ( 144 , 238 , 144 ) │ │
│ "lightgrey" │ #D3D3D3 │ rgb ( 211 , 211 , 211 ) │ │
│ "lightpink" │ #FFB6C1 │ rgb ( 255 , 182 , 193 ) │ │
│ "lightsalmon" │ #FFA07A │ rgb ( 255 , 160 , 122 ) │ │
│ "lightseagreen" │ #20B2AA │ rgb ( 32 , 178 , 170 ) │ │
│ "lightskyblue" │ #87CEFA │ rgb ( 135 , 206 , 250 ) │ │
│ "lightslategray" │ #778899 │ rgb ( 119 , 136 , 153 ) │ │
│ "lightslategrey" │ #778899 │ rgb ( 119 , 136 , 153 ) │ │
│ "lightsteelblue" │ #B0C4DE │ rgb ( 176 , 196 , 222 ) │ │
│ "lightyellow" │ #FFFFE0 │ rgb ( 255 , 255 , 224 ) │ │
│ "lime" │ #00FF00 │ rgb ( 0 , 255 , 0 ) │ │
│ "limegreen" │ #32CD32 │ rgb ( 50 , 205 , 50 ) │ │
│ "linen" │ #FAF0E6 │ rgb ( 250 , 240 , 230 ) │ │
│ "magenta" │ #FF00FF │ rgb ( 255 , 0 , 255 ) │ │
│ "maroon" │ #800000 │ rgb ( 128 , 0 , 0 ) │ │
│ "mediumaquamarine" │ #66CDAA │ rgb ( 102 , 205 , 170 ) │ │
│ "mediumblue" │ #0000CD │ rgb ( 0 , 0 , 205 ) │ │
│ "mediumorchid" │ #BA55D3 │ rgb ( 186 , 85 , 211 ) │ │
│ "mediumpurple" │ #9370DB │ rgb ( 147 , 112 , 219 ) │ │
│ "mediumseagreen" │ #3CB371 │ rgb ( 60 , 179 , 113 ) │ │
│ "mediumslateblue" │ #7B68EE │ rgb ( 123 , 104 , 238 ) │ │
│ "mediumspringgreen" │ #00FA9A │ rgb ( 0 , 250 , 154 ) │ │
│ "mediumturquoise" │ #48D1CC │ rgb ( 72 , 209 , 204 ) │ │
│ "mediumvioletred" │ #C71585 │ rgb ( 199 , 21 , 133 ) │ │
│ "midnightblue" │ #191970 │ rgb ( 25 , 25 , 112 ) │ │
│ "mintcream" │ #F5FFFA │ rgb ( 245 , 255 , 250 ) │ │
│ "mistyrose" │ #FFE4E1 │ rgb ( 255 , 228 , 225 ) │ │
│ "moccasin" │ #FFE4B5 │ rgb ( 255 , 228 , 181 ) │ │
│ "navajowhite" │ #FFDEAD │ rgb ( 255 , 222 , 173 ) │ │
│ "navy" │ #000080 │ rgb ( 0 , 0 , 128 ) │ │
│ "oldlace" │ #FDF5E6 │ rgb ( 253 , 245 , 230 ) │ │
│ "olive" │ #808000 │ rgb ( 128 , 128 , 0 ) │ │
│ "olivedrab" │ #6B8E23 │ rgb ( 107 , 142 , 35 ) │ │
│ "orange" │ #FFA500 │ rgb ( 255 , 165 , 0 ) │ │
│ "orangered" │ #FF4500 │ rgb ( 255 , 69 , 0 ) │ │
│ "orchid" │ #DA70D6 │ rgb ( 218 , 112 , 214 ) │ │
│ "palegoldenrod" │ #EEE8AA │ rgb ( 238 , 232 , 170 ) │ │
│ "palegreen" │ #98FB98 │ rgb ( 152 , 251 , 152 ) │ │
│ "paleturquoise" │ #AFEEEE │ rgb ( 175 , 238 , 238 ) │ │
│ "palevioletred" │ #DB7093 │ rgb ( 219 , 112 , 147 ) │ │
│ "papayawhip" │ #FFEFD5 │ rgb ( 255 , 239 , 213 ) │ │
│ "peachpuff" │ #FFDAB9 │ rgb ( 255 , 218 , 185 ) │ │
│ "peru" │ #CD853F │ rgb ( 205 , 133 , 63 ) │ │
│ "pink" │ #FFC0CB │ rgb ( 255 , 192 , 203 ) │ │
│ "plum" │ #DDA0DD │ rgb ( 221 , 160 , 221 ) │ │
│ "powderblue" │ #B0E0E6 │ rgb ( 176 , 224 , 230 ) │ │
│ "purple" │ #800080 │ rgb ( 128 , 0 , 128 ) │ │
│ "rebeccapurple" │ #663399 │ rgb ( 102 , 51 , 153 ) │ │
│ "red" │ #FF0000 │ rgb ( 255 , 0 , 0 ) │ │
│ "rosybrown" │ #BC8F8F │ rgb ( 188 , 143 , 143 ) │ │
│ "royalblue" │ #4169E1 │ rgb ( 65 , 105 , 225 ) │ │
│ "saddlebrown" │ #8B4513 │ rgb ( 139 , 69 , 19 ) │ │
│ "salmon" │ #FA8072 │ rgb ( 250 , 128 , 114 ) │ │
│ "sandybrown" │ #F4A460 │ rgb ( 244 , 164 , 96 ) │ │
│ "seagreen" │ #2E8B57 │ rgb ( 46 , 139 , 87 ) │ │
│ "seashell" │ #FFF5EE │ rgb ( 255 , 245 , 238 ) │ │
│ "sienna" │ #A0522D │ rgb ( 160 , 82 , 45 ) │ │
│ "silver" │ #C0C0C0 │ rgb ( 192 , 192 , 192 ) │ │
│ "skyblue" │ #87CEEB │ rgb ( 135 , 206 , 235 ) │ │
│ "slateblue" │ #6A5ACD │ rgb ( 106 , 90 , 205 ) │ │
│ "slategray" │ #708090 │ rgb ( 112 , 128 , 144 ) │ │
│ "slategrey" │ #708090 │ rgb ( 112 , 128 , 144 ) │ │
│ "snow" │ #FFFAFA │ rgb ( 255 , 250 , 250 ) │ │
│ "springgreen" │ #00FF7F │ rgb ( 0 , 255 , 127 ) │ │
│ "steelblue" │ #4682B4 │ rgb ( 70 , 130 , 180 ) │ │
│ "tan" │ #D2B48C │ rgb ( 210 , 180 , 140 ) │ │
│ "teal" │ #008080 │ rgb ( 0 , 128 , 128 ) │ │
│ "thistle" │ #D8BFD8 │ rgb ( 216 , 191 , 216 ) │ │
│ "tomato" │ #FF6347 │ rgb ( 255 , 99 , 71 ) │ │
│ "turquoise" │ #40E0D0 │ rgb ( 64 , 224 , 208 ) │ │
│ "violet" │ #EE82EE │ rgb ( 238 , 130 , 238 ) │ │
│ "wheat" │ #F5DEB3 │ rgb ( 245 , 222 , 179 ) │ │
│ "white" │ #FFFFFF │ rgb ( 255 , 255 , 255 ) │ │
│ "whitesmoke" │ #F5F5F5 │ rgb ( 245 , 245 , 245 ) │ │
│ "yellow" │ #FFFF00 │ rgb ( 255 , 255 , 0 ) │ │
│ "yellowgreen" │ #9ACD32 │ rgb ( 154 , 205 , 50 ) │ │
└────────────────────────┴─────────┴────────────────────┴──────────────────────┘
BLACK
module-attribute
BLACK : Final = Color ( 0 , 0 , 0 )
A constant for pure black.
WHITE
module-attribute
WHITE : Final = Color ( 255 , 255 , 255 )
A constant for pure white.
Color
class
Bases: NamedTuple
A class to represent a color.
Colors are stored as three values representing the degree of red, green, and blue in a color, and a
fourth "alpha" value which defines where the color lies on a gradient of opaque to transparent.
Example
>>> from textual.color import Color
>>> color = Color . parse ( "red" )
>>> color
Color ( 255 , 0 , 0 )
>>> color . darken ( 0.5 )
Color ( 98 , 0 , 0 )
>>> color + Color . parse ( "green" )
Color ( 0 , 128 , 0 )
>>> color_with_alpha = Color ( 100 , 50 , 25 , 0.5 )
>>> color_with_alpha
Color ( 100 , 50 , 25 , a = 0.5 )
>>> color + color_with_alpha
Color ( 177 , 25 , 12 )
a
class-attribute
instance-attribute
Alpha (opacity) component in range 0 to 1.
b
instance-attribute
Blue component in range 0 to 255.
brightness
property
The human perceptual brightness.
A value of 1 is returned for pure white, and 0 for pure black.
Other colors lie on a gradient between the two extremes.
clamped
property
A clamped color (this color with all values in expected range).
css
property
The color in CSS RGB or RGBA form.
For example, "rgb(10,20,30)"
for an RGB color, or "rgb(50,70,80,0.5)"
for an RGBA color.
g
instance-attribute
Green component in range 0 to 255.
hex
property
The color in CSS hex form, with 6 digits for RGB, and 8 digits for RGBA.
For example, "#46b3de"
for an RGB color, or "#3342457f"
for a color with alpha.
hex6
property
The color in CSS hex form, with 6 digits for RGB. Alpha is ignored.
For example, "#46b3de"
.
hsl
property
This color in HSL format.
HSL color is an alternative way of representing a color, which can be used in certain color calculations.
Returns
Type
Description
HSL
Color encoded in HSL format.
inverse
property
The inverse of this color.
Returns
Type
Description
Color
Inverse color.
is_transparent
property
Is the color transparent (i.e. has 0 alpha)?
monochrome
property
A monochrome version of this color.
Returns
Type
Description
Color
The monochrome (black and white) version of this color.
normalized
property
normalized : tuple [ float , float , float ]
A tuple of the color components normalized to between 0 and 1.
Returns
r
instance-attribute
Red component in range 0 to 255.
rgb
property
rgb : tuple [ int , int , int ]
The red, green, and blue color components as a tuple of ints.
rich_color
property
This color encoded in Rich's Color class.
Returns
Type
Description
RichColor
A color object as used by Rich.
blend
cached
def blend ( self , destination , factor , alpha = None ):
Generate a new color between two colors.
This method calculates a new color on a gradient.
The position on the gradient is given by factor
, which is a float between 0 and 1, where 0 is the original color, and 1 is the destination
color.
A value of gradient
between the two extremes produces a color somewhere between the two end points.
Parameters
Name
Type
Description
Default
destination
Color
Another color.
required
factor
float
A blend factor, 0 -> 1.
required
alpha
float | None
New alpha for result.
None
Returns
Type
Description
Color
A new color.
darken
cached
def darken ( self , amount , alpha = None ):
Darken the color by a given amount.
Parameters
Name
Type
Description
Default
amount
float
Value between 0-1 to reduce luminance by.
required
alpha
float | None
Alpha component for new color or None to copy alpha.
None
Returns
Type
Description
Color
New color.
from_hsl
classmethod
def from_hsl ( cls , h , s , l ):
Create a color from HLS components.
Parameters
Name
Type
Description
Default
h
float
Hue.
required
l
float
Lightness.
required
s
float
Saturation.
required
Returns
Type
Description
Color
A new color.
from_rich_color
classmethod
def from_rich_color ( cls , rich_color ):
Create a new color from Rich's Color class.
Parameters
Returns
Type
Description
Color
A new Color instance.
get_contrast_text
cached
def get_contrast_text ( self , alpha = 0.95 ):
Get a light or dark color that best contrasts this color, for use with text.
Parameters
Name
Type
Description
Default
alpha
float
An alpha value to apply to the result.
0.95
Returns
Type
Description
Color
A new color, either an off-white or off-black.
lighten
method
def lighten ( self , amount , alpha = None ):
Lighten the color by a given amount.
Parameters
Name
Type
Description
Default
amount
float
Value between 0-1 to increase luminance by.
required
alpha
float | None
Alpha component for new color or None to copy alpha.
None
Returns
Type
Description
Color
New color.
multiply_alpha
method
def multiply_alpha ( self , alpha ):
Create a new color, multiplying the alpha by a constant.
Parameters
Name
Type
Description
Default
alpha
float
A value to multiple the alpha by (expected to be in the range 0 to 1).
required
Returns
Type
Description
Color
A new color.
parse
classmethod
cached
def parse ( cls , color_text ):
Parse a string containing a named color or CSS-style color.
Colors may be parsed from the following formats:
Text beginning with a #
is parsed as a hexadecimal color code,
where R, G, B, and A must be hexadecimal digits (0-9A-F):
#RGB
#RGBA
#RRGGBB
#RRGGBBAA
Alternatively, RGB colors can also be specified in the format
that follows, where R, G, and B must be numbers between 0 and 255
and A must be a value between 0 and 1:
The HSL model can also be used, with a syntax similar to the above,
if H is a value between 0 and 360, S and L are percentages, and A
is a value between 0 and 1:
Any other formats will raise a ColorParseError
.
Parameters
Name
Type
Description
Default
color_text
str | Color
Text with a valid color format. Color objects will
be returned unmodified.
required
Raises
Returns
Type
Description
Color
Instance encoding the color specified by the argument.
with_alpha
method
def with_alpha ( self , alpha ):
Create a new color with the given alpha.
Parameters
Name
Type
Description
Default
alpha
float
New value for alpha.
required
Returns
Type
Description
Color
A new color.
ColorParseError
class
def __init__ ( self , message , suggested_color = None ):
Bases: Exception
A color failed to parse.
Parameters
Name
Type
Description
Default
message
str
The error message
required
suggested_color
str | None
A close color we can suggest.
None
Gradient
class
def __init__ ( self , * stops ):
Defines a color gradient.
A gradient is defined by a sequence of "stops" consisting of a float and a color.
The stop indicate the color at that point on a spectrum between 0 and 1.
Parameters
Raises
Type
Description
ValueError
If any stops are missing (must be at least a stop for 0 and 1).
get_color
method
def get_color ( self , position ):
Get a color from the gradient at a position between 0 and 1.
Positions that are between stops will return a blended color.
Parameters
Name
Type
Description
Default
position
float
A number between 0 and 1, where 0 is the first stop, and 1 is the last.
required
Returns
Type
Description
Color
A color.
HSL
class
Bases: NamedTuple
A color in HLS (Hue, Saturation, Lightness) format.
l
instance-attribute
Lightness in range 0 to 1.
s
instance-attribute
Saturation in range 0 to 1.
HSV
class
Bases: NamedTuple
A color in HSV (Hue, Saturation, Value) format.
s
instance-attribute
Saturation in range 0 to 1.
Lab
class
Bases: NamedTuple
A color in CIE-L*ab format.
L
instance-attribute
Lightness in range 0 to 100.
a
instance-attribute
A axis in range -127 to 128.
b
instance-attribute
B axis in range -127 to 128.
lab_to_rgb
function
def lab_to_rgb ( lab , alpha = 1.0 ):
Convert a CIE-L*ab color to RGB.
Uses the standard RGB color space with a D65/2⁰ standard illuminant.
Conversion passes through the XYZ color space.
Cf. http://www.easyrgb.com/en/math.php.
rgb_to_lab
function
Convert an RGB color to the CIE-L*ab format.
Uses the standard RGB color space with a D65/2⁰ standard illuminant.
Conversion passes through the XYZ color space.
Cf. http://www.easyrgb.com/en/math.php.