colors

import colors

This module provides functionalities for color conversion and manipulation.

This module also provides functionalities that enable cross-platform colored terminal outputs that will allow you create beautiful console apps that are user friendly.

RGB conversion to other colors that return a floating point or a list of floating points do so to allow users get absolute precision since its really easy for callers to do a num.round() on the components of the resulting list.

Example

The example below uses this module to create a success message that will print correctly on almost all terminals (Only Windows 10 version 1901+ supported. All linux and OSX terminals are supported). Try it out!

import colors
colors.text('Successful!', colors.text_color.green)

The text() function can be nested. For example,

colors.text(colors.text('Successful!', colors.style.bold), colors.text_color.green)

The module also features multiple functions for color conversion. For example,

%> import colors
%> colors.rgb_to_cmyk(103, 13, 69)
[0, 87.37864077669903, 33.009708737864095, 59.6078431372549]

The terminal colors also have simple wrappers that allow supplied colors to text() from various color formats. For example, we can specify the color from the HTML hexadecimal color.

import colors
colors.text('Colored text!', colors.hex('#fc0'))

The colors API

Every public name in colors, wherever it is declared. Each links to the page that documents it.

Constants

style

colors.style = {...}

ANSI font styles available for console applications.

text_color

colors.text_color = {...}

Standard ANSI text colors available for console applications.

background

colors.background = {...}

Standard ANSI background colors available for console applications.

NAMED

colors.NAMED: dict = {...}

The CSS Color Level 4 named colors, mapped to their hexadecimal values.

Values carry no leading #, matching every other function in this module that produces a hexadecimal color. Both the American and British spellings of the greys are present, as are rebeccapurple and transparent, which is the only entry with an alpha component and therefore the only 8-digit one.

Keys are lower case with no separators; use [[colors.named]] rather than indexing this directly if the name might arrive in mixed case or spaced out.

Functions

text()

colors.text(value, color, bg) -> string

Returns a terminal printable text with the given color (or style) and background if given.

Parameters

• value (string)
• color (?int)
• bg (?int)

Returns string

Note: The color argument can be replace with a style.

rgb_to_ansi256()

colors.rgb_to_ansi256(r: int, g: int, b: int) -> number

Converts RGB color to ASI-256 color number.

Parameters

• r (int)
• g (int)
• b (int)

Returns number

ansi256_to_ansi()

colors.ansi256_to_ansi(code: int) -> number

Converts ANSI-256 color number to ANSI-16 color number.

Parameters

• code (int)

Returns number

is_hex()

colors.is_hex(color) -> bool

Returns true if color is a hexadecimal color that [[colors.hex_to_rgb]] would accept, and false otherwise.

A leading # is optional and the digits may be in either case. This raises nothing, so it is the way to test a color before converting it rather than converting inside a catch.

%> import colors
%> colors.is_hex('#4f46e5')
true
%> colors.is_hex('rebeccapurple')
false

Parameters

• color (any)

Returns bool

hex_to_rgb()

colors.hex_to_rgb(h: string) -> list

Converts the hexadecimal string h to its RGBA component.

Accepts an optional leading #, is case-insensitive, and accepts the 3/4/6/8-digit forms (#f0c, #f0c8, #ff00cc, #ff00ccbb). Following the CSS Color 4 convention, alpha is the last component when present (RRGGBBAA/RGBA, not AARRGGBB/ARGB): an omitted alpha means fully opaque (1).

Parameters

• h (string)

Returns list — [r, g, b, a]

Raises ValueError When h is not a valid hexadecimal color.

hex_to_ansi256()

colors.hex_to_ansi256(color: string) -> number

Converts the given hexadecimal color to its ANSI-256 number.

Parameters

• color (string)

Returns number

hex_to_ansi()

colors.hex_to_ansi(color: string) -> number

Converts the given hexadecimal color to its ANSI-16 number.

Parameters

• color (string)

Returns number

Note: For use with text(), this should be preferred over hex_to_ansi256

hex()

colors.hex(color: string) -> number

Converts the given hexadecimal color to its terminal compatible color.

Parameters

• color (string)

Returns number

Note: For use with text(), this should be preferred over hex_to_ansi256 and hex_to_ansi

Note: color can include the ‘#’ character. E.g. #ff0.

rgb()

colors.rgb(r: int, g: int, b: int) -> number

