hexrgba 0.2.1__py3-none-any.whl

hexrgba/__init__.py

@@ -0,0 +1,36 @@
+"""Parse, validate and normalize CSS hex colors and named colors, with exact alpha,
+CSS serialization, WCAG contrast and alpha blending."""
+
+from __future__ import annotations
+
+from ._alpha import alpha_to_byte, css_alpha
+from ._blend import blend
+from ._color import Color, is_color, parse_color
+from ._errors import ChannelError, ColorError, ColorNameError, HexColorError
+from ._hex import is_hex, normalize, parse, shorten, to_hex
+from ._names import NAMED_COLORS
+from ._wcag import contrast_ratio, passes_contrast, relative_luminance
+
+__version__ = "0.2.1"
+
+__all__ = [
+    "NAMED_COLORS",
+    "ChannelError",
+    "Color",
+    "ColorError",
+    "ColorNameError",
+    "HexColorError",
+    "alpha_to_byte",
+    "blend",
+    "contrast_ratio",
+    "css_alpha",
+    "is_color",
+    "is_hex",
+    "normalize",
+    "parse",
+    "parse_color",
+    "passes_contrast",
+    "relative_luminance",
+    "shorten",
+    "to_hex",
+]

hexrgba/__main__.py

@@ -0,0 +1,10 @@
+"""Allow ``python -m hexrgba``."""
+
+from __future__ import annotations
+
+import sys
+
+from ._cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

hexrgba/_alpha.py

