colourings

A lightweight Python library for creating, converting, comparing and interpolating colours. No runtime dependencies, typed throughout.

📖 Read the documentation

This project is a modernized fork of vaab/colour with additional formats, typing, revised channel ranges, and updated packaging.

Install

pip install colourings

Minimal example

from colourings import Color

c = Color("red")

c.hsl  # HSL(hue=0.0, saturation=100.0, lightness=50.0)
c.oklch  # OKLCH(lightness=0.6279..., chroma=0.2576..., hue=29.2338...)
c.mix("white", 0.3).hex_l  # '#ff7765'
c.contrast_ratio("white")  # 3.9984...
c.best_text_color()  # <Color black>
c.darken(0.2).nearest_name()  # 'firebrick'

What it does

Correctness

Most of this library is arithmetic on published constants, and a wrong constant there does not raise — it returns a plausible colour that is simply wrong. So every constant is either quoted from a citable source or derived in exact arithmetic, and anything whose constants could not be confirmed raises instead of guessing.

CIEDE2000 is checked against all 34 pairs of the published Sharma–Wu–Dalal test data. The CSS wide-gamut matrices are each derived twice, independently. Coverage is 100% of statements and branches, and every example in the README and the docs is executed by the test suite with its claimed output checked.

Contributing

Bug reports, colour-science corrections and pull requests are welcome. CONTRIBUTING.md describes the checks CI runs, all of which you can run locally, and what a change needs before it can be merged.

Security

To report a vulnerability, use GitHub's private reporting rather than a public issue. SECURITY.md sets out what is in scope — the short version is that colourings performs no I/O, opens no network connections and has no runtime dependencies, which leaves crafted inputs and the release process itself.

License

BSD-3-Clause. See LICENSE.