XulbuX

Appearance

Color Module ​

Provides color manipulation across RGBA, HSLA, and hex spaces.
Includes dedicated classes for each color model, conversions, parsing, luminance calculation, color adjustments, and gradient generation.

rgba ​

python
class rgba(self, red: int, green: int, blue: int, alpha: float | None = None, /, *, _validate: bool = True)

An RGB/RGBA color object that includes a bunch of methods to manipulate the color.

  • red – The red channel in range [0, 255] inclusive.
  • green – The green channel in range [0, 255] inclusive.
  • blue – The blue channel in range [0, 255] inclusive.
  • alpha – The alpha channel in range [0.0, 1.0] inclusive or None if the color has no alpha channel.

Example Usage ​

python
from xulbux import rgba

color = rgba(30, 144, 255)  # Dodger Blue

# Adjust color properties:
lighter = color.lighten(0.2)
darker = color.darken(0.15)
blended = color.blend(rgba(255, 0, 0), ratio=0.5)

# Convert to other color spaces:
hex_str = color.as_hexa()  # #1E90FF
hsl_obj = color.as_hsla()  # hsla(210°, 100%, 56%)

.has_alpha() ​

python
def has_alpha(self) -> bool

Returns True if the color has an alpha channel and False otherwise.

.is_opaque() ​

python
def is_opaque(self) -> bool

Returns True if the color has no transparency.

.as_tuple() ​

python
def as_tuple(self) -> tuple[int, int, int, float | None]

Returns the color components as a tuple (red, green, blue, alpha).

.as_dict() ​

python
def as_dict(self) -> RgbaDict

Returns the color components as a dictionary with keys "red", "green", "blue" and optionally "alpha".

.as_rgba() ​

python
def as_rgba(self) -> rgba

Returns the color as rgba() color object.

.as_hsla() ​

python
def as_hsla(self) -> hsla

Returns the color as hsla() color object.

.as_hexa() ​

python
def as_hexa(self) -> hexa

Returns the color as hexa() color object.

.lighten() ​

python
def lighten(self, amount: float, /) -> rgba

Increases the colors lightness by the specified amount in range [0.0, 1.0] inclusive.

.darken() ​

python
def darken(self, amount: float, /) -> rgba

Decreases the colors lightness by the specified amount in range [0.0, 1.0] inclusive.

.saturate() ​

python
def saturate(self, amount: float, /) -> rgba

Increases the colors saturation by the specified amount in range [0.0, 1.0] inclusive.

.desaturate() ​

python
def desaturate(self, amount: float, /) -> rgba

Decreases the colors saturation by the specified amount in range [0.0, 1.0] inclusive.

.rotate() ​

python
def rotate(self, degrees: int, /) -> rgba

Rotates the colors hue by the specified number of degrees.

.invert() ​

python
def invert(self, *, invert_alpha: bool = False) -> rgba

Inverts the color by rotating hue by 180 degrees and inverting lightness.

.grayscale() ​

python
def grayscale(self, *, method: Literal["wcag2", "wcag3", "simple", "bt601"] = "wcag2") -> rgba

Converts the color to grayscale using the luminance formula.

  • method – The luminance calculation method to use:
    • "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)

.blend() ​

python
def blend(self, other: Rgba, /, ratio: float = 0.5, *, additive_alpha: bool = False) -> rgba

Blends the current color with another color using the specified ratio in range [0.0, 1.0] inclusive.

  • other – The other RGBA color to blend with.
  • ratio – The blend ratio between the two colors:
    • 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).
  • additive_alpha – Whether to blend the alpha channels additively or not.

.is_dark() ​

python
def is_dark(self) -> bool

Returns True if the color is considered dark (lightness < 50%).

.is_light() ​

python
def is_light(self) -> bool

Returns True if the color is considered light (lightness >= 50%).

.is_grayscale() ​

python
def is_grayscale(self) -> bool

Returns True if the color is grayscale.

.with_alpha() ​

python
def with_alpha(self, alpha: float | None, /) -> rgba

