color_tools._color_utils

Canonical strict RGB validation, hex parsing, and hex formatting.

Library code that uses these contracts must delegate to this module instead of reimplementing them. Format-specific boundary adapters may still parse transport syntax or present errors differently; output clipping, array processing, and color-space conversion are separate responsibilities.

color_tools._color_utils.validate_rgb(rgb)

Check that RGB contains exactly three built-in integers in 0-255.

Channels are interpreted as red, green, and blue, in that order. Both endpoints are allowed. Booleans, floats (including integral floats), and subclasses of int are rejected because each channel must have type int. Values are not converted, rounded, or clamped, and the input is not modified. Only tuple and list containers are accepted.

Parameters:

rgb (object) – Three 8-bit RGB channels to validate.

Return type:

None

Returns:

None when all checks pass.

Raises:

ValueError – If the channel count is not three, a channel is not a built-in integer, or a channel is outside the inclusive 0-255 range.

Example

>>> validate_rgb((255, 127, 0))

color_tools._color_utils.parse_hex(hex_code)

Validate an RGB hex string and return its three 8-bit integer channels.

Accepts three, four, six, or eight ASCII hexadecimal digits, optionally preceded by one #. Digits are case-insensitive. Short form repeats each digit, so #24c becomes #2244cc. Four/eight-digit forms use CSS/PNG RGBA order, not Windows/Android ARGB. Alpha is validated but dropped for now. Whitespace, multiple # prefixes, and non-ASCII hex digits are rejected.

Parameters:

hex_code (object) – RGB/RGBA/RRGGBB/RRGGBBAA, with an optional leading #.

Return type:

tuple[int, int, int]

Returns:

A (red, green, blue) tuple of integers in the inclusive 0-255 range.

Raises:

ValueError – If the input type or syntax is invalid.

Example

>>> parse_hex("#24c")
(34, 68, 204)

color_tools._color_utils.parse_hex_colors(hex_code)

Parse ordered components separated by -, spaces, comma, _, /, :, or ;.

ASCII spaces may surround punctuation and the complete compound value. Repeated punctuation and empty components are errors, not discarded colors. All components are validated, including alpha, and duplicates are retained. Any positive number of components is supported. Each uses the single-color RGB/RGBA/RRGGBB/RRGGBBAA grammar; alpha is validated then dropped.

Parameters:

hex_code (object) – Original single or compound hex string.

Return type:

tuple[tuple[int, int, int], ...]

Returns:

An immutable ordered tuple of RGB triples.

Raises:

ValueError – If the input type or any component is invalid.

Example

>>> parse_hex_colors("#f00 / #00f")
((255, 0, 0), (0, 0, 255))

color_tools._color_utils.format_hex(rgb)

Return normalized #RRGGBB after strict validation, without clipping.

Return type:

str

Parameters:

rgb (tuple[int, int, int] | list[int])

color_tools._color_utils.normalize_hex(hex_code)

Return a validated single color in canonical uppercase #RRGGBB form.

Short forms are expanded and valid CSS/PNG alpha-last components are discarded according to parse_hex()’s contract.

Parameters:

hex_code (str) – RGB, RGBA, RRGGBB, or RRGGBBAA with an optional leading #.

Return type:

str

Returns:

The parsed RGB color formatted as uppercase #RRGGBB.

Raises:

ValueError – If the input type or syntax is invalid.

Example

>>> normalize_hex("#a1c8")
'#AA11CC'