Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
232 changes: 207 additions & 25 deletions .github/workflows/build_and_publish.yml
Original file line number Diff line number Diff line change
@@ -1,34 +1,216 @@
name: Publish Python 🐍 distributions 📦 to PyPI

# Triggered by pushing a version tag such as `1.1.0` or `v1.1.0`.
#
# PyPI Trusted Publisher configuration (https://pypi.org/manage/project/hued/settings/publishing/):
# PyPI Project Name : hued
# Owner : Infinitode
# Repository name : Hued
# Workflow name : build_and_publish.yml
# Environment name : (leave blank)
on:
push:
tags:
- '*'
- "[0-9]*.*"
- "v[0-9]*.*"

# Strict least privilege at the workflow root; elevated permissions are granted
# only on the isolated jobs that require them.
permissions:
contents: read

concurrency:
group: publish-${{ github.ref }}
cancel-in-progress: false

jobs:
build-n-publish:
name: Build and publish Python 🐍 distributions 📦 to PyPI
build:
name: Build, test, and verify distributions
runs-on: ubuntu-latest
timeout-minutes: 15
steps:
- uses: actions/checkout@master
- name: Set up Python 3.12
uses: actions/setup-python@v3
with:
python-version: '3.12'
- name: Install pypa/setuptools
run: >-
python -m
pip install setuptools wheel
- name: Extract tag name
id: tag
run: echo ::set-output name=TAG_NAME::$(echo $GITHUB_REF | cut -d / -f 3)
- name: Update version in setup.py
run: >-
sed -i "s/{{VERSION_PLACEHOLDER}}/${{ steps.tag.outputs.TAG_NAME }}/g" setup.py
- name: Build a binary wheel
run: >-
python setup.py sdist bdist_wheel
- name: Publish distribution 📦 to PyPI
uses: pypa/gh-action-pypi-publish@master
with:
password: ${{ secrets.PYPI_API_TOKEN }}
- name: Check out repository
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
fetch-depth: 0

- name: Verify the tagged commit is on main
env:
TAG_NAME: ${{ github.ref_name }}
TAG_SHA: ${{ github.sha }}
run: |
if ! git rev-parse --verify -q refs/remotes/origin/main >/dev/null; then
git fetch --no-tags origin +refs/heads/main:refs/remotes/origin/main || true
fi
if git rev-parse --verify -q refs/remotes/origin/main >/dev/null; then
if ! git merge-base --is-ancestor "$TAG_SHA" refs/remotes/origin/main; then
echo "::error::Tag $TAG_NAME ($TAG_SHA) is not on main. Merge into main before tagging."
exit 1
fi
fi
echo "Tag $TAG_NAME is verified on main."

- name: Set up Python 3.12
uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
with:
python-version: "3.12"

- name: Install build and test tooling
run: |
python -m pip install --upgrade pip build twine
python -m pip install -e ".[dev]"

- name: Verify tag matches pyproject.toml and hued.__version__
env:
TAG_NAME: ${{ github.ref_name }}
run: |
python - <<'PY'
import os, re, sys, tomllib
import hued

raw_tag = os.environ["TAG_NAME"]
tag_version = raw_tag[1:] if raw_tag.startswith("v") else raw_tag
if not re.fullmatch(r"[0-9]+\.[0-9]+\.[0-9]+((a|b|rc)[0-9]+|\.post[0-9]+|\.dev[0-9]+)?", tag_version):
sys.exit(f"Tag {raw_tag!r} is not a valid PEP 440 release version.")

with open("pyproject.toml", "rb") as fh:
project_version = tomllib.load(fh)["project"]["version"]

if tag_version != project_version or tag_version != hued.__version__:
sys.exit(
f"Version mismatch: tag={tag_version!r}, "
f"pyproject.toml={project_version!r}, "
f"hued.__version__={hued.__version__!r}"
)
print(f"Verified release version: {tag_version} (from tag {raw_tag})")
PY

- name: Lint and run test suite
run: |
ruff check .
python -m pytest -q

