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.

BLACK module-attribute

BLACK = Color(0, 0, 0)

A constant for pure black.

TRANSPARENT module-attribute

TRANSPARENT = parse('transparent')

A constant for transparent.

WHITE module-attribute

WHITE = Color(255, 255, 255)

A constant for pure white.

Color

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 = 1.0

Alpha (opacity) component in range 0 to 1.

ansi class-attribute instance-attribute

ansi = None

ANSI color index. -1 means default color. None if not an ANSI color.

auto class-attribute instance-attribute

auto = False

Is the color automatic? (automatic colors may be white or black, to provide maximum contrast)

b instance-attribute

b

Blue component in range 0 to 255.

brightness property

brightness

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

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

css property

css

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

Green component in range 0 to 255.

hex property

hex

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

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

For example, "#46b3de".

hsl property

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

The inverse of this color.

Returns:

Type	Description
Color	Inverse color.

is_transparent property

is_transparent

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

monochrome property

monochrome

A monochrome version of this color.

Returns:

Type	Description
Color	The monochrome (black and white) version of this color.

normalized property

normalized

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

Red component in range 0 to 255.

rgb property

rgb

The red, green, and blue color components as a tuple of ints.

rich_color cached property

rich_color

This color encoded in Rich's Color class.

Returns:

Type	Description
Color	A color object as used by Rich.

automatic classmethod

automatic(alpha_percentage=100.0)

Create an automatic color.

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

darken(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

from_hsl(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

from_rich_color(rich_color, theme=None)

Create a new color from Rich's Color class.

Parameters:

Name	Type	Description	Default
rich_color	Color | None	An instance of Rich color.	required
theme	TerminalTheme | None	Optional Rich [terminal theme][rich.terminal_theme.TerminalTheme].	None

Returns:

Type	Description
Color	A new Color instance.

get_contrast_text cached

get_contrast_text(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

lighten(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

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

tint cached

tint(color)

Apply a tint to a color.

Similar to blend, but combines color and alpha.

Parameters:

Name	Type	Description	Default
color	Color	A color with alpha component.	required

Returns:

Type	Description
Color	New color

with_alpha

with_alpha(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

ColorParseError(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

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
stops	tuple[float, Color | str]	Color stops.	()
quality	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).

colors property

colors

A list of colors in the gradient.

from_colors classmethod

from_colors(*colors, quality=50)

Construct a gradient form a sequence of colors, where the stops are evenly spaced.

Parameters:

Name	Type	Description	Default
*colors	Color | str	Positional arguments may be Color instances or strings to parse into a color.	()
quality	int	The number of steps in the gradient.	50

Returns:

Type	Description
Gradient	A new Gradient instance.

get_color

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

get_rich_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
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 (Rich) color.

HSL

Bases: NamedTuple

A color in HLS (Hue, Saturation, Lightness) format.

css property

css

HSL in css format.

h instance-attribute

h

Hue in range 0 to 1.

l instance-attribute

l

Lightness in range 0 to 1.

s instance-attribute

s

Saturation in range 0 to 1.

HSV

Bases: NamedTuple

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

h instance-attribute

h

Hue in range 0 to 1.

s instance-attribute

s

Saturation in range 0 to 1.

v instance-attribute

v

Value un range 0 to 1.

Lab

Bases: NamedTuple

A color in CIE-L*ab format.

L instance-attribute

L

Lightness in range 0 to 100.

a instance-attribute

a

A axis in range -127 to 128.

b instance-attribute

b

B axis in range -127 to 128.

lab_to_rgb

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