Converts the given RGB color to its terminal compatible color.

Parameters

• r (number)
• g (number)
• b (number)

Returns number

hsl()

colors.hsl(h: number, s: number, l: number) -> number

Converts the given HSL color to its terminal compatible color.

Parameters

• h (number)
• s (number)
• l (number)

Returns number

hsv()

colors.hsv(h: number, s: number, v: number) -> number

Converts the given HSV color to its terminal compatible color.

Parameters

• h (number)
• s (number)
• v (number)

Returns number

hwb()

colors.hwb(h: number, w: number, b: number) -> number

Converts the given HWB color to its terminal compatible color.

Parameters

• h (number)
• w (number)
• b (number)

Returns number

cmyk()

colors.cmyk(c: number, m: number, y: number, k: number) -> number

Converts the given CMYK color to its terminal compatible color.

Parameters

• c (number)
• m (number)
• y (number)
• k (number)

Returns number

xyz()

colors.xyz(x: number, y: number, z: number) -> number

Converts the given XYZ color to its terminal compatible color.

Parameters

• x (number)
• y (number)
• z (number)

Returns number

rgb_to_hex()

colors.rgb_to_hex(r: int, g: int, b: int, a: ?int) -> string

Converts a RGB components into its corresponding hexadecimal color.

Following the CSS Color 4 convention, alpha (when given) is appended as the last component (RRGGBBAA), and every channel is zero-padded to two digits.

Parameters

• r (int)
• g (int)
• b (int)
• a (?int)

Returns string

rgb_to_hsl()

colors.rgb_to_hsl(r: int, g: int, b: int) -> list[float]

Converts a RGB color into its corresponding HSL components.

Parameters

• r (int)
• g (int)
• b (int)

Returns list[float]

rgb_to_hsv()

colors.rgb_to_hsv(r: int, g: int, b: int) -> list[float]

Converts a RGB color into its corresponding HSV components.

Parameters

• r (int)
• g (int)
• b (int)

Returns list[float]

rgb_to_hwb()

colors.rgb_to_hwb(r: int, g: int, b: int) -> list[float]

Converts a RGB color into its corresponding HWB components.

Parameters

• r (int)
• g (int)
• b (int)

Returns list[float]

rgb_to_cmyk()

colors.rgb_to_cmyk(r: int, g: int, b: int) -> list[float]

Converts a RGB color into its corresponding CMYK components.

Parameters

• r (int)
• g (int)
• b (int)

Returns list[float]

rgb_to_xyz()

colors.rgb_to_xyz(r: int, g: int, b: int) -> list[float]

Converts a RGB color into its corresponding XYZ color space components.

Parameters

• r (int)
• g (int)
• b (int)

Returns list[float]

rgb_to_lab()

colors.rgb_to_lab(r: int, g: int, b: int) -> list[float]

Converts a RGB color into its corresponding LAB color components.

Parameters

• r (int)
• g (int)
• b (int)

Returns list[float]

hsl_to_rgb()

colors.hsl_to_rgb(h: number, s: number, l: number) -> list[float]

Converts a HSL color into its corresponding RGB color components.

Parameters

• h (number)
• s (number)
• l (number)

Returns list[float]

hsl_to_hsv()

colors.hsl_to_hsv(h: number, s: number, l: number) -> list[float]

Converts a HSL color into its corresponding HSV color components.

Parameters

• h (number)
• s (number)
• l (number)

Returns list[float]

hsv_to_rgb()

colors.hsv_to_rgb(h: number, s: number, v: number) -> list[float]

Converts a HSV color into its corresponding RGB color components.

Parameters

• h (number)
• s (number)
• v (number)

Returns list[float]

hsv_to_hsl()

colors.hsv_to_hsl(h: number, s: number, v: number) -> list[float]

Converts a HSV color into its corresponding HSL color components.

Parameters

• h (number)
• s (number)
• v (number)

Returns list[float]

hwb_to_rgb()

colors.hwb_to_rgb(h: number, w: number, b: number) -> list[float]

Converts a HWB color into its corresponding RGB color components.

Parameters

• h (number)
• w (number)
• b (number)

Returns list[float]

cmyk_to_rgb()

colors.cmyk_to_rgb(c: number, m: number, y: number, k: number) -> list[float]

Converts a CMYK color into its corresponding RGB color components.

Parameters

• c (number)
• m (number)
• y (number)
• k (number)

