Show more of the parser in the README example - #340
Merged
Conversation
The 1.4 example showed the whole parse at once through the repr; 2.x had shrunk to two attribute accesses. The repr is back, since it is the only thing that shows every field in one place, and family_base / family_particles come with it because the particle split is a 2.x view 1.4 had no equivalent for. Six scripts now, all under the default configuration: Chinese and Japanese family-first, the Korean census split, a glued honorific, a Cyrillic title, and the Arabic bn chain. Russian patronymics go last because they are the one case here that needs its pack, which is worth showing rather than hiding. No subheadings and no explanatory prose. The comments carry it. Dropped the paragraph naming the seven fields: the intro two paragraphs up already names them, and the repr now shows them. Every line is doctested by the README doctest CI step. Verified the file is still valid RST and that twine accepts it as a long description, since PyPI renders it.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #340 +/- ##
=======================================
Coverage 98.48% 98.48%
=======================================
Files 41 41
Lines 2845 2845
=======================================
Hits 2802 2802
Misses 43 43 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
The example was '毛 泽东', spaced, which is not how Chinese names are written. It was chosen because the spaced form demonstrates family-first order without needing a pack, but that is a capability shown against input nobody has: a reader who tries the realistic '毛泽东' gets the whole name in family and concludes it does not work. It now uses '毛泽东' under locales.ZH, which is both the real spelling and the real answer, and it sits beside the Russian patronymic because they need a pack for the same class of reason. That grouping is the honest one. Korean unspaced works by default because hangul is written by one language and its surnames are a closed census set; Han text cannot say which language wrote it, so a Chinese surname list would split 高橋一郎 in the wrong place. The comment says so.
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
The 1.4 README showed the whole parse at once through the repr. 2.x had shrunk to two attribute accesses on one Western name, which showcases very little of what the parser now does.
This brings the repr back and adds six scripts.
What it shows now
family_base/family_particles, a 2.x view 1.4 had no equivalent for, which makes the particle handling visibleبنchainСидоров Иван Петровичparses wrong withoutlocales.RU, so showing the pack is more honest than picking a Cyrillic example that happens to need nothing.Choices worth reviewing
No subheadings, no explanatory prose. The comments carry it, per review feedback. Blank lines group the three ideas.
The Arabic line keeps its trailing comment like the others, for consistency. Renderers give code blocks an LTR base direction, so it reads correctly; I had considered moving its explanation to prose to avoid bidi mixing, but that would have meant a heading or a paragraph, which is what we were removing.
Dropped the "Those seven fields are…" paragraph. The intro two paragraphs above already names all seven, and the repr now shows six of them (
maidenis omitted when empty, as it is here).Verification
python -m doctest README.rst— 15 tests pass (was 4); this runs in CIdocutils.publish_doctreereports no warningstwine checkon the built sdist — PASSED, so PyPI will render ituv run pytest -q— 3065 passedNo code changed.
🤖 Generated with Claude Code