From 90b3c32898fa7f0892674994d92dcc019637f583 Mon Sep 17 00:00:00 2001 From: Derek Gulbranson Date: Tue, 7 Jul 2026 15:51:11 -0700 Subject: [PATCH] docs: describe the parser as vocabulary + positional layers in README Reorganize the README's how-it-works prose around the two-layer model: a vocabulary layer that recognizes pieces by what they are (the customizable sets), and a positional layer that assigns the rest by where it sits. States explicitly that parsing is deterministic (no statistical models) and that the positional layer assumes Western name order. All claims from the previous prose are preserved. Co-Authored-By: Claude Fable 5 --- README.rst | 58 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 36 insertions(+), 22 deletions(-) diff --git a/README.rst b/README.rst index bbecaba..0a09a80 100644 --- a/README.rst +++ b/README.rst @@ -29,19 +29,35 @@ are optional. Comma-separated format like "Last, First" is also supported. 2. Lastname [Suffix], Title Firstname (Nickname) Middle Middle[,] Suffix [, Suffix] 3. Title Firstname M Lastname [Suffix], Suffix [Suffix] [, Suffix] -Instantiating the `HumanName` class with a string splits on commas and then spaces, -classifying name parts based on placement in the string and matches against known name -pieces like titles and suffixes. - -It correctly handles some common conjunctions and special prefixes to last names -like "del". Titles and conjunctions can be chained together to handle complex -titles like "Asst Secretary of State". It can also try to correct capitalization -of names that are all upper- or lowercase names. - -It attempts the best guess that can be made with a simple, rule-based approach. -Its main use case is English and it is not likely to be useful for languages -that do not conform to the supported name structure. It's not perfect, but it -gets you pretty far. +How It Works +~~~~~~~~~~~~ + +The parser works in two layers. + +A **vocabulary layer** recognizes name pieces by what they are, using +configurable sets of known words: titles ("Dr."), suffixes ("III", "PhD"), +last-name prefixes ("de la"), conjunctions ("y", "&"), and delimited +nicknames ("Doc"). Titles and conjunctions chain together to handle complex +titles like "Asst Secretary of State"; prefixes join forward so "de la Vega" +stays one last name. This layer doesn't care where in the string a word +appears — and it's the layer you customize, by adding or removing entries +in the sets to fit your dataset. + +A **positional layer** then assigns everything the vocabulary layer didn't +claim, based purely on where it sits: the first unclaimed word is the first +name, the last one is the last name, and anything between them is a middle +name. There is no semantic understanding — "Dr" is a title when it comes +before a name and a suffix when it comes after ("pre-nominal" and +"post-nominal" would probably be better names) — and no attempt to correct +mistakes in the input. + +It attempts the best guess that can be made with a simple, deterministic, +rule-based approach — no statistical models or machine learning; the same +input always parses the same way. The positional layer assumes Western name +order (given name first), so the main use case is English and other +languages that share that structure. It can also try to correct the +capitalization of names that are all upper- or lowercase. It's not perfect, +but it gets you pretty far. Installation ------------ @@ -88,11 +104,8 @@ Quick Start Example 'Juan de la Vega' -The parser does not attempt to correct mistakes in the input. It mostly just splits on white -space and puts things in buckets based on their position in the string. This also means -the difference between 'title' and 'suffix' is positional, not semantic. "Dr" is a title -when it comes before the name and a suffix when it comes after. ("Pre-nominal" -and "post-nominal" would probably be better names.) +Because the positional layer has no semantic understanding, position is +everything: :: @@ -111,10 +124,11 @@ and "post-nominal" would probably be better names.) Customization ------------- -Your project may need some adjustment for your dataset. You can -do this in your own pre- or post-processing, by `customizing the configured pre-defined -sets`_ of titles, prefixes, etc., or by subclassing the `HumanName` class. See the -`full documentation`_ for more information. +Your project may need some adjustment for your dataset. Most customization +is vocabulary — `customizing the configured pre-defined sets`_ of titles, +prefixes, etc. that the vocabulary layer matches against. You can also do +your own pre- or post-processing, or subclass the `HumanName` class for +deeper changes. See the `full documentation`_ for more information. `Full documentation`_