Returns a new color with the specified alpha value, or None to clear alpha.

.complementary() ​

python
def complementary(self) -> rgba

Returns the complementary color (180 degrees on the color wheel).

hsla ​

python
class hsla(self, hue: int, sat: int, light: int, alpha: float | None = None, /, *, _validate: bool = True)

A HSL/HSLA color object that includes a bunch of methods to manipulate the color.

  • hue – The hue channel in range [0, 360] inclusive.
  • sat – The saturation channel in range [0, 100] inclusive.
  • light – The lightness channel in range [0, 100] inclusive.
  • alpha – The alpha channel in range [0.0, 1.0] inclusive or None if the color has no alpha channel.

Example Usage ​

python
from xulbux import hsla

color = hsla(210, 100, 56)  # Dodger Blue

# Rotate hue and adjust saturation:
complementary = color.complementary()  # hsla(30°, 100%, 56%)
saturated = color.saturate(0.2)
desaturated = color.desaturate(0.3)

# Convert to other color spaces:
rgb_obj = color.as_rgba()  # rgba(30, 144, 255)
hex_obj = color.as_hexa()  # #1E90FF

.has_alpha() ​

python
def has_alpha(self) -> bool

Returns True if the color has an alpha channel and False otherwise.

.is_opaque() ​

python
def is_opaque(self) -> bool

Returns True if the color has no transparency.

.as_tuple() ​

python
def as_tuple(self) -> tuple[int, int, int, float | None]

Returns the color components as a tuple (hue, sat, light, alpha).

.as_dict() ​

python
def as_dict(self) -> HslaDict

Returns the color components as a dictionary with keys "hue", "sat", "light" and optionally "alpha".

.as_rgba() ​

python
def as_rgba(self) -> rgba

Returns the color as rgba() color object.

.as_hsla() ​

python
def as_hsla(self) -> hsla

Returns the color as hsla() color object.

.as_hexa() ​

python
def as_hexa(self) -> hexa

Returns the color as hexa() color object.

.lighten() ​

python
def lighten(self, amount: float, /) -> hsla

Increases the colors lightness by the specified amount in range [0.0, 1.0] inclusive.

.darken() ​

python
def darken(self, amount: float, /) -> hsla

Decreases the colors lightness by the specified amount in range [0.0, 1.0] inclusive.

.saturate() ​

python
def saturate(self, amount: float, /) -> hsla

Increases the colors saturation by the specified amount in range [0.0, 1.0] inclusive.

.desaturate() ​

python
def desaturate(self, amount: float, /) -> hsla

Decreases the colors saturation by the specified amount in range [0.0, 1.0] inclusive.

.rotate() ​

python
def rotate(self, degrees: int, /) -> hsla

Rotates the colors hue by the specified number of degrees.

.invert() ​

python
def invert(self, *, invert_alpha: bool = False) -> hsla

Inverts the color by rotating hue by 180 degrees and inverting lightness.

.grayscale() ​

python
def grayscale(self, *, method: Literal["wcag2", "wcag3", "simple", "bt601"] = "wcag2") -> hsla

Converts the color to grayscale using the luminance formula.

  • method – The luminance calculation method to use:
    • "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)

.blend() ​

python
def blend(self, other: Hsla, /, ratio: float = 0.5, *, additive_alpha: bool = False) -> hsla

Blends the current color with another color using the specified ratio in range [0.0, 1.0] inclusive.

  • other – The other HSLA color to blend with.
  • ratio – The blend ratio between the two colors:
    • 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).
  • additive_alpha – whether to blend the alpha channels additively or not.

.is_dark() ​

python
def is_dark(self) -> bool

Returns True if the color is considered dark (lightness < 50%).

.is_light() ​

python
def is_light(self) -> bool

Returns True if the color is considered light (lightness >= 50%).

.is_grayscale() ​

python
def is_grayscale(self) -> bool

Returns True if the color is considered grayscale.

.with_alpha() ​

python
def with_alpha(self, alpha: float | None, /) -> hsla

Returns a new color with the specified alpha value, or None to clear alpha.

