nameparser 1.3.1__tar.gz → 2.0.0__tar.gz

nameparser-2.0.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: nameparser
+Version: 2.0.0
+Summary: A simple Python module for parsing human names into their individual components.
+Author-email: Derek Gulbranson <derek73@gmail.com>
+License: LGPL
+Keywords: names,parser
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU Library or Lesser General Public License (LGPL)
+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: 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
+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.0 is out.** Existing ``HumanName`` code keeps working
+through 2.x — most 1.x code needs no changes. The `migration guide
+<https://nameparser.readthedocs.io/en/latest/migrate.html>`__ has the
+field-by-field map, and anything the migration missed can be reported
+on `the discussion issue
+<https://github.com/derek73/python-nameparser/issues/284>`__.
+
+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")
+    >>> name.given, name.family
+    ('Juan', 'de la Vega')
+    >>> name.render("{family}, {given}")
+    'de la Vega, Juan'
+
+Those seven fields are ``title``, ``given``, ``middle``, ``family``,
+``suffix``, ``nickname``, and ``maiden`` — plus aggregate views like
+``given_names``, ``surnames``, ``family_base``, and ``family_particles``
+for combining or splitting them further.
+
+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 in 2.0 — same imports, same
+attributes, same mutation API. 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``.
+`Migrating from HumanName <https://nameparser.readthedocs.io/en/latest/migrate.html>`__
+covers both, 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

nameparser-2.0.0/README.rst

@@ -0,0 +1,87 @@
+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.0 is out.** Existing ``HumanName`` code keeps working
+through 2.x — most 1.x code needs no changes. The `migration guide
+<https://nameparser.readthedocs.io/en/latest/migrate.html>`__ has the
+field-by-field map, and anything the migration missed can be reported
+on `the discussion issue
+<https://github.com/derek73/python-nameparser/issues/284>`__.
+
+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")
+    >>> name.given, name.family
+    ('Juan', 'de la Vega')
+    >>> name.render("{family}, {given}")
+    'de la Vega, Juan'
+
+Those seven fields are ``title``, ``given``, ``middle``, ``family``,
+``suffix``, ``nickname``, and ``maiden`` — plus aggregate views like
+``given_names``, ``surnames``, ``family_base``, and ``family_particles``
+for combining or splitting them further.
+
+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 in 2.0 — same imports, same
+attributes, same mutation API. 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``.
+`Migrating from HumanName <https://nameparser.readthedocs.io/en/latest/migrate.html>`__
+covers both, 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

nameparser-2.0.0/nameparser/__init__.py

@@ -0,0 +1,42 @@
+from nameparser._version import VERSION as VERSION
+from nameparser._version import __version__ as __version__
+from nameparser.parser import HumanName as HumanName
+__author__ = "Derek Gulbranson"
+__author_email__ = 'derek73@gmail.com'
+__license__ = "LGPL"
+__url__ = "https://github.com/derek73/python-nameparser"
+
+from nameparser._lexicon import Lexicon
+from nameparser._locale import Locale
+from nameparser._parser import Parser, parse, parser_for
+from nameparser._policy import (
+    DEFAULT_NICKNAME_DELIMITERS,
+    FAMILY_FIRST,
+    FAMILY_FIRST_GIVEN_LAST,
+    GIVEN_FIRST,
+    UNSET,
+    PatronymicRule,
+    Policy,
+    PolicyPatch,
+)
+from nameparser._types import (
+    STABLE_TAGS,
+    Ambiguity,
+    AmbiguityKind,
+    ParsedName,
+    Role,
+    Span,
+    Token,
+)
+
+__all__ = [
+    # v1 (compatibility layer)
+    "HumanName",
+    # v2 core
+    "Span", "Role", "Token", "Ambiguity", "AmbiguityKind", "ParsedName",
+    "STABLE_TAGS",
+    "Lexicon", "Policy", "PolicyPatch", "PatronymicRule", "UNSET",
+    "GIVEN_FIRST", "FAMILY_FIRST", "FAMILY_FIRST_GIVEN_LAST",
+    "DEFAULT_NICKNAME_DELIMITERS", "Locale",
+    "Parser", "parse", "parser_for",
+]

nameparser-2.0.0/nameparser/__main__.py

@@ -0,0 +1,48 @@
+"""Command-line debug helper over the 2.0 API (migration spec §6).
+
+    python -m nameparser "Dr. Juan Q. Xavier de la Vega III"
+    python -m nameparser --json "Doe, John"
+"""
+import argparse
+import json
+
+from nameparser import parse
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(
+        prog="nameparser", description="Parse a personal name.")
+    ap.add_argument("name", help="the name string to parse")
+    ap.add_argument("--json", action="store_true",
+                    help="print the component dict as JSON")
+    ap.add_argument("--locale", metavar="CODE",
+                    help="parse with a locale pack (e.g. 'ru'); see "
+                         "nameparser.locales")
+    args = ap.parse_args(argv)
+    # `is not None`, not truthiness: --locale "" must reach get() and
+    # exit 2 listing the codes, not silently fall back to the default
+    if args.locale is not None:
+        from nameparser import locales, parser_for
+        try:
+            parser = parser_for(locales.get(args.locale))
+        except KeyError as exc:
+            ap.error(exc.args[0])  # exits 2, message to stderr
+        n = parser.parse(args.name)
+    else:
+        n = parse(args.name)
+    if args.json:
+        print(json.dumps(n.as_dict(), ensure_ascii=False))
+        return 0
+    # Label each section: the two reprs are byte-identical for input
+    # that is already correctly cased, so without labels there is no
+    # telling which is the parse and which is the capitalized view.
+    print("Parsed:")
+    print(repr(n))
+    print("Capitalized:")
+    print(repr(n.capitalized()))
+    print("Initials:", n.initials())
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())