- name: Build sdist and wheel
run: |
python -m build
python -m twine check --strict dist/*

- name: Smoke-test built wheel in clean virtualenv
run: |
python -m venv /tmp/smoke-venv
/tmp/smoke-venv/bin/pip install --no-index --find-links=dist hued
/tmp/smoke-venv/bin/python -c "import hued; assert hued.rgb_to_hex(255, 0, 0) == '#FF0000'; print('Smoke test OK:', hued.__version__)"

- name: Upload built distributions
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: python-package-distributions
path: dist/
if-no-files-found: error
retention-days: 7

publish:
name: Publish to PyPI (OIDC Trusted Publishing)
needs: build
runs-on: ubuntu-latest
timeout-minutes: 15
# NOTE: `environment` is intentionally omitted to match the blank environment
# configured in Hued's PyPI Trusted Publisher settings.
permissions:
id-token: write # Required for PyPI OIDC Trusted Publishing & PEP 740 provenance attestations
steps:
- name: Download built distributions
uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
with:
name: python-package-distributions
path: dist/

- name: Publish distributions and PEP 740 attestations to PyPI
uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3
with:
packages-dir: dist/
attestations: true

- name: Write publish summary
env:
TAG_NAME: ${{ github.ref_name }}
run: |
VERSION="${TAG_NAME#v}"
{
echo "### Published to PyPI 📦"
echo ""
echo "| Field | Value |"
echo "| --- | --- |"
echo "| Package | \`hued\` |"
echo "| Version | \`${VERSION}\` |"
echo "| Tag | \`${TAG_NAME}\` |"
echo "| Auth | PyPI OIDC Trusted Publishing (blank environment) |"
echo "| Provenance | PEP 740 Digital Attestations (\`attestations: true\`) |"
echo "| PyPI URL | https://pypi.org/project/hued/${VERSION}/ |"
} >> "$GITHUB_STEP_SUMMARY"

attest:
name: Attest SLSA build provenance
needs: publish
runs-on: ubuntu-latest
timeout-minutes: 10
permissions:
contents: read
id-token: write
attestations: write
steps:
- name: Download built distributions
uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
with:
name: python-package-distributions
path: dist/

- name: Generate GitHub SLSA build provenance attestation
id: attest
uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 # v4.2.2
with:
subject-path: "dist/*"

- name: Write attestation summary
env:
ATTESTATION_URL: ${{ steps.attest.outputs.attestation-url }}
REPO: ${{ github.repository }}
run: |
{
echo "### SLSA Build Provenance 🔐"
echo ""
echo "- Attestation bundle: ${ATTESTATION_URL}"
echo "- All attestations: https://github.com/${REPO}/attestations"
echo "- Verify locally: \`gh attestation verify <wheel-or-sdist> --repo ${REPO}\`"
} >> "$GITHUB_STEP_SUMMARY"

release:
name: Create GitHub Release
needs: [publish, attest]
runs-on: ubuntu-latest
timeout-minutes: 10
permissions:
contents: write
steps:
- name: Download built distributions
uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
with:
name: python-package-distributions
path: dist/

- name: Create GitHub Release (idempotent)
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
TAG_NAME: ${{ github.ref_name }}
REPO: ${{ github.repository }}
run: |
if gh release view "$TAG_NAME" --repo "$REPO" >/dev/null 2>&1; then
echo "Release $TAG_NAME already exists — leaving it untouched."
exit 0
fi
gh release create "$TAG_NAME" dist/* \
--repo "$REPO" \
--verify-tag \
--title "Hued ${TAG_NAME}" \
--generate-notes
69 changes: 69 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
name: CI

on:
push:
branches: [main, master]
pull_request:
branches: [main, master]
workflow_dispatch:

permissions:
contents: read

concurrency:
group: ci-${{ github.ref }}
cancel-in-progress: true

jobs:
lint:
name: Lint
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
with:
python-version: "3.12"
- name: Install ruff
run: python -m pip install "ruff>=0.6"
- name: Run ruff
run: ruff check .

test:
name: Tests (Python ${{ matrix.python-version }})
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
python-version: ${{ (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master') && fromJSON('["3.10", "3.11", "3.12", "3.13", "3.14"]') || fromJSON('["3.10", "3.14"]') }}
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
with:
python-version: ${{ matrix.python-version }}
- name: Install package and pytest
run: |
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
- name: Run tests
run: python -m pytest -q

build:
name: Build and verify distributions
runs-on: ubuntu-latest
needs: [lint, test]
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
with:
python-version: "3.12"
- name: Build sdist and wheel
run: |
python -m pip install --upgrade pip build twine
python -m build
python -m twine check --strict dist/*
14 changes: 11 additions & 3 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1,5 +1,13 @@
__pycache__
*.pyc
__pycache__/
*.py[cod]
*$py.class
*.egg-info/
dist/
build/
venv/
venv/
.venv/
.pytest_cache/
.ruff_cache/
.mypy_cache/
.coverage
coverage/
45 changes: 45 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
# Changelog

All notable changes to **Hued** are documented in this file.

## [1.1.0] - 2026-11-18

A full correctness, color-science accuracy, performance, and supply-chain security release.

### Fixed
- **`xyz_to_rgb` & all `xyz_to_*` conversions**: Fixed a `TypeError` crash caused by raising tiny negative linear channels (e.g. pure red `(255, 0, 0)` and pure green `(0, 255, 0)`) to a fractional power and producing `complex` numbers before clamping. Updated forward and inverse transformations to the standard IEC 61966-2-1 sRGB D65 matrix and companding curves for exact lossless round-trips across all sRGB colors.
- **`rgb_to_linear` & `get_luminance`**: Fixed a dead-code threshold bug (`c > 0.04045` compared against `[0, 255]` instead of normalized `c / 255`) and replaced the gamma `2.2` approximation with the exact IEC 61966-2-1 / WCAG 2.1 sRGB transfer function (`((s + 0.055) / 1.055) ** 2.4` above `0.04045`, `s / 12.92` otherwise).
- **`get_text_color_from_background`**: Fixed inverted accessibility recommendations that returned `"dark"` text on pure black `(0, 0, 0)` and charcoal backgrounds, and `"light"` text on pure yellow `(255, 255, 0)`, cyan `(0, 255, 255)`, lime `(0, 255, 0)`, and light silver `(180, 180, 180)`. Now always selects whichever of light or dark text maximizes WCAG 2.1 contrast.
- **`check_color_quality`**: Fixed a mathematical tautology where `is_good_quality` could never return `False` (`max(contrast_black, contrast_white) >= sqrt(21) ≈ 4.58 > 4.5` for all 16.7M RGB colors). Now defaults to WCAG AAA (`7.0`) when evaluating against black/white generically, and to WCAG AA (`4.5`) when evaluating against a specific `background`, while reporting explicit AA/AAA flags for both black and white.
- **`simulate_color_blindness`**: Fixed floating-point `int()` truncation and gamma drift that shifted neutral grays; updated achromatopsia weights to linear sRGB luminance (`0.2126, 0.7152, 0.0722`) and interpolated severity in linear sRGB space.
- **`get_temperature`, `is_pastel`, & `is_muted`**:
- `get_temperature` now correctly classifies yellow as `"Warm"`, cyan and teal as `"Cool"`, and near-grays as `"Neutral"`.
- `is_pastel` no longer misclassifies pure white `(255, 255, 255)` or light grays as pastel, and now recognizes soft pastels such as pastel green `(119, 221, 119)`.
- `is_muted` no longer misclassifies pure black `(0, 0, 0)` as muted, supports mid-lightness muted shades (e.g. sage green, dusty rose), and no longer shadows `brightness`.
- **`hex_to_rgb` & `rgb_to_hex`**: Fixed silent acceptance of malformed hex strings (`"##FF0000"`, `"#12345"`, `"#FF0000EXTRA"`, `"#+1+2+3"`) and out-of-range/boolean RGB values (`rgb_to_hex(-1, 0, 0)` → `"#-10000"`, `rgb_to_hex(256, 0, 0)` → `"#1000000"`). Added support for 3-digit shorthand hex codes (`"#FFF"`) and surrounding whitespace.
- **`hsl_to_hsv` & `hsv_to_hsl`**: Replaced lossy 8-bit RGB round-trips with direct analytical conversions, eliminating hue quantization drift. Enforced consistent input validation across all HSL, HSV, CMYK, XYZ, and LAB conversions, and prevented rounded hues from ever reaching `360.0`.
- **`blend_colors` & `ColorPalette.generate_gradient`**: Replaced `int()` truncation with `round()` so blending a color with itself always returns the exact input color, and added range validation for `ratio` and RGB channels.
- **`ColorPalette`**:
- Fixed `ZeroDivisionError` in `generate_monochromatic(shades=1)` and rejected `shades < 1`.
- Differentiated `generate_tetradic(angle=60)` (rectangular double-complementary) from `generate_square()` (`90°`).
- Fixed `TypeError` in `palette_to_hex()` when called after `generate_random_palette()`.
- Fixed `export_palette()` file-extension parsing (`os.path.splitext`) so extensionless filenames like `"json"` are rejected and dotted directory paths work; removed unsolicited `print()` output on errors.
- **`ColorManager` & named color catalog**:
- Removed a scraped Wikipedia vandalism entry and cleaned citation markers (`"Cinnamon[citation needed]"` → `"Cinnamon"`, `"Heidelberg Red[2]"` → `"Heidelberg Red"`).
- Disambiguated 7 duplicate color names that made secondary entries unreachable and normalized all hex strings to uppercase `#RRGGBB`.
- Preserved acronyms and apostrophes in `get_color_by_name()` (e.g. `"Air Force blue (RAF)"`, `"B'dazzled blue"`) instead of corrupting them with `.title()`.
- Added 21 missing W3C CSS named colors (`Green`, `Orange`, `Purple`, `Brown`, `Gold`, `Lavender`, `Lime`, `Maroon`, `Khaki`, `Chocolate`, `Chartreuse`, `Forest green`, `Olive drab`, `Dark gray`, and `Grey` spellings) plus hyphen/space-insensitive lookup so all 148 standard CSS Color Level 4 named colors resolve.
- **Packaging**: Migrated from broken `{{VERSION_PLACEHOLDER}}` `setup.py` to standards-compliant PEP 621 `pyproject.toml` (Python `>=3.9`), fixing local `pip install .` and `python -m build`.

### Added
- **CIE 1976 L\*a\*b\* conversions**: `rgb_to_lab`, `lab_to_rgb`, `xyz_to_lab`, `lab_to_xyz`, `hex_to_lab`, `lab_to_hex`, `hsl_to_lab`, `lab_to_hsl`, `hsv_to_lab`, `lab_to_hsv`, `cmyk_to_lab`, `lab_to_cmyk`.
- **Color adjustment helpers**: `linear_to_rgb`, `invert_color`, `to_grayscale`, `adjust_lightness`, `adjust_saturation`, and gamma-correct `blend_colors(..., linear=True)`.
- **Perceptual difference & accessibility**: `delta_e(color1, color2, method="cie2000" | "cie76")` (validated against Sharma, Wu & Dalal 2005 CIEDE2000 test vectors) and `check_wcag_contrast(foreground, background)`.
- **Richer `ColorManager` API**: `closest_color_name(..., space="rgb" | "lab" | "cie2000")`, `get_color_by_hex`, `search_colors`, `get_random_color`, `add_color`, `remove_color`, plus module-level RGB/LAB caching.
- **Enhanced `ColorPalette` API**: Multi-space gradients (`space="rgb" | "linear" | "lab" | "hsl"`), `.css` custom-properties export, `pathlib.Path` support, and configurable `angle` on `generate_tetradic` and `generate_split_complementary`.
- **Static typing & metadata**: Full inline type annotations, PEP 561 `py.typed` marker, `hued.__version__`, and explicit `__all__` across all modules.
- **CI & Supply-Chain Provenance**: Multi-version GitHub Actions CI (`ci.yml`) and OIDC Trusted Publishing (`build_and_publish.yml`) with PEP 740 PyPI digital attestations and GitHub SLSA build provenance attestations.

## [1.0.7] and earlier

See `readme.md` and the [GitHub Releases](https://github.com/Infinitode/Hued/releases) history for versions `1.0.0` through `1.0.7`.
Loading
Loading