.complementary() ​

python
def complementary(self) -> hsla

Returns the complementary color (180 degrees on the color wheel).

hexa ​

python
class hexa(
        self,
        color: Hexa | None = None,
        /,
        *,
        _red: int | None = None,
        _green: int | None = None,
        _blue: int | None = None,
        _alpha: float | None = None,
    )

A hex color object that includes a bunch of methods to manipulate the color.

  • color – The hex color string (prefix optional) or hex integer, that can be in formats:
    • RGB short format without alpha (only for strings)
    • RGBA short format with alpha (only for strings)
    • RRGGBB long format without alpha (for strings and hex integers)
    • RRGGBBAA long format with alpha (for strings and hex integers)

Example Usage ​

python
from xulbux import hexa

color = hexa("#1E90FF")  # Dodger Blue

# Manipulate hex color:
lighter = color.lighten(0.2)
inverted = color.invert()

# Convert to other representations:
rgb_obj = color.as_rgba()  # rgba(30, 144, 255)
hsl_obj = color.as_hsla()  # hsla(210°, 100%, 56%)

.has_alpha() ​

python
def has_alpha(self) -> bool

Returns True if the color has an alpha channel and False otherwise.

.is_opaque() ​

python
def is_opaque(self) -> bool

Returns True if the color has no transparency.

.as_tuple() ​

python
def as_tuple(self, *, round_alpha: bool = True) -> tuple[int, int, int, float | None]

Returns the color components as a tuple (red, green, blue, alpha).

.as_dict() ​

python
def as_dict(self) -> HexaDict

Returns the color components as a dictionary with hex string values for keys "red", "green", "blue" and optionally "alpha".

.as_rgba() ​

python
def as_rgba(self, *, round_alpha: bool = True) -> rgba

Returns the color as rgba() color object.

.as_hsla() ​

python
def as_hsla(self, *, round_alpha: bool = True) -> hsla

Returns the color as hsla() color object.

.as_hexa() ​

python
def as_hexa(self) -> hexa

Returns the color as hexa() color object.

.lighten() ​

python
def lighten(self, amount: float, /) -> hexa

Increases the colors lightness by the specified amount in range [0.0, 1.0] inclusive.

.darken() ​

python
def darken(self, amount: float, /) -> hexa

Decreases the colors lightness by the specified amount in range [0.0, 1.0] inclusive.

.saturate() ​

python
def saturate(self, amount: float, /) -> hexa

Increases the colors saturation by the specified amount in range [0.0, 1.0] inclusive.

.desaturate() ​

python
def desaturate(self, amount: float, /) -> hexa

Decreases the colors saturation by the specified amount in range [0.0, 1.0] inclusive.

.rotate() ​

python
def rotate(self, degrees: int, /) -> hexa

Rotates the colors hue by the specified number of degrees.

.invert() ​

python
def invert(self, *, invert_alpha: bool = False) -> hexa

Inverts the color by rotating hue by 180 degrees and inverting lightness.

.grayscale() ​

python
def grayscale(self, *, method: Literal["wcag2", "wcag3", "simple", "bt601"] = "wcag2") -> hexa

Converts the color to grayscale using the luminance formula.

  • method – The luminance calculation method to use:
    • "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)

.blend() ​

python
def blend(self, other: Hexa, /, ratio: float = 0.5, *, additive_alpha: bool = False) -> hexa

Blends the current color with another color using the specified ratio in range [0.0, 1.0] inclusive.

  • other – The other hex color to blend with.
  • ratio – The blend ratio between the two colors:
    • 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).
  • additive_alpha – Whether to blend the alpha channels additively or not.

.is_dark() ​

python
def is_dark(self) -> bool

Returns True if the color is considered dark (lightness < 50%).

.is_light() ​

python
def is_light(self) -> bool

Returns True if the color is considered light (lightness >= 50%).

.is_grayscale() ​

python
def is_grayscale(self) -> bool

Returns True if the color is grayscale (saturation == 0).

.with_alpha() ​