@@ -0,0 +1,56 @@
+"""Exact conversions between an 8-bit alpha byte and the 0..1 alpha of CSS.
+
+The serialization follows CSS Color Module Level 4, section 16.1.1 "Serializing legacy
+alpha values" (https://www.w3.org/TR/css-color-4/#serializing-alpha-values).
+"""
+
+from __future__ import annotations
+
+import math
+from fractions import Fraction
+
+from ._errors import ChannelError, shown
+from ._hex import check_channel
+
+
+def alpha_to_byte(alpha: float) -> int:
+    """Convert a 0..1 alpha into an alpha byte from 0 to 255.
+
+    The value is multiplied by 255 and rounded to the nearest integer, halves rounding
+    up. A float is read as its shortest decimal form (``repr``), the number you typed, so
+    ``0.3`` gives 77 (76.5 rounded up) rather than 76 from the binary value just below
+    0.3. Both ``a / 255`` and the string from :func:`css_alpha` convert back to the byte
+    ``a`` they came from, for every ``a`` from 0 to 255.
+
+    Raises ChannelError for booleans, non-numbers, NaN and values outside 0..1.
+    """
+    if isinstance(alpha, bool) or not isinstance(alpha, (int, float)):
+        raise ChannelError(f"alpha must be a number from 0 to 1, got {shown(alpha)}")
+    if not 0 <= alpha <= 1:
+        raise ChannelError(f"alpha must be from 0 to 1, got {shown(alpha)}")
+    exact = Fraction(alpha) if isinstance(alpha, int) else Fraction(repr(float(alpha)))
+    return math.floor(exact * 255 + Fraction(1, 2))
+
+
+def css_alpha(byte: int) -> str:
+    """Serialize an alpha byte as the CSS legacy alpha number, for example "0.5".
+
+    If a whole percentage ``n`` (0 to 100) satisfies ``round(n * 2.55) == byte`` the
+    result is ``n / 100``, so 237 gives "0.93". Otherwise it is ``byte / 0.255`` rounded
+    to an integer and divided by 1000, so 236 gives "0.925". Halves round up, there is
+    always a leading zero and trailing zeros are dropped; 255 gives "1" and 0 gives "0".
+    """
+    check_channel(byte, "alpha")
+    for percent in range(101):
+        if (percent * 255 + 50) // 100 == byte:
+            return _decimal(percent, 100)
+    return _decimal((byte * 2000 + 255) // 510, 1000)
+
+
+def _decimal(numerator: int, denominator: int) -> str:
+    """Render numerator / denominator (denominator 100 or 1000) without trailing zeros."""
+    whole, rest = divmod(numerator, denominator)
+    if rest == 0:
+        return str(whole)
+    width = len(str(denominator)) - 1
+    return f"{whole}.{rest:0{width}d}".rstrip("0")

hexrgba/_blend.py

@@ -0,0 +1,62 @@
+"""Alpha compositing of one color over another.
+
+Implements simple alpha compositing (source-over) from Compositing and Blending Level 1,
+section 5.1 (https://www.w3.org/TR/compositing-1/#simplealphacompositing):
+
+    co = Cs x as + Cb x ab x (1 - as)      ao = as + ab x (1 - as)      Co = co / ao
+"""
+
+from __future__ import annotations
+
+import math
+from fractions import Fraction
+
+from ._color import Color, parse_color
+
+_HALF = Fraction(1, 2)
+
+
+def to_color(value: Color | str) -> Color:
+    """Return value unchanged if it is a Color, else parse it leniently."""
+    return value if isinstance(value, Color) else parse_color(value)
+
+
+def composite(
+    source: tuple[Fraction, Fraction, Fraction],
+    source_alpha: Fraction,
+    backdrop: tuple[Fraction, Fraction, Fraction],
+    backdrop_alpha: Fraction,
+) -> tuple[tuple[Fraction, Fraction, Fraction], Fraction]:
+    """Composite exactly on 0..1 values, returning the un-premultiplied color and alpha."""
+    out_alpha = source_alpha + backdrop_alpha * (1 - source_alpha)
+    if out_alpha == 0:
+        zero = Fraction(0)
+        return (zero, zero, zero), zero
+    channels = tuple(
+        (cs * source_alpha + cb * backdrop_alpha * (1 - source_alpha)) / out_alpha
+        for cs, cb in zip(source, backdrop, strict=True)
+    )
+    return (channels[0], channels[1], channels[2]), out_alpha
+
+
+def _byte(unit: Fraction) -> int:
+    return math.floor(unit * 255 + _HALF)
+
+
+def blend(foreground: Color | str, background: Color | str) -> Color:
+    """Composite foreground over background and return the result as a Color.
+
+    The math is exact (fractions); each output channel is rounded to the nearest byte
+    once, halves rounding up. An opaque foreground returns itself; a fully transparent
+    foreground returns the background. If both are fully transparent the result is
+    transparent black. Strings are parsed with :func:`parse_color` (lenient).
+    """
+    fg = to_color(foreground)
+    bg = to_color(background)
+    (r, g, b), alpha = composite(
+        (Fraction(fg.r, 255), Fraction(fg.g, 255), Fraction(fg.b, 255)),
+        Fraction(fg.a, 255),
+        (Fraction(bg.r, 255), Fraction(bg.g, 255), Fraction(bg.b, 255)),
+        Fraction(bg.a, 255),
+    )
+    return Color(_byte(r), _byte(g), _byte(b), _byte(alpha))

hexrgba/_cli.py

@@ -0,0 +1,125 @@
+"""Command-line interface: ``hexrgba normalize | convert | contrast | blend``."""
+
+from __future__ import annotations
+
+import argparse
+import math
+import sys
+from collections.abc import Sequence
+
+from . import __version__
+from ._blend import blend
+from ._color import Color, parse_color
+from ._errors import ColorError
+from ._wcag import contrast_ratio, passes_contrast
+
+_EXAMPLES = """exit codes: 0 success, 1 the pair fails --level, 2 bad usage or invalid color
+
+examples (quote a leading # so the shell does not read it as a comment):
+  hexrgba normalize "#FFAA00"            ->  #ffaa00
+  hexrgba normalize ffaa0080             ->  #ffaa0080
+  hexrgba normalize "#aabbcc" --short    ->  #abc
+  hexrgba normalize RebeccaPurple        ->  #663399
+  hexrgba convert "#ff00ffed" --to css   ->  rgba(255, 0, 255, 0.93)
+  hexrgba convert "#00ffff" --to name    ->  aqua
+  hexrgba convert transparent --to channels  ->  0 0 0 0
+  hexrgba contrast "#767676" white       ->  4.54:1
+  hexrgba contrast "#777" white --level AA   ->  exits 1: 4.47:1 is below 4.5:1
+  hexrgba blend "#0000ff80" red          ->  #7f0080
+"""
+
+_FORMATS = ("hex", "short", "css", "channels", "name")
+
+
+# Exit codes: 0 success, 1 the pair fails --level, 2 bad usage or an invalid color.
+EXIT_FAILS_LEVEL = 1
+EXIT_BAD_INPUT = 2
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="hexrgba",
+        description="Normalize, convert, compare and blend CSS hex and named colors.",
+        epilog=_EXAMPLES,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("--version", action="version", version=f"hexrgba {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    norm = sub.add_parser("normalize", help="print the canonical lower-case hex form")
+    norm.add_argument("color", help="hex color or CSS named color")
+    norm.add_argument("--short", action="store_true", help="use #rgb / #rgba when lossless")
+    _add_strict(norm)
+
+    conv = sub.add_parser("convert", help="print the color in another notation")
+    conv.add_argument("color", help="hex color or CSS named color")
+    conv.add_argument("--to", choices=_FORMATS, default="css", help="output (default css)")
+    _add_strict(conv)
+
+    con = sub.add_parser("contrast", help="print the WCAG contrast ratio of two colors")
+    con.add_argument("foreground", help="text color (may be translucent)")
+    con.add_argument("background", help="opaque background color")
+    con.add_argument("--level", choices=("AA", "AAA"), help="exit 1 if the pair fails it")
+    con.add_argument(
+        "--large", action="store_true", help="with --level, use the large-text threshold"
+    )
+
+    ble = sub.add_parser("blend", help="composite a color over a background")
+    ble.add_argument("foreground", help="color on top (usually translucent)")
+    ble.add_argument("background", help="color underneath")
+    return parser
+
+
+def _add_strict(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--strict", action="store_true", help="follow the CSS grammar exactly")
+
+
+def _convert(color: Color, target: str) -> str:
+    if target == "hex":
+        return color.hex
+    if target == "short":
+        return color.to_hex(short=True)
+    if target == "channels":
+        return " ".join(str(channel) for channel in color.as_tuple())
+    if target == "name":
+        if color.name is None:
+            raise ColorError(f"no CSS named color equals {color.hex}")
+        return color.name
+    return color.to_css()
+
+
+def _ratio_text(ratio: float) -> str:
+    # Truncate rather than round, so a failing 4.499 never prints as a passing 4.50.
+    return f"{math.floor(ratio * 100) / 100:.2f}:1"
+
+
+def _run(args: argparse.Namespace) -> int:
+    if args.command == "normalize":
+        print(parse_color(args.color, strict=args.strict).to_hex(short=args.short))
+    elif args.command == "convert":
+        print(_convert(parse_color(args.color, strict=args.strict), args.to))
+    elif args.command == "contrast":
+        ratio = contrast_ratio(args.foreground, args.background)
+        print(_ratio_text(ratio))
+        if args.level and not passes_contrast(
+            args.foreground, args.background, level=args.level, large=args.large
+        ):
+            kind = "large text" if args.large else "normal text"
+            print(f"hexrgba: fails WCAG {args.level} for {kind}", file=sys.stderr)
+            return EXIT_FAILS_LEVEL
+    else:
+        print(blend(args.foreground, args.background).hex)
+    return 0
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the command-line interface and return a process exit code."""
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    if args.command == "contrast" and args.large and not args.level:
+        parser.error("--large only applies together with --level")
+    try:
+        return _run(args)
+    except (ColorError, TypeError) as exc:
+        print(f"hexrgba: error: {exc}", file=sys.stderr)
+        return EXIT_BAD_INPUT

hexrgba/_color.py

@@ -0,0 +1,141 @@
+"""The frozen ``Color`` value type and CSS color parsing (hex and named keywords)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ._alpha import alpha_to_byte, css_alpha
+from ._errors import ColorNameError, HexColorError, shown
+from ._hex import check_channel, decode, is_hex_body, shorten, to_hex
+from ._names import NAMED_COLORS
+
+# CSS keywords are ASCII case-insensitive: only A-Z fold, so look-alikes such as
+# the Kelvin sign (U+212A) never match "k" the way str.lower() would make them.
+_ASCII_LOWER = str.maketrans("ABCDEFGHIJKLMNOPQRSTUVWXYZ", "abcdefghijklmnopqrstuvwxyz")
+_NAME_BY_HEX: dict[str, str] = {}
+for _name, _value in NAMED_COLORS.items():
+    _NAME_BY_HEX.setdefault(_value, _name)
+
+
+@dataclass(frozen=True, slots=True)
+class Color:
+    """An sRGB color with integer channels ``r``, ``g``, ``b`` and alpha ``a``, 0 to 255.
+
+    Instances are immutable, hashable and compare by value. ``a`` defaults to 255
+    (fully opaque). Construction raises ChannelError for any channel that is not an int
+    from 0 to 255.
+    """
+
+    r: int
+    g: int
+    b: int
+    a: int = 255
+
+    def __post_init__(self) -> None:
+        for name in ("r", "g", "b", "a"):
+            check_channel(getattr(self, name), name)
+
+    @classmethod
+    def parse(cls, text: str, *, strict: bool = False) -> Color:
+        """Parse a hex color or CSS named color; see :func:`parse_color`."""
+        return parse_color(text, strict=strict)
+
+    @classmethod
+    def from_rgba(cls, r: int, g: int, b: int, alpha: float = 1.0) -> Color:
+        """Build a color from byte channels and a 0..1 alpha (see :func:`alpha_to_byte`)."""
+        return cls(r, g, b, alpha_to_byte(alpha))
+
+    @property
+    def alpha(self) -> float:
+        """The alpha as a float from 0 to 1, exactly ``a / 255``."""
+        return self.a / 255
+
+    @property
+    def is_opaque(self) -> bool:
+        """True when the alpha byte is 255."""
+        return self.a == 255
+
+    @property
+    def hex(self) -> str:
+        """Canonical lower-case hex: #rrggbb when opaque, #rrggbbaa otherwise."""
+        if self.is_opaque:
+            return to_hex(self.r, self.g, self.b)
+        return to_hex(self.r, self.g, self.b, self.a)
+
+    @property
+    def name(self) -> str | None:
+        """The CSS keyword for this exact color, or None.
+
+        ``transparent`` names (0, 0, 0, 0). When two keywords share a value (``aqua`` and
+        ``cyan``, ``gray`` and ``grey``) the first in the spec's alphabetical table wins.
+        """
+        if self == _TRANSPARENT:
+            return "transparent"
+        return _NAME_BY_HEX.get(self.hex) if self.is_opaque else None
+
+    def to_hex(self, *, short: bool = False) -> str:
+        """Return :attr:`hex`, or the lossless #rgb / #rgba form when ``short=True``."""
+        return shorten(self.hex) if short else self.hex
+
+    def to_css(self) -> str:
+        """Serialize as CSS does for sRGB values: ``rgb(r, g, b)`` when opaque, otherwise
+        ``rgba(r, g, b, alpha)`` with the alpha from :func:`css_alpha`."""
+        if self.is_opaque:
+            return f"rgb({self.r}, {self.g}, {self.b})"
+        return f"rgba({self.r}, {self.g}, {self.b}, {css_alpha(self.a)})"
+
+    def with_alpha(self, alpha: float) -> Color:
+        """Return a copy with a 0..1 alpha, converted by :func:`alpha_to_byte`."""
+        return Color(self.r, self.g, self.b, alpha_to_byte(alpha))
+
+    def as_tuple(self) -> tuple[int, int, int, int]:
+        """Return ``(r, g, b, a)``, the same shape :func:`parse` returns."""
+        return (self.r, self.g, self.b, self.a)
+
+    def __str__(self) -> str:
+        return self.hex
+
+
+_TRANSPARENT = Color(0, 0, 0, 0)
+
+
+def parse_color(text: str, *, strict: bool = False) -> Color:
+    """Parse a CSS hex color (#rgb, #rgba, #rrggbb, #rrggbbaa), a named color or
+    ``transparent`` into a :class:`Color`.
+
+    Hex digits and keywords are matched ASCII case-insensitively, as CSS requires.
+    ``strict=True`` follows the CSS grammar exactly: hex needs its leading ``#`` and no
+    surrounding whitespace is allowed. The default lenient mode also accepts a missing
+    ``#`` and strips surrounding whitespace, like :func:`parse`.
+
+    Raises HexColorError for a malformed hex color, ColorNameError for an unknown
+    keyword and TypeError when text is not a str.
+    """
+    if not isinstance(text, str):
+        raise TypeError(f"color must be a str, got {type(text).__name__}")
+    body = text.strip()
+    if strict and body != text:
+        error = HexColorError if body.startswith("#") else ColorNameError
+        raise error(f"surrounding whitespace is not allowed in strict mode: {shown(text)}")
+    if body.startswith("#"):
+        return Color(*decode(body[1:], text))
+    key = body.translate(_ASCII_LOWER)
+    if key == "transparent":
+        return _TRANSPARENT
+    value = NAMED_COLORS.get(key)
+    if value is not None:
+        return Color(*decode(value[1:], text))
+    if is_hex_body(body):
+        if strict:
+            raise HexColorError(f"hex color needs a leading '#' in strict mode: {shown(text)}")
+        return Color(*decode(body, text))
+    raise ColorNameError(f"not a hex color or CSS named color: {shown(text)}")
+
+
+def is_color(text: str, *, strict: bool = False) -> bool:
+    """Report whether :func:`parse_color` accepts text with the same ``strict`` setting."""
+    try:
+        parse_color(text, strict=strict)
+    except (ValueError, TypeError):
+        return False
+    return True

hexrgba/_errors.py

@@ -0,0 +1,32 @@
+"""Typed errors. Every error is a ``ValueError``, so 0.1.0 handlers keep working."""
+
+from __future__ import annotations
+
+
+class ColorError(ValueError):
+    """Base class for every error this library raises about a color value."""
+
+
+class HexColorError(ColorError):
+    """Raised when a string is not a valid CSS hex color."""
+
+
+class ChannelError(HexColorError):
+    """Raised when a channel or alpha value is outside its range or of the wrong type.
+
+    It subclasses HexColorError because 0.1.0 raised HexColorError for a bad channel in
+    ``to_hex``, and handlers written for that keep working.
+    """
+
+
+_SHOWN_LIMIT = 40
+
+
+def shown(value: object) -> str:
+    """Return ``repr(value)`` cut to a short prefix, so huge inputs keep messages small."""
+    text = repr(value)
+    return text if len(text) <= _SHOWN_LIMIT else text[:_SHOWN_LIMIT] + "..."
+
+
+class ColorNameError(ColorError):
+    """Raised when a string is neither a hex color nor a CSS named color keyword."""

hexrgba/_hex.py

@@ -0,0 +1,89 @@
+"""Core parsing, validation and normalization for CSS hex colors."""
+
+from __future__ import annotations
+
+from ._errors import ChannelError, HexColorError, shown
+
+_VALID_LENGTHS = frozenset({3, 4, 6, 8})
+_HEX_DIGITS = frozenset("0123456789abcdefABCDEF")
+
+
+def _body(value: str) -> str:
+    text = value.strip()
+    return text[1:] if text.startswith("#") else text
+
+
+def is_hex_body(body: str) -> bool:
+    """Report whether body (no hash) has 3, 4, 6 or 8 ASCII hex digits."""
+    return len(body) in _VALID_LENGTHS and all(ch in _HEX_DIGITS for ch in body)
+
+
+def decode(body: str, original: str) -> tuple[int, int, int, int]:
+    """Decode a hash-less hex body into channels, naming original in the error."""
+    if not is_hex_body(body):
+        raise HexColorError(f"not a valid hex color: {shown(original)}")
+    if len(body) in (3, 4):
+        body = "".join(ch * 2 for ch in body)
+    r = int(body[0:2], 16)
+    g = int(body[2:4], 16)
+    b = int(body[4:6], 16)
+    a = int(body[6:8], 16) if len(body) == 8 else 255
+    return r, g, b, a
+
+
+def is_hex(value: str) -> bool:
+    """Report whether value is a hex color in #rgb, #rgba, #rrggbb or #rrggbbaa form."""
+    return is_hex_body(_body(value))
+
+
+def parse(value: str) -> tuple[int, int, int, int]:
+    """Parse a hex color into (r, g, b, a) channels as integers from 0 to 255.
+
+    Shorthand (#rgb, #rgba) is expanded by doubling each digit, the leading hash is
+    optional, and a missing alpha channel defaults to 255 (fully opaque).
+    """
+    return decode(_body(value), value)
+
+
+def check_channel(value: int, name: str) -> int:
+    """Return value if it is an int from 0 to 255, else raise ChannelError."""
+    if not isinstance(value, int) or isinstance(value, bool):
+        raise ChannelError(f"{name} must be an int from 0 to 255, got {shown(value)}")
+    if not 0 <= value <= 255:
+        raise ChannelError(f"{name} must be from 0 to 255, got {value}")
+    return value
+
+
+def _channel(value: int, name: str) -> str:
+    return f"{check_channel(value, name):02x}"
+
+
+def to_hex(r: int, g: int, b: int, a: int | None = None) -> str:
+    """Build a canonical lowercase hex string from channels.
+
+    With no alpha the result is #rrggbb, with alpha it is #rrggbbaa.
+    """
+    out = "#" + _channel(r, "r") + _channel(g, "g") + _channel(b, "b")
+    if a is not None:
+        out += _channel(a, "a")
+    return out
+
+
+def shorten(value: str) -> str:
+    """Return the shortest lossless form of a hex color: #rgb or #rgba when every pair
+    repeats its digit, otherwise the canonical #rrggbb or #rrggbbaa from normalize."""
+    full = normalize(value)
+    pairs = [full[i : i + 2] for i in range(1, len(full), 2)]
+    if all(pair[0] == pair[1] for pair in pairs):
+        return "#" + "".join(pair[0] for pair in pairs)
+    return full
+
+
+def normalize(value: str, *, short: bool = False) -> str:
+    """Return the canonical form: #rrggbb when fully opaque, #rrggbbaa otherwise.
+
+    With ``short=True`` the result is shortened to #rgb or #rgba when that is lossless.
+    """
+    r, g, b, a = parse(value)
+    full = to_hex(r, g, b) if a == 255 else to_hex(r, g, b, a)
+    return shorten(full) if short else full

hexrgba/_names.py

@@ -0,0 +1,164 @@
+"""The CSS named color table, one keyword per row.
+
+Copied programmatically from the table in section 6.1 of CSS Color Module Level 4,
+https://www.w3.org/TR/css-color-4/#named-colors (Candidate Recommendation Draft of
+9 October 2026, fetched 2026-10-12). Rows keep the spec order, which is alphabetical.
+"""
+
+from __future__ import annotations
+
+from types import MappingProxyType
+
+_TABLE: dict[str, str] = {
+    "aliceblue": "#f0f8ff",
+    "antiquewhite": "#faebd7",
+    "aqua": "#00ffff",
+    "aquamarine": "#7fffd4",
+    "azure": "#f0ffff",
+    "beige": "#f5f5dc",
+    "bisque": "#ffe4c4",
+    "black": "#000000",
+    "blanchedalmond": "#ffebcd",
+    "blue": "#0000ff",
+    "blueviolet": "#8a2be2",
+    "brown": "#a52a2a",
+    "burlywood": "#deb887",
+    "cadetblue": "#5f9ea0",
+    "chartreuse": "#7fff00",
+    "chocolate": "#d2691e",
+    "coral": "#ff7f50",
+    "cornflowerblue": "#6495ed",
+    "cornsilk": "#fff8dc",
+    "crimson": "#dc143c",
+    "cyan": "#00ffff",
+    "darkblue": "#00008b",
+    "darkcyan": "#008b8b",
+    "darkgoldenrod": "#b8860b",
+    "darkgray": "#a9a9a9",
+    "darkgreen": "#006400",
+    "darkgrey": "#a9a9a9",
+    "darkkhaki": "#bdb76b",
+    "darkmagenta": "#8b008b",
+    "darkolivegreen": "#556b2f",
+    "darkorange": "#ff8c00",
+    "darkorchid": "#9932cc",
+    "darkred": "#8b0000",
+    "darksalmon": "#e9967a",
+    "darkseagreen": "#8fbc8f",
+    "darkslateblue": "#483d8b",
+    "darkslategray": "#2f4f4f",
+    "darkslategrey": "#2f4f4f",
+    "darkturquoise": "#00ced1",
+    "darkviolet": "#9400d3",
+    "deeppink": "#ff1493",
+    "deepskyblue": "#00bfff",
+    "dimgray": "#696969",
+    "dimgrey": "#696969",
+    "dodgerblue": "#1e90ff",
+    "firebrick": "#b22222",
+    "floralwhite": "#fffaf0",
+    "forestgreen": "#228b22",
+    "fuchsia": "#ff00ff",
+    "gainsboro": "#dcdcdc",
+    "ghostwhite": "#f8f8ff",
+    "gold": "#ffd700",
+    "goldenrod": "#daa520",
+    "gray": "#808080",
+    "green": "#008000",
+    "greenyellow": "#adff2f",
+    "grey": "#808080",
+    "honeydew": "#f0fff0",
+    "hotpink": "#ff69b4",
+    "indianred": "#cd5c5c",
+    "indigo": "#4b0082",
+    "ivory": "#fffff0",
+    "khaki": "#f0e68c",
+    "lavender": "#e6e6fa",
+    "lavenderblush": "#fff0f5",
+    "lawngreen": "#7cfc00",
+    "lemonchiffon": "#fffacd",
+    "lightblue": "#add8e6",
+    "lightcoral": "#f08080",
+    "lightcyan": "#e0ffff",
+    "lightgoldenrodyellow": "#fafad2",
+    "lightgray": "#d3d3d3",
+    "lightgreen": "#90ee90",
+    "lightgrey": "#d3d3d3",
+    "lightpink": "#ffb6c1",
+    "lightsalmon": "#ffa07a",
+    "lightseagreen": "#20b2aa",
+    "lightskyblue": "#87cefa",
+    "lightslategray": "#778899",
+    "lightslategrey": "#778899",
+    "lightsteelblue": "#b0c4de",
+    "lightyellow": "#ffffe0",
+    "lime": "#00ff00",
+    "limegreen": "#32cd32",
+    "linen": "#faf0e6",
+    "magenta": "#ff00ff",
+    "maroon": "#800000",
+    "mediumaquamarine": "#66cdaa",
+    "mediumblue": "#0000cd",
+    "mediumorchid": "#ba55d3",
+    "mediumpurple": "#9370db",
+    "mediumseagreen": "#3cb371",
+    "mediumslateblue": "#7b68ee",
+    "mediumspringgreen": "#00fa9a",
+    "mediumturquoise": "#48d1cc",
+    "mediumvioletred": "#c71585",
+    "midnightblue": "#191970",
+    "mintcream": "#f5fffa",
+    "mistyrose": "#ffe4e1",
+    "moccasin": "#ffe4b5",
+    "navajowhite": "#ffdead",
+    "navy": "#000080",
+    "oldlace": "#fdf5e6",
+    "olive": "#808000",
+    "olivedrab": "#6b8e23",
+    "orange": "#ffa500",
+    "orangered": "#ff4500",
+    "orchid": "#da70d6",
+    "palegoldenrod": "#eee8aa",
+    "palegreen": "#98fb98",
+    "paleturquoise": "#afeeee",
+    "palevioletred": "#db7093",
+    "papayawhip": "#ffefd5",
+    "peachpuff": "#ffdab9",
+    "peru": "#cd853f",
+    "pink": "#ffc0cb",
+    "plum": "#dda0dd",
+    "powderblue": "#b0e0e6",
+    "purple": "#800080",
+    "rebeccapurple": "#663399",
+    "red": "#ff0000",
+    "rosybrown": "#bc8f8f",
+    "royalblue": "#4169e1",
+    "saddlebrown": "#8b4513",
+    "salmon": "#fa8072",
+    "sandybrown": "#f4a460",
+    "seagreen": "#2e8b57",
+    "seashell": "#fff5ee",
+    "sienna": "#a0522d",
+    "silver": "#c0c0c0",
+    "skyblue": "#87ceeb",
+    "slateblue": "#6a5acd",
+    "slategray": "#708090",
+    "slategrey": "#708090",
+    "snow": "#fffafa",
+    "springgreen": "#00ff7f",
+    "steelblue": "#4682b4",
+    "tan": "#d2b48c",
+    "teal": "#008080",
+    "thistle": "#d8bfd8",
+    "tomato": "#ff6347",
+    "turquoise": "#40e0d0",
+    "violet": "#ee82ee",
+    "wheat": "#f5deb3",
+    "white": "#ffffff",
+    "whitesmoke": "#f5f5f5",
+    "yellow": "#ffff00",
+    "yellowgreen": "#9acd32",
+}
+
+#: Every named color keyword mapped to its canonical lower-case ``#rrggbb`` value.
+NAMED_COLORS = MappingProxyType(_TABLE)

hexrgba/_wcag.py

@@ -0,0 +1,70 @@
+"""WCAG 2.x relative luminance, contrast ratio and the AA / AAA text thresholds.
+
+Formulas from the WCAG 2.2 definitions (W3C Recommendation, 12 December 2024):
+https://www.w3.org/TR/WCAG22/#dfn-relative-luminance and
+https://www.w3.org/TR/WCAG22/#dfn-contrast-ratio. Thresholds from success criteria
+1.4.3 (https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum) and 1.4.6
+(https://www.w3.org/WAI/WCAG22/Understanding/contrast-enhanced).
+"""
+
+from __future__ import annotations
+
+from ._blend import blend, to_color
+from ._color import Color
+from ._errors import ColorError
+
+# (level, large text) -> minimum ratio. Compared without rounding, as WCAG requires.
+_THRESHOLDS = {("AA", False): 4.5, ("AA", True): 3.0, ("AAA", False): 7.0, ("AAA", True): 4.5}
+
+
+def _linear(byte: int) -> float:
+    srgb = byte / 255
+    return srgb / 12.92 if srgb <= 0.04045 else ((srgb + 0.055) / 1.055) ** 2.4
+
+
+def relative_luminance(color: Color | str) -> float:
+    """Return the WCAG relative luminance, 0.0 for black to 1.0 for white.
+
+    ``L = 0.2126 * R + 0.7152 * G + 0.0722 * B`` on linearized sRGB channels, with the
+    0.04045 threshold of the current definition. Alpha is ignored: composite a
+    translucent color first with :func:`blend`.
+    """
+    c = to_color(color)
+    return 0.2126 * _linear(c.r) + 0.7152 * _linear(c.g) + 0.0722 * _linear(c.b)
+
+
+def contrast_ratio(foreground: Color | str, background: Color | str) -> float:
+    """Return the WCAG contrast ratio ``(L1 + 0.05) / (L2 + 0.05)``, from 1.0 to 21.0.
+
+    L1 is the lighter luminance, so the order of two opaque colors does not matter. A
+    translucent foreground is first composited over the background with :func:`blend`
+    and rounded to 8-bit channels, as a browser paints it.
+    The background must be opaque, since what lies behind it is unknown: a translucent
+    background raises ColorError.
+    """
+    bg = to_color(background)
+    if not bg.is_opaque:
+        raise ColorError(f"background must be opaque to measure contrast, got {bg.hex}")
+    fg = blend(foreground, bg)
+    first, second = relative_luminance(fg), relative_luminance(bg)
+    lighter, darker = max(first, second), min(first, second)
+    return (lighter + 0.05) / (darker + 0.05)
+
+
+def passes_contrast(
+    foreground: Color | str,
+    background: Color | str,
+    *,
+    level: str = "AA",
+    large: bool = False,
+) -> bool:
+    """Report whether the pair meets WCAG text contrast at ``level`` "AA" or "AAA".
+
+    The minimum ratios are 4.5 (AA), 3 (AA, large text), 7 (AAA) and 4.5 (AAA, large
+    text). ``level`` is case-insensitive. The ratio is not rounded first, so 4.499 fails
+    4.5. Raises ValueError for an unknown level.
+    """
+    key = (level.upper() if isinstance(level, str) else level, large)
+    if key not in _THRESHOLDS:
+        raise ValueError(f"level must be 'AA' or 'AAA', (any case), got {level!r}")
+    return contrast_ratio(foreground, background) >= _THRESHOLDS[key]

hexrgba-0.2.1.dist-info/METADATA

@@ -0,0 +1,109 @@
+Metadata-Version: 2.5
+Name: hexrgba
+Version: 0.2.1
+Summary: CSS hex and named colors: parse, normalize, exact alpha, rgba(), WCAG contrast and blending
+Project-URL: Homepage, https://lianes8studio.com
+Project-URL: Repository, https://github.com/JaviLianes8/hexrgba
+Project-URL: Issues, https://github.com/JaviLianes8/hexrgba/issues
+Project-URL: Changelog, https://github.com/JaviLianes8/hexrgba/blob/main/CHANGELOG.md
+Project-URL: LinkedIn, https://www.linkedin.com/in/jlianes/
+Project-URL: Funding, https://buymeacoffee.com/jlianesglrs
+Author-email: Javier Lianes <javier@lianes8studio.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: blend,color,contrast,css,hex,named-colors,normalize,parse,rgba,wcag
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# hexrgba
+
+Parse, validate and normalize CSS hex colors and named colors, with exact alpha handling,
+CSS `rgb()` / `rgba()` output, WCAG contrast and alpha blending. Typed, zero dependencies.
+
+## Install
+
+```
+pip install hexrgba
+```
+
+## Usage
+
+```python
+from hexrgba import Color, contrast_ratio, is_hex, normalize, parse, parse_color, to_hex
+
+is_hex("#f00")  # True
+parse("#ff000080")  # (255, 0, 0, 128)
+normalize("#F00")  # "#ff0000"
+normalize("#AABBCC", short=True)  # "#abc"
+to_hex(255, 0, 128, 64)  # "#ff008040"
+
+color = parse_color("RebeccaPurple")  # Color(r=102, g=51, b=153, a=255)
+color.hex  # "#663399"
+color.to_css()  # "rgb(102, 51, 153)"
+parse_color("#ff00ffed").to_css()  # "rgba(255, 0, 255, 0.93)"
+parse_color("#00ffff").name  # "aqua"
+Color.from_rgba(255, 0, 0, 0.5).hex  # "#ff000080"
+
+contrast_ratio("#767676", "white")  # 4.54...
+```
+
+What it covers:
+
+- **All four hex forms** (`#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`) and **all 148 CSS named
+  colors** plus `transparent`, matched ASCII case-insensitively as CSS requires.
+- **Strict or lenient.** `strict=True` follows the CSS grammar (leading `#`, no surrounding
+  whitespace). The default also accepts a missing `#` and strips surrounding
+  Python whitespace (`str.strip()`).
+- **A frozen `Color`** with `hex`, `to_hex(short=True)`, `to_css()`, `name`, `alpha`,
+  `with_alpha()` and `from_rgba()`.
+- **Exact alpha.** `alpha_to_byte` and `css_alpha` follow CSS Color 4; every alpha byte
+  round-trips through its 0..1 float and through its CSS string.
+- **WCAG 2.x** `relative_luminance`, `contrast_ratio` and `passes_contrast` (AA / AAA).
+- **Blending** of a translucent color over a background with `blend`.
+- **Typed errors**, all `ValueError`: `ColorError`, `HexColorError`, `ColorNameError`,
+  `ChannelError`.
+
+The full guide, with the exact rules and the sources they come from, is in
+[GUIDE.md](GUIDE.md).
+
+## Command line
+
+```
+hexrgba normalize "#FFAA00"            # #ffaa00
+hexrgba normalize "#aabbcc" --short    # #abc
+hexrgba convert "#ff00ffed" --to css   # rgba(255, 0, 255, 0.93)
+hexrgba convert "#00ffff" --to name    # aqua
+hexrgba contrast "#767676" white       # 4.54:1
+hexrgba contrast "#777" white --level AA   # prints 4.47:1, exits 1
+hexrgba blend "#0000ff80" red          # #7f0080
+```
+
+Quote a leading `#`: most shells read it as the start of a comment. Errors go to stderr.
+Exit codes: 0 success, 1 the pair fails `--level`, 2 bad usage or an invalid color. `python -m hexrgba` works too.
+
+## Why
+
+`webcolors` is built around the CSS named-color tables, and most other color packages pull
+in a wider model of color spaces. `hexrgba` stays small and exact: the hex and keyword
+syntax of CSS, checked against the spec tables and the Web Platform Tests vectors, an
+alpha conversion that never drifts, and the WCAG contrast math, with no dependencies.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Links
+
+- Website: https://lianes8studio.com
+- GitHub: https://github.com/JaviLianes8
+- LinkedIn: https://www.linkedin.com/in/jlianes/

hexrgba-0.2.1.dist-info/RECORD

@@ -0,0 +1,16 @@
+hexrgba/__init__.py,sha256=9Cf4qBwBlW97uWC2qUjGQC8sfnY4wvGznG6F_2Xglo8,920
+hexrgba/__main__.py,sha256=5-6tPw_mmezSTz4Gzuu9YObksMe5frssWwKa0Dtziwg,156
+hexrgba/_alpha.py,sha256=QEklpgRrDcXZ5xd0WrWG1PNpp0uzOJB_4lrIUbZekwg,2419
+hexrgba/_blend.py,sha256=lXf4POQhXOfkwPpH8NyoCxmWXxR661xCrjI5DBmQvEI,2286
+hexrgba/_cli.py,sha256=qxg6VDiF9598vlap1LXkWDnHsRQonpJ3eq6VUi0DyDE,5040
+hexrgba/_color.py,sha256=PN5C8KtNZTS_RPvMbuQ8wPPSl-_N8tXXt1AajJoKIqo,5479
+hexrgba/_errors.py,sha256=U9q80RF1LGknT5MCrp8mCOneYpaYbhGXD5BcLji9kHo,977
+hexrgba/_hex.py,sha256=kVXiunGCV7Th1t19e2q9t0gcZm-dHfkDM30n00pci-U,3178
+hexrgba/_names.py,sha256=A0Kp-yMT6Xp1FdTgXQUoEWO0nRHtbh6uCusOKYpK6OY,4668
+hexrgba/_wcag.py,sha256=qfIGIXZhEQlOsL_6psZdw5Z8WScuVG4dmvabjtMc_Jw,2952
+hexrgba/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+hexrgba-0.2.1.dist-info/METADATA,sha256=c1LkganAl8QWukGXDInMkSbcmM6GCgMmqQjobIppS3w,4178
+hexrgba-0.2.1.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+hexrgba-0.2.1.dist-info/entry_points.txt,sha256=reKvZdBTUG_jz6woh-znKy3xHXdZzCIqzBMmzzJJ1Ac,46
+hexrgba-0.2.1.dist-info/licenses/LICENSE,sha256=_WmABlQG__oqlx4Rzp-qDJ10xND5KCLScftbhXbLC_c,1070
+hexrgba-0.2.1.dist-info/RECORD,,

hexrgba-0.2.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

hexrgba-0.2.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+hexrgba = hexrgba._cli:main

hexrgba-0.2.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Javier Lianes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.