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: Final = Color(0, 0, 0)

A constant for pure black.

TRANSPARENT module-attribute

TRANSPARENT: Final = Color.parse('transparent')

A constant for transparent.

WHITE module-attribute

WHITE: Final = 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: float = 1.0

Alpha (opacity) component in range 0 to 1.

ansi class-attribute instance-attribute

ansi: int | None = None

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

auto class-attribute instance-attribute

auto: bool = False

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

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.

hsv property

hsv: HSV

This color in HSV format.

HSV color is an alternative way of representing a color, which can be used in certain color calculations.

Returns:

Type	Description
HSV	Color encoded in HSV 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 cached property

rich_color: RichColor

This color encoded in Rich's Color class.

Returns:

Type	Description
RichColor	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 HSL components.

Parameters:

Name	Type	Description	Default
h	float	Hue.	required
s	float	Saturation.	required
l	float	Lightness.	required

Returns:

Type	Description
Color	A new color.

from_hsv classmethod

from_hsv(h, s, v)

Create a color from HSV components.

Parameters:

Name	Type	Description	Default
h	float	Hue.	required
s	float	Saturation.	required
v	float	Value.	required

Returns:

Type	Description
Color	A new color.

from_rich_color cached classmethod

from_rich_color(
    rich_color, theme=None, foreground=True, ansi=True
)

Create a new color from Rich's Color class.

Parameters:

Name	Type	Description	Default
rich_color	RichColor | None	An instance of Rich color.	required
theme	TerminalTheme | None	Optional Rich [terminal theme][rich.terminal_theme.TerminalTheme].	None
foreground	bool	Is the color a foreground color (False) or a background color (True)?	True
ansi	bool	Return ANSI colors if True, or attempt to convert to RGV if False.	True

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: list[Color]

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

HSL

Bases: NamedTuple

A color in HSL (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

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 in range 0 to 1.

Lab

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

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.