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.

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

a: float = 1.0

Alpha (opacity) component in range 0 to 1.

b instance-attribute

b: int

Blue component in range 0 to 255.

brightness property

brightness: float

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

clamped: Color

A clamped color (this color with all values in expected range).

css property

css: str

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

g: int

Green component in range 0 to 255.

hex property

hex: str

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

hex6: str

The color in CSS hex form, with 6 digits for RGB. Alpha is ignored.

For example, "#46b3de".

hsl property

hsl: HSL

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

inverse: Color

The inverse of this color.

Returns

Type	Description
Color	Inverse color.

is_transparent property

is_transparent: bool

Is the color transparent (i.e. has 0 alpha)?

monochrome property

monochrome: Color

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

Type	Description
tuple[float, float, float]	Normalized components.

r instance-attribute

r: int

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

rich_color: RichColor

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

Name	Type	Description	Default
rich_color	RichColor	An instance of Rich color.	required

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:

  • 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.

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

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 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.

css property

css: str

HSL in css format.

h instance-attribute

h: float

Hue in range 0 to 1.

l instance-attribute

l: float

Lightness in range 0 to 1.

s instance-attribute

s: float

Saturation in range 0 to 1.

HSV class

Bases: NamedTuple

A color in HSV (Hue, Saturation, Value) format.

h instance-attribute

h: float

Hue in range 0 to 1.

s instance-attribute

s: float

Saturation in range 0 to 1.

v instance-attribute

v: float

Value un range 0 to 1.

Lab class

Bases: NamedTuple

A color in CIE-L*ab format.

L instance-attribute

L: float

Lightness in range 0 to 100.

a instance-attribute

a: float

A axis in range -127 to 128.

b instance-attribute

b: float

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

def 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.