docs(readme): consolidate conformance, surface subtle correctness wins#22
Merged
Conversation
…ness wins
Restructures the README so conformance is the first H2 after the hero
code, replacing the older "WHATWG conformance" + "Test corpus matrix" +
"API surface" split which fragmented the same story across three
sections.
The new ``## Conformance`` section opens with the 469 / 469 headline,
shows a single seven-row table covering all five upstream WPT suites
plus the in-repo unit-test suite (599 tests total), and links out to:
- docs/wpt-compliance.md — the auto-regenerated per-case report
- SPEC_DEVIATIONS.md — documented deviations and stricter-than-yarl
rules
A new ``### What we get right that's easy to miss`` subsection promotes
the per-component canonicalisation rules that distinguish a spec-strict
implementation from a stdlib approximation:
- WHATWG URL parsing end-to-end via yarl (not urllib.parse)
- IDNA2008 / UTS46 hostname canonicalisation via the third-party
`idna` package (not Python's stdlib IDNA2003 codec)
- Strict port parsing — "8080xyz" rejected
- Case-preserving %XX in pattern literals (WPT 146 / 148)
- U+FFFD substitution for unpaired surrogates (WPT 157)
- Hostname truncation at ? / # / / / \
Drops the duplicate "three places stricter than yarl" list from the
``How this differs from yarl`` section in favour of a one-line pointer
to the Conformance section + SPEC_DEVIATIONS.md.
Folds the API-surface table into a single sentence — the table was
redundant alongside the WPT-suites table since every row was green.
Tightens the Install and BYO-regex-engine sections so the 99.5% /
100% framing lives in exactly one place (the Conformance section's
stdlib-only callout).
No behavior changes; README-only.
e149a9c to
5c55782
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Restructures the README so the conformance story is the first H2 after the hero code, replacing the older "WHATWG conformance" + "Test corpus matrix" + "API surface" split which fragmented the same story across three sections.
Depends on #21 — the new conformance table claims 469 / 469 + the in-repo 130 unit tests = 599. That's only true once
URLPattern.generate()lands. Either merge #21 first, or merge this and #21 together.What changes
New
## Conformancesection (right after the hero code)New
### What we get right that's easy to misssubsectionPromotes the per-component canonicalisation rules that distinguish a spec-strict implementation from a stdlib approximation:
urllib.parse)idnapackage (not Python's stdlib IDNA2003 codec)"8080xyz"rejected%XXin pattern literals (WPT 146 / 148)?/#///\Consolidations
Test plan
just lint— all tools green (ruff, mypy, pyright, ty, semgrep, shellcheck, rumdl, codespell, interrogate, validate-pyproject)pyproject.tomlrewrite the new relative links (docs/wpt-compliance.md,SPEC_DEVIATIONS.md,scripts/fetch_references.sh) to absolute GitHub URLs at sdist build timeNo behavior changes; README-only.