Name Parser

nameparser parses human names into seven fields — title, given, middle, family, suffix, nickname, maiden. Results are immutable, configuration is composable, and locale packs are opt-in.

📣 nameparser 3.0 removes HumanName and the rest of the 1.x compatibility layer. HumanName, Constants, the shared CONSTANTS and nameparser.util are gone, along with the 1.x names of the word lists; parse() and Parser are the replacement. 2.8 is the last release that has them, and it warns at each use 3.0 removes; Coming from 1.x or 2.x below says where to start. 3.0 also configures a Lexicon by reading (Lexicon.default().add("leed", kind="credential")), renders a name in the order it was written (str(parse("김민준")) is '김민준'), and adds packs that choose the languages a parse reads. The release log has the details. Please open an issue for anything that parses wrong.

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. See East Asian names.

Installation

pip install nameparser

Requires Python 3.11+.

Quick Start Example

>>> from nameparser import parse
>>> name = parse("Dr. Juan Q. Xavier de la Vega III (Doc Vega)")
>>> name
<ParsedName: [
    title: 'Dr.'
    given: 'Juan'
    middle: 'Q. Xavier'
    family: 'de la Vega'
    suffix: 'III'
    nickname: 'Doc Vega'
]>
>>> name.family_base, name.family_particles
('Vega', 'de la')
>>> name.given_names, name.surnames
('Juan Q. Xavier', 'Q. Xavier de la Vega')
>>> name.render("{family}, {given}")
'de la Vega, Juan'

>>> parse("Jack MA").suffix                    # capitals mark a credential
'MA'
>>> parse("Jack Ma").family                    # and a surname
'Ma'
>>> parse("Jane Smith, PhD MA").suffix
'PhD MA'

>>> parse("김민준").family                     # Korean: unspaced, split on the census list
'김'
>>> parse("高橋 みなみ").family                 # Japanese: kanji with kana, family first
'高橋'
>>> parse("김민준씨").suffix                   # an honorific written against the name
'씨'
>>> parse("г-н Иван Петров").title             # Cyrillic title
'г-н'
>>> parse("محمد بن سلمان").family              # Arabic: بن chains onto the family name
'بن سلمان'

>>> from nameparser import locales, parser_for
>>> chinese = parser_for(locales.ZH)           # Han text does not say which language
>>> chinese.parse("毛泽东").family              # so splitting it is opt-in
'毛'
>>> russian = parser_for(locales.RU)
>>> russian.parse("Сидоров Иван Петрович").family
'Сидоров'
>>> locales.available()
('bn', 'cs', 'es', 'es_ar', 'ga', 'gd', 'hi', 'hr', 'ja', 'ne', 'pt', 'pt_br', 'ru', 'sk', 'sl', 'tr_az', 'zh')

Learn more

• Using the parser — the full tour: input shapes, aggregates, rendering, comparison, ambiguities, tokens
• Customizing the parser — vocabulary, behavior, and presentation
• Locale packs — opt-in bundles for East Slavic patronymics, Turkic markers, and more
• There's also a CLI: python -m nameparser --json "Doe, John"

Coming from 1.x or 2.x

3.0 has no HumanName: parse(text) reads the same seven fields, named given and family where HumanName had first and last, and a Lexicon and Policy handed to a Parser replace Constants. Upgrade to 2.8.2 first and run your tests under python -W error::DeprecationWarning: it stops at every use 3.0 removes except a read of the shared CONSTANTS or of a Lexicon set field and the imports Migrating to 3.0 lists, which 2.8.2 does not warn on, so search for those too. A pickled HumanName or Constants does not load in 3.0; store parse(text).as_dict() or the original string instead. Migrating to 3.0 maps HumanName's attributes and the Constants settings onto the 3.0 API.

License

LGPL licensed. See LICENSE for details.