textual.color
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.
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)
class-attribute
instance-attribute
¶
ANSI color index. -1 means default color. None if not an ANSI color.
class-attribute
instance-attribute
¶
Is the color automatic? (automatic colors may be white or black, to provide maximum contrast)
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.
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.
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.
property
¶
The color in CSS hex form, with 6 digits for RGB. Alpha is ignored.
For example, "#46b3de".
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. |
property
¶
property
¶
A monochrome version of this color.
Returns:
| Type | Description |
|---|---|
Color
|
The monochrome (black and white) version of this color. |
property
¶
cached
property
¶
This color encoded in Rich's Color class.
Returns:
| Type | Description |
|---|---|
Color
|
A color object as used by Rich. |
cached
¶
blend(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 |
|---|---|---|---|
|
Color
|
Another color. |
required |
|
float
|
A blend factor, 0 -> 1. |
required |
|
float | None
|
New alpha for result. |
None
|
Returns:
| Type | Description |
|---|---|
Color
|
A new color. |
cached
¶
classmethod
¶
classmethod
¶
from_rich_color(rich_color)
Create a new color from Rich's Color class.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
|
Color | None
|
An instance of Rich color. |
required |
Returns:
| Type | Description |
|---|---|
Color
|
A new Color instance. |
cached
classmethod
¶
parse(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:
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 |
|---|---|---|---|
|
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(message, suggested_color=None)
Gradient(*stops, quality=50)
Defines a color gradient.
A gradient is defined by a sequence of "stops" consisting of a tuple containing a float and a color. The stop indicates the color at that point on a spectrum between 0 and 1. Colors may be given as a Color instance, or a string that can be parsed into a Color (with Color.parse).
The quality argument defines the number of steps in the gradient. Intermediate colors are
interpolated from the two nearest colors. Increasing quality can generate a smoother looking gradient,
at the expense of a little extra work to pre-calculate the colors.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
|
tuple[float, Color | str]
|
Color stops. |
()
|
|
int
|
The number of steps in the gradient. |
50
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If any stops are missing (must be at least a stop for 0 and 1). |
classmethod
¶
Construct a gradient form a sequence of colors, where the stops are evenly spaced.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
|
Color | str
|
Positional arguments may be Color instances or strings to parse into a color. |
()
|
|
int
|
The number of steps in the gradient. |
50
|
Returns:
| Type | Description |
|---|---|
Gradient
|
A new Gradient instance. |
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 |
|---|---|---|---|
|
float
|
A number between 0 and 1, where 0 is the first stop, and 1 is the last. |
required |
Returns:
| Type | Description |
|---|---|
Color
|
A Textual color. |
get_rich_color(position)
Get a (Rich) 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 |
|---|---|---|---|
|
float
|
A number between 0 and 1, where 0 is the first stop, and 1 is the last. |
required |
Returns:
| Type | Description |
|---|---|
Color
|
A (Rich) color. |
Bases: NamedTuple
A color in HLS (Hue, Saturation, Lightness) format.
Bases: NamedTuple
A color in HSV (Hue, Saturation, Value) format.
Bases: NamedTuple
A color in CIE-L*ab format.
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.
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.