color_tools.validation

Color validation functions to check if a hex code matches a color name. Uses fuzzy matching and perceptual color distance (Delta E 2000). Useful for validating imported color data or user input.

Note: For best fuzzy matching results, install the optional fuzzywuzzy package:: pip install fuzzywuzzy

A hybrid fallback matcher (exact/substring/Levenshtein) is used when fuzzywuzzy is not available.

class color_tools.validation.ColorValidationRecord(is_match, name_match, name_confidence, hex_value, suggested_hex, delta_e, message)[source]

Bases: object

Result record from validating if a hex code matches a color name.

This immutable dataclass contains comprehensive validation results including fuzzy name matching confidence, perceptual color distance (Delta E), and helpful suggestions for mismatches.

is_match: True if the color name and hex code are a good match

name_match: Best matching CSS color name from the database (e.g., “lightblue”)

name_confidence: Fuzzy matching confidence 0.0-1.0 (1.0 = exact match)

hex_value: The hex code that was validated (normalized with # prefix)

suggested_hex: Suggested hex code for the matched name, or None if exact match

delta_e: Perceptual color distance (Delta E 2000) between provided and suggested colors

message: Human-readable validation result message

Example

>>> from color_tools.validation import validate_color
>>> result = validate_color("light blue", "#ADD8E6")
>>> print(f"Match: {result.is_match}")
Match: True
>>> print(f"Matched '{result.name_match}' with {result.name_confidence:.0%} confidence")
Matched 'lightblue' with 100% confidence
>>> print(f"Delta E: {result.delta_e:.2f}")
Delta E: 0.00

Parameters:

is_match (bool)
name_match (Optional[str])
name_confidence (float)
hex_value (str)
suggested_hex (Optional[str])
delta_e (float)
message (str)

is_match: bool

name_match: Optional[str]

name_confidence: float

hex_value: str

suggested_hex: Optional[str]

delta_e: float

message: str

__str__()[source]

Human-readable validation result.

Return type:: str

__init__(is_match, name_match, name_confidence, hex_value, suggested_hex, delta_e, message)

Parameters:

is_match (bool)
name_match (Optional[str])
name_confidence (float)
hex_value (str)
suggested_hex (Optional[str])
delta_e (float)
message (str)

color_tools.validation.validate_color(color_name, hex_code, de_threshold=20.0)[source]

Validates if a given hex code approximately matches a given color name.

Parameters:

color_name (str) – The name of the color to check (e.g., “light red”).
hex_code (str) – The hex code to validate (e.g., “#FFC0CB”).
de_threshold (float) – The Delta E 2000 threshold for a color to be considered a match. Lower is stricter. Default is 20.0.

Return type:

ColorValidationRecord

Returns:

A ColorValidationRecord with the validation results.

Note

Uses fuzzywuzzy for fuzzy matching if available, otherwise falls back to a hybrid matcher using exact/substring/Levenshtein matching.