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.

hsv property

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

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