Skip to main content

Hued

PyPI Version Python Versions CI PyPI Trusted Publishing PEP 740 Provenance SLSA Build Provenance Code Size Downloads License Compliance

Documentation · Changelog · PyPI

An open-source, zero-dependency Python library for color space conversion, WCAG 2.1 accessibility analysis, perceptual color difference (CIEDE2000), color-blindness simulation, harmonious palette & gradient generation, and named color lookup.

Changes in version 1.1.0

See CHANGELOG.md for the full list of fixes and additions.

  • Correctness & color-science fixes:
    • Fixed xyz_to_rgb (and xyz_to_*) crashing with complex numbers on pure red, pure green, and other saturated colors; updated sRGB ↔ XYZ conversions to the exact IEC 61966-2-1 D65 specification for lossless round-trips.
    • Fixed rgb_to_linear and get_luminance to follow the exact IEC 61966-2-1 / WCAG 2.1 sRGB transfer function.
    • Fixed get_text_color_from_background returning unreadable text on black, charcoal, yellow, cyan, lime, and silver backgrounds — now guarantees maximum WCAG 2.1 contrast.
    • Fixed check_color_quality (previously always returned True for all 16.7M RGB colors), simulate_color_blindness (preserved exact neutral grays and linear luminance), get_temperature, is_pastel, is_muted, hex_to_rgb (added #RGB shorthand and strict validation), direct lossless hsl_to_hsv/hsv_to_hsl, blend_colors, and ColorPalette edge cases (generate_monochromatic(1), palette_to_hex() on random palette dicts, rectangular generate_tetradic(), and export_palette() extension handling).
    • Cleaned the named color catalog (removed scraped citation/vandalism artifacts, resolved duplicate names, preserved acronym casing, and added all missing W3C CSS Level 4 named colors including Green, Orange, Purple, Brown, Gold, and Lavender).
  • New features:
    • Full CIE 1976 L*a*b* conversion suite (rgb_to_lab, lab_to_rgb, hex_to_lab, lab_to_hex, xyz_to_lab, lab_to_xyz, hsl_to_lab, hsv_to_lab, cmyk_to_lab, and inverses).
    • Perceptual color difference delta_e (CIEDE2000 and CIE76) and full WCAG 2.1 report check_wcag_contrast.
    • Color utilities: linear_to_rgb, invert_color, to_grayscale, adjust_lightness, adjust_saturation, and linear-light blend_colors(..., linear=True).
    • Perceptual closest-color matching (space="lab" / "cie2000"), get_color_by_hex, search_colors, get_random_color, add_color, and remove_color on ColorManager.
    • Perceptual gradients (space="rgb" | "linear" | "lab" | "hsl") and .css custom-property export on ColorPalette.
    • Full inline type annotations (py.typed), modern pyproject.toml, automated test suite, and PyPI Trusted Publishing with PEP 740 & SLSA build provenance attestations.
Earlier releases (1.0.3 – 1.0.7)

Changes in version 1.0.7

  • 2 new functions in hued.analysis for testing color visibility/quality and simulating color blindness.

Changes in version 1.0.6

  • New methods under ColorPalette to create gradients and export ColorPalette data as CSV, TXT, or JSON.

Changes in version 1.0.5

  • Conversion functions for XYZ / CIE 1931 XYZ.

Changes in version 1.0.4

  • Updated colors.py with 500+ additional color names.

Changes in version 1.0.3

  • Added rgb_to_linear, get_luminance, get_vibrancy, color_contrast, and get_text_color_from_background to hued.analysis.
  • Added blend_colors and cross-format conversion helpers to hued.conversions.
  • Added additional harmony schemes and random color generators to ColorPalette.

Installation

pip install hued

Supported Python versions: Python 3.9+ (CI-tested across Python 3.10–3.14). Zero external runtime dependencies.

Features

  • Color Conversions: Lossless and validated conversions across RGB, HEX (#RRGGBB and #RGB), HSL, HSV, CMYK, Linear sRGB, CIE 1931 XYZ (D65), and CIE 1976 L*a*b* (D65), plus blending, inversion, grayscale, lightness, and saturation adjustments.
  • Accessibility & Analysis: WCAG 2.1 relative luminance, contrast ratios, AA/AAA compliance checks, optimal foreground text selection, CIEDE2000 / CIE76 perceptual color difference (delta_e), color-blindness simulation, and temperature/pastel/muted/vibrant classification.
  • Color Palettes & Gradients: Complementary, split-complementary, analogous, triadic, rectangular tetradic, square, and monochromatic harmonies; multi-space gradients (rgb, linear, lab, hsl); export to .json, .csv, .txt, and .css.
  • Named Colors: 1,300+ named colors (including all 148 W3C CSS Color Level 4 names) with exact lookup, CSS-token matching, substring search, and RGB / L*a*b* / CIEDE2000 closest-color matching.
  • Fully Typed: Ships a PEP 561 py.typed marker and complete inline annotations.

Usage

Named Colors

from hued import ColorManager

cm = ColorManager()

blue = cm.get_color_by_name("Blue")
print(blue)  # {'Name': 'Blue', 'Hex': '#0000FF', 'RGB': (0, 0, 255)}

# Find the perceptually closest named color using CIEDE2000
print(cm.closest_color_name("#FF5733", space="cie2000"))

# Search and pick random named colors
print(len(cm.search_colors("cerulean")))
print(cm.get_random_color())

Color Conversion & Manipulation

from hued import (
    adjust_lightness,
    blend_colors,
    hex_to_rgb,
    rgb_to_hsl,
    rgb_to_lab,
)

rgb = hex_to_rgb("#FF5733")      # (255, 87, 51) — 3-digit '#F53' also works
hsl = rgb_to_hsl(*rgb)           # (10.59, 1.0, 0.6)
lab = rgb_to_lab(*rgb)           # CIE 1976 L*a*b* (D65)

mixed = blend_colors((255, 0, 0), (0, 255, 0), 0.5, linear=True)
lighter = adjust_lightness(rgb, 0.15)

Accessibility, Contrast & Perceptual Analysis

from hued import (
    check_wcag_contrast,
    delta_e,
    get_temperature,
    get_text_color_from_background,
    is_pastel,
    simulate_color_blindness,
)

print(is_pastel((255, 200, 200)))                      # True
print(get_temperature((255, 215, 0)))                  # 'Warm'
print(get_text_color_from_background((255, 255, 0)))   # 'dark'
print(check_wcag_contrast((20, 20, 20), (255, 255, 255)))
print(round(delta_e((255, 0, 0), (240, 15, 10)), 2))   # CIEDE2000
print(simulate_color_blindness((220, 50, 80), "deuteranopia"))

Palettes, Gradients & Export

from hued import ColorPalette

palette = ColorPalette((255, 60, 52))
print(palette.generate_complementary())
print(palette.generate_tetradic())  # Rectangular double-complementary

# Perceptually smooth gradient in CIE L*a*b* space
gradient = palette.generate_gradient((255, 60, 52), (51, 247, 255), steps=5, space="lab")

# Export palettes to .json, .csv, .txt, or .css
palette.export_palette("palette.css")

Release Provenance & Verification

Releases of hued are published directly from GitHub Actions using PyPI OIDC Trusted Publishing (no long-lived API tokens) with automatic PEP 740 digital provenance attestations on PyPI and SLSA v1.0 build provenance attestations on GitHub.

You can verify any downloaded distribution artifact with the GitHub CLI:

gh attestation verify hued-*.whl --repo Infinitode/Hued

Contributing

Contributions are welcome! See CONTRIBUTING.md for development setup and testing instructions, or open an issue / pull request on GitHub.

License

Hued is released under the terms of the MIT License (Modified). See LICENSE for the full text.

Modified License Clause: Derivative works based on Hued are permitted provided that any substantial changes are clearly distinguished from the original work and distributed under a different name.

Metadata

Release files for hued 1.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for hued 1.1.0
File Size Uploaded Provenance Actions
hued-1.1.0.tar.gz 42.9 kB With provenance Details for hued-1.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for hued 1.1.0
File Interpreter ABI Platform Actions
hued-1.1.0-py3-none-any.whl Python 3 none any Details for hued-1.1.0-py3-none-any.whl

Total release size: 83.0 kB

Release files / hued-1.1.0.tar.gz

Download URL hued-1.1.0.tar.gz
Size 42.9 kB
Tags Source
SHA-256 checksum
How to use checksums
cd737cda53e922c06bc35e362a2eaa58b837db3ddc51909100b7dfeabbee1c45
BLAKE2b-256 checksum
How to use checksums
62bfc28ac873de0094f83c657428dab6873b7a41de9cb4d30ddb392c152d27c3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Release files / hued-1.1.0-py3-none-any.whl

Download URL hued-1.1.0-py3-none-any.whl
Size 40.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d539b0b1ac0b251df902ce066031d15ccb50495bf9570744e232e80183bd2f1c
BLAKE2b-256 checksum
How to use checksums
266908a72c9c8035f3387219a414f046a7fe65d08399c3a4cb435407f98cea67
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Security for hued 1.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for hued-1.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page