python
def with_alpha(self, alpha: float | None, /) -> hexa

Returns a new color with the specified alpha value, or None to clear alpha.

.complementary() ​

python
def complementary(self) -> hexa

Returns the complementary color (180 degrees on the color wheel).

is_valid_rgba() ​

python
def is_valid_rgba(
    color: object,
    /,
    *,
    allow_alpha: bool = True,
    allow_strings: bool = True,
) -> TypeGuard[Rgba | str] | TypeGuard[Rgba]

Check if the given color is a valid RGBA color.

  • color – The color to check (can be in any supported format).
  • allow_alpha – Whether to allow alpha channel in the color.
  • allow_strings – Whether to allow color strings.

is_valid_hsla() ​

python
def is_valid_hsla(
    color: object,
    /,
    *,
    allow_alpha: bool = True,
    allow_strings: bool = True,
) -> TypeGuard[Hsla | str] | TypeGuard[Hsla]

Check if the given color is a valid HSLA color.

  • color – The color to check (can be in any supported format).
  • allow_alpha – Whether to allow alpha channel in the color.
  • allow_strings – Whether to allow color strings.

is_valid_hexa() ​

python
def is_valid_hexa(
    color: object, /, *, allow_alpha: bool = True, get_prefix: bool = False
) -> TypeGuard[Hexa] | tuple[bool, Literal["#", "0x"] | None]

Check if the given color is a valid hex color.

  • color – The color to check (can be in any supported format).
  • allow_alpha – Whether to allow alpha channel in the color.
  • get_prefix – If true, the prefix used in the color (if any)
  • is returned along with validity.

is_valid() ​

python
def is_valid(color: object, /, *, allow_alpha: bool = True) -> TypeGuard[Rgba | Hsla | Hexa]

Check if the given color is a valid RGBA, HSLA or hex color.

  • color – The color to check (can be in any supported format).
  • allow_alpha – Whether to allow alpha channel in the color.

has_alpha() ​

python
def has_alpha(color: Rgba | Hsla | Hexa, /) -> bool

Check if the given color has an alpha channel.

  • color – The color to check (can be in any supported format).

to_rgba() ​

python
def to_rgba(color: Rgba | Hsla | Hexa, /) -> rgba

Will try to convert any color type to a color of type RGBA.

  • color – The color to convert (can be in any supported format).

to_hsla() ​

python
def to_hsla(color: Rgba | Hsla | Hexa, /) -> hsla

Will try to convert any color type to a color of type HSLA.

  • color – The color to convert (can be in any supported format).

to_hexa() ​

python
def to_hexa(color: Rgba | Hsla | Hexa, /) -> hexa

Will try to convert any color type to a color of type hex.

  • color – The color to convert (can be in any supported format).

extract_rgba() ​

python
def extract_rgba(string: str, /, *, only_first: bool = False) -> rgba | list[rgba] | None

Will try to recognize RGBA colors inside a string and output the found ones as RGBA objects.

  • string – The string to search for RGBA colors.
  • only_first – If true, only the first found color will be returned, otherwise a list of all found colors.

extract_hsla() ​

python
def extract_hsla(string: str, /, *, only_first: bool = False) -> hsla | list[hsla] | None

Will try to recognize HSLA colors inside a string and output the found ones as HSLA objects.

  • string – The string to search for HSLA colors.
  • only_first – If true, only the first found color will be returned, otherwise a list of all found colors.

rgba_to_hex_int() ​

python
def rgba_to_hex_int(red: int, green: int, blue: int, alpha: float | None = None, /, *, preserve_original: bool = False) -> int

Convert RGBA channels to a hex integer (alpha is optional).

  • red, green, blue – The red, green, and blue channels in range [0, 255] inclusive.
  • alpha – The alpha channel in range [0.0, 1.0] inclusive or None if not set.
  • preserve_original – Whether to preserve the original color exactly (explained below).

To preserve leading zeros, the function will add a 1 at the beginning, if the hex integer would start with a 0.
This could affect the color a little bit, but will make sure, that it won't be interpreted as a completely different color, when initializing it as a hexa() color or changing it back to RGBA using hex_int_to_rgba().

