color

rgba()

An RGBA color: is a tuple of 3 integers, representing the red (0-255), green (0-255), and blue (0-255).
It also includes an optional 4th param, which is a float, that represents the alpha channel (0.0-1.0):

rgba(
    r: int,
    g: int,
    b: int,
    a: Optional[float] = None
)

The rgba() color object can be treated like a list/tuple with the items:
0 = red channel value
1 = green channel value
2 = blue channel value
3 = alpha channel value (only if the color has an alpha channel)

If the rgba() color object is treated like a string, it will be the color in the format:
(R, G, B) if the color has no alpha channel
(R, G, B, A) if the color has an alpha channel

.dict()

This method will get the color components as a dictionary with keys 'r', 'g', 'b' and optionally 'a'.
Params: no parameters
Returns: the color as a dictionary:

{
    'r': red,
    'g': green,
    'b': blue,
    'a': alpha,  # ONLY IF THE COLOR HAS AN ALPHA CHANNEL
}

.values()

This method will get the color components as separate values R, G, B and optionally A.
Params: no parameters
Returns: the color as a tuple (R, G, B,) if the color has no alpha channel, else (R, G, B, A,)

.to_hsla()

This method will convert the current color to a HSLA color.
Params: no parameters
Returns: the converted color as a hsla() color object

.to_hexa()

This method will convert the current color to a HEXA color.
Params: no parameters
Returns: the converted color as a hexa() color object

.has_alpha()

This method will check if the current color has an alpha channel.
Params: no parameters
Returns: True if the color has an alpha channel, False otherwise

.lighten()

This method will create a lighter version of the current color.
Param: amount: float the amount to lighten the color by (0.0-1.0)
Returns: the lightened rgba() color object

.darken()

This method will create a darker version of the current color.
Param: amount: float the amount to darken the color by (0.0-1.0)
Returns: the darkened rgba() color object

.saturate()

This method will increase the saturation of the current color.
Param: amount: float the amount to saturate the color by (0.0-1.0)
Returns: the saturated rgba() color object

.desaturate()

This method will decrease the saturation of the current color.
Param: amount: float the amount to desaturate the color by (0.0-1.0)
Returns: the desaturated rgba() color object

.rotate()

This method will rotate the hue of the current color.
Param: degrees: int the amount to rotate the hue by (0-360)
Returns: the rotated rgba() color object

.invert()

This method will get the inverse color of the current color.
Param: invert_alpha: bool = False whether to invert the alpha channel as well or not
Returns: the inverse rgba() color object

.grayscale()

This method will convert the current color to grayscale (using the luminance formula).
Param: method: str = "wcag2" the luminance calculation method to use (see Luminance Method)
Returns: the grayscale rgba() color object

.blend()

This method will blend (additive) the current color with another color.
Params:

• other: Rgba the color to blend with
• ratio: float = 0.5 the weight of each color when blending (0.0-1.0)
• additive_alpha: bool = False whether to blend the alpha channels additively as well or not

Returns: the blended rgba() color

Ratio Example:

If ratio is 0.0 it means 100% of the current color and 0% of the other color (2:0 mixture)
If ratio is 0.5 it means 50% of both colors (1:1 mixture)
If ratio is 1.0 it means 0% of the current color and 100% of the other color (0:2 mixture)

.is_dark()

This method will confirm if the current color is considered dark (lightness < 50%).
Params: no parameters
Returns: True if the color is considered dark, False otherwise

.is_light()

This method will confirm if the current color is considered light (lightness >= 50%).
Params: no parameters
Returns: True if the color is considered light, False otherwise

.is_grayscale()

This method will confirm if the current color is grayscale (R = G = B).
Params: no parameters
Returns: True if the color is grayscale, False otherwise

.is_opaque()

This method will confirm if the current color has no transparency (alpha = 1.0 or no alpha channel).
Params: no parameters
Returns: True if the color is opaque, False otherwise

.with_alpha()

This method will create a new color with different alpha.
Param: alpha: float the new alpha value (0.0-1.0)
Returns: the rgba() color object with the new alpha channel value

.complementary()

This method will get the complementary color of the current color (180 degrees on the color wheel).
Params: no parameters
Returns: the complementary rgba() color object

hsla()

A HSLA color: is a tuple of 3 integers, representing hue (0-360), saturation (0-100), and lightness (0-100).
It also includes an optional 4th param, which is a float, that represents the alpha channel (0.0-1.0).

hsla(
    h: int,
    s: int,
    l: int,
    a: Optional[float] = None
)

A hsla() color object can be initialized with the three or four values mentioned above:

The hsla() color object can be treated like a list/tuple with the items:
0 = hue channel value
1 = saturation channel value
2 = lightness channel value
3 = alpha channel value (only if the color has an alpha channel)

