hexrgba 0.2.1__tar.gz

hexrgba-0.2.1/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Third-party test files, fetched locally by scripts/fetch_upstream.py; only the manifest is tracked.
+tests/upstream/*
+!tests/upstream/MANIFEST.json

hexrgba-0.2.1/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.1] - 2026-10-13
+
+### Changed
+
+- The Web Platform Tests color parsing pages are no longer committed or shipped in the
+  sdist: `scripts/fetch_upstream.py` fetches them at a pinned commit, checked against
+  `tests/upstream/MANIFEST.json`, and hand-written cases keep the default suite meaningful
+  without them.
+
+## [0.2.0] - Unreleased
+
+### Added
+
+- `parse_color` and `is_color`: hex colors plus all 148 CSS named colors and
+  `transparent`, matched ASCII case-insensitively, with a `strict` mode that follows the
+  CSS grammar exactly.
+- `Color`, a frozen, hashable value type with `hex`, `to_hex(short=...)`, `to_css()`,
+  `name`, `alpha`, `is_opaque`, `with_alpha()`, `from_rgba()` and `as_tuple()`.
+- `NAMED_COLORS`, the read-only CSS Color 4 named color table.
+- `alpha_to_byte` and `css_alpha`: exact alpha conversion and the CSS legacy alpha
+  serialization; every alpha byte round-trips through both.
+- `shorten` and `normalize(..., short=True)` for the lossless `#rgb` / `#rgba` form.
+- `relative_luminance`, `contrast_ratio` and `passes_contrast` (WCAG 2.x, AA and AAA).
+- `blend`, simple alpha compositing of one color over another.
+- `ColorError`, `ColorNameError` and `ChannelError`. `HexColorError` is now a
+  `ColorError`, still a `ValueError`.
+- The `hexrgba` command (`normalize`, `convert`, `contrast`, `blend`) and `python -m hexrgba`.
+- `GUIDE.md`, with the exact rules and their sources.
+
+## [0.1.0]
+
+- First release: `is_hex`, `parse`, `normalize`, `to_hex` and `HexColorError`.
+- Support for `#rgb`, `#rgba`, `#rrggbb` and `#rrggbbaa`, with optional leading hash,
+  any case, shorthand expansion and alpha round-tripping.

hexrgba-0.2.1/GUIDE.md

@@ -0,0 +1,145 @@
+# hexrgba guide
+
+This guide states the exact rules `hexrgba` follows and where each one comes from. All
+sources were fetched on 2026-10-12.
+
+| Topic | Source |
+| --- | --- |
+| Hex syntax, named colors, `transparent`, serialization | [CSS Color Module Level 4](https://www.w3.org/TR/css-color-4/), Candidate Recommendation Draft of 9 October 2026, sections 5.2, 6.1, 6.3 and 16 |
+| Golden parsing vectors | [Web Platform Tests `css/css-color/parsing`](https://github.com/web-platform-tests/wpt/tree/786385c76ca1c01d40eba0234dc59384e2eb73d4/css/css-color/parsing), commit `786385c` |
+| Luminance and contrast | [WCAG 2.2](https://www.w3.org/TR/WCAG22/), Recommendation of 12 December 2024 |
+| Blending | [Compositing and Blending Level 1](https://www.w3.org/TR/compositing-1/), section 5.1 |
+
+## Parsing
+
+`parse_color(text, *, strict=False)` returns a `Color`. It accepts:
+
+- `#rgb`, `#rgba`, `#rrggbb` and `#rrggbbaa`. Short forms expand by doubling each digit,
+  so `#123` is `#112233`. Without an alpha pair the color is opaque (alpha byte 255).
+- The 148 keywords of the CSS named color table (it includes `rebeccapurple` and both
+  spellings of every gray), and `transparent`, which is `rgba(0, 0, 0, 0)`.
+
+Hex digits and keywords are **ASCII** case-insensitive: only `A` to `Z` fold. That matters
+because Python's `str.lower()` folds more: the Kelvin sign `U+212A` lowers to `k`, so a
+naive parser would accept `blac` + Kelvin sign as `black`. CSS rejects it, the WPT suite
+tests it, and so does `hexrgba`.
+
+| Mode | Leading `#` | Surrounding whitespace | Upper case |
+| --- | --- | --- | --- |
+| `strict=True` | required for hex | rejected | accepted (CSS is case-insensitive) |
+| lenient (default) | optional | stripped with `str.strip()` (any Python whitespace) | accepted |
+
+No keyword is made only of hex digits, so lenient mode can never confuse a name with a
+hash-less hex color; a test pins that.
+
+`currentcolor`, system colors and the functional notations (`rgb()`, `hsl()`, `color()`)
+are not accepted as input: they need a cascade or a much larger grammar.
+
+The `0.1.0` functions (`is_hex`, `parse`, `normalize`, `to_hex`) keep their exact
+behaviour: hex only, lenient, `(r, g, b, a)` tuples.
+
+## Output
+
+- `Color.hex` and `normalize()` give canonical lower-case `#rrggbb` when opaque and
+  `#rrggbbaa` otherwise.
+- `to_hex(short=True)`, `normalize(..., short=True)` and `shorten()` give `#rgb` or `#rgba`
+  only when that is lossless (`#aabbcc` to `#abc`, `#aabbcd` stays long).
+- `Color.to_css()` follows "CSS serialization of sRGB values" (section 16.2.2): `rgb(r, g, b)`
+  when the alpha byte is 255, else `rgba(r, g, b, alpha)`, comma separated with one space.
+  The WPT expected strings are used as the test oracle.
+- `Color.name` gives the keyword for an exact match, or `None`. Where two keywords share a
+  value (`aqua` and `cyan`, `fuchsia` and `magenta`, `gray` and `grey`) the first in the
+  spec's alphabetical table wins.
+
+## Alpha: 0..255 versus 0..1
+
+The alpha is stored as a byte, `Color.a`, from 0 to 255. There are two float views and
+one way back:
+
+- `Color.alpha` is exactly `a / 255`.
+- `css_alpha(a)` is the CSS legacy alpha string (section 16.1.1). If a whole percentage
+  `n` satisfies `round(n * 2.55) == a`, the result is `n / 100` (237 gives `0.93`, 204
+  gives `0.8`, 128 gives `0.5`). Otherwise it is `a / 0.255` rounded and divided by 1000
+  (236 gives `0.925`). Halves round up. The arithmetic is exact, not binary floating point.
+- `alpha_to_byte(x)` multiplies by 255 and rounds halves up. A float is read as its
+  shortest decimal form, the number you typed: `0.3` is 76.5 and gives 77, where the
+  binary value just below 0.3 would give 76.
+
+**Round-trip contract**, tested for all 256 bytes:
+
+```python
+alpha_to_byte(a / 255) == a
+alpha_to_byte(float(css_alpha(a))) == a
+```
+
+So `#rrggbbaa` to `Color.alpha` (or to the `rgba()` string) and back to hex is lossless.
+The other direction cannot be: a byte has 256 values, so `alpha_to_byte(0.123)` gives 31,
+and `css_alpha(31)` is `0.12`, which reads back as 31, not as 0.123.
+
+One note on the spec: for byte 236 its prose example prints `0.92549`, but its own
+numbered steps give `0.925`. `hexrgba` follows the numbered steps.
+
+## Contrast
+
+`relative_luminance(color)` is `0.2126 R + 0.7152 G + 0.0722 B` on linearized sRGB
+channels, using the `0.04045` threshold of the current WCAG definition (older texts said
+`0.03928`; no 8-bit value falls between the two, so results are identical). Alpha is
+ignored.
+
+`contrast_ratio(fg, bg)` is `(L1 + 0.05) / (L2 + 0.05)` with `L1` the lighter, from 1 to 21.
+A translucent foreground is first blended over the background and rounded to 8-bit
+channels, as a browser paints it; the ratio is measured on that painted color. The background must be
+opaque, because what lies behind it is unknown.
+
+`passes_contrast(fg, bg, level="AA", large=False)` compares without rounding, as WCAG
+requires (4.499 fails 4.5):
+
+| Level | Normal text | Large text |
+| --- | --- | --- |
+| AA (1.4.3) | 4.5 | 3 |
+| AAA (1.4.6) | 7 | 4.5 |
+
+The test suite checks the worked examples published by WCAG (for example `#949494` on
+white is 3:1, `#E3660E` on white is 3.4:1). WCAG prints those with one decimal and does not
+round consistently, so each is checked to within 0.1.
+
+## Blending
+
+`blend(fg, bg)` is source-over simple alpha compositing:
+
+```
+ao = as + ab (1 - as)
+Co = (Cs as + Cb ab (1 - as)) / ao
+```
+
+It is computed with exact fractions and each channel is rounded to a byte once, halves
+up. If both inputs are fully transparent the result is transparent black.
+
+## Errors
+
+All errors are `ValueError` subclasses, so `0.1.0` handlers keep working:
+
+- `ColorError`: base class; also raised for a translucent contrast background.
+- `HexColorError`: malformed hex, or a hash-less hex in strict mode.
+- `ChannelError` (a `HexColorError`): a channel or alpha outside its range or of the
+  wrong type, including booleans.
+- `ColorNameError`: neither hex nor a known keyword.
+
+`parse_color` raises `TypeError` for a non-string. `is_color` never raises.
+`is_hex` and `parse` keep their 0.1.0 behaviour and raise `AttributeError` for a non-string.
+Error messages show at most the first 40 characters of the offending value.
+
+## Command line
+
+```
+hexrgba normalize COLOR [--short] [--strict]
+hexrgba convert COLOR [--to hex|short|css|channels|name] [--strict]
+hexrgba contrast FOREGROUND BACKGROUND [--level AA|AAA] [--large]
+hexrgba blend FOREGROUND BACKGROUND
+```
+
+`contrast` prints the ratio truncated to two decimals (a failing 4.499 never shows as
+4.50); with `--level` it exits 1 when the pair fails. `--large` is only valid with `--level`.
+Bad usage and invalid colors print to stderr and exit 2, so a script can tell a failing
+pair from bad input. Every example in `hexrgba --help` is executed by the
+test suite and by the wheel end-to-end check.

hexrgba-0.2.1/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.

hexrgba-0.2.1/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,82 @@
+# 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/pyproject.toml

@@ -0,0 +1,72 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "hexrgba"
+version = "0.2.1"
+description = "CSS hex and named colors: parse, normalize, exact alpha, rgba(), WCAG contrast and blending"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Javier Lianes", email = "javier@lianes8studio.com" }]
+keywords = [
+    "hex", "color", "css", "rgba", "parse", "normalize", "named-colors", "wcag", "contrast", "blend",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.scripts]
+hexrgba = "hexrgba._cli:main"
+
+[project.optional-dependencies]
+dev = ["ruff", "mypy", "pytest", "build", "twine"]
+
+[project.urls]
+Homepage = "https://lianes8studio.com"
+Repository = "https://github.com/JaviLianes8/hexrgba"
+Issues = "https://github.com/JaviLianes8/hexrgba/issues"
+Changelog = "https://github.com/JaviLianes8/hexrgba/blob/main/CHANGELOG.md"
+LinkedIn = "https://www.linkedin.com/in/jlianes/"
+Funding = "https://buymeacoffee.com/jlianesglrs"
+
+[tool.hatch.build.targets.sdist]
+# Third-party test files are fetched locally and never shipped; only their manifest is.
+include = [
+    "src/hexrgba",
+    "tests/*.py",
+    "tests/fixtures/css-color-4-named-colors.json",
+    "tests/upstream/MANIFEST.json",
+    "scripts/fetch_upstream.py",
+    "scripts/e2e_wheel.py",
+    "CHANGELOG.md",
+    "GUIDE.md",
+    "README.md",
+    "LICENSE",
+    "pyproject.toml",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hexrgba"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+addopts = "-q"

hexrgba-0.2.1/scripts/e2e_wheel.py

@@ -0,0 +1,106 @@
+"""Build the wheel, install it in a throwaway venv and drive the installed command.
+
+Run from anywhere: ``python scripts/e2e_wheel.py``. Exits 0 when every check passes.
+Needs pip and network access for the build backend. Every example printed by
+``hexrgba --help`` is executed against the installed script and must hold.
+"""
+
+from __future__ import annotations
+
+import os
+import shlex
+import subprocess
+import sys
+import tarfile
+import tempfile
+import zipfile
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+
+
+def run(cmd: list[str], *, cwd: Path, env: dict[str, str] | None = None) -> tuple[int, str, str]:
+    done = subprocess.run(cmd, capture_output=True, cwd=cwd, env=env, check=False, timeout=600)
+    return done.returncode, done.stdout.decode("utf-8"), done.stderr.decode("utf-8")
+
+
+def check(label: str, condition: bool, detail: object = "") -> None:
+    print(("ok   " if condition else "FAIL ") + label + ("" if condition else f": {detail!r}"))
+    if not condition:
+        raise SystemExit(1)
+
+
+def help_examples(help_text: str) -> list[tuple[list[str], int, str]]:
+    """Return (argv, exit code, stdout) for every ``hexrgba ... -> ...`` help line."""
+    examples = []
+    for line in help_text.splitlines():
+        if not line.startswith("  hexrgba ") or "->" not in line:
+            continue
+        command, expected = (part.strip() for part in line.split("->", 1))
+        code = 0
+        if expected.startswith("exits 1:"):
+            code, expected = 1, expected.removeprefix("exits 1:").split()[0]
+        examples.append((shlex.split(command)[1:], code, expected))
+    return examples
+
+
+def main() -> int:
+    with tempfile.TemporaryDirectory(prefix="hexrgba-e2e-") as raw:
+        work = Path(raw)
+        dist = work / "dist"
+        code, _, err = run(
+            [sys.executable, "-m", "pip", "wheel", "--no-deps", "-w", str(dist), str(ROOT)],
+            cwd=work,
+        )
+        check("wheel builds", code == 0, err[-2000:])
+        wheel = next(dist.glob("hexrgba-*.whl"))
+        names = zipfile.ZipFile(wheel).namelist()
+        check("wheel ships py.typed", "hexrgba/py.typed" in names, names)
+        check("wheel has no tests", not any(n.startswith(("tests/", "scripts/")) for n in names))
+        entry = [n for n in names if n.endswith("entry_points.txt")]
+        text = zipfile.ZipFile(wheel).read(entry[0]).decode() if entry else ""
+        check("console script declared", "hexrgba = hexrgba._cli:main" in text, text)
+
+        code, _, err = run(
+            [sys.executable, "-m", "build", "--sdist", "-o", str(dist), "."], cwd=ROOT
+        )
+        check("sdist builds", code == 0, err[-2000:])
+        with tarfile.open(next(dist.glob("hexrgba-*.tar.gz"))) as sdist:
+            members = [n.split("/", 1)[-1] for n in sdist.getnames()]
+        check("sdist ships the manifest", "tests/upstream/MANIFEST.json" in members, members)
+        check("sdist has no WPT page", not any(n.endswith(".html") for n in members), members)
+
+        venv = work / "venv"
+        check("venv created", run([sys.executable, "-m", "venv", str(venv)], cwd=work)[0] == 0)
+        bindir = venv / ("Scripts" if os.name == "nt" else "bin")
+        python = str(bindir / "python")
+        code, _, err = run(
+            [python, "-m", "pip", "install", "--no-index", "--no-deps", str(wheel)], cwd=work
+        )
+        check("wheel installs", code == 0, err[-2000:])
+        tool = str(bindir / "hexrgba")
+        env = {"PATH": os.environ.get("PATH", ""), "SYSTEMROOT": os.environ.get("SYSTEMROOT", "")}
+
+        code, out, _ = run([tool, "--version"], cwd=work, env=env)
+        check("--version", code == 0 and out.strip().startswith("hexrgba 0.2"), out)
+        code, out, _ = run([tool, "--help"], cwd=work, env=env)
+        check("--help shows examples", code == 0 and "examples" in out, out)
+        examples = help_examples(out)
+        check("help has examples", len(examples) >= 8, examples)
+        for argv, want_code, want_out in examples:
+            code, got, _ = run([tool, *argv], cwd=work, env=env)
+            check(f"example {' '.join(argv)}", (code, got.strip()) == (want_code, want_out), got)
+
+        code, out, err = run([tool, "normalize", "nope"], cwd=work, env=env)
+        check("bad input exits 2 on stderr", (code, out) == (2, "") and "error" in err, err)
+        code, out, _ = run([python, "-m", "hexrgba", "normalize", "BLACK"], cwd=work, env=env)
+        check("python -m hexrgba", (code, out.strip()) == (0, "#000000"), out)
+        probe = "import hexrgba; print(hexrgba.Color.parse('rebeccapurple').to_css())"
+        code, out, _ = run([python, "-c", probe], cwd=work, env=env)
+        check("library import", out.strip() == "rgb(102, 51, 153)", out)
+    print("e2e: all checks passed")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

hexrgba-0.2.1/scripts/fetch_upstream.py

@@ -0,0 +1,37 @@
+"""Fetch the third-party test files listed in tests/upstream/MANIFEST.json.
+
+The files are not part of the repository. Their tests skip until this script has fetched
+them; each download is checked against the size and sha256 in the manifest.
+
+    python scripts/fetch_upstream.py
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import sys
+import urllib.request
+from pathlib import Path
+
+FOLDER = Path(__file__).resolve().parents[1] / "tests" / "upstream"
+
+
+def main() -> int:
+    manifest = json.loads((FOLDER / "MANIFEST.json").read_text(encoding="utf-8"))
+    failed = 0
+    for name, entry in manifest.items():
+        with urllib.request.urlopen(entry["url"], timeout=60) as response:
+            body = response.read()
+        digest = hashlib.sha256(body).hexdigest()
+        if len(body) != entry["size"] or digest != entry["sha256"]:
+            print(f"{name}: got {len(body)} bytes, sha256 {digest}; manifest differs")
+            failed += 1
+            continue
+        (FOLDER / name).write_bytes(body)
+        print(f"{name}: ok")
+    return 1 if failed else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

hexrgba-0.2.1/src/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",
+]