Color

color

This module contains a powerful Color class which Textual uses to expose colors.

The only exception would be for Rich renderables, which require a rich.color.Color instance. You can convert from a Textual color to a Rich color with the rich_color property.

Named colors

The following named colors are used by the parse method.

Color

Bases: NamedTuple

A class to represent a RGB color with an alpha component.

a: float class-attribute

Alpha component (0-1)

b: int class-attribute

Blue component (0-255)

brightness: float property

Get the human perceptual brightness.

Returns:

Type	Description
float	Brightness value (0-1).

clamped: Color property

Get a color with all components saturated to maximum and minimum values.

Returns:

Type	Description
Color	A color object.

css: str property

The color in CSS rgb or rgba form.

Returns:

Type	Description
str	A CSS style color, e.g. "rgb(10,20,30)" or "rgb(50,70,80,0.5)"

g: int class-attribute

Green component (0-255)

hex: str property

The color in CSS hex form, with 6 digits for RGB, and 8 digits for RGBA.

Returns:

Type	Description
str	A CSS hex-style color, e.g. "#46b3de" or "#3342457f"

hex6: str property

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

Returns:

Type	Description
str	A CSS hex-style color, e.g. "#46b3de"

hsl: HSL property

Get the color as HSL.

Returns:

Type	Description
HSL	Color in HSL format.

inverse: Color property

The inverse of this color.

is_transparent: bool property

Check if the color is transparent, i.e. has 0 alpha.

Returns:

Type	Description
bool	True if transparent, otherwise False.

monochrome: Color property

Get a monochrome version of this color.

Returns:

Type	Description
Color	A new monochrome color.

normalized: tuple[float, float, float] property

A tuple of the color components normalized to between 0 and 1.

Returns:

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

r: int class-attribute

Red component (0-255)

rgb: tuple[int, int, int] property

Get just the red, green, and blue components.

Returns:

Type	Description
tuple[int, int, int]	Color components

rich_color: RichColor property

This color encoded in Rich's Color class.

Returns:

Type	Description
RichColor	A color object as used by Rich.

blend(destination, factor, alpha=None)

Generate a new color between two colors.

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. Defaults to None.	None

Returns:

Type	Description
Color	A new color.

darken(amount, alpha=None) cached

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. Defaults to None.	None

Returns:

Type	Description
Color	New color.

from_hsl(h, s, l) classmethod

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(rich_color) classmethod

Create a new color from Rich's Color class.

Parameters:

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

Returns:

Type	Description
Color	A new Color.

get_contrast_text(alpha=0.95) cached

Get a light or dark color that best contrasts this color, for use with text.

Parameters:

Name	Type	Description	Default
alpha		An alpha value to adjust the pure white / black by. Defaults to 0.95.	0.95

Returns:

Type	Description
Color	A new color, either an off-white or off-black

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. Defaults to None.	None

Returns:

Type	Description
Color	New color.

multiply_alpha(alpha)

Create a new color, multiplying the alpha with a new alpha.

Parameters:

Name	Type	Description	Default
alpha	float	The alpha value to multiple by.	required

Returns:

Type	Description
Color	A new color.

parse(color_text) cached classmethod

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

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. Defaults to None.	None

Gradient

Defines a color gradient.

__init__(*stops)

Create a color gradient that blends colors to form a spectrum.

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

Bases: NamedTuple

A color in HLS format.

css: str property

HSL in css format.

h: float class-attribute

Hue

l: float class-attribute

Lightness

s: float class-attribute

Saturation

HSV

Bases: NamedTuple

A color in HSV format.

h: float class-attribute

Hue

s: float class-attribute

Saturation

v: float class-attribute

Value

Lab

Bases: NamedTuple

A color in CIE-L*ab format.

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)

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.