If the hsla() color object is treated like a string, it will be the color in the format:
(H, S, L) if the color has no alpha channel
(H, S, L, A) if the color has an alpha channel

.dict()

This method will get the color components as a dictionary with keys 'h', 's', 'l' and optionally 'a'.
Params: no parameters
Returns: the color as a dictionary:

{
    'h': hue,
    's': saturation,
    'l': lightness,
    'a': alpha,  # ONLY IF THE COLOR HAS AN ALPHA CHANNEL
}

.values()

This method will get the color components as separate values H, S, L and optionally A.
Params: no parameters
Returns: the color as a tuple (H, S, L,) if the color has no alpha channel, else (H, S, L, A,)

.to_rgba()

This method will convert the current color to an RGBA color.
Params: no parameters
Returns: the converted color as a rgba() color object

.to_hexa()

This method will convert the current color to a HEXA color.
Params: no parameters
Returns: the converted color as a hexa() color object

.has_alpha()

This method will check if the current color has an alpha channel.
Params: no parameters
Returns: True if the color has an alpha channel, False otherwise

.lighten()

This method will create a lighter version of the current color.
Param: amount: float the amount to lighten the color by (0.0-1.0)
Returns: the lightened hsla() color object

.darken()

This method will create a darker version of the current color.
Param: amount: float the amount to darken the color by (0.0-1.0)
Returns: the darkened hsla() color object

.saturate()

This method will increase the saturation of the current color.
Param: amount: float the amount to saturate the color by (0.0-1.0)
Returns: the saturated hsla() color object

.desaturate()

This method will decrease the saturation of the current color.
Param: amount: float the amount to desaturate the color by (0.0-1.0)
Returns: the desaturated hsla() color object

.rotate()

This method will rotate the hue of the current color.
Param: degrees: int the amount to rotate the hue by (0-360)
Returns: the rotated hsla() color object

.invert()

This method will get the inverse color of the current color.
Param: invert_alpha: bool = False whether to invert the alpha channel as well or not
Returns: the inverse hsla() color object

.grayscale()

This method will convert the current color to grayscale (using the luminance formula).
Param: method: str = "wcag2" the luminance calculation method to use (see Luminance Method)
Returns: the grayscale hsla() color object

.blend()

This method will blend (additive) the current color with another color.
Params:

• other: Rgba the color to blend with
• ratio: float = 0.5 the weight of each color when blending (0.0-1.0)
• additive_alpha: bool = False whether to blend the alpha channels additively as well or not

Returns: the blended hsla() color

Ratio Example:

If ratio is 0.0 it means 100% of the current color and 0% of the other color (2:0 mixture)
If ratio is 0.5 it means 50% of both colors (1:1 mixture)
If ratio is 1.0 it means 0% of the current color and 100% of the other color (0:2 mixture)

.is_dark()

This method will confirm if the current color is considered dark (lightness < 50%).
Params: no parameters
Returns: True if the color is considered dark, False otherwise

.is_light()

This method will confirm if the current color is considered light (lightness >= 50%).
Params: no parameters
Returns: True if the color is considered light, False otherwise

.is_grayscale()

This method will confirm if the current color is grayscale (R = G = B).
Params: no parameters
Returns: True if the color is grayscale, False otherwise

.is_opaque()

This method will confirm if the current color has no transparency (alpha = 1.0 or no alpha channel).
Params: no parameters
Returns: True if the color is opaque, False otherwise

.with_alpha()

This method will create a new color with different alpha.
Param: alpha: float the new alpha value (0.0-1.0)
Returns: the hsla() color object with the new alpha channel value

.complementary()

This method will get the complementary color of the current color (180 degrees on the color wheel).
Params: no parameters
Returns: the complementary hsla() color object

hexa()

A HEXA color: is a string representing a hexadecimal color code (0-9, A-F) with optional alpha channel.

hexa(
    color: str | int
)

A hexa() color can be initialized with a string in the formats:
#RGB short form with no alpha channel
#RGBA short form with alpha channel
#RRGGBB normal form with no alpha channel
#RRGGBBAA normal form with alpha channel
... or as an integer in the formats:
0xRRGGBB with no alpha channel
0xRRGGBBAA with alpha channel

The hexa() color object can be treated like a list/tuple with the items:
0 = red channel value
1 = green channel value
2 = blue channel value
3 = alpha channel value (only if the color has an alpha channel)

If the hexa() color object is treated like a string, it will be the color in the format:
#RRGGBB if the color has no alpha channel
#RRGGBBAA if the color has an alpha channel

.dict()

This method will get the color components (hexadecimal as strings) as a dictionary with keys 'r', 'g', 'b' and optionally 'a'.
Returns: the color as a dictionary:

{
    'r': red_hexa,
    'g': green_hexa,
    'b': blue_hexa,
    'a': alpha,  # ONLY IF THE COLOR HAS AN ALPHA CHANNEL
}

.values()

This method will get the color components as separate values R, G, B and optionally A.
Params: no parameters
Returns: the color as a tuple (R, G, B,) if the color has no alpha channel, else (R, G, B, A,)

.to_rgba()

This method will convert the current color to an RGBA color.
Params: round_alpha: bool whether to round the alpha channel to 2 decimals, after conversion, or not
Returns: the converted color as a rgba() color object

.to_hsla()

This method will convert the current color to a HSLA color.
Params: round_alpha: bool whether to round the alpha channel to 2 decimals, after conversion, or not
Returns: the converted color as a hsla() color object

.has_alpha()

This method will check if the current color has an alpha channel.
Params: no parameters
Returns: True if the color has an alpha channel, False otherwise

.lighten()

This method will create a lighter version of the current color.
Param: amount: float the amount to lighten the color by (0.0-1.0)
Returns: the lightened hexa() color object

.darken()

This method will create a darker version of the current color.
Param: amount: float the amount to darken the color by (0.0-1.0)
Returns: the darkened hexa() color object

.saturate()

This method will increase the saturation of the current color.
Param: amount: float the amount to saturate the color by (0.0-1.0)
Returns: the saturated hexa() color object

.desaturate()

This method will decrease the saturation of the current color.
Param: amount: float the amount to desaturate the color by (0.0-1.0)
Returns: the desaturated hexa() color object

.rotate()

This method will rotate the hue of the current color.
Param: degrees: int the amount to rotate the hue by (0-360)
Returns: the rotated hexa() color object

.invert()

This method will get the inverse color of the current color.
Param: invert_alpha: bool = False whether to invert the alpha channel as well or not
Returns: the inverse hexa() color object

.grayscale()

This method will convert the current color to grayscale (using the luminance formula).
Param: method: str = "wcag2" the luminance calculation method to use (see Luminance Method)
Returns: the grayscale hexa() color object

.blend()

This method will blend (additive) the current color with another color.
Params:

• other: Rgba the color to blend with
• ratio: float = 0.5 the weight of each color when blending (0.0-1.0)
• additive_alpha: bool = False whether to blend the alpha channels additively as well or not

Returns: the blended hexa() color

Ratio Example:

If ratio is 0.0 it means 100% of the current color and 0% of the other color (2:0 mixture)
If ratio is 0.5 it means 50% of both colors (1:1 mixture)
If ratio is 1.0 it means 0% of the current color and 100% of the other color (0:2 mixture)

.is_dark()

This method will confirm if the current color is considered dark (lightness < 50%).
Params: no parameters
Returns: True if the color is considered dark, False otherwise

.is_light()

This method will confirm if the current color is considered light (lightness >= 50%).
Params: no parameters
Returns: True if the color is considered light, False otherwise

.is_grayscale()

This method will confirm if the current color is grayscale (R = G = B).
Params: no parameters
Returns: True if the color is grayscale, False otherwise

.is_opaque()

This method will confirm if the current color has no transparency (alpha = 1.0 or no alpha channel).
Params: no parameters
Returns: True if the color is opaque, False otherwise

.with_alpha()

This method will create a new color with different alpha.
Param: alpha: float the new alpha value (0.0-1.0)
Returns: the hexa() color object with the new alpha channel value

.complementary()

This method will get the complementary color of the current color (180 degrees on the color wheel).
Params: no parameters
Returns: the complementary hexa() color object

Color

This class includes all sorts of methods for working with colors in general (RGBA, HSLA and HEXA).

is_valid_rgba()

This method will confirm if the given color is a valid RGBA color.
Params:

• color: AnyRgba the color to check
• allow_alpha: bool = True whether to allow alpha channel or not

Returns: True if the color is valid, False otherwise

is_valid_hsla()

This method will confirm if the given color is a valid HSLA color.
Params:

• color: AnyHsla the color to check
• allow_alpha: bool = True whether to allow alpha channel or not

Returns: True if the color is valid, False otherwise

is_valid_hexa()

This method will confirm if the given color is a valid HEXA color.
Params:

• color: AnyHexa the color to check
• allow_alpha: bool = True whether to allow alpha channel or not
• get_prefix: bool = False whether to additionally return the HEX prefix if the color is valid

Returns:
if get_prefix is false: True if the color is valid, False otherwise
if get_prefix is true: (True, <prefix>) if the color is valid, (False, None) otherwise

is_valid()

This method will confirm if the color is a valid RGBA, HSLA or HEXA color.
Params:

• color: AnyRgba | AnyHsla | AnyHexa the color to check
• allow_alpha: bool = True whether to allow alpha channel or not

