HexTerm

Module: terminaltexteffects.utils.hexterm

Mappings for XTerm-256 color codes and helper functions for converting between RGB hex colors and XTerm-256 color codes.

Functions:

Name	Description
hex_to_xterm	Convert RGB Hex colors to their closest XTerm-256 color.
xterm_to_hex	Convert XTerm-256 color codes to RGB Hex colors.
is_valid_color	Check if the input is a valid XTerm-256 or RGB hex color code.

hex_to_xterm(hex_color)

Convert RGB Hex colors to their closest XTerm-256 color.

Closeness is determined by the mean absolute difference across the red, green, and blue channels.

Parameters:

Name	Type	Description	Default
hex_color	str	RGB Hex color code, '#' is optional	required

Returns:

Name	Type	Description
int	int	(0-255) XTerm-256 color code

Source code in terminaltexteffects/utils/hexterm.py

def hex_to_xterm(hex_color: str) -> int:
    """Convert RGB Hex colors to their closest XTerm-256 color.

    Closeness is determined by the mean absolute difference across the red, green,
    and blue channels.

    Args:
        hex_color (str): RGB Hex color code, '#' is optional

    Returns:
        int: (0-255) XTerm-256 color code

    """
    # Strip '#' if present and convert hex to RGB
    color_string = hex_color.strip("#")
    input_rgb = tuple(int(color_string[i : i + 2], 16) for i in range(0, 6, 2))

    # Compute the differences between input color and each xterm color
    min_diff = float("inf")

    for xterm_color, xterm_rgb in xterm_to_rgb_map.items():
        diff = sum(abs(input_rgb[i] - xterm_rgb[i]) for i in range(3)) / 3
        if diff < min_diff:
            min_diff = diff
            closest_color = xterm_color

    return closest_color  # type: ignore[unbound]

is_valid_color(color)

Check if the input is a valid XTerm-256 or RGB hex color code.

Parameters:

Name	Type	Description	Default
color	int | str	X-Term 256 color code or RGB Hex color code, '#' is optional	required

Returns:

Name	Type	Description
bool	bool	True if the input is a valid color code

Source code in terminaltexteffects/utils/hexterm.py

def is_valid_color(color: int | str) -> bool:
    """Check if the input is a valid XTerm-256 or RGB hex color code.

    Args:
        color (int | str): X-Term 256 color code or RGB Hex color code, '#' is optional

    Returns:
        bool: True if the input is a valid color code

    """
    if isinstance(color, str):
        if len(color.lstrip("#")) not in [6, 7]:
            return False
        try:
            int(color.strip("#"), 16)
        except ValueError:
            return False
        return True
    return color in range(256)

xterm_to_hex(xterm_color)

Convert XTerm-256 color code to RGB Hex color code.

Parameters:

Name	Type	Description	Default
xterm_color	int	(0-255) XTerm-256 color code	required

Returns:

Name	Type	Description
str	str	RGB hex color code without a leading #.

Raises:

Type	Description
ValueError	The input is not a valid XTerm-256 color code (0-255).

Source code in terminaltexteffects/utils/hexterm.py

def xterm_to_hex(xterm_color: int) -> str:
    """Convert XTerm-256 color code to RGB Hex color code.

    Args:
        xterm_color (int): (0-255) XTerm-256 color code

    Returns:
        str: RGB hex color code without a leading `#`.

    Raises:
        ValueError: The input is not a valid XTerm-256 color code (0-255).

    """
    if xterm_color not in xterm_to_hex_map:
        msg = f"Invalid XTerm-256 color code: {xterm_color}"
        raise ValueError(msg)
    return xterm_to_hex_map[xterm_color].strip("#")