NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI
PyPI, #2277 most downloaded on PyPI
Parse human names into title, given, middle, family, suffix, nickname and maiden name. Typed, zero-dependency, CJK-aware.
Latest stable
3.1.0
Last release 5 days ago
17 Nov 2026
Ships unpredictably
gaps range from 8 days to 2.7 years
Nearly every release is documented
notes for 56 of the last 60 stable releases
Nothing withdrawn
no release was ever pulled
15 years old
74 releases · first in 2012
Drag across the ruler to compare, or tap a release to open it.
nameparser 3.1 introduces two new tools for working with lists of names: one for configuration and one for matching. Parser.suggest() suggests the Pol
nameparser 3.1 introduces two new tools for working with lists of names: one for configuration and one for matching. Parser.suggest() suggests the Policy settings for the list of names you give it, and Parser.matching() provides tools for joining records from different sources. It also reads family names written in capitals (DUPONT Jean), Thai titles, and a given name written as a run of initials, and adds Mongolian, Arabic and Hebrew packs. Highlights:
Parser.suggest() the names from one source and it works out how they are written: family name first or last, with patronymics, with the family name in capitals or as trailing letters. It returns a parser set up that way, shows what it saw in each name, and leaves the base parser alone where the list gives no clear answer. It never guesses a language, so choosing a pack is still yours. (#1308)J. Smith in one source, John Smith in another and Smith, John Q. in a third. Parser.matching() says whether two names are consistent and why, role by role, and you choose how much difference to accept: an initial for a full name by default, Bill for William if you ask. For a long list it gives each name keys to group on, so you never compare every pair. (#1006)DUPONT Jean). A new setting has the parser take the capitals at their word, so a list that mixes DUPONT Jean with Jean DUPONT reads the same way throughout. A second setting does the same for a family name written as trailing letters. (#659, #1254)parse("นายสมชาย ใจดี") gives title นาย, given สมชาย, family ใจดี, the salutation split from the given name it is written joined to. (#317)locales.MN, locales.AR and locales.HE, for Mongolian, Arabic and Hebrew names. (#1237, #1248)Upgrading from 3.0
parse("J.R.R. Tolkien") gives given J., middle R.R., where 3.0 gave given J.R.R.. (#1296)Md. opening a name is the given name, Muhammad written short, where 3.0 read a title. (#1383)Lexicon, Parser or locale pack pickled by 2.x no longer loads; re-pickle it under 3.0 first. One pickled by 3.1 does not load under 3.0.x. (#1003)The migration guide lists every name whose reading moved, each with the releases that read it the old way.
Full list of changes: https://nameparser.readthedocs.io/en/latest/release_log.html
Your coding agent can read these notes before it upgrades. Set up the MCP server →
nameparser 3.1 introduces two new tools for working with lists of names: one for configuration and one for matching. Parser.suggest() suggests the Policy settings for the list of names you give it, and Parser.matching() provides tools for joining records from different sources. It also reads family names written in capitals ( DUPONT Jean ), Thai titles, and a given name written as a run of initials, and adds Mongolian, Arabic and Hebrew packs. Migrating to 3.0 lists the names whose reading moved, and which pickles load where. Highlights:
Derive a list’s settings from the list itself. Give Parser.suggest() the names from one source and it works out how they are written: family name first or last, with patronymics, with the family name in capitals or as trailing letters. It returns a parser set up that way, shows what it saw in each name, and leaves the base parser alone where the list gives no clear answer. It never guesses a language, so choosing a pack is still yours. See Settings for a list of names .
Find the records that could be the same person. The same person is J. Smith in one source, John Smith in another and Smith, John Q. in a third. Parser.matching() says whether two names are consistent and why, role by role, and you choose how much difference to accept: an initial for a full name by default, Bill for William if you ask. For a long list it gives each name keys to group on, so you never compare every pair. See Matching names across sources .
Read a family name written in capitals. Many lists mark the family name by writing it in capitals ( DUPONT Jean ), which tells a reader which word is the surname whichever end it is written at. A new setting has the parser take the capitals at their word, so a list that mixes DUPONT Jean with Jean DUPONT reads the same way throughout, and a surname of several words stays whole. A second setting does the same for a family name written as trailing letters. Parser.suggest() turns either on when a list calls for it. See Family names written in capitals and Names ending in initials that are the family name .
Read Thai titles. parse("นายสมชาย ใจดี") gives title นาย , given สมชาย , family ใจดี , the salutation split from the given name it is written joined to; ranks, academic titles and the noble family names that open with ณ are read too.
Read a run of initials as initials. parse("J.R.R. Tolkien") gives given J. , middle R.R. , where 1.4.0 through 3.0.1 gave given J.R.R. , and initials() reads every letter of a dotted run.
New packs. locales.MN , locales.AR and locales.HE , for Mongolian, Arabic and Hebrew names.
All changes
Change README’s License section to credit the sources nameparser’s word lists were measured on. The License-Expression stays LGPL-2.1-or-later , as in every release through 3.0.1: no list copied whole from a third party ships, the familiar forms being pairs the project found in ORCID and US public records and reviewed. No release shipped data from nam_dict (GNU FDL) or Old Dominion University’s nicknames list (Apache 2.0), which the 3.1 cycle’s familiar forms, and for nam_dict the suggester’s table, held until they were rebuilt. The section names Spain’s INE and Taiwan’s surname ranking, whose counts two locale lists were measured on. #1370 , #1382
Change where locales.ZH’s simplified surnames come from: Wikidata’s family-name items and the PRC’s character standards, no longer Unihan. parser_for(locales.ZH).parse("厐建国") gives family 厐建国 , undivided, where 2.5.0 through 3.0.1 gave family 厐 , given 建国 : 厐, which no character standard writes, left the list, its traditional form 龎 still divides, and every other surname reads as in 3.0.1. 2.5.0 through 3.0.1 shipped those forms from Unihan, whose Unicode License v3 their metadata did not name; 3.1 ships no Unihan-derived data. #1370 , #1445
Remove loading a Lexicon, Parser or locale pack pickled by 2.x, which 3.0 deprecated. pickle.loads of a Parser pickled by 2.8.0 raises ValueError saying to re-pickle it under 3.0, where 3.0.x loaded it with a DeprecationWarning ; the error for a 2.x Lexicon spelling now names Migrating to 3.0 ’s table rather than each word’s calls. A Lexicon , Parser , locale pack or Policy pickled by 3.1 does not load under 3.0.x; Pickles lists what loads where. #1003
Change PolicyPatch.script_orders to merge by script. Policy().patched(PolicyPatch(script_orders={Script.HAN: GIVEN_FIRST})) keeps the Hangul and hiragana entries beside its Han one, where 2.1.0 through 3.0.1 replaced the whole table with the patch’s; an empty patch no longer clears the table, which Policy(script_orders=()) on the base parser does. A pack can now add one script’s order without erasing a caller’s own, and parser_for warns where two packs set one script differently. #1237
Add locales.MN, a Mongolian pack. parser_for(locales.MN).parse("Батын Сүхээ") gives family Батын , the father’s name, given Сүхээ , where the default, as 1.4.0 through 3.0.1, gives given Батын , family Сүхээ . It reads a name written wholly in Cyrillic family first with the given name last, Russian and Kazakh names included, so keep it for Mongolian data; a romanized name keeps the caller’s order, since Mongolians mostly write their names given-first in Latin letters. See Mongolian names . #1237
Fix a Kyrgyz name with no surname reading the patronymic marker alone as the family under locales.TR_AZ. parser_for(locales.TR_AZ).parse("Bekmyrza Cholponbai uulu") gives given Bekmyrza , family Cholponbai uulu , where 1.4.0 (with Turkic handling) through 3.0.1 gave middle Cholponbai , family uulu ; a name of three name words ending in a standalone marker ( kyzy , oğlu , qizi ) reads the same way, and two still read the marker alone ( Cavad oğlu ). #1187
Add Parser.matching(), to group and compare names from several sources. Parser().matching().check("John A. Smith", "J. Smith") is consistent, with a table reading the given name as an initial and the middle name as written on one side only, where parse("John A. Smith").matches("J. Smith") is False , and keys() gives grouping keys that a consistent pair always shares. Consistent means nothing in the two names contradicts the match, not that they are one person, and it is not transitive ( J. Smith is consistent with John Smith and with Jane Smith ). An opt-in outcome, familiar-form , reads a familiar form as its longer given name ( Bill / William , Ricky / Richard ), from pairs people wrote both ways for themselves, mostly ORCID’s researchers, each read by two independent reviewers ( Kasia / Katarzyna ); a second, alternate-spelling , reads one given name spelled two ways from the same review ( Yuliya / Iuliia ), and the default reads a letter a keyboard lacks, written as one types it or as its standard transcription, as folded ( Łukasz / Lukasz , Müller / Mueller ). Initials written apart in a family name agree in order or not at all, and capitals spelled by the other side’s names read as initials ( JP Smith / John Paul Smith ); what a key promises is in Matching names across sources . A result has no truth value ( bool() raises TypeError ), so test .consistent . #1006 , #1267 , #1276 , #1261 , #1263 , #1350 , #1351 , #1403 , #1404
Add the order report, on a name of one word followed by initials. parse("Kavitha S").ambiguities holds an order ambiguity, which names no alternative (the other reading lays out the whole name: name_order=FAMILY_FIRST reads it), where 2.0.0 through 3.0.1 report nothing; the reading itself does not change. Capitals written as one word with no full stops ( Armitage JO ) are not reported, being written as a short surname is ( Zhi LI ). #1137 , #1254
Add Policy.capitals_as_family, to read the words a name writes in capitals as its family name. Parser(policy=Policy(capitals_as_family=True)).parse("DUPONT Marie") gives given Marie , family DUPONT , where 1.4.0 through 3.0.1, and the default still, give given DUPONT , family Marie . Parser.suggest() suggests it for a list whose names write the family in capitals of four letters or more. In lists that do not follow the convention capitals also write a given name or a credential, so it is off by default, and it cannot be set with unlisted_caps_suffixes=CapsSuffixes.EVERYWHERE . See Family names written in capitals and Settings for a list of names . #659
Add Policy.initials_as_family, to read the letters ending a name as its family name. Parser(policy=Policy(initials_as_family=True)).parse("Lakshmi R S") gives given Lakshmi , family R S , where 1.4.0 through 3.0.1, and the default still, give middle R , family S . locales.NE turns it on, and Parser.suggest() suggests it for a list whose names repeat one run of letters (Nepal’s B K ). The same string is a middle and a family initial in many lists and a byline written surname first in a bibliography, so it is off by default. #1163 , #1254
Add Parser.suggest(), to read the settings a list of names is written in. Parser().suggest(["Taylor Morgan", "Kim Minjun", "Wang Xiaoming", "Nguyen Anh", "Garcia Emily"]).parser.parse("Taylor Morgan") gives given Morgan , family Taylor , where Parser().parse("Taylor Morgan") gives given Taylor , family Morgan , the list carrying the evidence for a family-first name_order ; a group of East Slavic or Turkic patronymics gets the patronymic rule too. A list of names with no common surname, nor a common given name that is rarely a surname, carries no evidence and keeps the base, and moving the base takes from 5 names (Chinese, Korean, Czech) to 50 (Indian, Russian). A later release may suggest other settings for the same list, so keep the ones you applied with your data. See Settings for a list of names . #1308 , #1355 , #1356 , #1357 , #1397 , #1403 , #1442
Fix the commas of Ethiopic, Burmese, N’Ko, Mongolian, Manchu, Lisu, Vai and Bamum, and the Ethiopic wordspace, which did not divide a name. parse("ከበደ፣ አበበ") gives family ከበደ , given አበበ , where 1.4.0 through 3.0.1 gave given ከበደ፣ , family አበበ ; the other scripts’ commas read the same way, every non-ASCII comma also divides the words of a bracketed credential as the ASCII one does, and አበበ፡ከበደ፡ተሰማ divides into three words at the wordspace ፡ . #1202
Fix a Mongolian case suffix joined by a narrow no-break space, which read as a word of its own. Parser(policy=Policy(name_order=FAMILY_FIRST)).parse("ᠬᠣᠷᠯᠤᠠ ᠶ᠋ᠢᠨ ᠴᠣᠢᠢᠪᠠᠯᠰᠠᠩ") gives family ᠬᠣᠷᠯᠤᠠ ᠶ᠋ᠢᠨ , given ᠴᠣᠢᠢᠪᠠᠯᠰᠠᠩ , where 2.0.0 through 3.0.1 split at the U+202F and gave given ᠶ᠋ᠢᠨ . 1.4.0, which has no name order, split there too, reading middle ᠶ᠋ᠢᠨ . Elsewhere U+202F still divides like a space. #1236
Fix the unbalanced-delimiter report on Dutch ‘t and ‘s, and read ‘s as part of the surname. parse("Pieter 't Hart") and parse("Arent van 's-Gravesande") report nothing, where 2.0.0 through 3.0.1 reported unbalanced-delimiter ; Willem Jacob 's Gravesande gives family 's Gravesande , where 1.4.0 through 3.0.1 gave middle Jacob 's ; and Jan van 't Hof 'Jantje' gives nickname Jantje as 1.4.0 did, where 2.0.0 through 3.0.1 gave t Hof 'Jantje . #1241
Fix case repair capitalizing the vowel after a Ukrainian or Belarusian apostrophe. parse("БЕЗУГЛА МАР'ЯНА").capitalized() gives Безугла Мар'яна , where 1.4.0 through 3.0.1 gave Мар'Яна . An apostrophe before any other letter still starts a capital ( О'Коннор ), in Latin script too ( Dem'Yan ). #1214
Fix Georgian and Armenian titles written in their own scripts reading as the given name. parse("ბატონი დავით ყიფიანი") gives title ბატონი , given დავით , where 1.4.0 through 3.0.1 gave given ბატონი , middle დავით ; the Georgian ქალბატონი , ბ-ნი , ქ-ნი , პროფესორი , დოქტორი and აკადემიკოსი and the Armenian Պարոն , Տիկին , Պրոֆեսոր , Դոկտոր and Ակադեմիկոս read the same way. #1225
Fix El, Ait, Nait, Ould and Ouled, which read as a middle name. parse("Youssef Ait Haddou") gives family Ait Haddou , where 1.4.0 through 3.0.1 gave middle Ait , family Haddou ; Ould also fills patronymic ( Ahmed Ould Haddou ) and Sara El Haddou gives family El Haddou . El opening a name stays the given name, reported, as Al does, but an Algerian given name holding it gives the rest to the family ( Nour El Houda Haddou gives family El Houda Haddou ), and so does a bound given name before it ( Abd El Kader Haddou gives given Abd , family El Kader Haddou , where 2.2.0 through 3.0.1 gave given Abd El , middle Kader and 1.4.0 through 2.1.0 given Abd , middle El Kader ; #1378 ); the others are never a given name, so a name written family first without a comma reads whole as the family ( Ait Haddou Karim ). #1240 , #1249
Add locales.AR and locales.HE, which read Ben as a family-name particle. parser_for(locales.AR).parse("Karim Ben Haddad") gives family Ben Haddad , where the default, as 1.4.0 through 3.0.1, gives middle Ben ; a Ben opening a name stays the given name, reported. Choosing Arabic also reads ABD as Arabic’s given name rather than the credential ( Jane Smith, ABD gives given ABD ). The packs are for surnames: a register-style chain gives its last ben and the rest to the family ( Karim ben Ali ben Salah Haddad gives family ben Salah Haddad ), and parser_for(locales.AR, strict=True) reads a leading Ben as the family name and drops Ait and Nait unless it chooses ber too ( locales.HE keeps Ben given under strict=True ). #1248
Fix Hebrew-script בן, אבו and אל. parse("בן כהן") gives given בן , family כהן , as 1.4.0 did, where 2.0.0 through 3.0.1 gave family בן כהן ; inside a name בן still starts the family name but no longer fills patronymic , parse("סאמי אבו חליל") gives family אבו חליל and parse("נאדר אל חלבי") family אל חלבי , where 1.4.0 through 3.0.1 gave middle אבו and אל . A family name written alone reads as a given and a family name ( בן חיים ), one written family first under FAMILY_FIRST without a comma gives the family בן alone, reported ( בן חיים יעל ; write בן חיים, יעל ), and אל inside a given name gives the rest to the family ( עבד אל עזיז , #1378 ). #1209 , #1210 , #1211
Fix a standalone ال before a name, the clan prefix, reading as a middle name. parse("سارة علي ال ناصر") gives middle علي , family ال ناصر , where 1.4.0 through 3.0.1 gave middle علي ال , family ناصر ; as آل is, it is never a given name, so Arabic-script ال باتشينو (Al Pacino) reads as a family name. #1150
Fix Persian titles, Persian spellings of the Arabic ones, and the Arabic tatweel, which read as the given name. parse("دکتر محمد رضایی") gives title دکتر , given محمد , where 1.4.0 through 3.0.1 gave given دکتر ; parse("الدکتور محمد علی") and parse("الدكتــور خالد سالم") read the title الدکتور , الدكتــور . A Persian title addresses the family name ( دکتر رضایی gives family رضایی ). آقای , خانم , جناب , حضرت , آیتالله , حجتالاسلام and سرلشکر are titles too, and مهندس addresses the family name under a choice of fa ; حاج , شیخ and the spaced آیت الله are not listed. A Lexicon pickled with a word holding a tatweel, which is now deleted when a word is normalized, is refused on load. #1151
Fix the fullwidth full stop between Han, Hangul or kana names, which did not divide them. parse("台邦.撒沙勒") gives given 台邦 , family 撒沙勒 , where 1.4.0 through 3.0.1 gave given 台邦.撒沙勒 , 2.3.0 through 3.0.1 reporting given-or-family , as Taiwan’s Indigenous names written with U+FF0E in place of U+00B7 read; the name keeps its declared order, as the U+00B7 reading does. A fullwidth stop beside a Latin letter, and the ideographic full stop, still divide nothing. #1312
Fix the Armenian Տեր, a priest’s title and a surname’s opening, reading as a given or middle name. parse("Զավեն Տեր Եղիյան") gives family Տեր Եղիյան , where 1.4.0 through 3.0.1 gave middle Տեր , and parse("Տեր Հուսիկ Լազարյան") gives title Տեր , given Հուսիկ , where they gave given Տեր . A spaced Տեր surname written first without a comma ( Տեր Եղիյան Զավեն ) or behind a title ( Պարոն Տեր Պետրոսյան ) reads Տեր as a title. #1225
Fix initials() giving a Thai name its first letters. parse("สมชาย ใจดี").initials() gives '' , where 1.4.0 through 3.0.1 gave ส. ใ. ; Thai shortens no name to a letter. Name matching reads a Thai letter as a whole name, never an initial ( ส. ใจดี and สมชาย ใจดี conflict), and under initials_as_family Thai letters are no run; titles and degrees written short ( ดร. , ร.ต.อ. , พ.บ. ) read as before. #1256
Fix initials() giving a Burmese name its first letters. parse("ကြည် ကြည် ဌေး").initials() gives '' , as a Han, Hangul or kana name does, where 1.4.0 through 3.0.1 gave က. က. ဌ. ; Burmese shortens no name to a letter. Name matching reads a Burmese letter as a whole name, never an initial ( က. Smith and ကြည် Smith conflict), and Shan and Mon written in the Myanmar script read the same way. #1234
Fix a Georgian name read as written in mixed case beside a word in capitals. parse("ჯეკ MA") gives given ჯეკ , family MA , as محمد MA does, where 2.4.0 through 3.0.1 gave suffix MA and no family (1.4.0 through 2.3.0 gave family MA ). Georgian’s capitals are written only for a whole word set in them, so they make no case contrast in a name; a Georgian word behind a credential is a name word too ( ჯეკ ბერიძე Jr. ნინო gives family ნინო ). #1222
Change capitalized() to write a Georgian name mixing Mtavruli with Mkhedruli in Mkhedruli. parse("ნინო ᲑᲣᲠᲯᲐᲜᲐᲫᲔ").capitalized() gives ნინო ბურჯანაძე , where 1.4.0 through 3.0.1 kept it as written; a Mtavruli first letter on Mkhedruli is written in Mkhedruli the same way. A Latin surname in capitals in a name of mixed case is still kept ( Jean DUPONT ), Latin’s capitals being case and Mtavruli a style of a caseless script. #1222
Fix case repair of Georgian written in Mtavruli capitals. parse("ᲜᲘᲜᲝ ᲑᲣᲠᲯᲐᲜᲐᲫᲔ").capitalized() gives ნინო ბურჯანაძე , where 1.4.0 through 3.0.1 kept a Mtavruli first letter ( Ნინო Ბურჯანაძე ). #1223
Change case repair to capitalize a particle that opens a hyphenated word, and a spaced Ter or Der that opens the family name. parse("LEVON TER PETROSYAN").capitalized() gives Levon Ter Petrosyan , where 1.4.0 through 3.0.1 gave Levon ter Petrosyan ; the hyphenated Ter-Petrosyan takes the capital too. A ter or der after another particle in the family name keeps its lowercase ( Jan van der Berg ), while a Dutch surname opened by ter and a German epithet take the capital too ( Gerard Ter Borch , Johann Der Jüngere ); capitalized(force=True) now capitalizes an Arabic article written lowercase ( Mūsā al-Kāẓīm gives Mūsā Al-Kāẓīm ). #1224 , #1283
Change a given name written as a run of initials to read as the initials. parse("J.R.R. Tolkien") gives given J. , middle R.R. and initials() J. R. R. T. , where 1.4.0 through 3.0.1 gave given J.R.R. and J. T. ; str() still gives J.R.R. Tolkien . A run in lower case among capitals ( Dr. h.c. Hans Meier ), one with no family name beside it, and one under middle_as_family or two_given_names keep their one word; a spec or a nickname that sets the given name apart sets the letters apart ( render("{given} {family}") gives J. Tolkien , str() gives E. "Bob" T. Smith for E.T. "Bob" Smith ). initials() reads every letter of a run in the middle or family name too ( Ana J.R. García gives A. J. R. G. , where 1.4.0 through 3.0.1 gave A. J. G. ). Name matching reads the letters too, so Parser().matching().check("J.R.R. Tolkien", "John Ronald Reuel Tolkien") is consistent. #1296
Fix case repair capitalizing Dutch ‘s and ‘t before a hyphen. parse("WILLEM 'S-GRAVESANDE").capitalized() gives Willem 's-Gravesande , where 1.4.0 through 3.0.1 gave Willem 'S-Gravesande . A nickname written in one case with the same opening is lowered too ( AARON 'T-BONE WALKER gives Aaron 't-Bone Walker ). #1280
Fix locales.RU rotating a name with an initial before a surname ending like a patronymic. parser_for(locales.RU).parse("И. Б. Зубкевич") gives family Зубкевич , where 2.0.0 through 3.0.1 gave family И. , given Б. . A family-first name with a given initial and a whole patronymic reads given first now too: Сидоров И. Петрович gives family Петрович and no patronymic, where 2.0.0 through 3.0.1 gave family Сидоров and, since 3.0, patronymic Петрович . #1185
Fix locales.TR_AZ missing the Uzbek o‘g‘li written with a left curly quote, a modifier apostrophe or a backtick. parser_for(locales.TR_AZ).parse("Sa'dullayev Alisher Zafar o‘g‘li") gives family Sa'dullayev , given Alisher , patronymic Zafar o‘g‘li , where 2.0.0 through 3.0.1 gave family o‘g‘li . #1186
Fix a Latin initial spelled in Devanagari, Bengali and the scripts from them to Sinhala reading as a title. parse("एम. एस. वर्मा") gives given एम. , middle एस. , family वर्मा , where 1.4.0 through 3.0.1 gave title एम. एस. ; এম. , ਐਮ. , એમ. and ଏମ. read the same way. No word in the ten Brahmic scripts from Devanagari to Sinhala reads as a title by its period alone now, so an unlisted abbreviation there is a name word; listed titles ( डा. ) are unchanged. #1191
Fix a Turkic patronymic marker written with a combining mark reading as a name word. Parser(policy=Policy(patronymic_rules=frozenset({PatronymicRule.TURKIC}))).parse("Mamedov Ali Huseyn oğlu") with the ğ written as g and a combining breve (U+0306) gives given Ali , family Mamedov , patronymic Huseyn oğlu , as the composed spelling does, where 2.0.0 through 3.0.1 gave given Mamedov , family oğlu and no patronymic; the Cyrillic ўғли with a combining breve on the у and locales.TR_AZ read the same way. #1316
Fix a Cyrillic initial transliterated as two or more letters reading as a title. parse("Yu. A. Chibrikova") gives given Yu. , middle A. , where 1.4.0 through 3.0.1 gave title Yu. , given A. ; Ya. , Ye. , Yo. , Zh. , Kh. , Shch. and Dzh. read the same way, after a family comma too. Ts. , Ch. and Sh. , each also a title written short, are still titles, and other spellings ( Iu. ) are unchanged. #1136
Fix a leading Md., Muhammad written short, reading as a title, and Md after a family comma reading as the degree. parse("Md. Abdul Karim") gives given Md. , middle Abdul , where 1.4.0 through 3.0.1 gave title Md. , given Abdul , and parse("Rahman, Md Abdul") gives given Md , middle Abdul , where 1.4.0 through 2.5.0 gave title Md , given Abdul and 2.6.0 through 3.0.1 suffix Md Abdul ; MD after a name is still the medical degree ( John Smith, MD ), and so is MD in capitals alone after one word ( RAHMAN, MD ). A stop gluing MD. to the word after it still ends a name in a suffix ( SITI AMINAH MD.NOOR ). Name matching reads Md , Mohd and Moh as Muhammad written short, so Parser().matching().check("Mohd Rahman", "Mohammad Rahman") is consistent. To keep the title, see keeping Md. a title . #1383 , #1393 , #1394
Add a same_as naming several words. Lexicon.default().add("zed", kind="given", same_as=["zachary", "zebedee"]) makes Zed a given name written short for both, where 3.0.1 took one word only; words(kind="given", same_as="muhammad") finds a reading by any word it names. same_as="" raises ValueError , where 3.0.1 raised TypeError . #1383
Add the honorific 君 to locales.JA. parser_for(locales.JA).parse("逢沢 一郎君") gives given 一郎 , suffix 君 , as the Diet writes its members, where 2.1.0 through 3.0.1 gave given 一郎君 ; the default parse is unchanged, since 王君 is a complete Chinese name. locales.JA now chooses the language ja , so parser_for(locales.JA, strict=True) builds, keeping only Japanese and language-neutral vocabulary, where it raised, and a Chinese name ending in 君 loses it to the suffix under the pack ( 陳怡君 gives suffix 君 ). #1194
Fix ja_segmenter cutting a name with no kanji after its first character. parser_for(locales.JA, segmenter=locales.ja_segmenter()).parse("あいさわいちろう") gives family あいさわいちろう , as the pack with no segmenter does, where 2.1.0 through 3.0.1 gave family あ , given いさわいちろう . A name holding a kanji still divides ( 山田たろう gives family 山田 ). #1193
Fix a particle’s family name stopping at a credential that spells a name. parse("Ahmad bin Abd Rahman") gives family bin Abd Rahman , where 1.4.0 through 3.0.1 gave middle bin Abd , family Rahman ; Md for Muhammad reads the same way, and before a family comma too ( bin Abd Rahman, Ahmad ). A credential written as one ( Mariam binti MD Salleh ) still ends the name. #1177
Fix a connective before a military title written short. parse("John Smith y Maj.") gives title Maj. , family Smith y , as John Smith y Prof. does, where 3.0.0 and 3.0.1 gave family Smith y Maj. . #1168
Fix credentials written in two chunks joined at a full stop reading as a title or as a guess. parse("Ayu Pangestu, S.Pd, M.Pd") gives suffix S.Pd, M.Pd , where 1.4.0 through 2.3.0 gave title S.Pd and 2.4.0 through 3.0.1 gave title S.Pd M.Pd , and Ahmed Ali B.Pharm reads suffix B.Pharm without the suffix-or-name report 2.4.0 through 3.0.1 gave. 43 such degrees are listed, English ( B.Pharm , C.Psych , M.Tech ), Indonesian ( M.Kes , S.Kom , M.Pd ) and the Portuguese M.Enf . #998
Fix a title written with a full stop after each letter, such as U.S., before another title. parse("U.S. District Judge Marc Thomas Treadwell") gives title U.S. District Judge , given Marc , where 1.4.0 through 3.0.1 gave given U.S. , middle District Judge Marc Thomas . Only U.S. , U.K. and the German P.D. read this way, and only before another title the name keeps: U.S. Grant and U.S. Senator are not read as a title, and initials spelling a title of one word stay a name ( D.R. Judge Smith ). #490
Fix a name glued to the title or initial before it at a full stop reading as one word. parse("Dr.John Smith") gives title Dr. , given John , where 1.4.0 through 3.0.1 gave title Dr.John and no given name, and parse("Ц.Сандаг-Очир") gives given Ц. , family Сандаг-Очир , where they gave given Ц.Сандаг-Очир ; Mr.Smith , Ahmed Ali M.Hassan and Yu.A.Chibrikova read as their spaced writings do, an initial cut from the word ending the name still reporting the credential, and str() keeps the word as written. Only the part before a comma divides, so Ole Simonsen, Dr.Med keeps its degree; a word in lower case after the stop ( Dr.med ), one closed by its own stop ( Dr.Med. ) and a saint’s St.John stay whole. #1230 , #1235
Fix a saint particle glued to a name reading as a title or a credential. parse("St.John Price") gives given St.John , where 1.4.0 through 3.0.1 gave title St.John and no given name, and parse("Mark Jhon Sta.Ana") gives family Sta.Ana , where 2.4.0 through 3.0.1 gave suffix Sta.Ana ; Juan dela Cruz Sta.Maria reads middle dela Cruz , as Juan dela Cruz Sta. Maria does. #1071
Fix the Thai noble family names that open with ณ splitting into a middle and a family name. parse("สุดา ณ อยุธยา") gives family ณ อยุธยา , where 1.4.0 through 3.0.1 gave middle ณ , family อยุธยา . The Latin na ( Suda na Ayutthaya ) is not read as a particle, being also a Korean family name and given name. A royal clan’s surname written before ณ อยุธยา still reads as a middle name ( ปฐมพร อินทรางกูร ณ อยุธยา gives middle อินทรางกูร ). #1167
Fix Thai military and police ranks, the dotted salutations and the royal lineage titles reading as given names. parse("พ.ต.ท. สมมาตร เกลี้ยงสิน") gives title พ.ต.ท. , given สมมาตร , where 1.4.0 through 3.0.1 gave given พ.ต.ท. , middle สมมาตร ; ranks written out ( พันตำรวจโท ) and short, their feminine forms ( พ.อ.หญิง ), น.ส. , ด.ช. , ด.ญ. and หม่อมราชวงศ์ / ม.ร.ว. are listed, glued to the name or apart. #1319
Change a Thai title before one name word to read that word as the given name. parse("ดร. สุดา") gives title ดร. , given สุดา , where 1.4.0 through 3.0.1 gave family สุดา , since Thai addresses a person by the given name after any title. A Thai title alone in brackets now reads as a nickname, as (Sir) does ( parse("สุดา ใจดี (นาย)") gives nickname นาย ). #317
Fix a Thai salutation glued to the given name reading as part of it. parse("นายสมชาย ใจดี") gives title นาย , given สมชาย , where 1.4.0 through 3.0.1 gave given นายสมชาย ; นาย , นาง and นางสาว are listed, and they and the spelled-out titles split off the start of the name’s first word. A title written short ( นพ , ดร ) still reads as part of a glued given name, since given names open with the same letters. #317
Fix Thai academic and professional titles reading as given names. parse("รศ.ดร.สุดา ใจดี") gives title รศ.ดร. , given สุดา , where 1.4.0 through 3.0.1 gave given รศ.ดร.สุดา ; the spelled-out titles ( รองศาสตราจารย์ , อาจารย์ ), their short forms and the physician, dentist, pharmacist and veterinarian titles are listed. A title written short and glued to the name with no full stop ( ดรสุดา ) still reads as part of the given name. #1166
Fix a nickname, a title word and a suffix reading the word as the given name. parse("'Smitty' Pope Jr.") gives family Pope , as 'Smitty' Smith Jr. gives family Smith , where 2.3.0 through 3.0.1 gave given Pope and 1.4.0 through 2.2.0 gave title Pope , given Jr. ; the title-or-name report stays. A title-particle or an initial keeps its reading ( 'Smitty' St Jr. gives given St ); a bracketed credential beside a title word is read as a nickname is ( Pope (PhD) Jr. gives family Pope ). #1169
Fix two capitals before credentials after a comma reading as the given name. parse("Jane Doe, BM PhD") gives given Jane , family Doe , suffix BM PhD , where 1.4.0 through 3.0.1 gave given BM , family Jane Doe ; Jane Doe, BM, PhD and the dotted Jane Doe, B.M., PhD , the pair alone in its part before a listed credential in a later one, read suffix BM, PhD and B.M., PhD the same way. Only behind two or more name words and only before credentials: Jane Doe, BM , Jane Doe, BM, Jr. , Doe, BM PhD and Doe, BM, PhD keep given BM , and dotted initials with credentials in their own part ( John Smith, A.B. Ph.D. ) are still the given and middle names. #1323 , #1392
Fix initials after a one-word surname and a comma that spell a credential reading as the credential. parse("Jansen, J.P.") gives given J. , middle P. , reporting suffix-or-name , where 1.4.0 gave given J.P. and 2.0.0 through 3.0.1 gave suffix J.P. and no given name; de Waart, J.P. and Jansen, Ir. J.P. van read the same way. Smith, M.D. reads given M. , middle D. now too, the credential named in the report; two name words before the comma ( Bin Zhang, M.D. ), another credential in the part ( Smith, M.D. Ph.D. ) or the undotted Smith, MD keep the credential. #1238
Fix Token.reading naming a title phrase’s object a title by shape where the shape refuses it. parse("Member of Chas. John Smith").tokens[2].reading is Reading('title' as 'title', 'position') , where 3.0.0 and 3.0.1 gave source shape ; a CJK word there ( 田中. ) reads position too. #1191
Fix the Royal Colleges’ fellowships and memberships reading as the family name. parse("John Smith FRCS") gives given John , family Smith , suffix FRCS , where 1.4.0 through 3.0.1 gave middle Smith , family FRCS , and Smith, John MRCP reads suffix MRCP , where they gave middle MRCP . 34 are listed, among them FRCP , MRCP , MRCS , FRACS , FRCR , MRCOG , FRCPath , MRCPsych and the Canadian FRCSC and FRCPC ; the case repair of FRCPath , FRCOphth , FRCPsych , MRCPsych , FRCSEd and MRCSEd keeps their capitals. #1315
Add the Icelandic frá, “from”, as a particle before a place name. parse("Jónas Jónsson frá Hriflu") gives given Jónas , middle Jónsson , family frá Hriflu , where 1.4.0 through 3.0.1 gave middle Jónsson frá , family Hriflu . Only the accented spelling is listed. #1176
A packaging fix: the test suite now passes when run against the installed package, as Debian's autopkgtest runs it, where 3.0.0's stopped during colle
A packaging fix: the test suite now passes when run against the installed package, as Debian's autopkgtest runs it, where 3.0.0's stopped during collection. The library is unchanged from 3.0.0. See #1184.
Fix the test suite run against the installed package. Run as Debian’s autopkgtest runs it, with the tests beside the installed package and no source tree, 3.0.0’s suite stopped during collection; it now passes, and a test that reads the source tree or the user docs skips there. The library is unchanged from 3.0.0. #1184
nameparser 3.0 removes HumanName , Constants and the rest of the 1.x compatibility layer, which 2.8 deprecates, and rebuilds the vocabulary as reading…
nameparser 3.0 removes HumanName, Constants and the rest of the 1.x compatibility layer, which 2.8 deprecates, and rebuilds the vocabulary as readings of words, kept in files by language. A parser can be built for a choice of languages, the suffix splits by kind and the family name into two surnames, and every parsed word records the reading it took. Highlights:
parser_for(locales.ES).parse("Gabriel García Márquez") gives family García Márquez, where the default gives middle García, family Márquez. Spanish, Portuguese, Vietnamese, Czech, Slovak, Irish, Scottish Gaelic, Nepali and other packs are new, and strict=True reads only the chosen languages' words and those every language shares. (#753)parse("John Smith Jr., MD") gives generation Jr. and credentials MD, and surname1 and surname2 give the two family names two_family_names finds. (#754)parse("Dr. Juan de la Vega III").tokens[2].reading says de was read as a particle in the family name, from the vocabulary of the files that list it. (#754)Upgrading from 2.x
from nameparser import HumanName raises ImportError; parse() reads the same names. A pickled HumanName or Constants no longer loads. (#357)Lexicon is configured by reading: Lexicon.default().remove("dean", kind="given") replaces 2.8's add(titles={"dean"}), which now raises TypeError naming the new call.str(parse("김민준")) gives '김민준', where 2.1 through 2.8 gave '민준 김'. Pass 2.x's spec to render() to keep given-first output.Lexicon, Parser or locale pack pickled by 2.8 still loads, with a DeprecationWarning; 3.1 will refuse it, so re-pickle it under 3.0.The migration guide gives the 3.0 call for each 1.x and 2.x one.
Full list of changes: https://nameparser.readthedocs.io/en/latest/release_log.html
nameparser 3.0 removes HumanName , Constants and the rest of the 1.x compatibility layer, which 2.8 deprecates, and rebuilds the vocabulary as readings of words, kept in files by language. A parser can be built for a choice of languages, the suffix splits by kind and the family name into two surnames, and every parsed word records the reading it took. Migrating to 3.0 gives the 3.0 call for each 1.x and 2.x one. Highlights:
Build a parser for a choice of languages. parser_for(locales.ES).parse("Gabriel García Márquez") gives family García Márquez , where the default gives middle García , family Márquez . Spanish, Portuguese, Vietnamese, Czech, Slovak, Irish, Scottish Gaelic, Nepali and other packs are new, and strict=True reads only the chosen languages’ words and those every language shares.
Read the suffix by kind and the family name as two surnames. parse("John Smith Jr., MD") gives generation Jr. and credentials MD , and surname1 and surname2 give the two family names two_family_names finds.
See how each word was read. parse("Dr. Juan de la Vega III").tokens[2].reading says de was read as a particle in the family name, from the vocabulary of the files that list it.
Additions
Add Locale.languages, a choice of languages for the default vocabulary. parser_for(Locale(code="pt", lexicon=Lexicon.empty(), languages=frozenset({"pt"}))).parse("ANA SILVA E SOUZA") gives family SILVA E SOUZA , where the default reads family SOUZA , the E an initial: a chosen language’s reading of a word it has a vocabulary reading of wins, and the other languages’ vocabulary readings of that word leave, while its readings as a name and the readings shared by every language stay, so under pt John Smith DO reads family DO . A generation word another language collides with is read only under its own language: Jiří Dienstbier ml. gives suffix ml. under cs , and the Czech, Slovak, Slovenian and Croatian ml. and st. read this way. A pack choosing no language parses as before. See Locale packs . #753
Add locales.NE, a Nepali pack, the first that is a choice of languages. parser_for(locales.NE).parse("Guru Prasad Sharma") gives given Guru , middle Prasad , where the default parser gives title Guru , given Prasad ; श्री and गुरु read the same way, each a name word placed by position (the family name under a family-first order) and still a title inside a title phrase ( His Holiness Guru Prasad ). It reads Hindi and Marathi names too, where श्री is usually the salutation, so use it for Nepali data. #753
Add the Irish, Scottish Gaelic and Brazilian Portuguese packs, locales.GA, locales.GD and locales.PT_BR. parser_for(locales.GA).parse("Máire Uí Bhriain") gives family Uí Bhriain , where the default, as in 1.4.0 through 2.8.0, gives middle Uí . GA reads Nic , Mhic , Mic and Uí as surname particles, GD reads Nic , and PT_BR reads SB as the agnomen Sobrinho; F and N stay the name they spell. A choice settles its language’s clashes its way, at a cost: John Smith MC loses the Military Cross under GA and GD . See Locale packs . #753
Add the Spanish and Portuguese packs, locales.ES and locales.PT. parser_for(locales.ES).parse("Maestra Ana Ruiz") gives title Maestra , given Ana , where the default, as in 1.4.0 through 2.8.0, gives given Maestra , middle Ana . ES reads Maestra and Doña as titles, the Spanish and Portuguese titles no name bears being read by default (below); Don , Dona , Dom and Maestro stay names. ES reads Lady as a given name too ( Lady Heidenreich gives given Lady ), a title only in a phrase there ( Lady Chief Justice , Hon Lady ), so a peeress written with the bare title reads given Lady , her own given name joining the family ( Lady Annabel Goldsmith ). ES also reads two family names, a list of 1,000 Spanish given names keeping a given name out of the family: Gabriel García Márquez gives family García Márquez and José Luis Pérez family Pérez , and a given name written without its ñ, as data without the letter writes it, stays out of it too ( Maria Begona Lopez gives family Lopez , in ES_AR too). PT reads one family name, as the default does. See Locale packs . #753 , #980 , #913 , #1081
Add locales.ES_AR, an Argentine Spanish pack. parser_for(locales.ES_AR).parse("Pablo Sebastián Rosales") gives middle Sebastián , family Rosales , where locales.ES gives family Sebastián Rosales ; 1.4.0 through 2.8.0 and the default read it as ES_AR does. It is ES with a longer given-name list, holding given names that Spain bears often enough as surnames to leave off ES ’s list, which Argentine names write before a single surname, and two family names still read as two ( Gabriel García Márquez gives family García Márquez ). #1061
Add locales.VI, a Vietnamese pack. parser_for(locales.VI).parse("Nguyen Van Anh") gives family Nguyen , middle Van , given Anh , where the default, as in 1.4.0 through 2.8.0, gives given Nguyen , family Van Anh . It reads every name family first with the given name last, keeps Van , Le , Do and The as name words where other languages read particles or connectives, and CHI , BA and DO ending a name in capitals where they would read as credentials, and reads the academic titles written before a name ( PGS.TS. Nguyen Van Anh gives title PGS.TS. ). The order holds for any name of two words or more it reads without a family comma, so keep it for Vietnamese data; Nguyen Van Anh, DO reads given DO . See Locale packs . #1108
Add ParsedName.generation, ParsedName.credentials and ParsedName.honorifics, the suffix split by kind. parse("Smith, John, Jr., MD, Esq.") gives generation Jr. and credentials MD, Esq. , where 1.4.0 through 2.8.0 gave only suffix Jr., MD, Esq. , which is unchanged. They are views like family_base : render keys, not fields of as_dict() . A form of address after a name has a third view, honorifics ( parse("田中さん, PhD") gives credentials PhD and honorifics さん ), while a courtesy such as Esq. is a credential, and a suffix written by replace() , or in a name unpickled from 2.x, is all credentials. Token.reading reads Jr. and Sr. as a generation and さん as an honorific, and Ambiguity.alternative of a lone Jr names a generation, and of a lone जी an honorific, where 2.7.0 and 2.8.0 named a post-nominal. #326 , #754
Add ParsedName.patronymic, the words naming the bearer’s parent. parse("Mahathir bin Mohamad") gives patronymic bin Mohamad beside family bin Mohamad , which 1.4.0 through 2.8.0 gave alone and which is unchanged; under locales.RU , Ivan Ivanovich Ivanov gives patronymic Ivanovich and keeps it as the middle name, and under locales.TR_AZ a marker such as oglu reads with the name before it. A view like family_base , not a field of as_dict() , read only from a patronymic particle ( bin , binti , binte , ibn , bint , bar , bat and their Arabic and Hebrew forms) or a rule a locale turns on, so Anwar Ibrahim has none, and a name written by replace() , or unpickled from 2.x, has none either. Ambiguity.alternative of a leading bin read as a given name names a patronymic where 2.7.0 and 2.8.0 named a particle. #754
Add ParsedName.surname2, the second of two family names. Parser(policy=Policy(two_family_names=True)).parse("Gabriel García Márquez") gives surname2 Márquez beside family García Márquez , which 2.8.0 gave alone and which is unchanged. A view like family_base , not a field of as_dict() , filled where two_family_names reads the family as two, or locales.ZH a Chinese surname pair (below), so otherwise the default, a family comma ( Lloyd Webber, Andrew ) and a hyphenated family have none, and so does a name unpickled from 2.x or one whose family replace() rewrote. Reading.second_surname marks its words; it is not compared. #754
Add ParsedName.surname1, surname1_particles and surname1_base, the first of two family names. Parser(policy=Policy(two_family_names=True)).parse("Juan Pérez de la Vega") gives surname1_base Pérez , where family_base , in 2.8.0 as now, gives Pérez Vega , the base of both surnames. Views like surname2 , render keys and not fields of as_dict() ; a family read as one unit, the default’s included, is its own first surname, and a middle name middle_as_family folds in belongs to neither. Reading.first_surname marks its words; it is not compared. #1022
Add a switch for names with a compound given name. Parser(policy=Policy(two_given_names=True)).parse("Juan Carlos Pérez") gives given Juan Carlos , where 1.4.0 through 2.8.0 gave given Juan , middle Carlos . Off by default: under it a middle name beside the given name joins it ( John Quincy Adams gives given John Quincy ). With two_family_names on too, the family takes its word first, so María José García López reads given María José , family García López . A particle phrase the vocabulary marks completes the given name ( María del Carmen García gives given María del Carmen ), and the Sikh Kaur and Singh stay middle names under either two-name switch, as does a middle name behind a bound given-name pair ( Abu Bakr Carlos García keeps middle Carlos ); mark a word of your own with Lexicon.default().add("carmo", kind="given", after_particle=True) . A Policy pickled by 2.8 loads with it off. #704
Add Lexicon.given_names, given names two_family_names leaves out of the family. Parser(policy=Policy(two_family_names=True), lexicon=Lexicon.default() | Lexicon(given_names={"luis"})).parse("José Luis Pérez") gives middle Luis , family Pérez , where the switch alone, in 2.8.0 as now, gives family Luis Pérez . Empty by default, so the switch alone reads as before; an entry without accents matches the word with them. #959
Add Token.reading, the reading the parse took for each word. parse("John Smith PhD Jones").tokens[-1].reading is Reading('credential' as 'suffix', 'position') , the reading 2.7’s Ambiguity.alternative gave only for the other side of a fork, and ReadingKind gains patronymic . The field is not compared, and a ParsedName pickled by 2.x loads with no readings. #754
Add Reading.languages, the language files that list a word the way it was read. parse("Dr. Juan de la Vega III").tokens[2].reading.languages is ('ca', 'es', 'fil', 'fr', 'it', 'nl', 'pt', 'si') for the particle de , and Ambiguity.alternative names its files too; a reading by shape or position names none. Under a choice of languages it names the files the choice reads: parser_for(locales.PT) names ('pt',) for that de . It is not compared, and a Reading pickled by 2.7 or 2.8 loads with none. The first parse in a process that meets a listed word loads the reading index once: about 1 ms, or about 20 ms where Python writes no bytecode cache. #754 , #753
Add br.toml, so a choice of Breton reads the article ar. parser_for(Locale(code="br", lexicon=Lexicon.empty(), languages=frozenset({"br"}))).parse("Katell ar Gall") gives family ar Gall , where the default, as in 1.4.0 through 2.8.0, gives middle ar , family Gall . The default leaves it a name word, since AR is also initials and the Arabic article, and no pack makes the choice. #658
Add Czech, Slovak, Slovenian and Croatian packs, locales.CS, SK, SL and HR. parser_for(locales.CS).parse("Jana Malá, MgA") gives title MgA , given Jana , family Malá , where 1.4.0 through 2.8.0 gave given MgA , family Jana Malá . Each pack chooses its one language and turns on words the default does not read: ml. and st. after the name in all four ( Jiří Dienstbier ml. ), the Czech titles MgA and BcA and DrSc. , and Czech Pan and roz. , the doctorates being read by default (below). Choosing the language drops st ’s Saint readings ( St Clair Smith reads given St ), which choosing fr as well keeps. CS and SK also read two family names, so Alena Pešová Řehořová gives family Pešová Řehořová and two given names read as a given name and a family name ( Petr Pavel Novák gives family Pavel Novák ); a family comma keeps both. #753
Add Hindi and Bengali packs, locales.HI and locales.BN, for the romanized Indic titles. parser_for(locales.HI).parse("Smt Nirmala Sitharaman") gives title Smt , given Nirmala , where 1.4.0 through 2.8.0 gave given Smt , middle Nirmala . HI reads Smt , Shrimati and Shriyut as titles and BN Smt , Shrimati and Adhyapak ; Shri and Sushri stay name words under both, since each opens given names ( Shri Kant , Sushri Sangita ), though parser_for(locales.HI, strict=True) reads Sushri as the title. See Locale packs . #345 , #753
Add parser_for(…, strict=True), to read only the chosen languages’ words. parser_for(Locale(code="ko", lexicon=Lexicon.empty(), languages=frozenset({"ko"})), strict=True).parse("Kim Do Hyun") gives middle Do , family Hyun , where the default, as in 1.4.0 through 2.8.0, and a plain ko choice give family Do Hyun , Do read as the Portuguese particle. Only the chosen languages’ vocabulary files are read, with the words every language writes alike ( Dr , PhD , Mr , the numerals) and the words written in other scripts; every other language’s words leave, the rest of the English credentials and salutations included, so Kim Min Jun, MD gives given MD unless en is chosen too. A strict call that chooses no language raises ValueError . python -m nameparser gains --strict , and --locale takes a language tag no pack has ( --locale ko ). See Locale packs . #753 , #1005
Add Lexicon.words(kind=…) and remove(kind=…, every=True), to list or take out a whole kind. Lexicon.default().remove(kind="title", every=True) takes out every title reading, where 2.8.0 emptied three fields together, titles , given_name_titles and titles_ambiguous , and Lexicon.default().words(kind="title", addresses="given") lists the titles that address the given name. #1007
Add Parser.languages and Lexicon.languages, the choice of languages a parser was built under. With pt and en each a Locale choosing its language, parser_for(en, base=parser_for(pt)) holds both languages in .languages and reads Maria do Carmo family do Carmo , as parser_for(pt, en) does, the base’s choice joined with the call’s; strict is recorded too: a chained call left without strict keeps its base’s, and strict=False on a strict base raises ValueError . A word you add or remove with Lexicon.add and Lexicon.remove applies after the choice, so no choice drops it, and one that cannot stand beside a reading the choice turns on raises at parser_for , naming your call. See Locale packs . #754
Add –order to python -m nameparser, to read a name in another order. python -m nameparser --order family-first "Kovács János Péter" gives family Kovács , given János , where the command, in 2.0.0 through 2.8.0, read only the default order and gave family Péter . It takes given-first , family-first or family-first-given-last ; a name in Han, Hangul or kana keeps its script’s order. #983
Add the Policy switches to python -m nameparser, to try a rule on one name. python -m nameparser --two-given-names "Juan Carlos García" gives given Juan Carlos , where the command, in 2.0.0 through 2.8.0, read only the default policy and gave given Juan , middle Carlos . --two-given-names , --two-family-names , --middle-as-family , --lenient-comma-suffixes and --unlisted-dotted-suffixes each have a --no- form, and --unlisted-caps-suffixes takes off , after-comma or everywhere ; each replaces a --locale pack’s setting. #1114
Divide Japanese names under python -m nameparser –locale ja when nameparser[ja] is installed. python -m nameparser --locale ja "山田太郎" gives family 山田 , given 太郎 , where 2.1.0 through 2.8.0 left family 山田太郎 and warned. Without the extra it reads as before and prints how to install it, in place of the warning; parser_for(locales.JA) still needs segmenter=locales.ja_segmenter() . #984
Breaking Changes
Configure a Lexicon by reading; its set fields are internal. Lexicon.default().remove("dean", kind="given") reads Dean Smith title Dean , the spelling of 2.8.0’s Lexicon.default().add(titles={"dean"}) , which now raises TypeError naming that call, as do Lexicon(titles=...) and dataclasses.replace with a set field, and reading lexicon.titles raises AttributeError ; add(*words, kind=..., **properties) , remove(*words, kind=None) and readings_of(word) , returning LexiconReading , take the vocabulary files’ kinds, and Migrating to 3.0 has a row per 2.8.0 field. A 2.8.0 pickle of a Lexicon , Parser or Locale loads where readings compile its sets back, keeping the vocabulary it was pickled with rather than taking 3.0’s, and is refused otherwise; a 2.x call or pickle that left a word in a marker set over a set it took the word out of reads as though the marker went with it (after remove(titles={"air"}) , John Smith, AIR gives suffix AIR , given AIR in 2.8.0). #754
Deprecate loading a Lexicon, Parser or locale pack pickled by 2.x, which 3.1 refuses. pickle.loads of a Parser pickled by 2.8.0 emits a DeprecationWarning , once for each Lexicon it holds, and 3.1 will refuse it; re-pickle the loaded object under 3.0 and that pickle loads without one. The errors naming a word-by-word fix for a 2.x Lexicon spelling keep it in 3.0 and point at Migrating to 3.0 in 3.1. #754 , #1003
Remove the vocabulary modules in nameparser.config, which 2.8.1 warns of. from nameparser.config.titles import TITLES raises ModuleNotFoundError , as it does for suffixes , particles , conjunctions , bound_given_names , given_names , maiden_markers and capitalization , where 2.8.0 imported each; Lexicon.default().words(kind="title") lists the title words in 3.0, and Migrating to 3.0 gives the call or comprehension for each constant. #1007
Remove HumanName, Constants and the rest of the 1.x compatibility layer. from nameparser import HumanName raises ImportError , where 1.4.0 through 2.8.0 imported it (2.8.0 warning where it was constructed); parse("Dr. Juan de la Vega") reads the same name, with given Juan and family de la Vega . nameparser.parser , nameparser.util , nameparser.config ’s Constants , CONSTANTS and managers, and the five word-list names and two module paths 2.2 renamed go too, and a pickled HumanName or Constants no longer loads. See Migrating to 3.0 . #357
Make nameparser.config.surnames private, which 2.8.2 warns of. from nameparser.config.surnames import KOREAN_SURNAMES raises ModuleNotFoundError , where 2.1.0 through 2.8.2 imported it (2.8.2 warning where the constant is read); Lexicon.default().surnames holds the same words, on 2.x as in 3.0, and nameparser.config holds no public module. #1007
Remove nameparser.config.regexes, which the parser has not read since 2.0. from nameparser.config.regexes import REGEXES raises ImportError , where 1.4.0 through 2.8.1 imported it (2.8.1 warning where a constant of it is read); parse() reads every name as before, and a caller who reused a pattern copies it into their own code. #1008
Behavior Changes
Change a name of one word to read as the given name under every order, with Policy.lone_name_word to choose the family. Parser(policy=Policy(name_order=FAMILY_FIRST)).parse("Anh") gives given Anh , where 2.0.0 through 2.8.2 gave family Anh , the field following the order; parser_for(locales.VI) reads it the same way. For data whose lone words are surnames, Policy(lone_name_word=Role.FAMILY) reads them as the family under every order, and python -m nameparser gains --lone-name-word . A title, a nickname, a maiden name, a family comma or a script that settles the order (Han, Hangul, kana other than katakana alone) still decides first. #1111
Read عبد and a name of God after it as one name in Arabic script, past the first name word. parse("طارق عبد العزيز") gives family عبد العزيز , where 1.4.0 through 2.8.1 gave middle عبد , family العزيز ; it joins a listed name of God or devotional name after it, and before any other word it stays a name of its own ( نوال عبد هاشم , محمد عبد القريشي ). The Latin Abdul is unchanged ( Tariq Abdul Aziz keeps middle Abdul ). #694
Read a lowercase particle opening a family-first name as the start of the surname. Parser(policy=Policy(name_order=FAMILY_FIRST)).parse("van den Berg Cornelia") gives family van den Berg , given Cornelia , where 2.0.0 through 2.8.1 gave family van , given den Berg Cornelia , and reports nothing. A capitalized particle, or one in a name written in one case, keeps its reading ( Le Van Thanh gives family Le ), and the default order is unchanged. #670
Fix a family-first name behind St, Freiherr or Graf taking the given name into the family. Parser(policy=Policy(name_order=FAMILY_FIRST)).parse("St de Mesnil Jean") gives family de Mesnil , given Jean , as Dr. de Mesnil Jean reads, where 2.0.0 through 2.8.1 gave family de Mesnil Jean . #828
Read Graf, Gräfin, Fürst and Prinz inside a German surname as part of it, as Freiherr is. parse("Otto Graf Lambsdorff") gives family Graf Lambsdorff , where 1.4.0 through 2.8.1 gave middle Graf , family Lambsdorff ; opening a name each is still a title ( Graf Zeppelin ). Herzog and Ritter , common surnames, read as before. #709
Write St, San, Santa and Freiherr with their capital in case repair. str(parse("JOHN ST CLAIR").capitalized()) gives John St Clair , where 1.4.0 through 2.8.1 gave John st Clair ; every saint and rank particle is written this way, so Graf , Gräfin , Fürst and Prinz , particles since this release, keep the capital 2.8.1 gave them. A romanized honorific joined by a hyphen and spelled as one takes the capital too ( Suzuki-san repairs to Suzuki-San under a family-first order with force=True , or written in one case). #1069
Read Sta. and Sto. as surname particles. parse("Juan Sta. Maria Reyes") gives family Sta. Maria Reyes , where 1.4.0 through 2.8.1 gave middle Sta. Maria , family Reyes ; Juan Sto. Tomas gives family Sto. Tomas , and case repair keeps them in title case. A bare Sta opening a name now starts the family ( Sta Maria Juan gives family Sta Maria Juan ). #725
Read a compound given name written with a particle as a middle name. parse("María del Carmen García") gives middle del Carmen , family García , where 1.4.0 through 2.8.0 gave family del Carmen García . It reads marked words behind de , del , de los and the like, Spanish and Portuguese alike ( del Pilar , de los Ángeles , do Socorro , de Lurdes , das Graças , de Tarso ); a surname written that way moves too ( Pedro del Valle Llufrio gives middle del Valle ), and Maria do Carmo Silva and Domingo Santa María González keep their family. da Piedade is read only under locales.PT or locales.PT_BR : parser_for(locales.PT).parse("Maria da Piedade Costa") gives middle da Piedade , where the default gives family da Piedade Costa . #704 , #1118 , #1122
Fix a numeral VI to IX before a comma or ending a connective name costing the family name. parse("Dumas VI, Jr.") gives family Dumas , suffix VI, Jr. , as Dumas III, Jr. does, where 2.0.0 through 2.8.0 gave given Dumas and no family; parse("Ortega y Gasset VI") gives family Gasset , where 1.4.0 through 2.8.0 gave given Ortega y Gasset . #893
Change a bare I or V ending the given part after a comma to report suffix-or-name. parse("Doe, John V") still gives suffix V , and now reports that the letter may be a middle initial, as parse("John Doe V") already did; 1.4.0 through 2.8.0 reported nothing. #877
Change a bracketed clause of credentials, generations or titles to be set apart from the name. parse("John Smith (PhD) Withers") gives family Withers , suffix PhD , where 2.4.0 through 2.8.0 gave family Smith , suffix PhD Withers ; John Smith (PhD, MBA) gives suffix PhD, MBA where 1.4.0 through 2.8.0 gave the nickname, and John Smith (Dr) title Dr where 2.2.0 through 2.8.0 gave the nickname. Initials inside a name read as the nickname ( Justin (JP) Stearns , middle JP in 1.4.0 through 2.8.0), and a lone title of address ( (Sir) ) and a qualifier behind a credential ( Alex Green, FRCS (SN) ) stay the nickname. #792
Fix two_family_names leaving a hyphenated surname out of the family. Parser(policy=Policy(two_family_names=True)).parse("Andrés Sánchez-Cid Torres") gives family Sánchez-Cid Torres , where 2.6.0 through 2.8.0 gave middle Sánchez-Cid , family Torres ; a hyphenated given name is taken too unless every part of it is a listed given name, as under locales.ES ( Ana María-José López keeps middle María-José ), and hyphenated initials stay. #959
Fix particles joined by a connective reading the connective as the family’s base. parse("Fritz Freiherr und von Bar") gives family_base Freiherr und von Bar and initials F. F. v. B. , where 2.0.0 through 2.8.0 gave family_base und ; a connective ending the family is still its base ( Juan de y gives y ), and one joining particles before a name word stays in it ( Alois von und zu Liechtenstein gives und Liechtenstein ). #939
Read père after a French name as the generation, as fils is. parse("Alexandre Dumas père") gives family Dumas , suffix père , where 1.4.0 through 2.8.0 gave middle Dumas , family père . It is a French surname too, so Title case keeps it the family name ( Olivier Père ), as with fils ; M. before a name stays an initial. #684 , #658
Read the French professor titles Pr, Professeur and Professeure as titles. parse("Jean Dupont, Pr") gives title Pr , given Jean , family Dupont , where 1.4.0 through 2.8.0 gave given Pr , family Jean Dupont , and Pr Jean Dupont reads the same. Paired initials written PR as the whole given part read as the title too ( Hills, PR ), as DR already does. #804
Fix two_family_names under a family-first order taking the given name into a particle chain. Parser(policy=Policy(name_order=FAMILY_FIRST, two_family_names=True)).parse("Pérez de la Vega Juan") gives family Pérez de la Vega , given Juan , where 2.6.0 through 2.8.0 gave family Pérez , given de la Vega Juan ; the chain’s particles and the one name word they attach to are the second family name, and without the switch the name reads as before. #1024
Read the Spanish professor titles Profesor and Profesora as titles. parse("Juan Pérez, Profesor") gives title Profesor , given Juan , family Pérez , where 1.4.0 through 2.8.0 gave given Profesor , family Juan Pérez , and Profesora Ana López reads the same way; the Polish and Romanian spelling is the same word. #804
Render a name in the order it was read in, keeping its written separators. str(parse("김민준")) gives '김민준' , where 2.1.0 through 2.8.0 gave '민준 김' ; a name read family-first renders family-first, and a comma before a suffix stays ( John Smith, Jr. , Smith, Jr. ), while a family comma between name words never does ( Smith, John gives 'John Smith' ). A spec you pass to render() renders as written, so 2.x’s default spec keeps given-first output, and a name pickled by 2.x renders as it did. initials() gives nothing for a word in Han, Hangul or kana. The new ParsedName.order records the order; render() ’s spec now defaults to None . See Migrating to 3.0 . #754
Fix a credential written in Title case before a name word taking the name with it. parse("Badrul Akmal Hisham Md Yusoff") gives middle Akmal Hisham Md , family Yusoff , as 1.4.0 through 2.3.0 did, where 2.4.0 through 2.8.0 gave family Hisham , suffix Md Yusoff ; MD , M.D. and the part after a family comma ( Smith, John Md Jones ) still start the credential’s run. #1019
Read the spaced Ph. D. as a credential only where the lexicon lists phd. Parser(lexicon=Lexicon.default().remove("phd", kind="credential")).parse("John Smith Ph. D.") gives middle Smith Ph. , family D. , no credential, as PhD is none under it, where 1.4.0 through 2.8.0 merged the pair into suffix Ph. D. whatever the vocabulary; Lexicon.empty() and a strict choice over a lexicon without phd read it so too, and the default is unchanged. #1000
Stop warning when two locale packs set a policy field to the same value. parser_for(locales.CS, locales.SK) , which both turn two_family_names on, is silent, as is any pair of packs agreeing on a value, however each spells it, where 2.0.0 through 2.8.0 warned that the later pack overrides the field. Packs setting different values still warn, the later winning. #753
Fix British post-nominals read as the family name. parse("Jane Doe KC") gives family Doe , suffix KC , where 1.4.0 through 2.8.0 gave middle Doe , family KC , and parse("Jane Doe, CChem") no longer reverses the name around the credential. KC , PC , DL , FRS , LLB , CChem , FRAeS and 16 more join the vocabulary. KC is also a Nepali surname, so Ram KC keeps it as the family name, as do K.C. and Kc , while Gita Bahadur KC reads it as the suffix, and PC and DL keep a family name the same way ( Anna DL ); FIET and FREng keep the surnames Fiet and Freng the same way, so a bare Jane Doe FREng still gives family FREng . #965
Fix Policy(name_order=…) accepting a set. Policy(name_order=frozenset(FAMILY_FIRST)) raises TypeError , where 2.0.0 through 2.8.0 accepted it as an order under some hash seeds and raised ValueError under others; pass the tuple. #754
Read a four-character Chinese name opening with two surnames as a double surname under locales.ZH. 王李小明 under locales.ZH gives family 王李 , given 小明 , surname2 李 , where 2.1.0 through 2.8.0 gave family 王 , given 李小明 ; 王李 小明 , written with the space, reads the same way, where they gave given 李 , middle 小明 . A three-character given name after one surname whose first character is also a surname reads wrong under it ( 王安琪拉 gives family 王安 ). A word a CJK division cuts joins whole wherever its halves land in one field, so 김민준 John gives given_names 김민준 , where 2.1.0 through 2.8.0 gave 김 민준 . #845
Divide five more mainland Chinese surnames under locales.ZH. 付晓明 under locales.ZH gives family 付 , given 晓明 , where 2.1.0 through 2.8.0 gave family 付晓明 ; 代 , 候 , 芦 ( 蘆 ) and 农 ( 農 ) divide too. A Japanese name opening with 代 or 芦 now splits after it ( 芦川誠 gives family 芦 ). #952
Separate words at the invisible separator, U+2063, as at a zero-width space. parse("John\u2063Smith") gives given John , family Smith , where 1.4.0 through 2.8.0 gave given John\u2063Smith ; the character is unseen in pasted text. The other invisible characters are unchanged. #1018
Fix case repair writing Machado as MacHado. parse("JOHN MACHADO").capitalized() gives John Machado , where 1.4.0 through 2.8.0 gave John MacHado : a name opening Mac is title-cased unless the vocabulary records its casing, as it does for 42 surnames, nearly all Gaelic, most of whose bearers write the inner capital ( RONALD MACDONALD still gives Ronald MacDonald ). One most of its bearers write without it, or that the vocabulary does not list, loses it ( James Mackenzie , Shirley Maclaine ). A strict choice of languages keeps all 42 with English, 37 with Scottish Gaelic and the 4 Irish ones with Irish; add your own spelling with Lexicon.capitalization_exceptions . Mc is unchanged. #1014
Read Никитич and Саввич as patronymics under locales.RU. parser_for(locales.RU).parse("Петров Иван Никитич") gives family Петров , given Иван , where 2.0.0 through 2.8.0 gave family Никитич , given Петров ; Саввич and the Latin Nikitich and Savvich read the same way. #994
Fix a name that opens with a credential word losing its given name before a comma. parse("JP Clancy, MD") gives given JP , family Clancy , where 2.4.0 through 2.8.0 gave family JP Clancy ; initials that spell a credential ( A.M. , M.S. ), the given name Md and given names such as Cem read the same, as they do without the comma. #1017
Fix a generation word written mid-name taking the family name with it. parse("Guy Andre Junior Francois") gives middle Andre Junior , family Francois , as 1.4.0 through 2.3.0 did, where 2.4.0 through 2.8.0 gave family Andre , suffix Junior Francois ; a credential behind the generation word ( John Smith Jr. PhD Jones ) and the part after a family comma ( Smith, John Jr. Jones ) still start the credential’s run. #1023
Fix the given names Maj and Gen reading as titles, and read Brig Gen as one title. parse("Maj Sjöwall") gives given Maj , family Sjöwall , and parse("Gen Goto") given Gen , family Goto , where 1.4.0 through 2.8.1 gave title Maj and Gen ; each reports a title-or-name ambiguity. Maj Gen , Lt Gen , Sgt Maj , Gen Sir and the other common ranks and offices written together, either word with its period at the head ( Gen. John Smith , though Gen. Smith, John keeps family Gen. Smith ) and a trailing MAJ. or GEN. keep the title ( SMITH, JOHN B. MAJ. ), and Major Gen and Brig Gen now read as one title too ( Brig Gen Mark Kimmitt , where 1.4.0 through 2.8.1 gave given Brig ); a rank written bare with no period at the head of a name reads as the given name ( MAJ Ian Stewart, MD , Gen Pinochet ), as does one joined by and ( Gen. and Mrs. John Smith ). #999
Read Hon as a given name under a Chinese choice of languages. parser_for(Locale(code="zh", lexicon=Lexicon.empty(), languages=frozenset({"zh"}))).parse("Hon Wah Yeung") gives given Hon , where the default, as in 1.4.0 through 2.8.1, gives title Hon , which it still does; under the choice The Hon , Rt Hon , Hon Mrs and Hon. at the head keep the title, while Hon David Layton and John Smith, Hon read given Hon and a Hon past a second comma reads as a suffix. #999
Fix the given names Saint, Pharaoh, Sailor and Majesty reading as titles. parse("Pharaoh Mwale") gives given Pharaoh , family Mwale , where 1.4.0 through 2.8.1 gave title Pharaoh ; Saint Clair Soares , Mr Sailor Vinod and CAMPBELL, MAJESTY BARRETT read the same, and SAINT CLAIR, ELAINE gives family SAINT CLAIR , as 1.4.0 through 2.4.2 did, where 2.5.0 through 2.8.1 gave title SAINT . of , a style before the word and Pope keep the title ( Saint of Assisi , His Majesty King Charles , Pope Saint John Paul II ), while a saint or pharaoh written with the bare word reads it as a given name ( Saint Thomas More ), and a bare Saint opening a name reports a title-or-name ambiguity. #913
Fix 77 common US credentials ending the family name. parse("Jane Doe MSW") gives family Doe , suffix MSW , where 1.4.0 through 2.8.1 gave middle Doe , family MSW ; MBBS , FNP , BSN and the rest read the same with no comma, after a comma in a name written in one case, and ending the given part after a family comma. PAC , LAT and MOT are also surnames, so Jane Doe Lat keeps the family name, now reporting the fork, and a name written in one case with a word to spare loses it, reported the same way ( JANE DOE LAT gives suffix LAT ). #993
Fix the surname Mba read as the MBA degree. parse("Chinedu Mba") gives family Mba , as 1.4.0 did, where 2.0.0 through 2.8.1 gave suffix Mba and no family. John Smith, MBA and John Smith MBA still read the degree; where a name word can stand, it reads as the name, as MA does ( Smith, MBA Jane gives given MBA ). #1005
Fix the Filipino particle Delos, de los written as one word, reading as a middle name. parse("Juan Delos Reyes") gives family Delos Reyes , as Juan Dela Cruz gives Dela Cruz , where 1.4.0 through 2.8.1 gave middle Delos , family Reyes . Delos is a given name too, so Delos Wheeler still gives given Delos , now reporting particle-or-given. Case repair keeps both capitalized: parse("JUAN DELA CRUZ").capitalized() gives Juan Dela Cruz , where 1.4.0 through 2.8.1 gave Juan dela Cruz . #1037
Fix a family-comma name losing the given name Junior to the suffix. parse("Silva, Junior Carlos") gives given Junior , middle Carlos , as 2.2.0 and 2.3.0 did, where 2.4.0 through 2.8.1 gave suffix Junior Carlos and no given name. Junior and Júnior are given names too, so a name with no word to spare keeps one as the name ( Kofi Junior gives family Junior ), while John Smith Junior still gives suffix Junior . A generation word you give a name reading with Lexicon.add is weighed by the count alone, as Junior is; add it with title_case_is_name=True to have Title case read as the name, as fils does. #1039
Fix a lone letter behind a surname particle or a connective before a family comma reading as the generation. parse("Smith van der V, John") gives family Smith van der V , as 1.4.0 through 2.6.0 did, where 2.7.0 through 2.8.2 gave family Smith van der , suffix V ; de Mesnil V, Jean and Smith y V, John give family de Mesnil V and Smith y V too, where 2.7.0 through 2.8.2 gave suffix V . A generation written before the comma after a particle or connective surname is read as part of it, as after a one-word surname ( Du Hart V, John gives family Du Hart V , as Smith V, John gives Smith V ); after two name words and a particle the letter is still the generation ( Smith Jones van V, John gives suffix V ). #1080 , #1093
Fix a lone letter after a connective reading as the generation, and a connective ending a name read as the whole family. parse("John Smith y V") gives family Smith y V , where 1.4.0 through 2.8.2 gave middle Smith , family y , suffix V ; an initial reads so too ( Juan García y L. gives family García y L. ), and so does the Catalan i ( Puig i V, Joan gives family Puig i V ). A connective with nothing after it to link stays with the surname before it ( John Smith y III gives family Smith y , suffix III ). A name with no given name in front of the join keeps its reading ( Smith y V ), and so do a family-first order without a comma and a single-letter connective with nothing to link in a name written in one case ( CHENG GUI Y gives family Y ). #1097 , #1098
Fix an interpunct between hangul typed decomposed (NFD) keeping the name in one word. parse("이서연·김민준") typed with each syllable as its jamo gives given 이서연 , family 김민준 , as the composed spelling has since 2.1.0, where 1.4.0 through 2.8.2 gave given 이서연·김민준 . #1087
Fix a title written with a period or hyphen inside it reading as the family name at the end of a name. parse("Hans Meier Priv.-Doz.") gives title Priv.-Doz. , family Meier , as Hans Meier Prof. does, where 1.4.0 through 2.8.2 gave middle Meier , family Priv.-Doz. ; the given part after a family comma reads the same ( JORDAN, HERBERT T. LT.COL. gives title LT.COL. , middle T. ). A title the vocabulary lists with a period inside it needs no final one ( Maria Rossi Dott.ssa gives title Dott.ssa ), and so does one every part of which is a title ( John Smith Lt.Gov gives title Lt.Gov ), while one that is a title only by some part ( John Smith Dr.PhD ) or one a hyphen alone joins ( John Smith Co-Founder ) stays a name word there without it. #1116 , #1104 , #1131
Fix a credential spelled with its own hyphen or slash reading as the family name inside a joined credential. parse("Jane Smith PhD/NP-C") gives suffix PhD/NP-C , where 1.4.0 through 2.8.2 gave middle Smith , family PhD/NP-C : a credential listed with its joiner, such as NP-C or OTR/L , is one credential inside a longer word ( MS/OTR/L , APRN-FNP-C ), and OT/L , CCC-SLP/L , ATC/L , SLP/L and PTA/L are listed. A part that is not a listed credential still keeps the family ( CPNP-PC/AC ). #1103
Fix a credential that is also a name reading as the name beside one that is not. parse("John Smith MA/PhD") gives suffix MA/PhD , where 1.4.0 through 2.8.2 gave middle Smith , family MA/PhD , and parse("John Smith (Ma, PhD)") gives suffix Ma, PhD where they gave the nickname: a credential like PhD says the word or the brackets hold credentials, so MA , Ma or M.A beside it is one too. Inside the name the brackets still hold a nickname ( John (MA/PhD) Smith ), a generation settles nothing ( Edward Smith (Ed Jr) stays a nickname), and credentials that are all also names ( MA/MBA ) keep their reading. #1138
Change a word with periods inside it to read as a credential only where every part is one. parse("John Smith (Msc.Ed)") gives suffix Msc.Ed , where 1.4.0 through 2.8.2 gave nickname Msc.Ed . A word with a part that is no credential reads as an unlisted word with periods does, so after a family comma it is the given name ( Whinnett, BM.BS , as through 2.5.0), and MCh is listed. #1131
Change a nickname, one name word and a suffix to read the word as the family name, as without the suffix. parse("'Smitty' Jones Jr.") gives family Jones , suffix Jr. , where 2.0.0 through 2.8.2 gave given Jones with the family empty, reporting given-or-family since 2.3.0 (1.4.0 gave family Jr. ). A word read as an initial, a particle or a bound given name keeps the given name ( 'Smitty' J. Jr. ). #815
Change Muhammad, Achmad, Francisco and Sheikh written short to read as given names. parse("Mohd. Shameem Khan") gives given Mohd. , middle Shameem , where 1.4.0 through 2.8.2 gave title Mohd. , given Shameem ; so do Muh. , Moh. , Moch. , Mhd. , Ach. , Fco. and Sk. , as Sheikh written out does. Md. and Mo. stay titles there, as before. #1115 , #1129
Change the Spanish, Portuguese, Czech, Slovak and Vietnamese titles no name bears to read as titles by default. parse("Jan Novák, MUDr") gives title MUDr , given Jan , family Novák , where 1.4.0 through 2.8.2 gave given MUDr , family Jan Novák , and parse("Licenciado Juan Pérez") gives title Licenciado , where they gave given Licenciado . So do Lic , Licda , Lcdo , Ingeniero , Arq , Mtro , Doctora , Profr , Gral , Tte , Biól , Mgtr , Doutor , Professora , Profa , JUDr , PhDr , RNDr , RSDr , ThS , ĐBQH and the rest; Maestra , Doña , MgA , BcA , Mjr , GS , TS and PGS , which spell names or initials, stay the packs’. #1115 , #1129
Change Engr, Adv, Ir, Drs, Assist, Excm and Dipl to read as titles. parse("Esra Oz, Assist Prof") gives title Assist Prof , given Esra , family Oz , where 1.4.0 through 2.8.2 gave given Assist , middle Prof , family Esra Oz , and parse("Engr Ahsen Ali") gives title Engr , where they gave given Engr . Excma and Excmo read so too. Assist reads as Asst does: opening a name it is a title only in front of another title ( Assist John Smith keeps given Assist ), and ending a name or after a comma it is a title alone ( John Smith Assist. ). A title glued to a name word by a period takes the word with it, as Dr. already does ( Engr.Nurunnabi gives title Engr.Nurunnabi ). The German and Czech diploma degrees read so with their field ( Anselm Crombach, Dipl.-Psych. gives title Dipl.-Psych. , given Anselm , where 1.4.0 through 2.8.2 gave given Dipl.-Psych. , family Anselm Crombach ), save written with a hyphen alone ( Dipl-Psych ), and glued to its field and ending a name it is the title too ( Maxie Bunz Dipl.Psych. gives title Dipl.Psych. , family Bunz , where 2.8.2 gave suffix Dipl.Psych. ). #1115 , #1116
Read MST after a name as a credential. parse("Mary Smith, Mst") gives given Mary , family Smith , suffix Mst , where 1.4.0 through 2.8.2 gave given Mst , family Mary Smith . A leading Mst , the Bengali Mosammat, stays the given name, as Md does; as for Md , the credential opening the part after a family comma takes that part, so Begum, Mst Amina gives suffix Mst Amina where it gave given Mst . #1130
Deprecate nameparser.config.surnames, which 3.0 makes private. from nameparser.config.surnames import KOREAN_SURNAMES now emits a DeprecationWarning n…
nameparser 2.8.2 adds one warning for a 3.0 change 2.8.1 did not announce: importing nameparser.config.surnames, which 3.0 makes private. Code that runs with warnings as errors (-W error, or pytest's filterwarnings = error) will fail where it imports it.
Deprecations
from nameparser.config.surnames import KOREAN_SURNAMES now emits a DeprecationWarning naming Lexicon.default().surnames, which holds the same words in 2.8.2 and 3.0. #1007Full release log: https://nameparser.readthedocs.io/en/latest/release_log.html
Deprecate configuring Lexicon through its set fields, which 3.0 makes internal. Lexicon.default().add(titles={"dean"}) now emits a DeprecationWarning…
nameparser 2.8.1 adds warnings for three 3.0 changes 2.8.0 did not announce: writing a Lexicon set field, reading a vocabulary constant in nameparser.config, and reading nameparser.config.regexes. Reading a Lexicon field (lexicon.titles) does not warn, though 3.0 refuses that too. Code that runs with warnings as errors (-W error, or pytest's filterwarnings = error) will fail where it does any of the three.
Deprecations
Lexicon.default().add(titles={"dean"}) now emits a DeprecationWarning naming the field and the migration guide's row for it; 3.0 refuses the call with a TypeError naming the readings that replace it. remove(), Lexicon(...) and dataclasses.replace() with a set field warn too, and add() or remove() with surnames. #754from nameparser.config.titles import TITLES now emits a DeprecationWarning naming Lexicon.default().words(kind="title"), which lists every title in 3.0. nameparser.config.surnames stays. #1007REGEXES now emits a DeprecationWarning; the parser has not read it since 2.0. #1008Full release log: https://nameparser.readthedocs.io/en/latest/release_log.html
HumanName and Constants warn that 3.0 removes them. HumanName("Dr. Juan de la Vega") emits a DeprecationWarning ; parse("Dr. Juan de la Vega") reads t…
nameparser 2.8 is the last 2.x feature release. It warns about everything 3.0 removes, chiefly HumanName and the rest of the 1.x compatibility layer, so that code can move to parse() while 2.x still runs it. It also carries on 2.7's reading of titles that are also given names: a title only inside a title phrase. After 2.8 the 2.x line takes fixes only, and new work goes into 3.0. Highlights:
HumanName("Dr. Juan de la Vega") emits a DeprecationWarning; parse("Dr. Juan de la Vega") reads the same name, with given Juan and family de la Vega. (#925)Queen Latifah and Marquis Johnson give given Queen and Marquis, where 2.7 read both as titles; Her Majesty Queen Elizabeth and Marquis of Queensberry keep the title. (#913)Prince Consort Albert gives title Prince Consort, given Albert, and Lord Justice Leveson title Lord Justice, where 2.7 gave given Prince and given Justice; Prince Fielder keeps the given name Prince. (#913)Some default words changed role: Queen, Marquis, Marquise, Deacon, Burgess, Ranger and Chancellor are titles only inside a title phrase or behind a style (Chancellor Smith gives given Chancellor). Lexicon.default().add(titles={"queen"}) makes a word a title everywhere again. (#913)
To find every use 3.0 removes, run your tests under python -W error::DeprecationWarning. The migration guide maps each use to its replacement. Pickles from 2.7 still load.
Full list of changes: https://nameparser.readthedocs.io/en/latest/release_log.html
nameparser 2.8 is the last 2.x feature release. It warns about everything 3.0 removes, chiefly HumanName and the rest of the 1.x compatibility layer, so that code can move to parse() while 2.x still runs it. It also carries on 2.7’s reading of titles that are also given names: a title only inside a title phrase. After 2.8 the 2.x line takes fixes only, and new work goes into 3.0. Highlights:
HumanName and Constants warn that 3.0 removes them. HumanName("Dr. Juan de la Vega") emits a DeprecationWarning ; parse("Dr. Juan de la Vega") reads the same name, with given Juan and family de la Vega .
More given names that are also titles read as names. Queen Latifah and Marquis Johnson give given Queen and Marquis , where 2.7 read both as titles; Her Majesty Queen Elizabeth and Marquis of Queensberry keep the title.
Royal and judicial title phrases read as one title. Prince Consort Albert gives title Prince Consort , given Albert , and Lord Justice Leveson title Lord Justice , where 2.7 gave given Prince and given Justice ; Prince Fielder keeps the given name Prince .
Deprecations
Deprecate HumanName, Constants and the rest of the 1.x compatibility layer, which 3.0 removes. HumanName("Dr. Juan de la Vega") now emits a DeprecationWarning ; parse("Dr. Juan de la Vega") reads the same name, with given Juan and family de la Vega where HumanName has first and last. Constructing a Constants , loading a pickled HumanName or Constants , and reading nameparser.config.SetManager or nameparser.util.lc warn too, each naming its replacement; python -W error::DeprecationWarning finds every site except a read of the shared CONSTANTS . #925
Behavior Changes
Fix given names that are also titles, such as Queen, Marquis and Deacon, reading as titles. Queen Latifah gives given Queen , family Latifah , where 1.4.0 through 2.7.0 gave title Queen ; Marquis , Marquise , Deacon , Burgess and Ranger read the same, behind another title or after a family comma too ( The Rev. Deacon John Smith , Smith, Queen ). A holder written with the bare title reads it as a given name too ( Queen Elizabeth II gives given Queen , family Elizabeth ); of or a style keeps the title ( Marquis of Queensberry , Her Majesty Queen Elizabeth ). Queen and Burgess opening the name or behind another title also report a title-or-name ambiguity ( Burgess Meredith ). #913
Fix the given name Chancellor reading as a title, and read Lord Justice as one title. Chancellor Smith gives given Chancellor , family Smith , where 1.4.0 through 2.7.0 gave title Chancellor ; Smith, Chancellor reads the same. A bare Chancellor opening the name reports a title-or-name ambiguity ( Chancellor Merkel ). A modifier, of or Lord keeps the title ( Vice Chancellor Jane Smith , Chancellor of the Exchequer , Lord Chancellor John Smith ). Lord Justice Leveson and Lady Justice Arden give title Lord Justice and Lady Justice , where 1.4.0 through 2.7.0 gave title Lord and Lady , given Justice . #913
Read the royal title phrases Prince Consort, Princess Royal and the other consorts as one title. Prince Consort Albert gives title Prince Consort , given Albert , where 2.7.0 gave given Prince , middle Consort , and 1.4.0 through 2.6.0 title Prince , given Consort ; the other consorts read the same, and Princess Royal Anne gives given Anne , where 2.7.0 gave given Princess . Royal after a family comma is the given name ( Bales, Royal , where 1.4.0 through 2.7.0 gave title Royal ). A bare King , Queen , Prince , Princess or Royal opening the name or behind another title now reports a title-or-name ambiguity ( Prince Fielder , Dr. King ). #913
nameparser 2.7 is the first release working towards the new language and vocabulary model described in the vocabulary model RFC . It introduces more n
nameparser 2.7 is the first release working towards the new language and vocabulary model described in the vocabulary model RFC. It introduces more nuanced handling of titles and particles, adjusts the default vocabulary to better align with example name corpora, and surfaces alternative name readings in the published API. Highlights:
Chief Justice John Roberts gives title Chief Justice, given John, where 2.6 gave title Chief, given Justice; outside a phrase the word is a name, so Justice Smith gives given Justice. (#752, #853)John Smith, MD/PhD gives suffix MD/PhD, where 2.6 gave given MD/PhD, family John Smith. (#752, #797)Chas. Smith and Ma. Cristina Reyes give the given name Chas. and Ma., where 2.6 read both as titles. (#789)Ambiguity.alternative says what the word would have been and why. (#752)Some default words changed role: King, Prince, Sheikh, Sultan and other titles that are also given names are titles only inside a title phrase (King Curtis gives given King), bon, dí and heer are no longer particles, and herren and heren are no longer titles. Lexicon.default().add(titles={"king"}) makes a word a title everywhere again. (#752, #766)
A Lexicon, Parser or locale pack pickled by an earlier release no longer loads; re-pickle after upgrading. Policy, ParsedName and HumanName pickles still load. (#752)
Full list of changes: https://nameparser.readthedocs.io/en/latest/release_log.html
nameparser 2.7 is the first release working towards the new language and vocabulary model described in the vocabulary model RFC . It introduces more nuanced handling of titles and particles, adjusts the default vocabulary to better align with example name corpora, and surfaces alternative name readings in the published API. Highlights:
Titles that are also given names read as titles only inside a title phrase. Chief Justice John Roberts gives title Chief Justice , given John , where 2.6 gave title Chief , given Justice ; outside a phrase the word is a name, so Justice Smith gives given Justice .
Credentials joined by a hyphen or a slash, or split by a space, read as one credential. John Smith, MD/PhD gives suffix MD/PhD , where 2.6 gave given MD/PhD , family John Smith .
Given names written short read as given names. Chas. Smith and Ma. Cristina Reyes give the given name Chas. and Ma. , where 2.6 read both as titles.
An ambiguity report names the reading the parse did not take. Ambiguity.alternative says what the word would have been and why.
Additions
Add Ambiguity.alternative, the reading a report’s parse did not take. parse("JOHN SMITH MA").ambiguities[0].alternative is Reading('name' as 'family', 'declared') : read as a name, MA would be the family name. Reading , ReadingKind and ReadingSource are exported from nameparser ; the field is not compared, and a ParsedName pickled by 2.6 still loads. #752
Behavior Changes
Read a title that is also a given name as a title only inside a title phrase. Chief Justice John Roberts gives title Chief Justice , given John , where 1.4.0 through 2.6.0 gave title Chief , given Justice . Outside a phrase the word is a name, and Dean Smith now reports a title-or-name ambiguity. Lexicon.default().add(titles={"dean"}) still makes a word a title everywhere; for King and the other words 2.6.0 listed as titles, a v1 Constants cannot. #752 , #853
Fix given names that are also titles, such as King, Prince and Sheikh, reading as titles. King Curtis gives given King , family Curtis , where 1.4.0 through 2.6.0 gave title King ; Prince , Princess , Sultan , Sultana , Sheikh and its spellings, Mahdi , Bard , Wing , Buddha , Siddha and Gyani read the same, and so does a lone Vice or Grand opening the name. A style or a title phrase keeps the title ( His Majesty King Henry , Prince of Wales ), and after a full name and a comma a bare given name among them reverses the name, as Dean does ( John Smith, Wing gives given Wing ). #752 , #348 , #853 , #867 , #869
Read Chas., Wm. and the other given names written short as given names rather than titles. Chas. Smith and Ma. Cristina Reyes give the given name Chas. and Ma. , where 1.4.0 through 2.6.0 gave title Chas. and Ma. . An unlisted abbreviation in front is still a title ( Insp. Jane Morse ); Lexicon.given_name_abbreviations lists the words. #789 , #752
Fix Bon, Dí and Heer joining the next word into the family name, and Herren and Heren reading as titles. Marie Bon Durand gives middle Bon , family Durand , where 1.4.0 through 2.6.0 gave family Bon Durand , and Herren Hans gives given Herren , where they gave title Herren . #766
Read a credential joined by a hyphen or a slash as a suffix. John Smith, MD/PhD gives given John , family Smith , suffix MD/PhD , where 1.4.0 through 2.6.0 gave given MD/PhD , family John Smith . Each part must be a listed credential that is not also a name, so Smith-Jones is untouched and John Smith, MA/PhD still reverses; an unlisted one in capitals after a comma behind a mixed-case name reads as a credential too ( John Smith, PU-PH ), and so can a hyphenated name written in capitals ( KIM, AE-RA gives suffix AE-RA ). #752 , #797
Read a credential written with a space inside it, such as Pharm D, as one credential. John Smith, Pharm D gives given John , family Smith , suffix Pharm D , where 1.4.0 through 2.6.0 gave given Pharm , middle D , family John Smith . It counts only where the name has words to spare, so Smith, Pharm D still gives given Pharm . #752
Read a credential that is also a name, written in capitals in a mixed-case name, as settled. Smith, John MA Jones gives suffix MA Jones , where 2.0.0 through 2.6.0 gave middle MA Jones , and John Smith MA no longer reports a suffix-or-name ambiguity. A name written in one case still reports ( JOHN SMITH MA ). #785 , #752
Read a bracketed credential that is also a name as a suffix where its writing settles it. Andrew Perkins (JD) gives suffix JD , where 1.4.0 through 2.6.0 gave nickname JD , and John Smith (MA) gives suffix MA again, as 1.4.0 did. Only capitals in a mixed-case name or a period inside the word settle it, so John Smith (Ed) and JOHN SMITH (MA) keep the nickname and report a suffix-or-nickname ambiguity. #810 , #752
Read a hyphen or a slash standing alone between post-nominals as a comma. Jane Smith, Dr. / MD gives given Jane , family Smith , where 1.4.0 through 2.6.0 gave given / , family Jane Smith . It counts only after a full name and its comma, or after a second comma, and only with a space on each side, so Smith - Jones, John and John Smith, MD- PhD read as before. #889 , #156
Read the Brazilian agnomens and French fils as suffixes where the name has a word to spare. Pedro Alves Filho gives family Alves , suffix Filho , where 1.4.0 through 2.6.0 gave middle Alves , family Filho ; fils , Neto , Sobrinho , their feminines and the abbreviations Brazilian filings write for them ( FH , NT ) read the same. Each is a surname too, so the parse reports a suffix-or-name ambiguity, and a name of two words keeps it as the family name ( Ana Neto ). #843 , #752
Fix roman numerals VI to X reading as names where III reads as a suffix. John Smith VI MD gives suffix VI MD and Smith, John VI suffix VI , as III does, where 1.4.0 through 2.6.0 gave family VI and middle VI . A one-letter numeral before a credential is still a name ( John Smith V PhD ), and so is a Title-case Vi in a mixed-case name ( Nguyen Van Vi gives family Van Vi , where 2.2.0 through 2.6.0 gave suffix Vi ). #784 , #774
Fix a lone letter before a further comma reading as part of a credential. Smith, John PhD I, Jr. gives middle I , suffix PhD, Jr. , as 1.4.0 through 2.3.0 did, where 2.4.0 through 2.6.0 gave suffix PhD I, Jr. . #819
Fix a split Ph. D. in the middle of a name stopping short of the words after it. John Smith Ph. D. Jones gives suffix Ph. D. Jones , as John Smith PhD Jones does, where 1.4.0 through 2.6.0 gave family Jones , suffix Ph. D. ; John Smith V Ph. D. gives family V , as John Smith V PhD does, where 1.4.0 through 2.6.0 read V as a suffix. #827
A Lexicon, Parser or locale pack pickled by an earlier release no longer loads. Loading one raises ValueError naming the new fields ( suffix_words_ambiguous , agnomens , titles_ambiguous , title_modifiers , title_styles , title_phrases , given_name_abbreviations ); re-pickle after upgrading. ParsedName and HumanName pickles still load. #752
nameparser 2.6 ships the default vocabulary as per-word data files, adds an opt-in reading for names with two family names, and fixes words read as a
nameparser 2.6 ships the default vocabulary as per-word data files, adds an opt-in reading for names with two family names, and fixes words read as a credential or a title that are part of the name. Highlights:
Policy(two_family_names=True) reads Gabriel García Márquez with family García Márquez. (#754)Luo Si and Maria de Sa give family Si and de Sa, where 2.5 read Si and Sa as credentials. (#791, #796, #857)Wm Smith and Mr Md Karim Uddin give first Wm and Md, where 2.5 read both as titles. (#789, #853)John Smith, MBChB gives suffix MBChB, where 2.5 gave first MBChB, last John Smith. (#797, #848)One default is removed: sa is no longer a post-nominal acronym, so John Smith SA gives last SA. Add it back with Lexicon.default().add(suffix_acronyms={"sa"}). (#857)
A Lexicon, Policy or Parser pickled by an earlier release no longer loads; re-pickle after upgrading. ParsedName and HumanName pickles still load. (#754, #835)
Full list of changes: https://nameparser.readthedocs.io/en/latest/release_log.html
nameparser 2.6 ships the default vocabulary as per-word data files, adds an opt-in reading for names with two family names, and fixes words read as a credential or a title that are part of the name. Highlights:
An opt-in reading for names with two family names. Policy(two_family_names=True) reads Gabriel García Márquez with family García Márquez .
Surnames that are also credentials read as surnames. Luo Si and Maria de Sa give family Si and de Sa , where 2.5 read Si and Sa as credentials.
Wm and Md read as the given names they abbreviate. Wm Smith and Mr Md Karim Uddin give first Wm and Md , where 2.5 read both as titles.
More credentials after a comma read as suffixes. John Smith, MBChB gives suffix MBChB , where 2.5 gave first MBChB , last John Smith .
Additions
Ship the default vocabulary as per-word data files. The word lists in nameparser.config are now compiled from nameparser/vocab/*.toml , one file per language, which record what each word can be read as and why a word was left out; the re-encoding itself changes no word list and no parse. #737
Add a switch for names with two family names. Parser(policy=Policy(two_family_names=True)) reads Gabriel García Márquez as given Gabriel , family García Márquez , where the default reads middle García , family Márquez . Off by default: under it a name with one family name behind two given names loses one to the family ( Juan Carlos Pérez gives family Carlos Pérez ). #754
Behavior Changes
Fix credentials that are also surnames reading as credentials. Luo Si and Robert Capa give a family name, where 2.0.0 through 2.5.0 gave suffix Si or Capa with no family name. A Title-case word after a full name takes the family name, as Ma does; the all-caps form stays a credential ( John Smith CAPA keeps suffix CAPA ). #791 , #796
Fix Sa reading as a credential or a title. Maria de Sa and MARIA DE SA give family de Sa and DE SA , and Joao Sa gives family Sa , where 1.4.0 through 2.5.0 gave suffix Sa ( Joao Sa : 2.0.0 through 2.5.0); Mrs Sa Li gives given Sa , where it read Sa as a second title. SA is no longer a credential: John Smith SA gives family SA and John Smith, SA gives given SA , family John Smith , where 1.4.0 through 2.5.0 gave suffix SA ; a caller who needs it adds it to their own lexicon. #857
Fix more credentials after a comma reading as the given name. John Smith, MBChB and John Smith, OTR/L give suffix MBChB and OTR/L , where 2.0.0 through 2.5.0 gave given MBChB and family John Smith ; 37 degrees and certifications are listed, and PA and Ing are marked ambiguous ( John Pa and John Ing keep the family name). Ing. after a full name and a comma gives suffix Ing. , where 2.5.0 gave title Ing. . An unlisted hyphen- or slash-joined credential still reverses. #797 , #848
Fix case repair writing a joined credential like a hyphenated name. john smith, kchs/dchs repairs to John Smith KCHS/DCHS , where 2.0.0 through 2.5.0 gave Kchs/Dchs ; a listed acronym joined by a hyphen or slash is written in capitals as one word, and a casing the caller records for it wins. Hyphenated names such as Smith-Jones keep their per-part casing. #808
Add Cllr as a title. Cllr John Smith gives title Cllr , first John , last Smith , where 1.4.0 through 2.5.0 gave first Cllr , middle John . A bare Cllr after the name is still a name word. #847
Fix case repair lowering a capital after a full stop or an ayn. j.r.r. tolkien repairs to J.R.R. Tolkien and AHMAD IBN-ʿALĪ to Ahmad ibn-ʿAlī , where 1.4.0 through 2.5.0 gave J.r.r. and ʿalī . A joined word is written the same way ( st.john gives St.John ), so an unlisted abbreviation’s ending is capitalized too: dr.philol. gives Dr.Philol. . #838
Add the Italian abbreviated salutations such as Dott.ssa and Sig.na as titles. Dott.ssa Anna Bianchi gives title Dott.ssa , first Anna , where 1.4.0 through 2.5.0 gave first Dott.ssa , middle Anna . A bare Sig or Ing before a name is still read as a first name. #840
Add Júnior as a suffix. José Silva Júnior gives last Silva , suffix Júnior , as José Silva Junior does, where 1.4.0 through 2.5.0 gave middle Silva , last Júnior . Filho , Neto and Sobrinho still read as the last name. #843
Read a semicolon between post-nominals as a comma. John Smith, MD; PhD gives first John , last Smith , suffix MD; PhD , where 1.4.0 through 2.5.0 gave first MD; , last John Smith . A delimiter set in extra_suffix_delimiters counts the same way when glued to a suffix word or written between two ( MD/PhD ), and a semicolon before the first comma ( John Smith MD; PhD ) is still read as part of a word. #871
Read a leading Md as the given name it abbreviates, Muhammad, rather than a title. Mr Md Karim Uddin gives title Mr , first Md , middle Karim , where 1.4.0 through 2.5.0 gave title Mr Md , first Karim ; John Smith, MD Jones gives last Smith , suffix MD Jones where it gave title MD , last John Smith . MD after a name is still the degree, and Md. with a full stop is still a title. One limit: Md opening the part after a family comma reads as a credential, so Uddin, Md Karim gives suffix Md Karim where it gave title Md , first Karim . #853
Read Wm as the given name it abbreviates, William, rather than a title. Wm Smith gives first Wm , last Smith , where 1.4.0 through 2.5.0 gave title Wm with no first name. Wm. with a full stop opening the name is still a title. #789
Fix a surname written as two dotted initials reading as a credential. Ram Bahadur B.K. gives middle Bahadur , last B.K. , where 2.4.0 through 2.5.0 gave last Bahadur , suffix B.K. , restoring 2.3.0’s reading, and Hari G.C. gives last G.C. , where 2.0.0 through 2.5.0 gave suffix G.C. with no last name. Three or more dotted letters after a full name are still a credential ( John Smith X.Y.Z. ), and so is a listed one ( John Smith M.A. ). #864
Read a salutation ending the first name after a family comma as the title. Doe, Jane Mrs gives title Mrs , first Jane , last Doe , where 1.4.0 through 2.5.0 gave middle Mrs ; Doe, Jane Mrs. has read as the title since 2.3.0. A salutation also borne as a name, such as Goodman or Herr , is still read as a middle name, and so is any other title, such as King or Dr ; Lexicon.after_given_titles lists the salutations. #835
A Lexicon, Policy or Parser pickled by an earlier release no longer loads. Loading one raises ValueError naming the new field ( after_given_titles or two_family_names ); re-pickle after upgrading. ParsedName and HumanName pickles still load. #754 , #835
Fix a zero-width space or byte-order mark sticking to the word beside it. Dr. John Smith with an invisible zero-width space in front gives title Dr. , first John , where 1.4.0 through 2.5.0 gave first Dr. (the character kept), middle John . The two now divide the words of a name as a space does, with no setting to turn that off, though not inside quotes or a (née ...) clause; the zero-width joiner and non-joiner still stay inside the word. #851
nameparser 2.5 reads more of the shapes real listings write. Highlights:
nameparser 2.5 reads more of the shapes real listings write. Highlights:
Antonio Pavlović mlađi gives suffix mlađi, where 2.4 read it as the last name. (#661, #679)Dr. Smith, John gives title Dr., last Smith, where 2.4 gave last Dr. Smith. (#701)Malcolm X gives last X, as 1.4.0 did. (#718, #721)田中社長 gives family 田中, suffix 社長, and locales.ZH knows more surnames, compound ones included. (#671, #707, #695)One default is removed: mai is no longer a post-nominal acronym, so Tran Thi Mai keeps its given name and John Smith MAI gives last MAI. Add it back with Lexicon.default().add(suffix_acronyms={"mai"}). (#687)
Full list of changes: https://nameparser.readthedocs.io/en/latest/release_log.html
nameparser 2.5 reads more of the shapes real listings write. Highlights:
Junior and senior in 45 languages. Antonio Pavlović mlađi gives suffix mlađi , where 2.4 read it as the last name.
A title before a family comma is a title. Dr. Smith, John gives title Dr. , last Smith , where 2.4 gave last Dr. Smith .
A lone first name followed by V, I or X keeps its last name again. Malcolm X gives last X , as 1.4.0 did.
Chinese and Japanese credential and office words. 田中社長 gives family 田中 , suffix 社長 , and locales.ZH knows more surnames, compound ones included.
Behavior Changes
Add junior and senior in other languages as suffixes. Antonio Pavlović mlađi gives last Pavlović , suffix mlađi , where 1.4.0 through 2.4.2 gave middle Pavlović , last mlađi . The words come from 45 languages and are read when written as a separate word after the name. #661 , #679
Fix a title written before a family comma reading as part of the family name. Dr. Smith, John gives title Dr. , last Smith , where 1.4.0 through 2.4.2 gave last Dr. Smith . Only listed titles are read there, so Xyz. Smith, John keeps its family, and a title that is also a surname particle, such as St or Freiherr , stays in the surname. #701
Add Gov as a title. Gov Smith gives title Gov , last Smith , where 1.4.0 through 2.4.2 gave first Gov , and Lt. Gov. Smith, John gives title Lt. Gov. with the change above. #701
Fix a capital V, I or X after a lone first name being read as a generational suffix, leaving no last name. John V gives first John , last V , and Malcolm X last X , where 2.0.0 through 2.4.2 gave suffix V and X with no last name, restoring 1.4.0’s reading. A title is no word to spare, so Dr. Smith V gives first Smith , last V (1.4.0’s reading too) where 2.0.0 through 2.4.2 gave last Smith , suffix V ; a name with a word to spare keeps the suffix, and John Smith V still gives suffix V . A name written all in lower case reads the same way ( john v gives last v ). #718 , #721
Fix a credential after a generational suffix and a comma reversing the name. John Smith II, AD gives first John , last Smith , suffix II, AD , where 1.4.0 through 2.4.2 gave first AD , last John Smith . A given name after the comma keeps the last-name-first reading ( Garcia Lopez Jr., Juan ), and so does a name written all in capitals. #656
Fix a given-name title after a comma making the name before it the last name. Elizabeth II, Queen gives first Elizabeth , suffix II , where 1.4.0 through 2.4.2 gave last Elizabeth , as Queen Elizabeth II reads. A title that addresses by surname is unchanged ( John III, Dr. gives last John ), and Smith, Sir now gives first Smith . Under a family-first name_order , Sir John gives first John rather than last. #720
Fix a surname particle such as d’ or al- reading as a middle name when a listing puts it after the given name. Ivoi, Paul d' gives last d' Ivoi , where 1.4.0 through 2.4.2 gave middle d' . The Arabic article reads the same in its plain and assimilated spellings ( al- , az- , aš- ). A particle written joined to the surname, as in Paul d'Ivoi , is unchanged. #700
Fix case repair capitalizing the Dutch particle ‘t. jacobus henricus van 't hoff repairs to Jacobus Henricus van 't Hoff , where 1.4.0 through 2.4.2 gave van 'T Hoff . #700
Add Chinese and Japanese credential, office and generational words as suffixes. 彭德威 议员 under locales.ZH gives family 彭 , given 德威 , suffix 议员 , where 2.1 through 2.4.2 gave middle 议员 ; 田中社長 gives family 田中 , suffix 社長 , where 2.1 through 2.4.2 gave family 田中社長 . Read when written as a separate word, after a comma, or glued to the end of the name, except that 部長 and 部长 are not split off a glued name ( 田中部長 is unchanged) unless locales.ZH divides it at a listed surname ( 李部長 ). #671 , #707
Extend the Chinese surname list in locales.ZH past the census top 100, and add the compound surnames it was missing. 柯洁 under locales.ZH gives family 柯 , given 洁 , where 2.1.0 through 2.4.2 gave family 柯洁 ; 钟离小凤 gives family 钟离 where they gave 钟 . A Japanese name read under locales.ZH splits after its first character more often ( 安藤一郎 gives family 安 ), so use locales.JA for Japanese names. #695 , #657
Remove mai from the default post-nominal acronyms, so a trailing Mai keeps the name. Tran Thi Mai read in Vietnamese order ( FAMILY_FIRST_GIVEN_LAST ) gives given Mai , middle Thi , family Tran , where 2.0.0 through 2.4.2 gave suffix Mai and no given name; Nguyen Mai gives family Mai , as 1.4.0 did. The cost is that John Smith MAI gives last MAI instead of suffix; Smith, John, MAI and John Smith M.A.I. still read as credentials. A caller who needs it back adds it: Lexicon.default().add(suffix_acronyms={"mai"}) . See the suffix-acronym-collisions entry of docs/design/decisions/ ( #687 )
Add the Akan and Indonesian salutations owura and bapak as titles. Bapak Dwi Putro gives title Bapak , first Dwi , last Putro , where 1.4.0 through 2.4.2 gave first Bapak , middle Dwi . #662
Fix a single letter in a name written all in lower case reading differently from the same name in capitals. jose j y lopez gives first jose , middle j y , last lopez , as JOSE J Y LOPEZ does, where 1.4.0 through 2.4.2 gave last j y lopez . A lone letter before a maiden marker stays the first name ( j nee smith as J NEE SMITH ), 田中さん v reads as 田中さん V does, and Policy(lenient_comma_suffixes=False) reads john smith, v as it reads JOHN SMITH, V . #723 , #727
nameparser 2.4.2 fixes two readings.
nameparser 2.4.2 fixes two readings.
John й Smith typed with й as и plus a combining breve gives middle й, where 2.3.0 through 2.4.1 read the whole name as the first name, restoring 1.4.0's reading. (#665)Shehu Shagari gives first Shehu, last Shagari, where 1.4.0 through 2.4.1 gave title Shehu and no first name. (#660)Full list of changes: https://nameparser.readthedocs.io/en/latest/release_log.html
nameparser 2.4.2 fixes two readings: a name typed with decomposed accents or hangul, and the Hausa given name Shehu.
Behavior Changes
Fix a name typed with decomposed (NFD) accents or hangul reading differently from its composed spelling. John й Smith typed with й as и plus a combining breve gives middle й , where 2.3.0 through 2.4.1 read the whole name as the first name, restoring 1.4.0’s reading. #665
Fix the Hausa given name Shehu being read as a title. Shehu Shagari gives first Shehu , last Shagari , where 1.4.0 through 2.4.1 gave title Shehu and no first name. #660
nameparser 2.4.1 fixes two readings.
nameparser 2.4.1 fixes two readings.
Dr. inž. Janez Novak gives title Dr. inž. when the ž is written as z plus a combining caron, where 1.4.0 and 2.0 through 2.4 made inž. the given name. (#652)Jane (Janey, Jo) Smith gives nickname Janey, Jo, where 2.0 through 2.4 gave Janey Jo, restoring 1.4.0's reading. (#653)Full list of changes: https://nameparser.readthedocs.io/en/latest/release_log.html
nameparser 2.4.1 fixes two readings: an accented abbreviation written in decomposed form, and a comma inside a nickname.
Behavior Changes
Fix a decomposed (NFD) accented letter ending its word early. Dr. inž. Janez Novak gives title Dr. inž. when the ž is written as z plus a combining caron, where 1.4.0 and 2.0 through 2.4 made inž. the given name; Janez Novak, ŽŠČ likewise gives suffix ŽŠČ , where 2.4 reversed it. #652
Fix a comma inside a nickname being dropped. Jane (Janey, Jo) Smith gives nickname Janey, Jo , where 2.0 through 2.4 gave Janey Jo , restoring 1.4.0’s reading. #653
nameparser 2.4 reads post-nominal credentials much more reliably, recognizes more naming conventions, and writes credentials the usual way when it rep
nameparser 2.4 reads post-nominal credentials much more reliably, recognizes more naming conventions, and writes credentials the usual way when it repairs case.
Jack MA is Jack with an MA and Jack Ma is the surname Ma, where 2.3 read both as the surname. Credentials the word lists don't carry, such as LEED AP and N.C.C., are read too.Jane Smith, PhD MA gives suffix PhD MA, where 2.3 read PhD as her first name, and Eric H. Holder Jr. Attorney General gives suffix Jr. and title Attorney General.Josep Carod i Rovira), the Irish particles (Liam Ó Murchú), salutations in Finnish, Icelandic, Malay and other languages (Herra Väinö Johansson), and Japanese names in halfwidth katakana (山田 タロウ).john smith phd capitalizes to John Smith PhD and JANE DOE MBA to Jane Doe MBA.Full list of changes: https://nameparser.readthedocs.io/en/latest/release_log.html
nameparser 2.4 reads post-nominal credentials much more reliably, recognizes more naming conventions, and writes credentials the usual way when it repairs case. Highlights:
Capitals tell a credential from a surname. Jack MA is Jack with an MA and Jack Ma is the surname Ma, where 2.3 read both as the surname. Credentials the word lists don’t carry, such as LEED AP and N.C.C. , are read too.
Credentials after a name stay together. Jane Smith, PhD MA gives suffix PhD MA , where 2.3 read PhD as her first name, and Eric H. Holder Jr. Attorney General gives suffix Jr. and title Attorney General .
More naming conventions. The Catalan surname link ( Josep Carod i Rovira ), the Irish particles ( Liam Ó Murchú ), salutations in Finnish, Icelandic, Malay and other languages ( Herra Väinö Johansson ), and Japanese names in halfwidth katakana ( 山田 タロウ ).
Case repair writes credentials the usual way. john smith phd capitalizes to John Smith PhD and JANE DOE MBA to Jane Doe MBA , where 2.3 gave Ph.D. and Mba .
More ambiguity reports, each naming the field its word ends up in.
Python 3.15 support.
Behavior Changes
Fix a credential acronym that is also a surname being read by position alone. Capitals now decide in a mixed-case name: Jack MA gives suffix MA while Jack Ma keeps last Ma , where 2.0 through 2.3 read both as the last name. A name written wholly in one case keeps its old reading. See Credentials that are also surnames . #289
New Policy field unlisted_dotted_suffixes, on by default: a dotted acronym nobody has listed is read by position. Jane Smith N.C.C. now gives suffix N.C.C. , where 2.3.0 gave last N.C.C. , while a lone Jack X.Y.Z. keeps its surname. A dotted version string is no longer a suffix: John Smith 1.4.2 gives last 1.4.2 . See Dotted acronyms . #516
New Policy field unlisted_caps_suffixes: an unlisted all-caps word after a comma reads as a credential by default, and elsewhere on request. Jane Smith, LEED AP now gives suffix LEED AP , where 2.3.0 gave first LEED , middle AP , last Jane Smith . The cost is a given name written in capitals after a two-word surname: García Márquez, GABRIEL gives suffix GABRIEL ; CapsSuffixes.OFF keeps the old reading. See All-caps words . #516 , #564
A credential after the name now starts a run of suffixes and titles to the end of its part, with or without a comma. Eric H. Holder Jr. Attorney General gives title Attorney General , suffix Jr. , where 2.3.0 gave middle H. Holder Jr. Attorney , last General , and Steven Hardman, RN - CRNA gives suffix RN - CRNA , where 2.3.0 read RN as the first name. #602 , #603 , #613
Fix a credential run after a comma losing the acronyms in it that are also names or particles. Jane Smith, PhD MA gives suffix PhD MA , where 2.3.0 gave first PhD , middle MA , last Jane Smith . #544 , #562
Fix a credential ending the given part of a family-comma listing being read as a middle name. Doe, John MA gives suffix MA , where 2.0 through 2.3 gave middle MA , restoring 1.4.0’s reading; Doe, John Ma , written the way a name is, keeps middle Ma . #531
Fix a bare trailing Meng or Lac being read as a credential and losing the family name. wang meng gives last meng and reports a suffix-or-name ambiguity, where 2.0.0 through 2.3.0 gave suffix meng and no last name. The cost falls on the degree spellings: John Smith MEng gives last MEng . See Credentials that are also surnames . #540
Fix a surname particle that is also a credential (vd, mc) being split away from the surname or the credentials around it. SMITH VD MA, JOHN gives last SMITH VD MA , where 2.2 and 2.3 gave last SMITH MA , suffix VD . #573
Fix a particle surname before a comma being split when a credential follows it. van der Berg, PhD now gives last van der Berg , suffix PhD ; 1.4.0 through 2.3.0 gave first van , last der Berg . #575
Fix a trailing title being taken into a surname that begins with a particle. John van der Berg Prof. gives title Prof. , last van der Berg , where 1.4.0 through 2.3.0 took Prof. into the last name. See titles at the end of a name . #614 , #623 , #637
Change a title word in a part after a second comma to read as a title. Eric H. Holder, Jr., Attorney General gives title Attorney General , suffix Jr. , where 1.4.0 through 2.3.0 gave suffix Jr., Attorney General . #603 , #629 , #636 , #640
Add the Catalan and Polish surname link i. Josep Carod i Rovira gives last Carod i Rovira , where 1.4.0 through 2.3.0 gave middle Carod i , last Rovira . In a name written wholly in one case the letter reads as an initial and is reported, so JOSEP CAROD I ROVIRA keeps its old fields; remove i from Lexicon.conjunctions_ambiguous to join it there too. See One-letter connectives that are also initials . #397 , #538
Fix a one-letter connective joining a name written wholly in one case. jose e maria santos gives first jose , middle e maria , last santos , where 1.4.0 through 2.3.0 gave first jose e maria , and reports the call. Mixed-case names are unchanged: Jose e Maria Santos still gives first Jose e Maria . See One-letter connectives that are also initials . #383 , #479
Fix the Irish particles Ó, Ní and Ua and the Malay binti being read as a middle name. Liam Ó Murchú gives last Ó Murchú , where 1.4.0 through 2.3.0 gave middle Ó , last Murchú . Your own capitalization_exceptions entries now outrank the lowercase case repair gives a particle. See Fixing the case of a particular word . #604
Fix salutations in Finnish, Estonian, Romanian, Croatian/Serbian, Icelandic, Czech, Lithuanian, Malay, Filipino and other languages being read as a first name. Herra Väinö Johansson now gives title Herra , first Väinö ; 1.4.0 through 2.3.0 gave first Herra , middle Väinö . #606
Change where a maiden marker takes a maiden name: only behind a surname, and only up to the credentials and titles the name ends with. Jane Doe nee Smith MA gives maiden Smith , suffix MA , where 2.0 through 2.3 gave maiden Smith MA . After a family comma the marker is an ordinary word again, as in 1.4.0: Doe, Jane nee Smith gives middle nee Smith . See Nicknames and maiden names . #601
Fix a declared suffix delimiter being taken into a joined name part instead of separating suffixes. With suffix_delimiter=" - " , Smith, John, PhD - and MD gives suffix PhD, and MD , 1.4.0’s reading, where 2.0 through 2.3 gave PhD - and MD . See Suffixes not separated by commas . #549
Report more of the parser’s credential-or-name decisions, and name the right field in each report. parse("Smith, MA").ambiguities now names suffix-or-name , as every decision at an ambiguous credential does, before or after a comma. A report now names the field its word ends up in rather than the one it was first placed in, and a part read wholly as suffixes no longer reports a particle in it as a name. See When the parser had to guess . #289 , #544 , #626
Change case repair to write credentials the way they are usually written. john smith phd now capitalizes to John Smith PhD , JANE DOE MBA to Jane Doe MBA , jane smith r.d.n. to Jane Smith R.D.N. and john smith vi to John Smith VI , where 2.3.0 gave Ph.D. , Mba , R.d.n. and Vi . A capitalization_exceptions value is now a case mask over its key’s letters, and one that spells anything else ( {"jr": "Junior"} ) raises ValueError . See Fixing the case of a particular word . #459
Fix case repair treating a suffix written in capitals as evidence that the whole name was cased on purpose. juan garcia III now capitalizes to Juan Garcia III , where every release returned it untouched. #492
Fix case repair capitalizing the connective inside a hyphenated compound surname. jose ortega-y-gasset capitalizes to Jose Ortega-y-Gasset again, fixing a 2.2 regression that gave Ortega-Y-Gasset . #478
Fix initials and case repair on a name typed with decomposed accents (NFD). Decomposed josé garcía now capitalizes to José García , where every release gave José GarcíA , and decomposed émile zola initials é. z. , where every release dropped the accent. #542 , #585
Fix initials disagreeing with the parse about one-letter connectives. HumanName("john e smith").initials() gives j. e. s. , where earlier releases gave j. s. , and John and Jane Smith gives J. J. S. , where 2.0 through 2.3 also gave and an initial. A v1 subclass overriding _process_initial must now accept and pass on a tokens keyword. #461 , #528
Fix a Japanese name written in halfwidth katakana being read given-first. 山田 タロウ gives last 山田 , first タロウ , as 山田 タロウ does, where every release gave the reverse. See East Asian names . #594
Fix a katakana name typed with a separate voicing mark being read family-first. ア゙イ タロウ gives first ア゙イ , last タロウ , as アイ タロウ does, where 2.1 through 2.3 gave the reverse. #596
Fix halfwidth corner brackets not being read as a nickname. 山田 「タロー」 タロウ gives nickname タロー , where every release kept the bracketed word in the name. See Nicknames, maiden names, and brackets . #597
Fix a v1 Constants entry with stray whitespace, or that is only a CJK full stop, raising or changing the parse. Such an entry ( c.titles.add(" dean ") , c.titles.add("。") ) is now ignored with a UserWarning naming it, as 1.4.0 ignored it, where 2.0 through 2.3 raised ValueError or applied it. #541 , #582
Fix three rare input shapes that cost quadratic time. A long given part after a family comma, a name ending in many alternating credentials and titles, and many leading titles with many surname particles now cost linear time. Speed on ordinary names is unchanged, and no parse output changes. #546 , #553 , #558 , #559
Additions
Add Python 3.15 support. #259
Add Lexicon.conjunctions_ambiguous, the one-letter connectives that read as initials in a one-case name. It holds e and i by default; Portuguese data can remove e with Lexicon.default().remove(conjunctions_ambiguous={"e"}) . See One-letter connectives that are also initials . #383 , #479
Add AmbiguityKind.CONJUNCTION_OR_INITIAL, reported when a one-letter connective in a name written wholly in one case is read as an initial. #383 , #479
Remove ph from the default post-nominal acronyms. Ph. D. and PhD parse as before, but a bare John Smith Ph. now gives last Ph. ; add it back with Lexicon.default().add(suffix_acronyms={"ph"}) . #459
Parsing fixes and new honorific vocabulary; nothing in the API is removed or renamed.
Parsing fixes and new honorific vocabulary; nothing in the API is removed or renamed.
The fixes cluster around post-nominals and titles. A space-separated run of post-nominals keeps the spacing the writer typed (John Smith MD PhD → suffix MD PhD, not MD, PhD), and the acronyms that are also surnames — Rai, Cha, Ba — no longer take a name's family name. A run of titles addresses by its last, and a trailing abbreviated title reads as a title. CJK names and honorifics written with a full stop of any width now parse. The additions are renunciate and royal given-name titles, Devanagari and the first Bengali honorifics, and two AmbiguityKind members that report a reading nothing in the name decided.
Incompatibility: a Lexicon pickled by 2.1.x or 2.2.x with a caller-added entry written with a fullwidth or ideographic full stop, or in NFD, no longer loads (ValueError: incompatible Lexicon pickle: entries are not normalized). The shipped vocabulary is unaffected; rebuild the Lexicon from its source rather than unpickling it.
Full release notes: https://nameparser.readthedocs.io/en/latest/release_log.html
nameparser 2.3 is parsing fixes and new honorific vocabulary; nothing in the API is removed or renamed.
The fixes cluster around post-nominals and titles. A space-separated run of post-nominals keeps the spacing the writer typed, and the acronyms that are also surnames – Rai, Cha, Ba – no longer take a name’s family name. A run of titles addresses by its last, and a trailing abbreviated title reads as a title. CJK names and honorifics written with a full stop of any width now parse. The additions are renunciate and royal given-name titles, Devanagari and the first Bengali honorifics, and two AmbiguityKind members that report a reading nothing in the name decided.
One incompatibility: a Lexicon pickled by 2.1.x or 2.2.x with a caller-added wide-stop or NFD entry no longer loads; the full-stop bullet below has the remedy.
Behavior Changes
Fix HumanName.initials() dropping a middle- or family-group initial that is also a one-letter conjunction. HumanName("Scott E. Werner").initials() gives S. E. W. again where 2.0.0 through 2.2.0 gave S. W. ; Juan Y. Garcia and a bare ASCII capital John E Smith likewise. v1 excluded initial-shaped words from its conjunction test and the 2.0 facade had not; parse(...).initials() was already right and is unchanged. A bare lowercase john e smith still reads the e as the connective. See the R3 entry of docs/design/decisions/ (closes #462 )
Record a 2.0.0 change to HumanName.initials() that no release note had classified: since 2.0.0 the facade initials each WORD of a name part, where 1.4.0 initialed a joined run as one group – HumanName("Juan Velasquez y Garcia").initials() is J. V. G. and was J. V G. ; Abdul Salam Hassan is A. S. H. and was A S. H. . Nothing changes in 2.3.0; the differential gate now compares initials() ( #484 ) and this is what it found. See the differential-ledger, the initials view entry of docs/design/decisions/
Fix a space-separated run of post-nominals rendering with a comma the writer never typed. HumanName("John Smith MD PhD").suffix is MD PhD and was MD, PhD at every release since 1.4.0; Kenneth Clarke QC MP gives QC MP , and the CJK honorific runs ( 김민준 박사 씨 ) follow the same rule. This is a deliberate deviation from 1.4.0, and the v1-parity suite is re-pinned to match. The comma forms are unchanged – HumanName("Smith, MD, PhD").suffix is still MD, PhD – because the separator is now the comma the writer typed; a configured suffix delimiter still parts a run, as does a name word standing between two post-nominals. Round-tripping is fixed for these runs, which the 2.2.0 note below recorded as broken: str(HumanName("Smith, MD PhD")) is Smith MD PhD and re-parses to suffix MD PhD . str() is still a rendering rather than a canonical form. See the R1 entry of docs/design/decisions/ (closes #436 , closes #437 )
Fix Parser.revise() splitting a space-separated suffix value into comma-separated entries. Parser().revise(n, suffix="MD PhD").suffix is MD PhD and was MD, PhD . A suffix value’s entries are now derived from the value’s own commas by the rule a whole name uses – a comma parts two credentials and a space joins them – so revise(n, suffix="MD, PhD") is still two entries, and revise(n, suffix="Ph. D.") renders Ph. D. where the 2.2.0 note below accepted Ph., D. . One limit: a delimiter configured through extra_suffix_delimiters parts a value only where the value’s own words read as a name with a tail segment, so in a run of post-nominals it stays a word; write a comma at the boundary instead. ParsedName.replace() is unchanged. See the R1 entry of docs/design/decisions/ (closes #511 )
Remove rai and cha from the default post-nominal acronyms, so a trailing Rai or CHA keeps the family name. HumanName("Aishwarya Rai") gives last Rai , where 2.0.0 through 2.2.0 gave suffix Rai and no last name at all – 1.4.0’s reading, restored. The cost is that a genuine credential written after a full name is no longer recognized: John Smith RAI gives last RAI , and John Smith, RAI gives first RAI , last John Smith . A caller who needs either back adds it: Lexicon.default().add(suffix_acronyms={"cha"}) . See the suffix-acronym-collisions entry of docs/design/decisions/ (closes #342 )
Mark ba as an acronym that is also an ordinary name, so a bare trailing Ba keeps the family name. HumanName("Anna Ba") gives last Ba and reports a suffix-or-name ambiguity, where 2.0.0 through 2.2.0 gave suffix Ba and no last name. The spaced full-name form keeps the credential reading – John Smith BA still gives suffix BA , now flagged – and the dotted John Smith B.A. is an unflagged suffix. The comma forms move, which is the marking’s cost: John Smith, BA gives first BA , last John Smith , as Smith, Ed already did for the other ambiguous acronyms. Write B.A. to keep the credential reading. Ba is a real surname in Vietnamese and Senegalese Fula, the ma / Ma shape exactly ( #342 )
Fix a title run addressing by its first title rather than its last. HumanName("Her Majesty Queen Elizabeth") gives first Elizabeth with an empty last name, where every release since 1.4.0 gave last Elizabeth . Several titles written together are one form of address and the one that does the addressing is the last, so the run is now matched whole or by its last word: Reverend Mother Teresa , Dr. Sir John and Sir Sheikh abdul rahman move the same way. A run whose last word addresses by surname does not move: His Excellency Lord Duncan still gives last Duncan , lord not being a given-name title. A caller’s multi-word entry still matches as a phrase. See the H1 entry of docs/design/decisions/ (closes #489 )
Fix the leading title peel taking a name word and leaving a post-nominal to be the name. HumanName("Dr King Jr") gives title Dr , last King , suffix Jr , where every release since 1.4.0 gave title Dr King , last Jr and no suffix at all; Dr. King MD moves the same way, and both now read as the comma spelling King, Dr Jr always has. A name that is nothing but titles or nothing but post-nominals is untouched ( Marquess of Bath , MD DDS ), and so is a title written as one joined unit: Prince of Wales Jr keeps title Prince of Wales . Where the only word left is the title itself, Dr Jr gives first Dr , suffix Jr and reports a title-or-name ambiguity. See the H3 entry of docs/design/decisions/
Fix a trailing abbreviated title reading as a name word. HumanName("John Smith Prof.") gives title Prof. , first John , last Smith , where every release since 1.4.0 gave last Prof. and lost the surname; John Smith Dr. , John Smith Rev. and Andrew Perkins (Mgr.) move the same way, and the comma form Smith, John Prof. now agrees with the bare one where it gave middle Prof. . A run chains from the end ( John Smith Prof. Dr. gives title Prof. Dr. ), a leading title keeps its place ( Dr. John Smith Prof. gives title Dr. Prof. ), and a post-nominal is read through it ( John Smith Jr. Prof. gives suffix Jr. ). Only a listed title word wearing the abbreviation period is claimed: an unlisted abbreviation ( John Smith Xyz. ), a bare title word ( John Smith Sir ) and a post-nominal ( John Smith Esq. ) do not move. The reach is the whole title vocabulary, ordinary surnames in it included, so Mary Jane King. gives title King. where the bare Mary Jane King keeps last King – accepted rather than prevented, the period being evidence the bare spelling never gives. The same argument holds in a native script: 毛 泽东 Dr. gives title Dr. , first 泽东 , last 毛 , where 2.2.0 gave last Dr. . See the H5 entry of docs/design/decisions/ (closes #316 )
Remove esq from the default post-nominal acronyms, and assert the two post-nominal sets disjoint. HumanName("John Smith E.S.Q.") gives middle Smith , last E.S.Q. , where every release since 1.4.0 gave suffix E.S.Q. ; Esq , Esq. , ESQ and esq are unchanged, the post-nominal word list carrying every single-token spelling. Esquire is a contraction rather than an initialism, and it was the one word in both post-nominal sets, which can now assert they do not overlap. A caller who needs the dotted spelling back adds it: Lexicon.default().add(suffix_acronyms={"esq"}) . See the suffix-acronym-collisions entry of docs/design/decisions/
Fix the East Slavic and Turkic patronymic rotations overriding a declared family-first name order. With patronymic_rules opted in and Policy(name_order=FAMILY_FIRST) , Мицкевич Адам Юзеф gave last Адам through 2.2.0 and now gives last Мицкевич – the reading the declaration asks for – and oglu Ahmad Vali Ali with Turkic handling gave last Ahmad and now oglu . The rotations exist to restore the given-first reading a family-first listing hides, so under a declared family-first order the declaration decides. See the O1 entry of docs/design/decisions/ (closes #384 )
Fix CJK honorifics and names written with a full stop of any width. HumanName("김민준 씨.").suffix is 씨. (the fullwidth stop a Japanese or Chinese IME produces by default), with last 김 and first 민준 , where every release since 2.1.0 gave first 김 , middle 민준 , last 씨. and no suffix; the ideographic 씨。 and halfwidth 씨。 spellings move the same way. The vocabulary lookup now composes NFC, so a decomposed Señor or née from macOS-origin data is recognized too. A period glued to a name word no longer breaks the name: 양. 지훈 gives last 양. , first 지훈 where 2.1.0 through 2.2.0 gave first 양. , middle 지 , last 훈 , and 김민준씨. peels its honorific as the stop-less spelling does. The period stays on the word it was written with; nothing is rewritten. A Latin name written with ASCII periods is untouched ( Smith. John still reads title Smith. ), but a Latin or Cyrillic word wearing one of the three wider stops now reaches the vocabulary: Dr。 John Smith reads title Dr。 where it read first Dr。 . This retires the 2.2.0 note below that read period strictly. One incompatibility, by decision: a Lexicon pickled by 2.1.x or 2.2.x that carries a caller-added entry the widened fold now changes – a non-ASCII entry written with a fullwidth or ideographic stop, or in NFD – no longer loads ( ValueError: incompatible Lexicon pickle: entries are not normalized ); the shipped vocabulary is unaffected, and the remedy is to rebuild the Lexicon from its source rather than unpickle it. See the cjk-full-stops entry of docs/design/decisions/ (closes #322 , closes #323 )
Additions
Add the renunciate titles to the given-name title list, so a renunciate’s one name is a given name. HumanName("Swami Vivekananda") gives first Vivekananda with an empty last name, where every release since 1.4.0 gave last Vivekananda ; Guru Nanak , Baba Ramdev and Lama Zopa move the same way, and so do the Devanagari and Bengali spellings added below. Two name words behind the title are unchanged – Swami Vivekananda Saraswati keeps last Saraswati – and a surname-retaining title is untouched: Rabbi Cohen still gives last Cohen . venerable is deliberately not in the list, the traditions using it splitting on whether the family name survives. See the indic-honorifics entry of docs/design/decisions/ (closes #346 )
Add prince and princess to the given-name title list, so a royal’s one name is a given name. HumanName("Prince Harry") gives first Harry with an empty last name, where every release since 1.4.0 gave last Harry ; Princess Anne and Her Royal Highness Princess Anne move the same way. Two name words behind the title are unchanged – Prince Harry Windsor keeps last Windsor – and so is Prince of Wales Jr , the joined title addressing by its last word. lord and lady are deliberately NOT in the list: they address by given name only as a courtesy style ( Lord Peter , Lady Diana ) and by surname for every peer and every wife ( Lord Byron , Lady Thatcher ), which the list cannot express. The given-name collision is untouched: Prince Fielder now gives first Fielder ( #348 ). See the H1 entry of docs/design/decisions/ (closes #519 )
Add trailing honorifics as post-nominal vocabulary: Latin rinpoche , Devanagari जी , साहब , साहिब , साहेब , महाराज , and Bengali সাহেব , বাবু , মহারাজ . HumanName("Lama Zopa Rinpoche") reads title Lama , first Zopa , suffix Rinpoche ; नरेन्द्र मोदी जी reads last मोदी , suffix जी . They are recognized SPACED only and are deliberately absent from Lexicon.honorific_tails : Banerjee, Mukherjee and Chatterjee end in the जी substring ( बनर्जी , मुखर्जी , चटर्जी ), so a glued peel would cut a real family name in two, and गांधीजी staying unpeeled is the accepted cost. Bengali বাবু is trailing where Devanagari बाबू is a leading title ( #344 , #343 )
Add Devanagari honorifics (#344): डॉक्टर , डा , प्रो , प्रोफेसर , प्राध्यापक , प्रा , पंडित , पं , सरदार , सुश्री , श्रीयुत , श्रीमान , सौ , बाबू , महात्मा , न्यायमूर्ति , मौलाना , जनाब and महाराजा as titles, beside the श्री / श्रीमती / डॉ that shipped in 2.1.0, and स्वामी , गुरु , बाबा , संत as given-name titles. डॉक्टर शर्मा reads title डॉक्टर , last शर्मा ; स्वामी विवेकानंद reads first विवेकानंद with no last name. Dotted spellings ( प्रो. , पं. ) match the same entries. Excluded under the collision rule: कुमारी (Kumari is a given and a family name), बेगम , शेख , आचार्य , राजा / रानी and ठाकुर , all borne as ordinary names (closes #344 )
Add Bengali honorifics – the first Bengali vocabulary in the default lexicon (#343): ড , ডঃ , ডক্টর , ডাঃ , ডা , ডাক্তার , শ্রী , শ্রীমতী , জনাব , অধ্যাপক , প্রফেসর , বিচারপতি , মাওলানা , মুফতি , আলহাজ্ব , আলহাজ , মিঃ , মি , মিসেস , মোঃ , মো , মোসাঃ , মোসা , মোছাঃ and মোছা as titles, and স্বামী , শ্রীল , গুরু , বাবা as given-name titles. ড. মুহাম্মদ ইউনূস reads title ড. , first মুহাম্মদ , last ইউনূস – the vocabulary beats the initial reading – while real initials are untouched: র. কে. নারায়ণ is unchanged. মোঃ আবদুল করিম reads title মোঃ , first আবদুল , last করিম , the mirror of Latin Md ; the visarga spelling and the মো. period spelling both match, and the women’s মোসাঃ / মোসা. rides the same pair of entries. ঠাকুর stays out, being Tagore. Latin transliterations ( Sri , Pandit , Mst ) are not added – they collide with real given names where the native scripts cannot – and belong to the opt-in packs of #345 (closes #343 )
Add AmbiguityKind.GIVEN_OR_FAMILY, reported when a name of one name word had nothing to decide which field it is: parse("Andrew") still gives given Andrew and now says that field was a convention rather than a reading – the library picks the given name under the default order and the family name under a declared family-first one, and detail names the field it picked. parse("Smith Jr.") reports it too, the suffix being peeled first. A name something DID decide stays silent – "Dr. Smith" , "Smith, Andrew" , "abdul" (bound given-name vocabulary), "J." (an initial’s shape) – and so does "毛泽东" , where the writing system settles the order. No field moves anywhere. See the O5 entry of docs/design/decisions/ (closes #449 )
Add AmbiguityKind.TITLE_OR_NAME, reported when an input that is nothing but honorifics had its last word read as the name: parse("Lord Chancellor") still gives title Lord , family Chancellor , and now says so – this is a name parser, not a title parser, so handed a string with no name in it, it reads the last title word as one. "His Holiness" and "Dr. King" move the same way, king being title vocabulary. A title with an ordinary word behind it is silent ( "Dr. Smith" , "King Charles" ), and so is a lone title word: parse("Dr.") is a title with no name beside it. The same convention on the post-nominal vocabulary reports the existing suffix-or-name: parse("Rinpoche") gives given Rinpoche and flags it, as does "QC MP" . No field moves for this change; Dr King Jr , Dr. King MD and Dr Jr gain the report from the title-peel fix above. See the H4 entry of docs/design/decisions/ (closes #491 )
Documentation
Document the family-first and East Asian input shapes beside the three Latin ones. The input-shapes list in usage.rst grows from three forms to seven: forms 4 and 5 for a declared FAMILY_FIRST or FAMILY_FIRST_GIVEN_LAST order, and forms 6 and 7 for the native East Asian arrangements the script carries on its own. A comma or a Latin wrapper around a CJK name is named as tolerated input – parsed best-effort, its handling changeable without notice – and the customize.rst correspondence between forms 2 and 4 is written out. Behavior is unchanged ( #469 )
Every 1.x name still imports with a DeprecationWarning until 3.0. The rename itself changes no parse.
A rename plus about thirty parsing fixes.
The nameparser.config word lists are renamed to match the Lexicon they feed — PREFIXES → PARTICLES, BOUND_FIRST_NAMES → BOUND_GIVEN_NAMES, FIRST_NAME_TITLES → GIVEN_NAME_TITLES, SUFFIX_NOT_ACRONYMS → SUFFIX_WORDS, and NON_FIRST_NAME_PREFIXES → NON_GIVEN_NAME_PARTICLES — and are now frozen. Every 1.x name still imports with a DeprecationWarning until 3.0. The rename itself changes no parse.
The fixes cluster around surname particles, largely what a declared name_order means for Latin-script names; then maiden-name clauses, Arabic bound given names, and credentials after a comma.
Breaking: TITLES.add("dean") now raises AttributeError. Build a private Constants (c = Constants(); c.titles.add("dean"); HumanName(name, constants=c)) or a Lexicon (Parser(lexicon=Lexicon.default().add(titles={"dean"}))) instead. See the migration guide.
Full release notes: https://nameparser.readthedocs.io/en/latest/release_log.html
nameparser 2.2 is a rename plus about thirty parsing fixes.
The nameparser.config word lists were still named for v1’s fields — PREFIXES , BOUND_FIRST_NAMES , FIRST_NAME_TITLES — while the Lexicon they feed has used particles and given names since 2.0. They now agree, and the lists are frozen, which retires editing one in place as a way to change a default. The rename itself changes no parse.
The fixes cluster around surname particles, largely what a declared name_order means for Latin-script names, which this release settles; then maiden-name clauses, Arabic bound given names, and credentials after a comma. Most reach the default name order, and a bullet says so where its change is family-first only. Each names the shapes it moves, and the issue it closes carries the measurement.
What breaks is code that writes to a default word list. Code that imports one by its 1.x name has until 3.0.
Breaking Changes
Add docs/design/ contributor documentation: rules.md (the parser’s normative rules, with executable examples), decisions.md (the decision record) and mechanisms.md (the solution-pattern catalog). New tests execute every documented example and verify every code citation
Change every vocabulary set in nameparser.config to a frozenset. Editing one in place – TITLES.add("dean") , the old way of changing a global default – now raises AttributeError at the line that writes it. To change the defaults for HumanName , build a private Constants and pass it ( c = Constants(); c.titles.add("dean"); HumanName(name, constants=c) ); for the 2.0 API, build a lexicon ( Parser(lexicon=Lexicon.default().add(titles={"dean"})) ). Mutating the shared CONSTANTS still works, but warns and goes away in 3.0. CAPITALIZATION_EXCEPTIONS is a mapping, not a set, and is unchanged. See Migrating to 3.0 and Customizing the parser ( #293 )
Behavior Changes
Fix a title changing how the name behind it is read. "Dr. Van Johnson" gave family Van Johnson with no given name, and "Sir Van Johnson" gave given Van Johnson with no family at all; both now read given Van , family Johnson – the reading the untitled "Van Johnson" has always had. A leading word that is both a title and a particle is unchanged: "St John Smith" , "Do John Smith" and "Freiherr von Richthofen" keep their readings. See the P2 entry of docs/design/decisions/ (closes #367 )
Fix a given-name title keeping a bound given name from joining the word after it. "Sheik abdul salam" read given abdul , family salam , and now reads given abdul salam with an empty family, as "Sir John" does; "الشيخ عبد الله" reads given عبد الله . A title that addresses by family is unchanged ( "Dr. abdul salam" ). This also restores "Sheik Abu Bakar" to given Abu Bakar , which the fix above had regressed, and drops the PARTICLE_OR_GIVEN ambiguity that name reported through 2.1 (closes #369 )
Fix a bound given name swallowing the family name before a single-letter generational suffix. "abdul Smith V" read given abdul Smith with no family, where "abdul Smith II" and "abdul Smith Jr" read correctly; it now reads given abdul , family Smith , suffix V , and so do I and X , for every bound given-name word. A suffix word before the numeral no longer hides it ( "abdul Smith Jr V" reads family Smith ). Shipped since 1.x: 1.4.0 read first abdul Smith , last V (closes #401 )
Fix a bound given name joining a suffix as “the word after it”. "abdul Jr Smith Berg" read given abdul Jr and now reads given abdul , middle Jr Smith , where "John Jr Smith Berg" puts it. Where the suffix was a split credential the bound word joined into it – "abdul Ph. D. Smith Berg" read suffix abdul Ph. D. , a 2.0 regression – and now reads given abdul , middle Smith , suffix Ph. D. (closes #421 )
Fix a bound given name joining past a credential that the suffix rule then takes, leaving no family. "abdul Smith Jr Ma" read given abdul Smith with no family and now reads family Smith , suffix Jr, Ma , as "John Smith Jr Ma" does; "abdul Smith Ma" reads family Smith , suffix Ma . Both as 1.4.0 read them. "abdul Smith Berg Ma" keeps its join, and "Berg, abdul Sir" still reads given abdul Sir (closes #425 )
Remove the Czech/Slovak abbreviation roz. from the default maiden markers. Marker matching is case-folded and period-insensitive, so Roz – the diminutive of Rosalind – was the same string as the marker, and a marker takes every word after it: "Rosalind Roz Smith" read maiden Smith with no family name at all . It and "Rosalind Roz Jones Smith" now read as 1.4.0 read them. The full participle is untouched – "Anna Nováková rozená Svobodová" still reads maiden Svobodová – and a caller who wants the abbreviation back adds it to their own lexicon: Parser(lexicon=Lexicon.default().add(maiden_markers={"roz"})) (found in #335 ’s review)
Add the Polish maiden marker z domu to the default vocabulary, and let a maiden_markers entry be more than one word. "Maria Kowalska z domu Nowak" now reads family Kowalska , maiden Nowak , where every earlier version read the marker as part of the name (1.4.0: middle Kowalska z domu , family Nowak ). The bracketed spelling moves with it. maiden_markers and given_name_titles are now the two fields exempt from the multi-word warning. See Behavior: Policy ( #434 )
Fix a bracketed maiden clause reading as a nickname because its brackets were not declared. "Jane Smith nee Jones" gave maiden Jones while "Jane Smith (née Jones)" gave nickname née Jones ; the bracketed spelling now reads family Smith , maiden Jones too, and so does the Japanese "山田 花子(旧姓 佐藤)" , which needed Policy(maiden_delimiters=...) through 2.1. Every delimiter pair the parser ships moves the same way, quotes included. An interior clause no longer eats the name behind it ( "Jane (née Jones) Smith" keeps family Smith ), and two clauses beside each other each keep their own role ( "Jane "Janey" Smith (née Jones)" reads nickname Janey , maiden Jones ). A clause with no marker in it is still a nickname, which is what Policy(maiden_delimiters=...) remains for. This reaches HumanName (closes #335 )
Fix a particle chain and a maiden name taking a trailing generational numeral as a name word. "John van der Berg V" read family van der Berg V and "John née Jones Smith V" read maiden Jones Smith V , where "John Smith V" reads suffix V ; both now stop before the numeral, for I and X alike. A word before the numeral that is an initial keeps its reading ( "John van der J. V" ). The chain also stops before a bare credential with words to spare – "John van der Berg Ma" reads suffix Ma , as 1.4.0 did – and no longer swallows the given name behind an unlisted abbreviation: "Xyz. van Johnson" and "Esq. van Gogh" read given van (closes #424 )
Fix a name losing its given/family split when a comma is followed only by an honorific. "John Smith, Mr." returned the whole of "John Smith" as the family name and now gives given John , family Smith , title Mr. : it is "Mr. John Smith" with the honorific moved to the end, and marks no surname boundary. A comma followed by an actual name still fixes the family ( "John Smith, Jones" ), and a single pre-comma piece has no split to keep ( "Smith, Dr." is unchanged). The pre-comma name now also picks up the declared name order – "de Mesnil Jean, Dr." keeps family de Mesnil under a family-first order – and the particle-or-given ambiguity report ( "Van Johnson, Mr." )
Fix pure postnominals being claimed as titles: jr , junior , phd , do and se have left the default titles vocabulary, and dr / sra have left the suffix vocabulary they never belonged in, so "Smith, PhD" gives suffix rather than title PhD . Twelve words are genuine duals and keep both memberships, with position deciding – "Lt. Smith" is a title, "Smith, LT" a postnominal, bare Md before a name the Bengali and South Asian abbreviation of Muhammad, MD after it the degree. The cost is in leading position, where a dropped word now reads as a name: "PhD Smith" gives given PhD , which is what makes "Do Nguyen" parse as the Vietnamese name it is. dr and sra also stop being recognized in trailing position, so "John Smith Dr." gives family Dr. . An ambiguous credential acronym ( ma , ed , jd , do ) counts as a suffix only when written with its periods, so "Jack Ma." keeps family Ma. as 1.4.0 read it. Routing a trailing title word to title is a separate open question ( #316 )
Fix a credential run after a one-word family comma reading as a title or a given name. "Smith, Jr." and "Smith, PhD" now give suffix Jr. / PhD where they gave title, and "Smith, Ph. D. Jr." gives suffix Ph. D. Jr. where the split credential landed in the given name – a regression from 1.4.0. The position right after a family comma is postnominal position. Vocabulary still decides which words qualify ( "Smith, Dr." keeps title Dr. ), the leading readings are untouched ( "Sr. Garcia" is still title Sr. ), and a name word in the run makes it the given-and-suffix reading it always had ( "Smith, John Jr." ) (closes #296 , closes #325 )
Fix a space-separated credential run after a family comma rendering with a comma the name never had. "Smith, MD PhD" gives suffix MD PhD where it gave MD, PhD , and "Smith, CBE MC" , "Smith, BSc MBA" and "Smith, Dr. MD PhD" the same. The roles are unchanged; only the rendered string carried the extra comma. This reaches any family comma whose following segment holds no name word, not only a one-word family, so "John Smith, Jr. III" gives suffix Jr. III – also what 1.4.0 gave. A run written with commas keeps them ( "Smith, MD, PhD" ), and a name written without a comma is unaffected and still renders its run comma-joined, so re-parsing str() output does not reproduce the run (closes #429 )
Fix a one-character suffix word after a comma being read by the wrong neighbour. "Smith, PSM I" gives suffix PSM I where it gave given PSM and suffix I , and "Smith, John V." gives middle V. where it gave suffix V. . Inside a comma part a suffix word short enough to be mistaken for an initial – I , V and 2 in the shipped vocabulary – is read by what stands before it: behind a credential it describes that credential ( PSM I is Professional Scrum Master level I), and behind a name a period marks an abbreviation and so a middle initial. A numeral written bare after a name is still the generation it looks like ( "Smith, John V" is suffix V ), and a name with no comma is untouched (closes #430 , closes #432 )
Fix a name opening with a particle that is never a given name being split at the particle under a family-first name order. "de Mesnil" read as family de , given Mesnil and "de la Vega" as family de , given la Vega ; each is now the whole surname, as it has always been in the default order, under FAMILY_FIRST and FAMILY_FIRST_GIVEN_LAST alike. A word that can never be a given name leaves name_order nothing to decide. Standing alone is the whole of it: "Juan de la Vega" under FAMILY_FIRST still reports given de la Vega . A leading particle that may be a given name is genuinely order-dependent and is untouched, so "van Gogh" still reads family van , given Gogh under both family-first orders (closes #359 )
Fix a family name made only of particle words reporting no base, so the surname vanished from family_base and from the initials. parse("Anh Do") gave family Do with family_base '' and initials A. , and under Policy(name_order=FAMILY_FIRST) "Del Toro" gave family Del the same way. A particle standing alone in a name part is not doing a particle’s work there and now reads as an ordinary name word: "Anh Do" is base Do , initials A. D. ; "Juan van der" is base van der , initials J. v. d. ; "Nguyen, Van Le" initials V. L. N. where the middle name used to be dropped. The parse fields themselves do not move – only the derived views and the initials. See the R2 entry of docs/design/decisions/ (closes #385 , closes #402 )
Fix case repair lowercasing the words of a family name made only of particle words, where every other view already reads them as ordinary name words. HumanName("ANH DO").capitalize() gives Anh Do where it gave Anh do , and "anh van do" gives Anh Van Do . This DIFFERS FROM 1.4.0 deliberately and does not restore it: 1.4.0 returned Anh do . The accepted cost is that a family which is nothing but particles capitalizes too, so "juan van der" gives Juan Van Der . A conjunction is untouched ( "der, y van" gives y Van Der ), and where the particles DO join a name word nothing changes ( "juan de la vega" still gives Juan de la Vega ) (closes #407 )
Change case repair to read the parser’s own conjunction tag instead of re-deciding, from the word’s spelling, whether a word is a conjunction or an initial. Two spellings of one name disagreed because of it: "jose ortega-y-gasset" capitalized to Jose Ortega-y-Gasset while "JOSE ORTEGA-Y-GASSET" gave Jose Ortega-Y-Gasset ; both give Jose Ortega-Y-Gasset now, a hyphenated token being one word to the parse whatever it contains. The spaced spelling is untouched and still repairs to Jose Ortega y Gasset . A field assigned after the parse was never classified, so repair asks the vocabulary there – today’s vocabulary, which is narrower than 1.4.0 parity: h.last = "хосе и мария сантос" gives Хосе И Мария Сантос on 1.4.0 and Хосе и Мария Сантос here. One reading changes for hand-built Token s in the 2.0 API: an untagged token whose text is conjunction vocabulary now capitalizes as an ordinary name word. See the R4 entry of docs/design/decisions/ (closes #458 )
Change the parse-cost benchmark to bound function calls per parse rather than wall-clock seconds. The old one-second bound failed four times on CI while the same code re-ran green on master; frame counts do not move under load. The bound is a per-interpreter band of ±2%, with a loose five-second backstop for what frame counts cannot see. Recomputable with uv run python tools/perf/call_count.py --against v2.1.0 ; the counts and the per-PR attribution are in the parse-cost entry of docs/design/decisions/ . No user-visible behavior changes (closes #475 )
Fix a name that opens with a spaced Ph. D. losing its surname. parse("Ph. D. Van Johnson") read given Van Johnson with an empty family and suffix Ph. D. ; it now reads title Ph. , given D. , family Van Johnson . A suffix never begins a name, and the split credential was the only shape that reached the defect. A family comma still opens a listing rather than a name ( "John Smith Ph. D." and "Smith, Ph. D. Jr." keep their suffixes), and “the head” means the head of the string rather than of the name, so "Sir Ph. D. Van Johnson" is unchanged. This RESTORES 1.4.0. One accepted consequence: Parser.revise(suffix="Ph. D.") renders Ph., D. (closes #371 )
Fix a trailing surname particle being stranded as a standalone middle name under a family-first name order. Under Policy(name_order=FAMILY_FIRST) the same listing written with a comma reads it as part of the surname: "Jong Anke de" gave family Jong with de left as a middle name and now gives family de Jong , given Anke – the answer parse("Jong, Anke de") has always given. FAMILY_FIRST is the only order that puts a trailing piece in a middle; FAMILY_FIRST_GIVEN_LAST puts it in the given slot, so "Nguyen Thi Van" under that order still reads given Van . "Beethoven Ludwig van" under FAMILY_FIRST now gives family van Beethoven . A particle standing alone in the given slot is no longer folded into the family either, so "Ménil de" reports given de . Nothing moves under the DEFAULT name order. See Behavior: Policy for what declaring an order settles, and the P6 entry of docs/design/decisions/ for the reasoning (closes #467 )
Fix initials() ordering a name differently from the fields of the same parse. Two rules fold words into the family and render them ahead of it – Policy(middle_as_family=True) and the tussenvoegsel attachment after a family comma – and the family field honored the fold where initials() did not: parse("der, y van") gave family van der but initials y. d. v. , and now gives y. v. d. . Under middle_as_family this RESTORES v1, that option being middle_name_as_last ’s successor: "Doe, Dr. John A." gives J. A. D. again where 2.0 through 2.2 gave J. D. A. . HumanName.initials() was already right and is unchanged. See the R3 entry of docs/design/decisions/ (closes #408 )
Fix a tussenvoegsel attached to the family name after a comma deciding a genuinely uncertain reading and reporting nothing. "Van Johnson" reports a PARTICLE_OR_GIVEN ambiguity – Van is a Dutch particle and a Vietnamese given name – while "Nguyen, Thi Van" picked the same word the same way, silently. The attachment now reports the fork it decides: "Nguyen, Thi Van" , "Berg, Jan van der" and "Vega, Juan de la" each gain a PARTICLE_OR_GIVEN , while a particle already read as a post-nominal reports SUFFIX_OR_NAME instead ( "Berg, Jan vd" ). Worth knowing before you filter on this: "Beethoven, Ludwig van" – read exactly right – now carries a report too, nothing in the input separating it from "Nguyen, Thi Van" . ambiguities is the only value that grows (closes #405 )
Fix a tussenvoegsel after a family comma being parsed as a middle name. Dutch and Belgian alphabetized listings move the particle behind the given name – "Beethoven, Ludwig van" is how "Ludwig van Beethoven" is filed – and it was read as a middle name rather than as part of the surname: "Beethoven, Ludwig van" gave middle van , last Beethoven , and "Berg, Jan van der" gave middle van der . Those now read family van Beethoven and van der Berg . Two guards bound it: a name whose only given word is the particle keeps it ( "Nguyen, Van" still reads given Van ), and where the word is BOTH particle and suffix vocabulary the attachment wins, so "Berg, Jan vd" reads family vd Berg where 1.4.0 and 2.1 alike gave suffix vd – as does mc . (closes #379 , closes #380 )
Add abd to BOUND_GIVEN_NAMES, so the spellings that write the article as its own word join like the others do: "abd Allah Smith" was given abd , middle Allah and is now given abd Allah . abdul , abdel and abdal were already there, and the Arabic-script عبد has covered the same word since 2.0, so only the Latin spelling was short. The word is also the postnominal ABD (“All But Dissertation”) and stays in SUFFIX_ACRONYMS : position tells the two readings apart, so "Jane Smith ABD" , "Jane Smith, ABD" and "Jane Smith A.B.D." all still read the credential as a suffix ( #400 )
Change how far a leading never-given particle takes the surname when a family-first name_order is declared. Policy(name_order=FAMILY_FIRST) read "de Mesnil Jean" as family de Mesnil Jean – the whole name – and now reads family de Mesnil , given Jean . The default order is unchanged, deliberately: with no order declared nothing marks where the surname ends, and a particle followed by several words really can be all surname ( von Bergen Wessels ); a caller who means family de la Vega plus given Juan there writes the comma. The stop cannot land inside a conjunction-joined run or a bound given-name pair: "de la Vega y Santos Juan" reads family de la Vega y Santos , "ibn Awf abdul Rahman" given abdul Rahman . Where two or more words are left over, the two family-first orders differ from each other for the first time: "de la Cruz Juan Carlos" reads given Juan , middle Carlos under FAMILY_FIRST and the reverse under FAMILY_FIRST_GIVEN_LAST . See Behavior: Policy , and the P1 entry of docs/design/decisions/ for the reasoning (closes #395 )
Change the detail text of a PARTICLE_OR_GIVEN ambiguity to name the role the leading particle was actually given. It said “read as a given name” under every name_order , which is false under Policy(name_order=FAMILY_FIRST) – there "Van Johnson" reads family Van , given Johnson , and the report described the reading not taken. It now ends “read as a family name” in that case. The kind is unchanged and stays PARTICLE_OR_GIVEN ; only the human-readable text moved, and default-order output is identical ( #355 )
Fix a maiden name being lost when a particle stood in front of the marker. "Ursula Leyen geb. Albrecht" reported maiden Albrecht correctly, but "Ursula von der Leyen geb. Albrecht" – the same words one particle chain apart – gave family von der Leyen geb. Albrecht and no maiden name at all, as did "Jane van der Berg née Jones" . A suffix already stopped the particle chain; a marker now does too, so those read family von der Leyen maiden Albrecht and family van der Berg maiden Jones . Under a family-first order "de la Cruz née Vega" now reads family de la Cruz , maiden Vega . Two limits remain, both recorded in rules/M2 : a conjunction join and a bound given-name join each still absorb a marker first (closes #399 )
Move mc and ste into the never-given half of the particle vocabulary, and add los, las and das. The Spanish and Portuguese articles were absent from it entirely. A never-given particle opening a name folds into the family ( rules/P1 ) instead of being read as a given name, so "Mc Donald" was first Mc , last Donald and is now last Mc Donald ; "Ste Marie" , "Los Santos" , "Las Casas" and "Das Silva" move the same way, and "Mc Donald Smith" becomes last Mc Donald Smith . The PARTICLE_OR_GIVEN ambiguity goes with it for mc and ste . los , las and das were not particles at all, so for those three the ordinary particle join fires from a non-leading position too: "Maria das Neves" is now last das Neves . (closes #360 )
Fix a bound given-name join leaving no family name when the name also carries a maiden clause, and stop the join absorbing the marker itself. "abdul Berg née Jones" read given abdul Berg with an EMPTY family, where "abdul Berg" alone reads given abdul , family Berg ; it now reads given abdul , family Berg , maiden Jones . The join also declines when the piece it would absorb is a marker, so "van der Berg, abdul née Jones" reads given abdul , family van der Berg , maiden Jones where it read given abdul née . Where the bound word is ALSO suffix vocabulary, a declining join after a family comma leaves the post-nominal reading: "Berg, abd née Jones" reads family Berg , suffix abd , maiden Jones , as "Berg, abd" alone always has (closes #411 )
Fix a maiden clause changing how the rest of the name is read, and a connective join keeping the marker in the surname. The grouping rules that count a name’s words counted the maiden clause too: "juan y garcia" reads given juan , middle y , family garcia , while "juan y garcia nee jones" read given juan y garcia with NO family name at all. A name of two or more name words now reads as it reads without its maiden clause, plus the maiden name. The connective join used to merge the marker into a multi-word piece, so "Jane van der Berg née y Jones" kept family van der Berg née y Jones and now reads family van der Berg , maiden y Jones . Two limits: a bound given-name word still never joins onto a marker standing as a word of its own ( "Berg, abdul née PhD" ), and a suffix-vocabulary word inside the maiden name stops the marker, so "Jane née Jr y Jones" now reads family Jr y Jones with no maiden name (closes #412 , closes #417 , closes #418 )
Fix a title-plus-surname name losing its family name whenever anything stood beside it. "Dr. Smith" reads family Smith , but "Dr. Smith née Jones" read given Smith with no family at all, and so did "Dr. Smith PhD" and "Dr. "Smitty" Smith" . A suffix, a nickname and a maiden name each stand beside the name rather than in it, and the rule now counts name words alone: those read family Smith with maiden Jones , suffix PhD and nickname Smitty respectively, and "Freiherr von Richthofen geb. Albrecht" reads family von Richthofen , maiden Albrecht . A given-name title still names no family: "Sir John née Jones" keeps given John , exactly as "Sir John" does. One name moves where the nickname LEADS: "'Smitty' Dr. Jones" reads family Jones where it read given (closes #410 )
Fix a name that is a surname and a maiden clause reporting no family at all. "Smith née Jones" read given Smith with an empty family ; it now reads family Smith , maiden Jones . A maiden marker announces a FORMER surname, which only means something beside a current one, so the lone name word left standing is the surname in use now. Every spelling of the shape moves, including a bracket pair you declared to mean maiden: under Policy(maiden_delimiters=frozenset({("(", ")")})) , "Smith (Jones)" reads family Smith , maiden Jones . "Smith (née Jones)" RESTORES 1.4.0, which read family Smith with the clause as a nickname. Two shapes deliberately do NOT move: a word the vocabulary claims as a given name ( "abd née Jones" ) and a word written as an initial ( "J. née Jones Smith V" ) – this rule changes what POSITION decided and does not reach what a word already is. If you have code that reads the lone name word beside a maiden clause out of given, this is the release where it moves to family (closes #445 )
Change what a star import of the two 2.2 vocabulary modules binds. nameparser.config.particles and nameparser.config.bound_given_names now declare all , which their 1.x shims already did, so from ... import * binds their vocabulary alone – it also bound the assert_normalized invariant helper, and from particles the BOUND_GIVEN_NAMES it imports only for a disjointness check. Importing a constant by name is unaffected, and no parse changes ( #356 )
Deprecations
Rename the four vocabularies whose 1.x names described the fields they feed in v1’s words, so the data layer matches the Lexicon :
1.x name
2.2 name
nameparser.config.prefixes
nameparser.config.particles
prefixes.PREFIXES
particles.PARTICLES
prefixes.NON_FIRST_NAME_PREFIXES
particles.NON_GIVEN_NAME_PARTICLES
nameparser.config.bound_first_names
nameparser.config.bound_given_names
bound_first_names.BOUND_FIRST_NAMES
bound_given_names.BOUND_GIVEN_NAMES
titles.FIRST_NAME_TITLES
titles.GIVEN_NAME_TITLES
suffixes.SUFFIX_NOT_ACRONYMS
suffixes.SUFFIX_WORDS
Every row above still resolves and is removed in 3.0. The two module rows are import paths: importing them still works and says nothing, since both modules are now empty shims. Reading a constant – by attribute access, by from ... import , or by from ... import * – emits a DeprecationWarning naming the module and constant to move to, once per line that reads it rather than once per process, so every place you have to edit is reported rather than only whichever one ran first. python -W error::DeprecationWarning -c "import yourapp" surfaces them; Python hides DeprecationWarning outside main . The CONSTANTS attribute names ( prefixes , non_first_name_prefixes , bound_first_names , first_name_titles , suffix_not_acronyms ) are v1 facade surface and are unchanged. See Migrating to 3.0 ( #293 )
nameparser 2.1 makes East Asian names work without configuration. Chinese, Japanese and Korean names written in their own scripts are read family-firs
nameparser 2.1 makes East Asian names work without configuration. Chinese, Japanese and Korean names written in their own scripts are read family-first, unspaced Korean names are split against the census surname list, and CJK honorifics are recognized whether they are spaced or written against the name.
The two conventions that need you to declare a language, Han segmentation and kana-aware division, ship as the opt-in locales.ZH and locales.JA packs.
Most of this is default-on, deliberately: wherever nameparser acts unasked, the script itself settles the convention and no language detection is involved. Only names bearing CJK characters parse differently from 2.0 — measured across 751 corpus names, with zero changes on Latin-only input.
Existing HumanName code keeps working through 2.x.
Please open an issue for anything that parses wrong.
nameparser 2.1 makes East Asian names work without configuration. A name written wholly in Han or hangul, or in kanji with kana, is read family-first. An unspaced Korean name is split against the census surname list. CJK honorifics are recognized whether they are spaced or written against the name. The two conventions that need you to declare a language, Han segmentation and kana-aware division, ship as the opt-in locales.ZH and locales.JA packs. See East Asian names for how it fits together, and East Asian names for the switches that turn it off.
Most of this is default-on , deliberately: wherever nameparser acts unasked, the script itself settles the convention and no language detection is involved. Latin-script names are unaffected. To restore 2.0’s reading of CJK text, use Parser(policy=Policy( script_orders=(), segment_scripts=frozenset())) .
East Asian name support
Add the Chinese locale pack locales.ZH: opt-in Han segmentation for unspaced names like 毛泽东 , with the surname vocabulary it needs. A pack rather than a default because a Chinese surname list corrupts Japanese names written in the same characters ( 高橋一郎 would split 高 + 橋一郎 ). Japanese data goes through locales.JA instead. See Locale packs ( #271 )
Add Lexicon.surnames, Policy.script_orders, Policy.segment_scripts, the Script enum and the DEFAULT_SCRIPT_ORDERS constant to the public API. This is the first behavior nameparser keys on the script a name is written in, allowed only where the script itself settles a convention and never as a proxy for guessing the language. See API reference ( #271 )
Add Lexicon.honorific_tails, the vocabulary the glued-honorific peel matches: entries that may be split off the end of a name token. It is a narrower set than the spaced honorific vocabulary, since a glued tail has no token boundary to lean on, and every entry must also be a suffix_words entry. Extend both in one call, or adding to honorific_tails alone raises ValueError . See Customizing the parser ( #308 )
Add AmbiguityKind.SEGMENTATION, reported when a surname split had a vocabulary-supported alternative: "남궁민수" is 남궁 + 민수 by the compound surname but 남 + 궁민수 by the single-syllable one, and longest-match had to pick. A name with only one possible split reports nothing ( #271 )
Add the Japanese locale pack locales.JA and the segmenter factory locales.ja_segmenter(), which together divide an unspaced Japanese name: parser_for(locales.JA, segmenter=locales.ja_segmenter()) reads 山田太郎 as family 山田 , given 太郎 . They are separate because no surname list can do this job, so the pack activates the stage and a third-party divider performs it. ja_segmenter() wraps namedivider-python , installed with the new nameparser[ja] extra; the core stays dependency-free. locales.available() is now ('ja', 'ru', 'tr_az', 'zh') . See Locale packs (closes #272 )
Add Segmentation and the Segmenter type alias to the public API, plus the keyword-only Parser(segmenter=…) hook: any callable from a token’s text to a Segmentation or to None to decline. It is consulted only for scripts in Policy.segment_scripts , and only where the surname vocabulary declined first. Note what that ordering means when packs are stacked: a Japanese name opening on a listed Chinese surname never reaches the segmenter, so 高橋一郎 still splits 高 + 橋一郎 . The packs are alternatives, one per corpus. See Writing your own segmenter ( #272 )
Add a construction-time UserWarning when a parser activates segmentation for scripts nothing can divide. parser_for(locales.JA) without segmenter= used to build a parser that behaved like a working one minus the feature, silently. It now names the dead scripts and the call to pass. Any configured segmenter or covering surname vocabulary silences it, so the default parser and the zh pack never warn. A from-scratch lexicon with no hangul surnames warns under the default policy, with Policy(segment_scripts=frozenset()) offered as the deactivation. See East Asian names
Add the Script members HIRAGANA and KATAKANA. Two members rather than one KANA because the parser treats them differently: hiragana never transcribes a foreign name, while a wholly-katakana name usually is one ( #272 )
Breaking Changes
Change the pickle compatibility of Policy and Lexicon: the new fields change the field layout their guarded setstate checks, so a pickle written by 2.0.0 raises ValueError naming the missing fields instead of loading. Re-pickle after upgrading. HumanName pickles are unaffected, since the facade pickles v1-shaped component state rather than these objects
Change the pickle compatibility of Parser the same way, for the new segmenter field. Re-pickle after upgrading. A Parser carrying a segmenter pickles only if that segmenter does, which a module-level function does and a closure or lambda does not ( #272 )
Change one thing about parse totality: parse() still never raises on any input, but a user-supplied Parser(segmenter=...) runs inside the parse and its own exceptions propagate rather than being absorbed. A failure there is a bug in your callable, not a fact about the name ( #272 )
Behavior Changes
Fix names written wholly in Han or hangul parsing given-first. Native-script CJK now reads family-first through the new Policy.script_orders table, so "毛 泽东" gives family 毛 where 1.x gave family 泽东 . A single unspaced token moves the same way, which is the easiest form of this to miss: "毛泽东" renders identically whichever field holds it, while the spaced form shows the change ( str(HumanName("毛 泽东")) is now "泽东 毛" ). No language detection is involved, and an explicit comma still wins. Default-on , and it reaches HumanName . See East Asian names (closes #271 )
Fix unspaced Korean names not splitting. The census surname list now ships as default vocabulary with hangul segmentation on by default, so "김민준" parses family 김 , given 민준 where 1.x returned the whole string as first . Rendering follows the split. Nothing but Korean is written in hangul and its surnames are a closed set, which is what makes this safe as a default rather than a pack. Default-on . See East Asian names for the two switches ( #271 )
Fix Japanese names carrying kana parsing given-first. The family-first rule extends to any name whose characters stay within kanji and kana while carrying at least one kana character, so "高橋 みなみ" gives family 高橋 . The reasoning is the one hangul already uses: hiragana never transcribes a foreign name, and a transcription is kana alone, so kanji-plus-kana is a Japanese name in Japanese order. A name written wholly in katakana is excluded and stays positional, being predominantly a transcribed foreign name. Default-on . See East Asian names ( #272 )
Fix names containing 〆 (U+3006, the shime mark opening Japanese surnames like 〆木) parsing given-first. The script classifier now counts it as Han, so these names take the family-first reading like any other wholly-Han name ( #303 )
Fix the katakana middle dot ・ (U+30FB, and its halfwidth twin U+FF65) being read as part of a name rather than as a divider. It now separates tokens exactly as a space does, so "マイケル・ジャクソン" gives given マイケル , family ジャクソン where 1.x left the whole string in first . Native Japanese names never contain this character, so the separation is unconditional and the policy opt-outs do not cover it. Rendering returns the dot as a space ( #272 )
Fix 间隔号-divided transcriptions parsing as one unsplit token. U+00B7, the interpunct Chinese text divides a transcribed foreign name with, is now a token separator between characters of a classified script, and a name it divides keeps its source order and is never segmented. It divides only between classified-script characters, so the Catalan punt volat in Gal·la is untouched. The Japanese nakaguro is deliberately not a transcription marker, so 高橋・一郎 keeps its family-first reading ( #298 )
Fix spaced CJK postnominal honorifics parsing as name parts. 씨, 박사, 선생님, 교수님, 군, 양, 先生, 女士, 小姐, 博士, 教授, 様 and 氏 now route to suffix , so 王小明 先生 reads family 王小明 where the family-first default had made 先生 the given name. See East Asian names (closes #307 )
Fix glued CJK honorifics parsing as part of the name. 田中さん , 김민준씨 and 王小明先生 now split the honorific off the end of the name into suffix . Previously it stayed in the name: 田中さん was entirely the family name, and 김민준씨 gave given 민준씨. The peel runs before the name is split or ordered, so 김민준씨 still divides into family 김, given 민준. Only entries that can never end a name peel; 양, 군, 氏, 博士 and 殿 are recognized in their spaced form only, since 김지양 is a given name and some ninety Japanese surnames end in 殿. Default-on , and a lone family name written with a glued honorific now divides where it did not. See East Asian names for the full set and East Asian names for the off-switch (closes #308 )
Fix a comma or a 间隔号 stopping the glued-honorific peel. 김, 민준씨 now gives family 김, given 민준, suffix 씨, the same as the spaced 김 민준씨 , and likewise 田中, 太郎さん . Previously each left the honorific inside the name. Both marks say where a name divides into surname and given, and an honorific is not part of the name in either reading. What a comma does instead is say which runs to look in: the two around a family comma. Anything past those is out of reach, so 김, 민준 지훈씨 peels while 김, 민준, 지훈씨 does not. Default-on . See East Asian names (closes #312 )
Fix a glued honorific staying inside the name when the whole post-comma remainder is a credential. 田中さん, V. and 田中さん, Ph. D. now give up さん to suffix the way 田中さん, PhD already did. The peel had been taking the post-comma run for name text on the strength of the comma alone, walking into the credentials and abandoning the peel there. That run is now tested with the same rule that decides the comma structure, and declined where it is credentials, provided the part before the comma offers a peel site of its own. Where the credential itself lands is still the comma’s business and still differs by spelling. Default-on (closes #319 )
Fix an ASCII period after a CJK honorific stopping it being recognized. 씨. , 様. , 氏. , 님. , 군. , 양. and 殿. now route to suffix like their periodless spellings, where the trailing period had left them inside the name. The cause was v1’s initial regex, whose \w is Unicode-aware and matched a hangul syllable or Han ideograph as readily as a letter; a veto written for Latin was being asked of scripts it was never about. Alphabets keep their initials untouched, and "А. С. Пушкин" is unaffected. Read period strictly: only the ASCII full stop is covered, so "김민준 씨." written with the fullwidth stop still reads the honorific as the family name (superseded in 2.3.0, above). Default-on ( #320 )
Fix NFD-decomposed input missing the East Asian defaults entirely. Script classification now normalizes to NFC before deciding, so a Korean or Japanese name typed on macOS, where decomposed text is routine, gets the same order rule as its composed twin. Segmentation matching deliberately stays raw, so an unspaced NFD hangul name is ordered correctly but not split, rather than being split in the wrong place. One gotcha: parse output preserves the encoding it was given, so for NFD input name.family == "김" is False even though it is the same name. Compare NFC-normalized text when comparing across encodings. See East Asian names ( #272 )
Fix the Ukrainian conjunction й not joining the pieces around it. It is the euphonic alternate of і , chosen by the surrounding sounds rather than by meaning, so real Ukrainian data carries both spellings. "Олесь й Олена Коваленки" now gives given "Олесь й Олена" where the й previously landed in middle . Same treatment as the и / і entries added in 2.0.0: the conjunction joins only once the name has enough pieces, and a punctuated initial still wins, so "Й. Сліпий" is unaffected. Raised in a comment on #267
Add the Japanese maiden-name marker 旧姓 to the default vocabulary. "山田花子 旧姓 佐藤" now gives family 山田花子 and maiden 佐藤 , where 1.4.0 left the marker in the name. It sits beside the Cyrillic урожд. and German geb. entries rather than in locales.JA , on the rule that admitted those: a native-script marker cannot collide with a Latin-script name, so it is safe as a default. Matching is whole-token, so the marker has to be a token, which for Japanese means a space or a configured delimiter must divide it from the name. The fullwidth colon does not, so "山田(旧姓:佐藤)" still returns maiden "旧姓:佐藤" ; that one wants the head-peel #317 tracks. Default-on . See Behavior: Policy ( #309 )
Fix a maiden marker inside bracketed content staying in the maiden value. Where a delimiter pair is routed to maiden by Policy(maiden_delimiters=...) , a marker at the head of the clause is now dropped the way it always has been in the bare form, so "Jane Smith (née Jones)" gives maiden Jones , the same answer as the unbracketed spelling. Each clause loses its own leading marker, and only where the clause holds more than one token, so "Jane Smith (Nee) (Jones)" still gives maiden Nee Jones ( Nee is a real surname). Scope before you count on it: Policy.maiden_delimiters is empty by default , so under the default policy brackets route to nickname and none of this applies. See Behavior: Policy (closes #329 )
Documentation
Correct the documented scope of the period-abbreviation title rule. It was described as applying to “a leading word”, which was never true of any comma form: the rule runs at the front of the part that carries the given name, which after a family comma is the part after the comma, so "Morse, Det. Insp. Jane" gives title Det. Insp. . Behavior is unchanged and matches 1.4.0; only the description was wrong
What 2.0 removes is the batch of deprecations announced in 1.3 and 1.4; if your suite runs clean on 1.4 under python -W error::DeprecationWarning, you…
nameparser 2.0 — a new immutable core API, with full compatibility for existing code through 2.x.
parse() returns an immutable ParsedName whose seven fields are named for what they are (given, family) rather than where they sit in a Western name, configured by two frozen value objects — a Lexicon of vocabulary and a Policy of behavior — instead of a mutable global. Every parse can tell you what it had to guess at (ambiguities) and exactly where each token came from (tokens, with character spans).
HumanName keeps working. It is now a compatibility facade over the same pipeline and stays through 2.x — most 1.x code needs no changes. What 2.0 removes is the batch of deprecations announced in 1.3 and 1.4; if your suite runs clean on 1.4 under python -W error::DeprecationWarning, you are nearly done. One removal changes results silently rather than raising: name == "John Smith" is now False — use matches(). The migration guide has the field-by-field map.
Highlights:
title, given, middle, family, suffix, nickname, maiden — plus derived views (family_particles, given_names, …), render(spec), initials(), capitalized(), and semantic comparison via matches()/comparison_key()Lexicon + Policy, partial PolicyPatch deltas, Policy.patched(), and Parser.revise() for tag-preserving correctionsPolicy(name_order=FAMILY_FIRST)) and opt-in locale packs (parser_for(locales.RU)) — never auto-detectednée, geb., …)The full change list is in the release log; rc1/rc2 testers can read its "Changed since 2.0.0rc1" section. Please report anything the migration missed on #284.
🤖 Generated with Claude Code
Two release candidates preceded this release (rc1 on 2026-07-23, rc2 on 2026-07-26). Please report anything the migration missed on issue #284 . The notes below describe 2.0.0 as a whole.
nameparser 2.0 adds a new parsing API alongside HumanName . parse() returns an immutable ParsedName whose seven fields are named for what they are ( given , family ) rather than where they sit in a Western name, configured by two frozen value objects – a Lexicon of vocabulary and a Policy of behavior – instead of a mutable global. HumanName keeps working: it is now a compatibility facade over the same pipeline, and it stays through 2.x. The removals below are the deprecations announced in 1.3.0 and 1.4.0 coming due; if your code runs warning-free on 1.4.0, most of them will not affect you. See Migrating to 3.0 for the field-by-field map.
The 2.0 API
Add parse(text), returning an immutable ParsedName with seven fields – title , given , middle , family , suffix , nickname , maiden – plus the derived views given_names , surnames , family_base and family_particles . Parsing is a pure function of the text, a Lexicon and a Policy : nothing global is consulted and nothing is mutated
Add Lexicon, the frozen vocabulary object. Lexicon.default() is the shipped vocabulary and Lexicon.empty() is a blank one; add(**entries) , remove(**entries) and field-wise | all return new instances. Its fields are titles , given_name_titles , suffix_acronyms , suffix_words , suffix_acronyms_ambiguous , particles , particles_ambiguous , conjunctions , bound_given_names , maiden_markers and capitalization_exceptions
Add Policy , the frozen behavior object: name_order , patronymic_rules , middle_as_family , nickname_delimiters , maiden_delimiters , extra_suffix_delimiters , lenient_comma_suffixes , strip_emoji and strip_bidi
Add Parser , a reusable parser bound to a lexicon and policy ( Parser(lexicon=..., policy=...).parse(text) ), and parser_for(*locales, base=None) , which folds locale packs onto a base parser
Add name_order and the constants GIVEN_FIRST , FAMILY_FIRST and FAMILY_FIRST_GIVEN_LAST , so a family-first name can be parsed as written rather than reordered by hand (the configuration half of #270 ; the locale packs below complete it)
Add PatronymicRule with the members EAST_SLAVIC and TURKIC . v1’s single patronymic_name_order flag enabled both detectors at once; Policy(patronymic_rules=...) lets you enable either one alone
Add PolicyPatch and the UNSET sentinel for partial policy deltas that compose – set-valued fields union, scalar fields override with later winning. This is the mechanism locale packs are built from, and UNSET is only needed when you must distinguish “not set” from a real False or None
Add Token, Span and Role: every field is backed by tokens carrying exact (start, end) offsets into the original string, reachable with tokens_for(Role.GIVEN) . This replaces v1’s *_list attributes and makes it possible to highlight or re-slice the input the parse came from. Role is a StrEnum , so members compare and stringify as their field names ( Role.GIVEN == "given" ), matching AmbiguityKind ; tokens_for() accepts a role’s string name too, and raises ValueError for an unknown role
Add STABLE_TAGS to the public API: the four documented Token.tags values ( particle , conjunction , initial , joined )
Add Policy.patched(patch) , applying a PolicyPatch directly without wrapping it in a locale pack
Add Parser.matches(a, b) and Parser.capitalized(name): the ParsedName methods of the same names fall back to the default configuration for str/omitted arguments, which is silently wrong for names parsed with a custom Parser
Add Parser.revise(name, **fields) : ParsedName.replace() with the replacement text classified by the parser’s vocabulary, so particle/initial/suffix-join behavior survives the edit
Add Ambiguity and the AmbiguityKind enum, so a parse reports what it had to guess at instead of guessing silently. The kinds emitted today are particle-or-given , suffix-or-name , suffix-or-nickname , unbalanced-delimiter and comma-structure ; order is reserved and not yet emitted. The two suffix kinds cover the post-nominals that are also ordinary words: "John Smith MA" reports that MA was read as a credential rather than a surname, and "JEFFREY (JD) BRICKEN" that the delimited JD was read as a nickname rather than a suffix. A reading the vocabulary settles on its own — "John Smith M.A." , "Andrew Perkins (MBA)" — is not a guess and reports nothing
Add ParsedName output and comparison methods: render(spec) , initials() , capitalized() (which returns a new value rather than mutating in place), as_dict() (whose include_empty flag is keyword-only, unlike HumanName.as_dict() ’s), replace(**fields) , matches() and comparison_key()
Add Locale , the public pack type. Writing your own needs no registration – construct a Locale and pass it to parser_for()
Ship a fully typed public API (PEP 561): the core modules are checked under strict mypy settings, and nameparser 2.0 has no runtime dependencies
Breaking Changes
Raise the minimum Python to 3.11 and drop the last runtime dependency, typing_extensions ( #257 ). Python 3.10 is no longer supported
Remove HumanName.eq and hash (deprecated in 1.3.0, #223): instances now compare and hash by identity, so HumanName("John Smith") == "John Smith" is False where 1.x returned True . This changes result silently rather than raising – it is the one removal that can pass unnoticed into production. Use matches() to ask whether two names are the same, and comparison_key() as a dict key or sort key
Remove every v1 parsing hook and subclass extension point: pre_process , post_process , parse_pieces , parse_nicknames , join_on_conjunctions , the is_* predicates, cap_word / cap_piece , handle_firstnames , fix_phd and the rest. A subclass that overrides one gets a DeprecationWarning at construction naming the hooks, because the facade delegates to the core Parser and never calls them (closes #280 ). Customize through Lexicon / Policy instead
Remove regex configuration: CONSTANTS.regexes is now a read-only proxy. Reads still work, but CONSTANTS.regexes.bidi = False , item assignment and Constants(regexes=...) all raise TypeError . If you followed 1.3.1’s advice to keep bidi marks with CONSTANTS.regexes.bidi = False , that opt-out is now Policy(strip_bidi=False) on the 2.0 API; the same applies to regexes.emoji and Policy(strip_emoji=False)
Remove bytes input and the encoding argument (#245): passing bytes to HumanName or to a set manager raises TypeError with a decode hint, and SetManager.add_with_encoding() and DEFAULT_ENCODING are gone. Decode first, then use add()
Remove SetManager.call (#243); iterate the manager or call set(manager). remove() of a missing member now raises KeyError like set.remove – discard() is the ignore-missing form – and the set operators | , & , - and ^ return a plain set
Remove HumanName slice access and item assignment (#258): name[1:-3] and name['first'] = value raise TypeError . String-key reads ( name['first'] ) and iteration are unchanged; assign fields as plain attributes
Remove Constants.empty_attribute_default ( #255 ): empty fields are always '' . Assigning it raises AttributeError ; a pickle carrying the key still loads, with the value ignored
Remove constants=None ( #261 ): both HumanName(..., constants=None) and hn.C = None raise TypeError . Use Constants() for library defaults or CONSTANTS.copy() for a private snapshot
Remove silent unknown-key access on the mapping managers (#256): CONSTANTS.capitalization_exceptions.typo and CONSTANTS.regexes.typo raise AttributeError naming the miss, instead of returning None / EMPTY_REGEX ( capitalization_exceptions also lists the known keys). .get() remains available on both for intentional soft access
Remove support for Constants pickles written by nameparser 1.2.x or earlier ( #279 ): loading one raises ValueError telling you to re-pickle under 1.3/1.4 first
Remove the dead regexes.no_vowels pattern ( #268 ) and the Constants.suffixes_prefixes_titles cached union; neither was read by the parser
Change HumanName ’s *_list attributes to read-only properties: they remain readable snapshots, but name.first_list = [...] now raises AttributeError
Change the Constants constructor to keyword-only; positional construction no longer works
Behavior Changes
Recognize maiden-name markers – née , nee , geb. , roz. and the Scandinavian participle forms – and route the following name to the new maiden field. 1.x folded them into middle / last , so "Jane Smith née Jones" parsed as middle="Smith née" (closes #274 )
Recognize typographic nickname delimiters by default in both APIs (closes #273): smart quotes ( “Jack” ), German and Polish low-high quotes ( „Hansi“ ), Swedish right-right quotes ( ”Ann” ), guillemets in either direction ( «Petit» , »Hansi« ), CJK corner brackets ( 「タロ」 , 『ハナ』 ) and fullwidth parentheses. In 1.x these leaked into middle as literal text. Curly single quotes stay excluded, because U+2019 is the apostrophe in “O’Connor”
Fix the pre-comma piece being routed to first when everything after the comma is a suffix or title: "Andrews, M.D." now reads family Andrews / suffix M.D. where 1.x read given M.D. / family Andrews , and "Smith, Dr." moves Smith from first to family (the title was already correct in 1.x). The piece before a comma is definitionally the family name
Fix a lone recognized trailing suffix with no comma being routed to first/last: "Johnson PhD" and "Mr. Johnson PhD" now keep the suffix in suffix
Fix a split “Ph. D.” credential being read as two tokens; it now classifies as one suffix, replacing v1’s fix_phd hook. This now holds wherever the credential sits: 1.x healed the pair only when it trailed, so "Ph. D. John Smith" parsed as title Ph. / given D. with the real given name pushed to middle ; it now reads given John , family Smith , suffix Ph. D.
Fix chargé d’affaires: shipped as one unmatchable TITLES entry since it was added, it is now two chainable entries ( chargé , d'affaires ), so the title is recognized; the unaccented spelling charge ships too, like attaché / attache
Remove seven multi-word SUFFIX_ACRONYMS entries ( leed ap , nicet i – nicet iv , psm i , psm ii ) that could never match in any release; splitting them would swallow real names (“John Leed”, “Smith, A.P.”), so they are dropped instead
Add a UserWarning when a multi-word entry is stored in a per-word Lexicon field or as a capitalization_exceptions key – such entries can never match
Parse an input with no alphanumeric character to an empty name in both APIs. 1.x kept pure punctuation as a name part, so "." gave first="." and bool() was True ; 2.0 empties it, keeping bool(parse(x)) an honest “did I get a name?” test. The check is Unicode-aware, so names in any script are unaffected; only inputs that are entirely punctuation or symbols ( "." , "- -" ) change. Junk embedded in a name with real content – the stray dot in "John . Smith" – is still kept, since that parse is already truthy
Fold a leading never-given particle into the family name. Note that Lexicon.particles_ambiguous is the complement of v1’s non_first_name_prefixes , not a rename – it lists the particles that may double as a given name, where v1 listed the ones that may not. Copying a v1 customization across without inverting it silently reverses the behavior; see Migrating to 3.0
Add ma and do to suffix_acronyms_ambiguous, the set of post-nominals that are also ordinary surnames. An entry there is read as a credential when the name can spare it — written with periods ( "John Smith M.A." ), or when removing it still leaves a given and a family name ( "John Smith MA" → suffix MA ). With only two pieces to go around, the surname reading wins instead: "Jack Ma" and "Anh Do" keep their family names. As a side effect, a parenthesized or quoted "(MA)" / "(DO)" now falls through to nickname parsing rather than escaping to suffix , since inside delimiters the nickname reading is the plausible one
Change comparison_key() and matches() in both APIs to fold with str.casefold() where 1.4 used str.lower(), so Unicode case pairs compare equal – "STRASSE" matches "Straße" , and a Greek final sigma matches its regular form. This is strictly more permissive: anything 1.4 matched still matches. Vocabulary normalization deliberately still uses lower() , for v1 parity
Change the 2.0 API’s default render()/str() spec to show every non-empty field: '{title} {given} "{nickname}" {middle} {family} ({maiden}) {suffix}' . The quoted nickname round-trips exactly; the parenthesized maiden re-parses as a nickname, a deliberate choice of presentation over lossless round-trip – use née {maiden} in a custom spec if you need it to survive a reparse. HumanName keeps v1’s own string_format default, unchanged
Change delimiter-overlap precedence in the 2.0 API: a pair listed in Policy.maiden_delimiters is dropped from the effective nickname set, so Policy(maiden_delimiters={("(", ")")}) alone routes parenthesized content to maiden . The default nickname set is exported as DEFAULT_NICKNAME_DELIMITERS . HumanName keeps v1’s nickname-wins precedence, so no existing behavior changes
Change suffix-delimiter rendering when a custom suffix delimiter is configured: for suffix_delimiter="/" and "John Smith, RN/CRNA" , 1.x split the token and rendered suffix="RN, CRNA" where 2.0 keeps it whole as "RN/CRNA" . Role assignment is unchanged; only rendering differs
Correct a long-standing typo in the shipped vocabulary that 1.x carried: actor and television had trailing spaces in TITLES , so "actor" in TITLES was False . Parse output is unchanged – the parser normalizes entries on ingest, which is exactly what let the typo go unnoticed – but code that tests membership against the exported constants directly will see corrected results. The data modules now assert their invariants at import time, alongside the ones prefixes.py already checked; entries must be stored lowercase and whitespace-free, so this class of typo now fails the build
International name support
Add nameparser.locales with the first two packs: locales.RU (East Slavic patronymic order) and locales.TR_AZ (Turkic patronymic markers). Packs are pure data folded in at parser_for(locales.RU) , they compose ( parser_for(locales.RU, locales.TR_AZ) unions the rules), and they are never auto-detected – there is no reliable way to detect a name’s language from the name alone. locales.available() and locales.get(code) look packs up by code; loading is lazy, so importing the package imports no pack (completes #270 ; #271 /#272/#146 stay staged for 2.x)
Add non-Latin vocabulary to the default lexicon (#269): Cyrillic, Greek, Arabic and Hebrew titles, conjunctions and name particles. Native-script entries cannot collide with Latin-script names, which is what makes them safe to enable by default. Deferred pending vetting: the Cyrillic мл / ст suffixes and the bare Greek κ title, which collides with the initial-plus-surname shape. Behavior note: محمد بن سلمان now chains بن onto the family name where 1.x read it as a middle name
Add Arabic-script bound given names (#269): عبد , the kunya pair أبو / ابو , and أم / ام join the following word into the given name exactly as their transliterations ( abdul , abu , umm ) always did, so عبد الرحمن محمد parses given عبد الرحمن , family محمد where 1.x split it into given plus middle
Add Arabic honorific titles and the conjunction و (#269): the doctor, professor, hajj, sheikha and engineer forms ( الدكتور / الدكتورة / دكتور / دكتورة , الأستاذ / الأستاذة / أستاذ / أستاذة , الحاج / الحاجة , الشيخة , مهندس ) as given-name titles, since Arabic honorifics precede the given name like الشيخ . Deferred under the collision rule: bare سيد / شيخ / أمير / سلطان (all common given names), the د. abbreviation (bare د would swallow initials), and the Ottoman post-nominals باشا / بك / أفندي (which survive as family names)
Add Hebrew honorifics and post-nominals, and Devanagari titles (#269): the Israeli honorifics גברת , פרופ' / פרופ׳ , פרופסור , עו"ד / עו״ד and הרב as titles; ז"ל / ז״ל and שליט"א / שליט״א as suffixes, in both gershayim spellings; and Devanagari श्री , श्रीमती and डॉ . Latin sri / shri were deliberately not added, because they collide with real given names where the native script cannot. Deferred: bare רב (an ordinary word meaning “many”) and בר as a particle (Bar is a common modern given name)
Compatibility layer
Reimplement HumanName as a facade over the 2.0 pipeline, and Constants as a shim resolving to a (Lexicon, Policy) snapshot with a shared parser cache. Fields, aggregates, mutation through name.C.titles.add(...) , rendering defaults, capitalize() , matches() , comparison_key() , iteration, as_dict() and pickling are all preserved, and nameparser.parser and nameparser.config remain importable. The compatibility layer ships through 2.x and is removed in 3.0
Note that CONSTANTS.capitalize_name and force_mixed_case_capitalization are still honored through the facade, but the 2.0 API never capitalizes during parse() – call capitalized() when you want it
Add Role members (and their string values given / family ) as valid HumanName subscript keys: hn[Role.GIVEN] returns hn.first
Add a UserWarning when assigning HumanName.given or .family: the facade spells those attributes first / last , so the assignment creates an inert stray attribute while the parse keeps the old value. The assignment still happens (v1-legal ad-hoc attributes keep working); the warning names the v1 spelling to use
Command line
Rewrite python -m nameparser over the 2.0 API with a real argument parser. It prints the parse plus its capitalized form and initials by default, takes --json to emit the fields as JSON ( python -m nameparser --json "Doe, John" ), takes --locale CODE to apply a pack, and exits with a usage message on bad arguments
Documentation
Rewrite the documentation new-API-first: a new front page and README, usage.rst as a tour of the 2.0 API, a principle-first customize.rst , a reference split into the 2.0 API and the compatibility layer, and new pages for How the parser works , Locale packs and Migrating to 3.0 – the last carrying full attribute and configuration maps from v1 names to 2.0 names ( #262 ). The 1.x documentation remains online as the readthedocs stable build
Parsing changes were checked against a 652-name differential corpus – names harvested from the v1 test banks, plus names reported in the issue tracker – and everything not listed above parses identically between 1.4.0 and 2.0. The harness lives in tools/differential/ in the source repository (it is development tooling, not part of the installed package) – see its README to reproduce the comparison against your own names.
Changed since 2.0.0rc1 (for anyone who tested the release candidate)
Role became a StrEnum ; str(Role.GIVEN) is now "given"
ParsedName.tokens_for() raises ValueError for unknown roles instead of returning no tokens; it also accepts role-name strings
ParsedName.as_dict() ’s include_empty is keyword-only
HumanName subscripting accepts Role members
Assigning HumanName.given / .family warns (the facade spells them first / last ; the assignment was and remains an inert stray attribute)
The eight multi-word vocabulary entries that could never match were repaired ( chargé d'affaires split; seven credential acronyms removed), and storing a new multi-word entry now warns; those eight are dropped silently, not warned about, when a restored Constants pickle carries all eight of them (the pre-2.0 signature)
PolicyPatch ’s repr shows only the fields a patch sets, instead of all nine with UNSET sentinels
New since rc1: STABLE_TAGS , Policy.patched() , Parser.matches() , Parser.capitalized() , and Parser.revise() – see the API section above
Second release candidate for nameparser 2.0.0. Install it with pip install --pre nameparser (a plain pip install will not select a pre-release). Pleas
Second release candidate for nameparser 2.0.0. Install it with pip install --pre nameparser (a plain pip install will not select a pre-release). Please report anything the migration missed on #284.
rc2 is rc1 plus the post-rc1 API-polish bundle (#290). If you tested rc1, the release log's "Changed since 2.0.0rc1" section lists exactly what you'd notice:
Role became a StrEnum — members compare and stringify as their field namesParsedName.tokens_for() raises ValueError for unknown roles instead of silently returning no tokens, and accepts role-name stringsParsedName.as_dict()'s include_empty is keyword-onlyHumanName subscripting accepts Role memberschargé d'affaires split into chainable words, both spellings; seven credential acronyms removed), and storing a new multi-word entry now warns — a restored pre-2.0 Constants pickle carrying all eight is cleaned up silentlyPolicyPatch's repr shows only the fields a patch setsSTABLE_TAGS, Policy.patched(), Parser.matches(), Parser.capitalized(), and Parser.revise()🤖 Generated with Claude Code
The removals are the deprecations announced in 1.3.0 and 1.4.0 coming due. The one that matters most:
This is a release candidate. A plain
pip install nameparserwill not pick it up — pre-releases are opt-in:pip install --pre nameparser==2.0.0rc1Please try it against your real code and report anything the migration missed on #284. The final 2.0.0 follows once the RC settles.
nameparser 2.0 adds a new parsing API alongside HumanName. HumanName keeps working unchanged as a compatibility facade over the same pipeline, and stays through the 2.x series — if your code runs warning-free on 1.4.0, most of 2.0 will not affect you.
parse(text) returns an immutable ParsedName whose seven fields are named for what they are — given, family — rather than where they sit in a Western name:
from nameparser import parse
name = parse("Dr. Juan Q. Xavier de la Vega III")
name.given # 'Juan'
name.family # 'de la Vega'
name.family_base # 'Vega' (particles split off)
name.suffix # 'III'
Lexicon of vocabulary and a Policy of behavior replace the mutable global Constants. Both are immutable, hashable value objects; parsing is a pure function of the text, a lexicon, and a policy — nothing global is read or mutated. Build a reusable Parser(lexicon=..., policy=...).Policy(name_order=FAMILY_FIRST) and FAMILY_FIRST_GIVEN_LAST (#270).parser_for(locales.RU) folds in East Slavic patronymic order; locales.TR_AZ covers Turkic markers. Packs are pure data, they compose, and they're never auto-detected.née, geb. → a maiden field, #274), typographic nickname delimiters (smart quotes, guillemets, CJK brackets, #273), and non-Latin vocabulary — Cyrillic, Greek, Arabic, Hebrew titles and particles (#269).ParsedName.ambiguities instead of guessing silently — e.g. "John Smith MA" reports that MA was read as a credential rather than a surname. A reading the vocabulary settles on its own reports nothing.Tokens carrying (start, end) offsets into the original string, reachable via tokens_for(Role.GIVEN) — so you can highlight or re-slice the input a parse came from.The removals are the deprecations announced in 1.3.0 and 1.4.0 coming due. The one that matters most:
HumanName.__eq__ and __hash__ are removed (#223). Instances now compare and hash by identity, so HumanName("John Smith") == "John Smith" is now False where 1.x returned True. This changes results silently rather than raising — it's the one removal that can slip into production unnoticed. Use matches() to compare names and comparison_key() as a dict/sort key.Also: minimum Python is now 3.11 (#257); bytes input is gone (decode first, #245); regex configuration, subclass parsing hooks, HumanName slicing, and empty_attribute_default are removed. Each raises with a migration hint (except the __eq__ case above).
HumanName is unchanged, so most users need to do nothing yet. If you customized Constants, subclassed HumanName, or compared names with ==, see the migration guide for the field-by-field and attribute-by-attribute map.
Deprecate passing constants=None to HumanName (or assigning hn.C = None): it silently builds a fresh Constants(), discarding any customizations the ca…
Constants.copy(), a detached deep copy that preserves the source instance's current customizations (unlike Constants(), which always starts from library defaults) -- useful as CONSTANTS.copy() for a private snapshot of the shared config (#260)constants=None to HumanName (or assigning hn.C = None): it silently builds a fresh Constants(), discarding any customizations the caller may have expected to carry over from the shared CONSTANTS. Emits DeprecationWarning; will raise TypeError in 2.0. Use constants=Constants() for fresh library defaults or constants=CONSTANTS.copy() for a private snapshot instead (closes #260)Constants.empty_attribute_default for removal in 2.0 (#255): once None support goes, the only legal value left is the default '', so a dial with one position isn't configuration. Emits DeprecationWarning; reading the attribute is unaffectedTupleManager/RegexTupleManager (CONSTANTS.regexes.typo, CONSTANTS.capitalization_exceptions.typo, etc.) for removal in 2.0 (#256): a misspelled or omitted key currently degrades silently (None/EMPTY_REGEX) with no traceback pointing at the typo. Emits DeprecationWarning naming the miss and the known keys; will raise AttributeError in 2.0. .get() remains available for intentional soft accessHumanName slice access (name[1:-3]) and item assignment (name['first'] = value) for removal in 2.0 (#258): field access by position has no real use case, and item assignment duplicates plain attribute assignment. Both emit DeprecationWarning; string-key access (name['first']) is unaffectedSetManager.add_with_encoding() itself for removal in 2.0 (#245), regardless of argument type: use add() instead (decoding bytes first). Previously only the bytes path warned; the str path was silent even though the whole method goes awayConstants pickle (written by nameparser <= 1.2.x, before the 1.3.0 pickle fix) for removal in 2.0 (#279): __setstate__'s migration shim currently skips the stale computed-property key silently. Emits DeprecationWarning once per call telling users to re-pickle; will raise ValueError in 2.0"Lastname, Firstname" comma format not being recognized when the input uses the Arabic comma ، (U+060C, the standard comma in Arabic/Persian/Urdu text) or the fullwidth CJK comma , (U+FF0C) instead of the ASCII comma: both variants now also split the format and no longer leak into the parsed output (closes #265)Full changelog: https://github.com/derek73/python-nameparser/blob/master/docs/release_log.rst
Patch release with two output-corruption bug fixes. No API changes. Full details in the release log.
Patch release with two output-corruption bug fixes. No API changes. Full details in the release log.
first/last/etc., so a copy-pasted right-to-left name silently failed equality and dedup. Disable via CONSTANTS.regexes.bidi = False.str() no longer corrupts name text containing the substring "None" when empty_attribute_default is None (#254) — e.g. "Nonez Smith" rendered as "z Smith". Empty attributes are now substituted as '' before the format string is applied, instead of scrubbing the interpolated "None" from the output afterward. Present since 2016; the default '' configuration was never affected.Fix invisible Unicode bidirectional control characters (LRM/RLM/ALM, the embedding/override marks, and the isolates U+2066–U+2069) surviving parsing and sticking to first / last /etc., so a copy-pasted right-to-left name silently failed equality and dedup. They are now stripped in preprocessing like emoji; disable via CONSTANTS.regexes.bidi = False (closes #266 )
Fix str() corrupting name text containing the substring “None” when empty_attribute_default is None (e.g. “Nonez Smith” rendered as “z Smith”): empty attributes are now substituted as '' before the format string is applied, instead of scrubbing the interpolated "None" from the output afterward (closes #254 )
This release is the bridge release ahead of 2.0: every planned 2.0 removal now has its replacement shipped and emits a DeprecationWarning naming it, s…
This release works through essentially the entire backlog of open issues — nearly every bug and feature request in the tracker, including several dating back to 2014. Alongside the fixes, it adds long-requested functionality: maiden name support, surname-prefix splitting, patronymic name ordering, and a set of new customization hooks on Constants.
The release was developed with Claude Code, and every fix and feature ships with regression tests. The complete list of changes is below.
This release is the bridge release ahead of 2.0: every planned 2.0 removal now has its replacement shipped and emits a DeprecationWarning naming it, so code can migrate while both APIs work. Full details in the release log.
== and hash() on HumanName (#223) — the design's three promises (case-insensitive equality, equality with plain strings, hashability) are mutually inconsistent, equality depends on string_format, and maiden is invisible to it. Replacements, new in this release: matches() for semantic comparison (name.matches("Smith, John") and name.matches("John Smith") both match) and comparison_key() for sets, dicts, dedup, and sorting.bytes input (#245) — decode first, e.g. value.decode('utf-8'); the encoding kwarg is deprecated with it.SetManager.__call__ (#243) — iterate the manager or copy with set(manager).SetManager.remove() of a missing member (#243) — will raise KeyError in 2.0 like set.remove; new discard() is the intentional ignore-missing spelling.HumanName is no longer its own iterator; iter(name) returns a fresh independent iterator (fixes state corruption from break/nested loops/len() mid-loop) (#225)unparsable attribute removed (unreachable since 2013; use len(name) == 0); __ne__ removed (derived from __eq__)REGEXES and CAPITALIZATION_EXCEPTIONS are now dicts — iterate with .items() (#227, #233)__process_initial__ renamed _process_initial (dunder names are reserved)abdul, abu, …) join forward into the first name (#150); disable via CONSTANTS.bound_first_names.clear()"Major.") parses as a title (#109)CONSTANTS it reads — parse results no longer depend on what was parsed earlier in the process, and parsing is thread-safe against config writesmaiden field with maiden_delimiters routing (#22); given_names (#157); last_base/last_prefixes for surname particles (#130, #132)patronymic_name_order for Russian and Turkic formal-order names (#85, #185); middle_name_as_last (#133); non_first_name_prefixes (#121); expanded international titles and prefixes (#18, #101, #187)initials_separator (#171), suffix_delimiter (#156), nickname_delimiters (#110, #112), suffix_acronyms_ambiguous (#111)TupleManager rejects malformed input (#242), membership checks normalize like every other operation (#244), Constants subclasses are respected (#226)Constants survive pickle/deepcopy (#167, #168, #169); many parsing fixes — suffix boundaries with prefixed last names (#100), repeated prefix chains (#208), degenerate comma input, roman-numeral and suffix recognition in comma formats (#136, #144), and moreBreaking Changes & Deprecations
Deprecate HumanName.eq and hash for removal in 2.0 (#223): the current design’s three promises — case-insensitive equality, equality with plain strings, and hashability — are mutually inconsistent (equal objects can hash differently), equality depends on string_format , and maiden is invisible to it. Both now emit DeprecationWarning naming the replacement; behavior is otherwise unchanged until 2.0 (closes #224 )
Deprecate bytes input for removal in 2.0 (#245): passing bytes to HumanName / full_name or to SetManager.add() / add_with_encoding() now emits DeprecationWarning — decode first, e.g. value.decode('utf-8') . The encoding constructor argument is deprecated with it
Deprecate SetManager.call for removal in 2.0 (#243): calling a manager returns the raw underlying set, so mutating the result bypasses normalization and cache invalidation; iterate the manager or copy with set(manager) instead
Add SetManager.discard(), and deprecate remove() of a missing member (#243): it currently does nothing but will raise KeyError in 2.0, matching set.remove ; use discard() for intentional ignore-missing removal. Removing present members is unchanged and does not warn
Fix HumanName acting as its own iterator with a stored cursor: breaking out of a loop, iterating in nested loops, or calling len(name) mid-loop corrupted subsequent iteration; iter(name) now returns a fresh independent iterator each time. next(name) on the instance itself (undocumented) now raises TypeError — call next(iter(name)) instead (closes #225 )
Remove the vestigial unparsable attribute: the guard that was meant to set it has been unreachable since 2013 (v0.2.9), so it has reported False for every parsed name for over a decade; check len(name) == 0 to detect an empty parse
Remove ne ; Python 3 derives != from eq automatically
Change internal initials helper process_initial to _process_initial : double-underscore-both-sides names are reserved for Python special methods; subclasses overriding the old name must rename their override
Change REGEXES from a set of (name, pattern) tuples to a dict , so a duplicate name is a visible overwrite in the source instead of a nondeterministic winner at import time; code iterating REGEXES directly now gets keys instead of pairs — use .items() ( #227 )
Change CAPITALIZATION_EXCEPTIONS from a tuple of (key, value) tuples to a dict ; code iterating it directly now gets keys instead of pairs — use .items() ( #233 )
Behavior Changes (affect existing parse output)
Add bound_first_names set to Constants ; bound Arabic given-name prefixes ( abdul , abu , etc.) now join forward to form a single first name (e.g. "abdul salam ahmed salem" → first="abdul salam" , middle="ahmed" , last="salem" ). Disable via CONSTANTS.bound_first_names.clear() . Default-on: changes parsing output for names with these prefixes. ( #150 )
Treat an unrecognized, multi-letter token ending in a period in the leading title run (before the first name is set), e.g. "Major." , as a title instead of a first name; internal-period abbreviations ( "E.T." ) and single-letter initials ( "J." ) are unaffected. Default-on: changes parsing of names with a leading unknown period-abbreviation (closes #109 )
Fix parsing writing back into the Constants it reads (usually the shared module-level CONSTANTS): pieces derived while parsing a name — period-joined titles/suffixes like "Lt.Gov." and conjunction-joined pieces like "Mr. and Mrs." or "von und zu" — are now tracked per parse instead of being permanently add() -ed to the config, so parse results no longer depend on which names were parsed earlier in the process and parsing no longer mutates shared state across threads
Fix hash to lowercase the name like eq does, so equal HumanName instances hash equal and behave correctly in sets and dicts
New comparison methods
Add matches() and comparison_key() for explicit name comparison: matches() compares parsed components case-insensitively (parsing str arguments first, so name.matches("Smith, John") and name.matches("John Smith") both match) and comparison_key() returns a hashable tuple of the seven components for dedup, dict keys, and sorting ( #224 )
New name fields
Add a first-class maiden field and maiden_delimiters to Constants , so a delimiter (e.g. parenthesis) can be routed to maiden instead of nickname for alternate/maiden surnames, e.g. "Baker (Johnson), Jenny" (closes #22 )
Add given_names (and given_names_list ) attribute as aggregate of first and middle names, mirroring surnames (closes #157 )
Add last_base , last_prefixes (and _list variants) for splitting last-name prefix particles (tussenvoegsels) from the core surname ( #130 , #132 )
New customization options
Add initials_separator to Constants and HumanName to control spacing between consecutive initials within a name group ( #171 )
Add suffix_delimiter to Constants and HumanName for parsing suffixes separated by arbitrary delimiters, e.g. "RN - CRNA" ( #156 )
Add nickname_delimiters to Constants for registering additional nickname-delimiter regex patterns at runtime, without subclassing (closes #110 , #112 )
Add suffix_acronyms_ambiguous to Constants for acronym suffixes that also read as given-name nicknames (e.g. "JD" , "Ed" ), used when disambiguating parenthesized/quoted content ( #111 )
International name support
Add patronymic_name_order flag to Constants and HumanName for opt-in detection and reordering of Russian formal-order names (Surname GivenName Patronymic) ( #85 )
Add Turkic (Azerbaijani/Central-Asian) patronymic detection to patronymic_name_order , rotating the reversed 4-token formal shape ( Surname GivenName PatronymicRoot Marker , e.g. oglu / qizi ) into Western order ( #185 )
Add middle_name_as_last flag to Constants and HumanName for opt-in folding of middle names into the last name, for naming systems with no middle-name concept (e.g. Arabic patronymic chaining) ( #133 )
Add non_first_name_prefixes to Constants: a leading particle that is never a first name (e.g. "de Mesnil" , "dos Santos" ) now parses as a surname with an empty first name, instead of treating the particle as the first name (closes #121 )
Add international honorifics to TITLES ( #187 )
Add German/Austrian nobility and ecclesiastical titles to TITLES (closes #101 )
Add German/Dutch last-name prefixes and title/degree suffixes; fix join_on_conjunctions() to register multi-word prefix chains (e.g. "von und zu" ) as prefixes, mirroring existing title handling (closes #18 )
Parsing fixes
Fix suffix boundary lookup for prefixed last names with a title before and after (e.g. "dr Vincent van Gogh dr" producing a corrupted middle name) (closes #100 )
Fix a repeated prefix word in a prefix chain (e.g. “Juan de la de la Vega”) silently dropping the earlier occurrence in join_on_conjunctions(): value-based pieces.index(prefix) lookups re-found the wrong occurrence once the list had already been mutated by prior joins; prefix positions are now tracked positionally instead of re-derived by value (closes #208 )
Fix a trailing suffix being silently dropped after an empty comma segment, e.g. "Doe, John,, Jr." losing the "Jr."
Fix degenerate comma input (a bare "," or an empty comma segment, e.g. "Doe,, Jr." , "John Doe, Jr.,," ) leaving an empty-string member in first_list , last_list , or suffix_list ; whitespace-only tokens assigned via the setters are dropped the same way
Fix suffix-shaped parenthesized/quoted content (e.g. "(Ret)" , "(MBA)" ) being misclassified as a nickname instead of a suffix (closes #111 )
Fix single-character symbol conjunctions (e.g. "&" , "/" ) being ignored in short names ( #173 )
Fix recognition of single-letter roman numeral suffixes (e.g. "I" , "V" ) in suffix-comma format (closes #136 )
Fix recognition of trailing suffix_not_acronyms (e.g. "Jr." ) in lastname-comma format (closes #144 )
Fix missing comma between 'msc' and 'mscmsm' in suffix_acronyms , which silently concatenated them into a bogus 'mscmscmsm' entry ( #111 )
Fix 'apn aprn' split into separate suffix_acronyms entries so each is recognized independently (closes #155 )
Formatting and output fixes
Fix IndexError in initials() / initials_list() when a *_list attribute was assigned directly with an element containing unnormalized whitespace (e.g. name.middle_list = ['Q R'] ), bypassing the parser’s whitespace normalization (closes #232 )
Fix initials() emitting a stray empty initial (e.g. “J. . V.”) – or raising TypeError when empty_attribute_default is None – for name parts with no initialable words, e.g. a prefix-only middle name like "de la"
Fix capitalization of suffix acronyms written with dots, e.g. "M.D." (closes #141 )
Fix extra whitespace before punctuation in str() output when a string_format field is empty (closes #139 )
Fix spurious leading space in surnames and empty token in suffix list after capitalize() with an empty middle or suffix ( #164 )
API correctness and cleanup
Fix the five non-cached-union SetManager -backed Constants attributes ( first_name_titles , conjunctions , bound_first_names , non_first_name_prefixes , suffix_acronyms_ambiguous ) accepting non- SetManager assignment silently (e.g. constants.conjunctions = 'and' ), degrading membership checks into substring tests with no error; assignment now raises TypeError like the four cached-union attributes already did (closes #241 )
Fix HumanName.C accepting an invalid constants value on post-construction assignment (e.g. hn.C = 'garbage' ), bypassing the constructor’s validation and failing later with an unrelated AttributeError ; C is now a property that validates on assignment too (closes #239 )
Fix TupleManager (and RegexTupleManager ) accepting a bare string/bytes argument (raising a cryptic dict -internals ValueError ) or an iterable of 2-character strings (silently shredding each into a key/value pair, e.g. Constants(capitalization_exceptions=['ii']) becoming {'i': 'i'} ); both now raise TypeError with a clear message (closes #242 )
Fix SetManager.contains being the one operation that didn’t normalize (lowercase, strip leading/trailing periods) its operand, so e.g. 'Dr.' in constants.titles could return False even though the title was correctly configured; membership checks now normalize like add() / remove() /the constructor/the set operators (closes #244 )
Fix a bare string passed to a set-backed Constants argument (e.g. Constants(titles='dr') ), to SetManager , or as a SetManager set-operator operand (e.g. constants.titles |= 'esq' ) being silently split into single characters, replacing or polluting the set and producing wrong parses with no error; it now raises TypeError with the suggested fix — wrap strings in a list, decode bytes first (closes #238 )
Fix SetManager set operators and the constructor skipping the lowercase/strip-edge-periods normalization that add() applies: constants.titles |= ['Esq.'] kept a raw 'Esq.' the parser’s lookups could never match, titles & ['Dr.'] missed 'dr' , and Constants(titles=[...]) stored raw elements that silently never matched; elements and operands are now normalized everywhere, and non- str elements ( bytes , None , numbers) raise TypeError instead of crashing cryptically or being coerced
Fix the constants constructor argument silently discarding Constants subclass instances: the exact-type check replaced them with fresh defaults, throwing away the caller’s configuration. Subclass instances are now used as given; anything that is neither None nor a Constants instance now raises TypeError instead of being silently swapped for defaults (closes #226 )
Fix Constants customizations, singleton identity, and TupleManager subclass being lost across pickle / deepcopy round-trips ( #167 , #168 , #169 )
Fix is_rootname() returning stale results after add() / remove() on titles , prefixes , suffix_acronyms , or suffix_not_acronyms ( #166 )
Fix the library logger calling setLevel(logging.ERROR) on import, which silently discarded log records regardless of an application’s own logging configuration; the logger now leaves its level at NOTSET and lets the application control verbosity (closes #228 )
Minor internal cleanups: drop a dead length check in the initials helper, simplify double-wrapped len(list(...)) calls, and other small parser tidy-ups with no behavior change (closes #229 )
Change Constants.repr to report collection sizes and non-default scalar config, replacing the uninformative <Constants() instance> ( #221 )
Fix initials() interpolating the literal None for empty name parts when empty_attribute_default = None (e.g. "J. None D." ); empty parts now render as an empty string and a fully-empty result returns empty_attribute_default
Add python -m nameparser "Name String" command-line helper that prints a parsed name
Reorganize the test suite from a single tests.py into a tests/ pytest package
Drop Python 2 and Python < 3.10 support; Python 3.10–3.14 now required
Add type hints and type declarations (PEP 561 py.typed marker)
Migrate build tooling to pyproject.toml , drop setup.py
Remove dead Python 2 compatibility shims ( ENCODING constant, next() aliases)
Modernize CI: uv-based workflow, trusted publishing to PyPI, Dependabot
Fix case when we have two same prefixes in the name ( #147 )
Add support for attributes in constructor ( #140 )
Make HumanName instances hashable ( #138 )
Update repr for names with single quotes ( #137 )
Fix bug in is_suffix handling of lists ( #129 )
Add initials support ( #128 )
Add more titles and prefixes ( #120 , #127 , #128 , #119 )
Fix Python 3.8 syntax error ( #104 )
Fix suffix parsing bug in comma parts ( #98 )
Fix deprecation warning on Python 3.7 ( #94 )
Improved capitalization support of mixed case names ( #90 )
Remove “elder” from titles ( #96 )
Add post-nominal list from Wikipedia to suffixes ( #93 )
Better nickname handling of multiple single quotes ( #86 )
full_name attribute now returns formatted string output instead of original string ( #87 )
fix sys.stdin usage when stdin doesn’t exist ( #82 )
support for escaping log entry arguments ( #84 )
Fix handling of only nickname and last name ( #78 )
Fix overzealous regex for “Ph. D.” ( #43 )
Add surnames attribute as aggregate of middle and last names
Fix support for nicknames in single quotes ( #74 )
Change prefix handling to support prefixes on first names ( #60 )
Fix prefix capitalization when not part of lastname ( #70 )
Handle erroneous space in “Ph. D.” ( #43 )
Add “Junior” to suffixes ( #76 )
Add “dra” and “srta” to titles ( #77 )
Fix doc link ( #73 )
Fix handling of “do” and “dos” Portuguese prefixes ( #71 , #72 )
Fix python version check ( #64 )
Support J.D. as suffix and Wm. as title
Add Dr to suffixes ( #62 )
Add the full set of Italian derivatives from “di” ( #59 )
Add parameter to specify the encoding of strings added to constants, use ‘UTF-8’ as fallback ( #67 )
Fix handling of names composed entirely of conjunctions ( #66 )
Remove emojis from initial string by default with option to include emojis ( #58 )
Added names scrapped from VIAF data, thanks daryanypl ( #57 )
Fix error for names that end with conjunction ( #54 )
Refactor join_on_conjunctions(), fix #53
Remove “bishop” from titles because it also could be a first name
Fix handling of lastname prefixes with periods, e.g. “Jane St. John” ( #50 )
Remove “CONSTANTS.suffixes”, replaced by “suffix_acronyms” and “suffix_not_acronyms” ( #49 )
Add “du” to prefixes
Add “sheikh” variations to titles
Add parameter to force capitalization of mixed case strings
Clarify LGPL licence version ( #47 )
Skip pickle tests if pickle not installed ( #48 )
Fix string format when empty_attribute_default = None ( #45 )
Include tests in release source tarball ( #46 )
Add CONSTANTS.empty_attribute_default to customize value returned for empty attributes ( #44 )
Improve string format handling ( #41 )
Fix first name clash with suffixes ( #42 )
Fix encoding of constants added via the python shell
Add “MSC” to suffixes, fix #41
Fix bug capitalization exceptions ( #39 )
Fix encoding of byte strings on python 2.x ( #37 )
Separate suffixes that are acronyms to handle periods differently, fixes #29 , #21
Don’t find titles after first name is filled, fixes ( #27 )
Add “chair” titles ( #37 )
Use regex to check for roman numerals at end of name ( #36 )
Add DVM to suffixes
Speed improvement, 3x faster
Make HumanName instances pickleable
Fix strings that start with conjunctions ( #20 )
handle assigning lists of names to a name attribute
support dictionary-like assignment of name attributes
Fix handling of string encoding in python 2.x ( #34 )
Add support for dictionary key access, e.g. name[‘first’]
add ‘santa’ to prefixes, add ‘cpa’, ‘csm’, ‘phr’, ‘pmp’ to suffixes ( #35 )
Fix prefixes before multi-part last names ( #23 )
Fix capitalization bug ( #30 )
Fix #24 , handle first name also a prefix
Fix #26 , last name comma format when lastname is also a title
Allow suffixes to be chained ( #8 )
Handle trailing suffix in last name comma format ( #3 ). Removes support for titles with periods but no spaces in them, e.g. “Lt.Gen.”. ( #21 )
Retain original string in “original” attribute.
Collapse white space when using custom string format.
Fix #19 , single comma name format may have trailing suffix
Fix Pypi package, include new config module.
Refactor configuration to simplify modifications to constants (backwards incompatible)
use unicode_literals to simplify Python 2 & 3 support.
Generate documentation using sphinx and host on readthedocs.
If name is only a title and one part, assume it’s a last name instead of a first name, with exceptions for some titles like ‘Sir’. ( #7 ).
Add some judicial and other common titles. ( #9 )
Add a new nickname attribute containing anything in parenthesis or double quotes ( Issue 33 ).
Add support for Python 3.3+. Thanks to @corbinbs.
Fix bug with multiple conjunctions in title
add legal and crown titles
Fix python 2.6 import error on logging.NullHandler
Set logging handler to NullHandler
Remove ‘ben’ from PREFIXES because it’s more common as a name than a prefix.
Deprecate BlankHumanNameError. Do not raise exceptions if full_name is empty string.
Adjust logging, don’t set basicConfig. Fix Issue 10 and Issue 26 .
Fix handling of single lower case initials that are also conjunctions, e.g. “john e smith”. Re Issue 11 .
Fix handling of initials with no space separation, e.g. “E.T. Jones”. Fix #11 .
Do not remove period from first name, when present.
Remove ‘e’ from PREFIXES because it is handled as a conjunction.
Python 2.7+ required to run the tests. Mark known failures.
tests/test.py can now take an optional name argument that will return repr() for that name.
Fix initials() interpolating the literal None for empty name parts when empty_attribute_default = None (e.g. "J. None D."); empty parts now render as
initials() interpolating the literal None for empty name parts when empty_attribute_default = None (e.g. "J. None D."); empty parts now render as an empty string and a fully-empty result returns empty_attribute_defaultpython -m nameparser "Name String" command-line helper that prints a parsed nametests.py into a tests/ pytest packageFull Changelog: https://github.com/derek73/python-nameparser/compare/v1.2.0...v1.2.1
Drop Python 2 and Python < 3.10 support; Python 3.10–3.14 now required
py.typed marker)pyproject.toml, drop setup.pyENCODING constant, next() aliases)Fix case when we have two same prefixes in the name
Fix bug in is_suffix() handling of lists
is_suffix() handling of lists (#129)Nothing published for this version
Add more titles, suffixes and and prefixes (#120, #127, #128, #119, #116, #114, #117, #126, #102, #123)
Fix Python 3.8 syntax error warning
Fix deprecation warning on Python 3.7
Better nickname handling of multiple single quotes
fix sys.stdin usage when stdin doesn't exist
Nothing published for this version
Fix overzealous regex for "Ph. D."
surnames attribute as aggregate of middle and last namesRefactor prefix handling based on learnings from issues #72, #23, #70, and #60. New algorithm joins prefixes to the following pieces but stops at othe
Nothing published for this version
Fix handling of "do" and "dos" Portuguese prefixes (#71, #72)
Fix python version check
Fix python version check (#64)
Nothing published for this version
Add the full set of Italian derivatives from "di"
Remove emojis from initial string by default with option to include emojis
Added names scrapped from VIAF data, thanks daryanypl
Fix error for names that end with conjunction
Fix error for names that end with conjunction (#54)
Refactor join_on_conjunctions(), fix #53
Refactor join_on_conjunctions(), fix #53
Remove "bishop" from titles because it also could be a first name
Remove "CONSTANTS.suffixes", replaced by "suffix_acronyms" and "suffix_not_acronyms"
Skip pickle tests if pickle not installed
Fix string format when empty_attribute_default = None
empty_attribute_default = None (#45)Add CONSTANTS.empty_attribute_default to customize value returned for empty attributes
CONSTANTS.empty_attribute_default to customize value returned for empty attributes (#44)Improve customization documentation
Fix first name clash with suffixes
Fix #39, capitalization bug with initials that are also conjunctions ("e" and "y")
fix bytestring handling on python 2.x
Separate suffixes that are acronyms to handle periods differently, fixes #29, #21
Fixes for #36, better handling of roman numerals at the end of a name
Make HumanName instances pickleable
Fix strings that start with conjunctions
Fix handling of string encoding in python 2.x
Fix #24, handle first name also a prefix
Handle trailing suffix in last name comma format (#3). Removes support for titles with periods but no spaces in them, e.g. "Lt.Gen.".
Retain original string in "original" attribute.
One column per quarter.