Color

Text background and foreground color, as well as its style, is defined by the yuio.color.Color class. It stores RGB components and ANSI escape codes for every aspect of text presentation.

This is a low-level module upon which yuio.io builds its higher-level abstraction.

class yuio.color.Color(
fore: ColorValue | None = None,
back: ColorValue | None = None,
bold: bool | None = None,
dim: bool | None = None,
italic: bool | None = None,
underline: bool | None = None,
inverse: bool | None = None,
blink: bool | None = None,
)

Data about terminal output style. Contains foreground and background color, as well as text styles.

When converted to an ANSI code and printed, a color completely overwrites a previous color that was used by a terminal. This behavior prevents different colors and styles bleeding one into another. So, for example, printing Color.STYLE_BOLD and then Color.FORE_RED will result in non-bold red text.

Colors can be combined before printing, though:

>>> Color.STYLE_BOLD | Color.FORE_RED  # Bold red
<Color fore=<RED> bold=True>

Yuio supports true RGB colors. They are automatically converted to 256- or 8-bit colors if needed.

fore: ColorValue | None

Foreground color.

back: ColorValue | None

Background color.

bold: bool | None

If true, render text as bold.

dim: bool | None

If true, render text as dim.

italic: bool | None

If true, render text in italic font.

underline: bool | None

If true, underline the text.

inverse: bool | None

If true, swap foreground and background.

If true, render blinking text.

classmethod fore_from_rgb(r: int, g: int, b: int, **kwargs) → Color

Create a foreground color value from rgb components.

Each component should be between 0 and 255.

Example:
>>> Color.fore_from_rgb(0xA0, 0x1E, 0x9C)
<Color fore=<ColorValue #A01E9C>>
classmethod fore_from_hex(h: str, **kwargs) → Color

Create a foreground color value from a hex string.

Example:
>>> Color.fore_from_hex('#A01E9C')
<Color fore=<ColorValue #A01E9C>>
classmethod back_from_rgb(r: int, g: int, b: int, **kwargs) → Color

Create a background color value from rgb components.

Each component should be between 0 and 255.

Example:
>>> Color.back_from_rgb(0xA0, 0x1E, 0x9C)
<Color back=<ColorValue #A01E9C>>
classmethod back_from_hex(h: str, **kwargs) → Color

Create a background color value from a hex string.

Example:
>>> Color.back_from_hex('#A01E9C')
<Color back=<ColorValue #A01E9C>>
static lerp(
*colors: Color,
) → Callable[[float], Color]

Return a lambda that allows linear interpolation between several colors.

If either color is a single ANSI escape code, the first color is always returned from the lambda.

Parameters:

colors – colors of a gradient.

Returns:

a callable that allows interpolating between colors: it accepts a float value between 1 and 0 and returns a color.

Raises:

ValueError if no colors given.

Example:
>>> a = Color.fore_from_hex('#A01E9C')
>>> b = Color.fore_from_hex('#22C60C')
>>> lerp = Color.lerp(a, b)

>>> lerp(0)
<Color fore=<ColorValue #A01E9C>>
>>> lerp(0.5)
<Color fore=<ColorValue #617254>>
>>> lerp(1)
<Color fore=<ColorValue #22C60C>>
as_code(color_support: ColorSupport) → str

Convert this color into an ANSI escape code with respect to the given terminal capabilities.

Parameters:

color_support – level of color support of a terminal.

Returns:

either ANSI escape code for this color or an empty string.

NONE: ClassVar[Color] = <Color>

No color.

STYLE_BOLD: ClassVar[Color] = <Color bold=True>

Bold font style.

STYLE_DIM: ClassVar[Color] = <Color dim=True>

Dim font style.

STYLE_ITALIC: ClassVar[Color] = <Color italic=True>

Italic font style.

STYLE_UNDERLINE: ClassVar[Color] = <Color underline=True>

Underline font style.

STYLE_INVERSE: ClassVar[Color] = <Color inverse=True>

Swaps foreground and background colors.

Makes the text blink.

STYLE_NORMAL: ClassVar[Color] = <Color bold=False dim=False italic=False underline=False inverse=False blink=False>

Normal style.

FORE_NORMAL: ClassVar[Color] = <Color fore=<ColorValue 9>>

Normal foreground color.

FORE_NORMAL_DIM: ClassVar[Color] = <Color fore=<ColorValue '2'>>

Normal foreground color rendered with dim setting.

This is an alternative to bright black that works with most terminals and color schemes.

FORE_BLACK: ClassVar[Color] = <Color fore=<BLACK>>

Black foreground color.

Warning

Avoid using this color, in most terminals it is the same as background color. Instead, use FORE_NORMAL_DIM.

FORE_RED: ClassVar[Color] = <Color fore=<RED>>

Red foreground color.

FORE_GREEN: ClassVar[Color] = <Color fore=<GREEN>>

Green foreground color.

FORE_YELLOW: ClassVar[Color] = <Color fore=<YELLOW>>

