docs: phase 5 — architecture page (Layout + Why pure Python → docs/)#8
Merged
Conversation
Migrates the README's contributor-only "Layout" and "Why pure Python" sections (both below the <!-- pypi-end --> marker, so neither showed on PyPI in the first place) into a polished docs/explanation/ architecture.md, with three deepenings the README sections didn't have room for: * **The matching pipeline.** Two ASCII diagrams: pattern compile (input → constructor FSM → canonicalize → tokenize → parts → regex source → compiled engine) and match-time (yarl.URL → canonicalize → fullmatch → structured URLPatternResult). Made the "same canonicalization runs on both sides" property explicit. * **The engine seam.** A Protocol sketch showing how the optional regex-package adapter plugs in, and how a future PyO3 backend around liburlpattern or rust-urlpattern would slot under ``_regex_engine/`` without touching the URLPattern surface. * **Where the implementation diverges from the simplest possible shape.** Names the three places (yarl.URL fast path, ``with_*`` derivers, the three WHATWG-strictness rules) so a reader doesn't have to spelunk to find them — and forward-links the strictness detail to the existing yarl comparison page. README's Layout and Why-pure-Python sections collapse to a single three-line forward-link block. properdocs nav gets a new "Explanation" section. Phase 5 task #47 closed.
github-actions
Bot
added
the
documentation
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
1 participant
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
Migrates the README's contributor-only Layout + Why-pure-Python sections (both already below the `` marker) into a polished `docs/explanation/architecture.md`. Adds three things the README sections didn't have room for:
README collapses the two sections to a three-line forward-link block. properdocs nav grows an "Explanation" section.
Test plan