hex_int_to_rgba() ​

python
def hex_int_to_rgba(hex_int: int, /, *, preserve_original: bool = False) -> rgba

Convert a hex integer to RGBA channels.

  • hex_int – The hex integer to convert.
  • preserve_original – Whether to preserve the original color exactly (explained below).

If the red channel is 1 after conversion, it will be set to 0, because when converting from RGBA to a hex integer, the first 0 will be set to 1 to preserve leading zeros.
This is the correction, so the color doesn't even look slightly different.

get_luminance() ​

python
def get_luminance(
    red: int,
    green: int,
    blue: int,
    /,
    *,
    output_type: type[int | float] | None = None,
    method: Literal["wcag2", "wcag3", "simple", "bt601"] = "wcag2",
) -> int | float

Calculates the relative luminance of a color according to various standards.

  • red, green, blue – The red, green and blue channels in range [0, 255] inclusive.
  • output_type – The range of the returned luminance value:
    • int returns integer in range [0, 100] inclusive.
    • float returns float in range [0.0, 1.0] inclusive.
    • None returns integer in range [0, 255] inclusive.
  • method – The luminance calculation method to use:
    • "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)

get_text_fg() ​

python
def get_text_fg(text_bg_color: Rgba | Hexa, /) -> rgba | hexa | int

Returns either black or white text color for optimal contrast on the given background color.

  • text_bg_color – The background color (can be in RGBA or hex format).

adjust_lightness() ​

python
def adjust_lightness(color: Rgba | Hexa, light_change: float, /) -> rgba | hexa

In- or decrease the lightness of the input color.

  • color – The color to adjust (can be in RGBA or hex format).
  • light_change – The amount to change the lightness by, in range -1.0 (darken by 100%) and 1.0 (lighten by 100%).

adjust_saturation() ​

python
def adjust_saturation(color: Rgba | Hexa, sat_change: float, /) -> rgba | hexa

In- or decrease the saturation of the input color.

  • color – The color to adjust (can be in RGBA or hex format).
  • sat_change – The amount to change the saturation by, in range -1.0 (saturate by 100%) and 1.0 (desaturate by 100%).

ColorStop ​

python
type ColorStop = Rgba | Hsla | Hexa | tuple[Rgba | Hsla | Hexa, float | int]

A color stop for gradient generation: a color value or a (color, position) tuple.

interpolate_color() ​

python
def interpolate_color(
    color1: Rgba | Hsla | Hexa,
    color2: Rgba | Hsla | Hexa,
    /,
    *,
    ratio: float = 0.5,
    space: Literal["rgb", "hsl", "hsl_long", "linear_rgb", "oklab"] = "hsl",
) -> rgba

Linearly interpolates between two colors in the specified color space.

  • color1 – The starting color (RGBA, HSLA, hex, or tuple).
  • color2 – The ending color (RGBA, HSLA, hex, or tuple).
  • ratio – The blend ratio between 0.0 (100% color1) and 1.0 (100% color2).
  • space – The color space to interpolate in ("rgb", "hsl", "hsl_long", "linear_rgb", or "oklab"). Default is "hsl".

Raises ValueError if space is invalid.

create_gradient() ​

python
def create_gradient(
    colors: Sequence[ColorStop],
    /,
    *,
    steps: int = 10,
    space: Literal["rgb", "hsl", "hsl_long", "linear_rgb", "oklab"] = "hsl",
) -> tuple[rgba, ...]

Creates a tuple of steps smoothly interpolated colors across the given color stops.

  • colors – Sequence of colors or (color, position) tuples defining the gradient stops.
  • steps – Total number of color steps to generate. Default is 10.
  • space – The color space to interpolate in ("rgb", "hsl", "hsl_long", "linear_rgb", or "oklab"). Default is "hsl".

Raises ValueError if steps < 1, colors is empty, or space is invalid.

Released under the MIT License.

✨ From XulbuX ✨