Color
color
¶
This module contains a powerful Color class which Textual uses to expose colors.
The only exception would be for Rich renderables, which require a rich.color.Color instance. You can convert from a Textual color to a Rich color with the rich_color property.
Named colors¶
The following named colors are used by the parse method.
Color
¶
Bases: NamedTuple
A class to represent a RGB color with an alpha component.
a: float
class-attribute
¶
Alpha component (0-1)
b: int
class-attribute
¶
Blue component (0-255)
brightness: float
property
¶
clamped: Color
property
¶
Get a color with all components saturated to maximum and minimum values.
Returns:
Type | Description |
---|---|
Color
|
A color object. |
css: str
property
¶
The color in CSS rgb or rgba form.
Returns:
Type | Description |
---|---|
str
|
A CSS style color, e.g. |
g: int
class-attribute
¶
Green component (0-255)
hex: str
property
¶
The color in CSS hex form, with 6 digits for RGB, and 8 digits for RGBA.
Returns:
Type | Description |
---|---|
str
|
A CSS hex-style color, e.g. |
hex6: str
property
¶
The color in CSS hex form, with 6 digits for RGB. Alpha is ignored.
Returns:
Type | Description |
---|---|
str
|
A CSS hex-style color, e.g. "#46b3de" |
inverse: Color
property
¶
The inverse of this color.
is_transparent: bool
property
¶
Check if the color is transparent, i.e. has 0 alpha.
Returns:
Type | Description |
---|---|
bool
|
True if transparent, otherwise False. |
monochrome: Color
property
¶
normalized: tuple[float, float, float]
property
¶
r: int
class-attribute
¶
Red component (0-255)
rgb: tuple[int, int, int]
property
¶
rich_color: RichColor
property
¶
This color encoded in Rich's Color class.
Returns:
Type | Description |
---|---|
RichColor
|
A color object as used by Rich. |
blend(destination, factor, alpha=None)
¶
darken(amount, alpha=None)
cached
¶
from_hsl(h, s, l)
classmethod
¶
from_rich_color(rich_color)
classmethod
¶
get_contrast_text(alpha=0.95)
cached
¶
Get a light or dark color that best contrasts this color, for use with text.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
alpha |
An alpha value to adjust the pure white / black by. Defaults to 0.95. |
0.95
|
Returns:
Type | Description |
---|---|
Color
|
A new color, either an off-white or off-black |
lighten(amount, alpha=None)
¶
multiply_alpha(alpha)
¶
parse(color_text)
cached
classmethod
¶
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:
rgb(R,G,B)
rgb(R,G,B,A)
-
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:
hsl(H,S,L)
hsla(H,S,L,A)
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:
Type | Description |
---|---|
ColorParseError
|
If the color is not encoded correctly. |
Returns:
Type | Description |
---|---|
Color
|
Instance encoding the color specified by the argument. |
ColorParseError
¶
Gradient
¶
Defines a color gradient.
__init__(*stops)
¶
Create a color gradient that blends colors to form a spectrum.
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:
Name | Type | Description | Default |
---|---|---|---|
stops |
tuple[float, Color]
|
A colors stop. |
()
|
Raises:
Type | Description |
---|---|
ValueError
|
If any stops are missing (must be at least a stop for 0 and 1). |
get_color(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 |
---|---|---|---|
factor |
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
¶
Bases: NamedTuple
A color in HLS format.
HSV
¶
Bases: NamedTuple
A color in HSV format.
Lab
¶
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(rgb)
¶
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.