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 instance-attribute class-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

Parameter	Default	Description
destination Color	required	Another color.
factor float	required	A blend factor, 0 -> 1.
alpha float | None	None	New alpha for result.

Returns

Type	Description
Color	A new color.

darken cached

def darken(self, amount, alpha=None):

Darken the color by a given amount.

Parameters

Parameter	Default	Description
amount float	required	Value between 0-1 to reduce luminance by.
alpha float | None	None	Alpha component for new color or None to copy alpha.

Returns

Type	Description
Color	New color.

from_hsl classmethod

def from_hsl(cls, h, s, l):

Create a color from HLS components.

Parameters

Parameter	Default	Description
h float	required	Hue.
l float	required	Lightness.
s float	required	Saturation.

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

Parameter	Default	Description
rich_color RichColor	required	An instance of Rich color.

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

Parameter	Default	Description
alpha float	0.95	An alpha value to apply to the result.

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

Parameter	Default	Description
amount float	required	Value between 0-1 to increase luminance by.
alpha float | None	None	Alpha component for new color or None to copy alpha.

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

Parameter	Default	Description
alpha float	required	A value to multiple the alpha by (expected to be in the range 0 to 1).

Returns

Type	Description
Color	A new color.

parse cached classmethod

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

Parameter	Default	Description
color_text str | Color	required	Text with a valid color format. Color objects will be returned unmodified.

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

Parameter	Default	Description
alpha float	required	New value for alpha.

Returns

Type	Description
Color	A new color.

ColorParseError class

def __init__(self, message, suggested_color=None):

Bases: Exception

A color failed to parse.

Parameters

Parameter	Default	Description
message str	required	The error message
suggested_color str | None	None	A close color we can suggest.

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

Parameter	Default	Description
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

Parameter	Default	Description
position float	required	A number between 0 and 1, where 0 is the first stop, and 1 is the last.

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.