Yellow foreground color.

FORE_BLUE: ClassVar[Color] = <Color fore=<BLUE>>

Blue foreground color.

FORE_MAGENTA: ClassVar[Color] = <Color fore=<MAGENTA>>

Magenta foreground color.

FORE_CYAN: ClassVar[Color] = <Color fore=<CYAN>>

Cyan foreground color.

FORE_WHITE: ClassVar[Color] = <Color fore=<WHITE>>

White foreground color.

Warning

Avoid using it. In some terminals, notably in the Mac OS default terminal, it is unreadable.

BACK_NORMAL: ClassVar[Color] = <Color back=<ColorValue 9>>

Normal background color.

BACK_BLACK: ClassVar[Color] = <Color back=<BLACK>>

Black background color.

BACK_RED: ClassVar[Color] = <Color back=<RED>>

Red background color.

BACK_GREEN: ClassVar[Color] = <Color back=<GREEN>>

Green background color.

BACK_YELLOW: ClassVar[Color] = <Color back=<YELLOW>>

Yellow background color.

BACK_BLUE: ClassVar[Color] = <Color back=<BLUE>>

Blue background color.

BACK_MAGENTA: ClassVar[Color] = <Color back=<MAGENTA>>

Magenta background color.

BACK_CYAN: ClassVar[Color] = <Color back=<CYAN>>

Cyan background color.

BACK_WHITE: ClassVar[Color] = <Color back=<WHITE>>

White background color.

class yuio.color.ColorValue(data: int | str | tuple[int, int, int])

Data about a single color.

data: int | str | tuple[int, int, int]

Color data.

Can be one of three things:

  • an int value represents an 8-bit color code (a value between 0 and 7).

    The actual color value for 8-bit color codes is controlled by the terminal’s user. Therefore, it doesn’t permit operations on colors.

    Depending on where this value is used (foreground or background), it will result in either 3x or 4x SGR parameter.

  • an RGB-tuple represents a true color.

    When converted for a terminal that doesn’t support true colors, it is automatically mapped to a corresponding 256- or 8-bit color.

    Depending on where this value is used (foreground or background), it will result in either 38/3x or 48/4x SGR parameter sequence.

  • A string value represents a parameter for the SGR command. Yuio will add this value to an SGR escape sequence as is, without any modification.

classmethod from_rgb(r: int, g: int, b: int, /) → ColorValue

Create a color value from rgb components.

Each component should be between 0 and 255.

Example:
>>> ColorValue.from_rgb(0xA0, 0x1E, 0x9C)
<ColorValue #A01E9C>
classmethod from_hex(h: str, /) → ColorValue

Create a color value from a hex string.

Example:
>>> ColorValue.from_hex('#A01E9C')
<ColorValue #A01E9C>
to_hex() → str | None

Return color in hex format with leading #.

Example:
>>> a = ColorValue.from_hex('#A01E9C')
>>> a.to_hex()
'#A01E9C'
to_rgb() → tuple[int, int, int] | None

Return RGB components of the color.

Example:
>>> a = ColorValue.from_hex('#A01E9C')
>>> a.to_rgb()
(160, 30, 156)
darken(amount: float, /) → ColorValue

Make this color darker by the given percentage.

Amount should be between 0 and 1.

Example:
>>> # Darken by 30%.
... ColorValue.from_hex('#A01E9C').darken(0.30)
<ColorValue #70156D>
lighten(amount: float, /) → ColorValue

Make this color lighter by the given percentage.

Amount should be between 0 and 1.

Example:
>>> # Lighten by 30%.
... ColorValue.from_hex('#A01E9C').lighten(0.30)
<ColorValue #BC23B7>
match_luminosity(
other: ColorValue,
/,
) → ColorValue

Set luminosity of this color equal to one of the other color.

This function will keep hue and saturation of the color intact, but it will become as bright as the other color.

static lerp(
*colors: ColorValue,
) → Callable[[float], ColorValue]

Return a lambda that allows linear interpolation between several colors.

If either color is a single ANSI escape code, the first color is always returned from the lambda.

Parameters:

colors – colors of a gradient.

Returns:

a callable that allows interpolating between colors: it accepts a float value between 1 and 0 and returns a color.

Raises:

ValueError if no colors are given.

Example:
>>> a = ColorValue.from_hex('#A01E9C')
>>> b = ColorValue.from_hex('#22C60C')
>>> lerp = ColorValue.lerp(a, b)

>>> lerp(0)
<ColorValue #A01E9C>
>>> lerp(0.5)
<ColorValue #617254>
>>> lerp(1)
<ColorValue #22C60C>
class yuio.color.ColorSupport(*values)

Terminal’s capability for coloring output.

NONE = 0

yuio.color.Color codes are not supported.

ANSI = 1

Only simple 8-bit color codes are supported.

ANSI_256 = 2

256-encoded colors are supported.

ANSI_TRUE = 3

True colors are supported.