Returns: True if the color is valid, False otherwise

has_alpha()

This method will confirm if the given color has an alpha channel.
Param: color: Rgba | Hsla | Hexa the color to check
Returns: True if the color has an alpha channel, False otherwise

to_rgba()

This method will convert the given color to a rgba() color object.
Param: color: Hsla | Hexa the color to convert
Returns: the converted color as a rgba() color object

to_hsla()

This method will convert the given color to a hsla() color object.
Param: color: Rgba | Hexa the color to convert
Returns: the converted color as a hsla() color object

to_hexa()

This method will convert the given color to a hexa() color object.
Param: color: Rgba | Hsla the color to convert
Returns: the converted color as a hexa() color object

str_to_rgba()

This method will try to find RGBA colors in the given string and convert them into a rgba() color object.
Params:

• string: str the string to search in
• only_first: bool = False whether to return all found colors as a list or just one

Returns:
If only_first is true: the first found color as a rgba() color object
If only_first is false: all found colors as a list of rgba() color objects

rgba_to_hex_int()

This method will convert the given RGBA color to a HEX integer.
Params:

• r: int the red channel
• g: int the green channel
• b: int the blue channel
• a: Optional[float] = None an optional alpha channel
• preserve_original: bool = False whether to preserve the exact original color (not recommended setting this to true)

Returns: the converted color as a HEX integer

Preserve Original (RGBA to HEX int):

The problem with converting to an integer is that an integer will not preserve leading zeros.

Example:
opaque blue (no alpha): 0x0000FF ⇾ is 255 as number ⇾ back to hexadecimal representation, is 0xFF
opaque black (with alpha): 0x000000FF ⇾ is 255 as number ⇾ back to hexadecimal representation, is 0xFF

Since both colors are the same number as integers, it will lead to wrong results later on (e.g. when converting back to a color).

To fix this, if the converted HEXA color starts with zeros, the first zero will be changed to 1, so there's no leading zeros any more. This will change the color slightly, but almost unnoticeably.
If you don't want this behavior, set the preserve_original param to True.

hex_int_to_rgba()

This method will convert the given HEX integer to RGBA color channels. Params:

• hex_int: int the red channel
• preserve_original: bool = False whether to preserve the exact original color (not recommended setting this to true)

Returns: the converted RGBA color channels

Preserve Original (HEX int to RGBA):

As explained for the method rgba_to_hex_int(), if preserve_original is true while converting an RGBA color to a HEX integer, if there's leading zeros, the first leading zero will be changed to 1.

To handle this when converting back to an RGBA color, if preserve_original is true and the red channel is only 1, it will be set to 0, since it assumes that this comes from the rgba_to_hex_int() conversion.

luminance()

This method will calculate the luminance of the given R, G and B values.
Params:

• r: int the red channel
• g: int the green channel
• b: int the blue channel
• output_type: Optional[type] = None the type/range of the returned luminance value
• method: Literal["wcag2", "wcag3", "simple", "bt601"] = "wcag2" the luminance calculation method to use

Returns:
the luminance value of the given RGB values as:
 integer in [0, 100] if output_type is int
 float in [0.0, 1.0] if output_type is float
 integer in [0, 255] if output_type is None

Method:

The method param can be set to any of the following luminance calculation methods:

• "wcag2" WCAG 2.0 standard (default and most accurate for perception)
• "wcag3" Draft WCAG 3.0 standard with improved coefficients
• "simple" Simple arithmetic mean (less accurate)
• "bt601" ITU-R BT.601 standard (older TV standard)

text_color_for_on_bg()

This method will calculate if text should be black or white, depending on contrast to the given background color.
Param: text_bg_color: Rgba | Hexa the background color to check against
Returns:
the color black or white in the format of the given background color:
 rgba() color object if text_bg_color is an RGBA color
 hexa() color object if text_bg_color is a HEXA color
 HEX integer if text_bg_color is a HEX integer

adjust_lightness()

This method will adjust the lightness of the given color.
Params:

• color: Rgba | Hexa the color to adjust
• lightness_change: float the amount to adjust the lightness by, between -1.0 (darken by 100%) and 1.0 (lighten by 100%)

Returns:
the adjusted color as a rgba() color object, if the given color is an RGBA color
the adjusted color as a hexa() color object, if the given color is a HEXA color

adjust_saturation()

This method will adjust the saturation of the given color.
Params:

• color: Rgba | Hexa the color to adjust
• saturation_change: float the amount to adjust the saturation by, between -1.0 (desaturate by 100%) and 1.0 (*saturate by 100%)

Returns:
the adjusted color as a rgba() color object, if the given color is an RGBA color
the adjusted color as a hexa() color object, if the given color is a HEXA color