Metadata-Version: 2.4
Name: nameparser
Version: 2.8.0
Summary: A simple Python module for parsing human names into their individual components.
Author-email: Derek Gulbranson <derek73@gmail.com>
License-Expression: LGPL-2.1-or-later
Keywords: names,parser
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Development Status :: 5 - Production/Stable
Classifier: Natural Language :: English
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.11
Description-Content-Type: text/x-rst
License-File: LICENSE
License-File: AUTHORS
Provides-Extra: ja
Requires-Dist: namedivider-python>=0.4; extra == "ja"
Dynamic: license-file

Name Parser
===========

|Build Status| |PyPI| |PyPI version| |Documentation| |License| |Downloads| |Codecov|

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 2.8 is out, the last 2.x feature release.**

⚠️ **HumanName is deprecated, and 3.0 removes it.** From 2.8 the 1.x
compatibility layer — ``HumanName``, ``Constants`` and the shared
``CONSTANTS`` — emits a ``DeprecationWarning`` where your code
constructs it, loads it from a pickle, or changes the shared
``CONSTANTS``. It keeps working through 2.x; ``parse()`` is the
replacement, and `Coming from 1.x`_ below says where to start. After
2.8 the 2.x line takes fixes only, and new work goes into 3.0.

2.8 also carries on 2.7's reading of titles that are also given names:
a title only inside a title phrase, so ``Queen Latifah`` keeps the
given name ``Queen`` while ``Her Majesty Queen Elizabeth`` reads the
title. The `release log
<https://nameparser.readthedocs.io/en/latest/release_log.html>`__ has
the details. Please `open an
issue <https://github.com/derek73/python-nameparser/issues>`__ 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
<https://nameparser.readthedocs.io/en/latest/usage.html#east-asian-names>`__.

Installation
------------

::

  pip install nameparser

Requires Python 3.11+.

Quick Start Example
--------------------

.. code-block:: python

    >>> 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()
    ('ja', 'ru', 'tr_az', 'zh')

Learn more
----------

* `Using the parser <https://nameparser.readthedocs.io/en/latest/usage.html>`__ — the full tour: input shapes, aggregates, rendering, comparison, ambiguities, tokens
* `Customizing the parser <https://nameparser.readthedocs.io/en/latest/customize.html>`__ — vocabulary, behavior, and presentation
* `Locale packs <https://nameparser.readthedocs.io/en/latest/locales.html>`__ — 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
----------------

``HumanName`` and ``CONSTANTS`` keep working through 2.x — same imports,
same attributes, same mutation API — and warn from 2.8 on, since 3.0
removes them. Run your tests under ``python -W error::DeprecationWarning``
to find the sites; a read of ``CONSTANTS`` does not warn. What 2.0 removes is the batch of
deprecations 1.3 and 1.4 announced, so if your test suite runs clean on
1.4 under ``python -W error::DeprecationWarning``, you are nearly done.
Two things that check will not catch: four removals 1.4 never warned
about (three raise on contact, the fourth only warns), and one that
changes results silently — ``name == "John Smith"`` is now ``False``.
Later 2.x releases add a few breaks of their own.
`Migrating from HumanName <https://nameparser.readthedocs.io/en/latest/migrate.html>`__
covers all of them, and translates a v1 customization into the new API whenever
that's convenient for you.

See the `release log <https://nameparser.readthedocs.io/en/latest/release_log.html>`__
for the full list of changes in the 2.0 series.

License
-------

LGPL licensed. See `LICENSE <https://github.com/derek73/python-nameparser/blob/master/LICENSE>`__
for details.

.. |Build Status| image:: https://github.com/derek73/python-nameparser/actions/workflows/python-package.yml/badge.svg
   :target: https://github.com/derek73/python-nameparser/actions/workflows/python-package.yml
.. |PyPI| image:: https://img.shields.io/pypi/v/nameparser.svg
   :target: https://pypi.org/project/nameparser/
.. |Documentation| image:: https://readthedocs.org/projects/nameparser/badge/?version=latest
   :target: http://nameparser.readthedocs.io/en/latest/?badge=latest
.. |PyPI version| image:: https://img.shields.io/pypi/pyversions/nameparser.svg
   :target: https://pypi.org/project/nameparser/
.. |License| image:: https://img.shields.io/pypi/l/nameparser.svg
   :target: https://pypi.org/project/nameparser/
.. |Downloads| image:: https://static.pepy.tech/badge/nameparser
   :target: https://pepy.tech/project/nameparser
.. |Codecov| image:: https://codecov.io/gh/derek73/python-nameparser/branch/master/graph/badge.svg
   :target: https://codecov.io/gh/derek73/python-nameparser