Returns list[float]

xyz_to_rgb()

colors.xyz_to_rgb(x: number, y: number, z: number) -> list[float]

Converts a XYZ color into its corresponding RGB color components.

Parameters

• x (number)
• y (number)
• z (number)

Returns list[float]

lab_to_rgb()

colors.lab_to_rgb(l: number, a: number, b: number) -> list[float]

Converts a LAB color into its corresponding RGB color components. The inverse of rgb_to_lab.

Parameters

• l (number)
• a (number)
• b (number)

Returns list[float]

lighten()

colors.lighten(hex: string, amount: number) -> string

Returns hex lightened by amount percentage points in HSL space (clamped to 0-100).

Parameters

• hex (string)
• amount (number)

Returns string

darken()

colors.darken(hex: string, amount: number) -> string

Returns hex darkened by amount percentage points in HSL space (clamped to 0-100). The inverse of lighten.

Parameters

• hex (string)
• amount (number)

Returns string

saturate()

colors.saturate(hex: string, amount: number) -> string

Returns hex with its saturation increased by amount percentage points in HSL space (clamped to 0-100).

Parameters

• hex (string)
• amount (number)

Returns string

desaturate()

colors.desaturate(hex: string, amount: number) -> string

Returns hex with its saturation decreased by amount percentage points in HSL space (clamped to 0-100). The inverse of saturate.

Parameters

• hex (string)
• amount (number)

Returns string

grayscale()

colors.grayscale(hex) -> string

Returns hex fully desaturated (HSL saturation set to 0), the same hue and lightness otherwise preserved. This is an HSL desaturation, not a perceptual-luminance-weighted grayscale.

Parameters

• hex (string)

Returns string

invert()

colors.invert(hex: string) -> string

Returns hex with each RGB channel inverted (255 - channel). Alpha, if present, is left unchanged.

Parameters

• hex (string)

Returns string

mix()

colors.mix(hex_a: string, hex_b: string, weight: ?number) -> string

Linearly interpolates between two colors, including their alpha channels.

Parameters

• hex_a (string)
• hex_b (string)
• weight (?number) — How far from hex_a (0) to hex_b (1). Default: 0.5 (the midpoint).

Returns string

relative_luminance()

colors.relative_luminance(r, g, b) -> number

Returns the relative luminance of an RGB color, from 0 (black) to 1 (white), as defined by WCAG 2.x.

This is perceived brightness in linear light, not the l of HSL: pure green is far brighter to the eye than pure blue even though HSL gives both a lightness of 0.5. It is what contrast_ratio() is built on, and what to compare against a threshold when deciding whether light or dark text belongs on a background.

%> import colors
%> colors.relative_luminance(255, 255, 255)
1
%> colors.relative_luminance(0, 255, 0)
0.7152

Parameters

• r (int)
• g (int)
• b (int)

Returns number

contrast_ratio()

colors.contrast_ratio(hex_a: string, hex_b: string) -> number

Returns the WCAG 2.x contrast ratio between two colors, from 1 (no contrast) to 21 (black on white).

A ratio of at least 4.5 meets WCAG AA for normal text (3 for large text); 7 meets AAA (4.5 for large text).

Parameters

• hex_a (string)
• hex_b (string)

Returns number

named()

colors.named(name: string) -> string

Returns the hexadecimal value of a CSS named color.

Matching ignores case, whitespace, hyphens and underscores, so 'Tomato', 'tomato' and ' TOMATO ' all resolve, as do both 'darkseagreen' and 'Dark Sea Green'.

The result carries no leading #, the same as [[colors.rgb_to_hex]] and [[colors.lighten]], so it can be handed straight to any function here that takes a hexadecimal color. Every name returns 6 digits except transparent, which returns the 8-digit '00000000'.

%> import colors
%> colors.named('rebeccapurple')
'663399'
%> colors.named('Dark Sea Green')
'8fbc8f'

Parameters

• name (string)

Returns string

Raises ValueError When name is not a CSS color name.

Note: Spaces inside the name are ignored, so both the CSS spelling and the spaced-out reading of a name resolve to the same color.

is_named()

colors.is_named(name) -> bool

Returns true if name is a CSS color name that [[colors.named]] would resolve, and false otherwise.

Parameters

• name (string)

Returns bool

2022, Richard Ore and The Zuri Contributors