PyPI - nameparser - Versions diffs - 1.2.1__tar.gz → 1.3.1__tar.gz - Mend

nameparser 1.2.1tar.gz → 1.3.1tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (60) hide show

{nameparser-1.2.1/nameparser.egg-info → nameparser-1.3.1}/PKG-INFO RENAMED Viewed

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nameparser
-Version: 1.2.1
+Version: 1.3.1
 Summary: A simple Python module for parsing human names into their individual components.
 Author-email: Derek Gulbranson <derek73@gmail.com>
 License: LGPL
@@ -29,7 +29,7 @@ Dynamic: license-file
 Name Parser
 ===========
-|Build Status| |PyPI| |PyPI version| |Documentation|
+|Build Status| |PyPI| |PyPI version| |Documentation| |License| |Downloads| |Codecov|
 A simple Python (3.10+) module for parsing human names into their
 individual components.
@@ -40,8 +40,12 @@ individual components.
 * hn.last
 * hn.suffix
 * hn.nickname
+* hn.maiden
 * hn.surnames *(middle + last)*
+* hn.given_names *(first + middle)*
 * hn.initials *(first initial of each name part)*
+* hn.last_base *(last, minus any prefixes)*
+* hn.last_prefixes *(leading last-name particles, e.g. "van der")*
 Supported Name Structures
 ~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -53,19 +57,35 @@ are optional. Comma-separated format like "Last, First" is also supported.
 2. Lastname [Suffix], Title Firstname (Nickname) Middle Middle[,] Suffix [, Suffix]
 3. Title Firstname M Lastname [Suffix], Suffix [Suffix] [, Suffix]
-Instantiating the `HumanName` class with a string splits on commas and then spaces,
-classifying name parts based on placement in the string and matches against known name
-pieces like titles and suffixes.
-It correctly handles some common conjunctions and special prefixes to last names
-like "del". Titles and conjunctions can be chained together to handle complex
-titles like "Asst Secretary of State". It can also try to correct capitalization
-of names that are all upper- or lowercase names.
-It attempts the best guess that can be made with a simple, rule-based approach.
-Its main use case is English and it is not likely to be useful for languages
-that do not conform to the supported name structure. It's not perfect, but it
-gets you pretty far.
+How It Works
+~~~~~~~~~~~~
+The parser works in two layers.
+A **vocabulary layer** recognizes name pieces by what they are, using
+configurable sets of known words: titles ("Dr."), suffixes ("III", "PhD"),
+last-name prefixes ("de la"), conjunctions ("y", "&"), and delimited
+nicknames ("Doc"). Titles and conjunctions chain together to handle complex
+titles like "Asst Secretary of State"; prefixes join forward so "de la Vega"
+stays one last name. This layer doesn't care where in the string a word
+appears — and it's the layer you customize, by adding or removing entries
+in the sets to fit your dataset.
+A **positional layer** then assigns everything the vocabulary layer didn't
+claim, based purely on where it sits: the first unclaimed word is the first
+name, the last one is the last name, and anything between them is a middle
+name. There is no semantic understanding — "Dr" is a title when it comes
+before a name and a suffix when it comes after ("pre-nominal" and
+"post-nominal" would probably be better names) — and no attempt to correct
+mistakes in the input.
+It attempts the best guess that can be made with a simple, deterministic,
+rule-based approach — no statistical models or machine learning; the same
+input always parses the same way. The positional layer assumes Western name
+order (given name first), so the main use case is English and other
+languages that share that structure. It can also try to correct the
+capitalization of names that are all upper- or lowercase. It's not perfect,
+but it gets you pretty far.
 Installation
 ------------
@@ -93,17 +113,18 @@ Quick Start Example
     >>> name = HumanName("Dr. Juan Q. Xavier de la Vega III (Doc Vega)")
     >>> name
     <HumanName : [
-    	title: 'Dr.'
-    	first: 'Juan'
-    	middle: 'Q. Xavier'
-    	last: 'de la Vega'
-    	suffix: 'III'
-    	nickname: 'Doc Vega'
+        title: 'Dr.'
+        first: 'Juan'
+        middle: 'Q. Xavier'
+        last: 'de la Vega'
+        suffix: 'III'
+        nickname: 'Doc Vega'
+        maiden: ''
     ]>
     >>> name.last
     'de la Vega'
     >>> name.as_dict()
-    {'last': 'de la Vega', 'suffix': 'III', 'title': 'Dr.', 'middle': 'Q. Xavier', 'nickname': 'Doc Vega', 'first': 'Juan'}
+    {'title': 'Dr.', 'first': 'Juan', 'middle': 'Q. Xavier', 'last': 'de la Vega', 'suffix': 'III', 'nickname': 'Doc Vega', 'maiden': ''}
     >>> str(name)
     'Dr. Juan Q. Xavier de la Vega III (Doc Vega)'
     >>> name.string_format = "{first} {last}"
@@ -111,32 +132,31 @@ Quick Start Example
     'Juan de la Vega'
-The parser does not attempt to correct mistakes in the input. It mostly just splits on white
-space and puts things in buckets based on their position in the string. This also means
-the difference between 'title' and 'suffix' is positional, not semantic. "Dr" is a title
-when it comes before the name and a suffix when it comes after. ("Pre-nominal"
-and "post-nominal" would probably be better names.)
+Because the positional layer has no semantic understanding, position is
+everything:
 ::
     >>> name = HumanName("1 & 2, 3 4 5, Mr.")
     >>> name
     <HumanName : [
-    	title: ''
-    	first: '3'
-    	middle: '4 5'
-    	last: '1 & 2'
-    	suffix: 'Mr.'
-    	nickname: ''
+        title: ''
+        first: '3'
+        middle: '4 5'
+        last: '1 & 2'
+        suffix: 'Mr.'
+        nickname: ''
+        maiden: ''
     ]>
 Customization
 -------------
-Your project may need some adjustment for your dataset. You can
-do this in your own pre- or post-processing, by `customizing the configured pre-defined
-sets`_ of titles, prefixes, etc., or by subclassing the `HumanName` class. See the
-`full documentation`_ for more information.
+Your project may need some adjustment for your dataset. Most customization
+is vocabulary — `customizing the configured pre-defined sets`_ of titles,
+prefixes, etc. that the vocabulary layer matches against. You can also do
+your own pre- or post-processing, or subclass the `HumanName` class for
+deeper changes. See the `full documentation`_ for more information.
 `Full documentation`_
@@ -172,3 +192,9 @@ https://github.com/derek73/python-nameparser
    :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-1.2.1 → nameparser-1.3.1}/README.rst RENAMED Viewed

@@ -1,7 +1,7 @@
 Name Parser
 ===========
-|Build Status| |PyPI| |PyPI version| |Documentation|
+|Build Status| |PyPI| |PyPI version| |Documentation| |License| |Downloads| |Codecov|
 A simple Python (3.10+) module for parsing human names into their
 individual components.
@@ -12,8 +12,12 @@ individual components.
 * hn.last
 * hn.suffix
 * hn.nickname
+* hn.maiden
 * hn.surnames *(middle + last)*
+* hn.given_names *(first + middle)*
 * hn.initials *(first initial of each name part)*
+* hn.last_base *(last, minus any prefixes)*
+* hn.last_prefixes *(leading last-name particles, e.g. "van der")*
 Supported Name Structures
 ~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -25,19 +29,35 @@ are optional. Comma-separated format like "Last, First" is also supported.
 2. Lastname [Suffix], Title Firstname (Nickname) Middle Middle[,] Suffix [, Suffix]
 3. Title Firstname M Lastname [Suffix], Suffix [Suffix] [, Suffix]
-Instantiating the `HumanName` class with a string splits on commas and then spaces,
-classifying name parts based on placement in the string and matches against known name
-pieces like titles and suffixes.
-It correctly handles some common conjunctions and special prefixes to last names
-like "del". Titles and conjunctions can be chained together to handle complex
-titles like "Asst Secretary of State". It can also try to correct capitalization
-of names that are all upper- or lowercase names.
-It attempts the best guess that can be made with a simple, rule-based approach.
-Its main use case is English and it is not likely to be useful for languages
-that do not conform to the supported name structure. It's not perfect, but it
-gets you pretty far.
+How It Works
+~~~~~~~~~~~~
+The parser works in two layers.
+A **vocabulary layer** recognizes name pieces by what they are, using
+configurable sets of known words: titles ("Dr."), suffixes ("III", "PhD"),
+last-name prefixes ("de la"), conjunctions ("y", "&"), and delimited
+nicknames ("Doc"). Titles and conjunctions chain together to handle complex
+titles like "Asst Secretary of State"; prefixes join forward so "de la Vega"
+stays one last name. This layer doesn't care where in the string a word
+appears — and it's the layer you customize, by adding or removing entries
+in the sets to fit your dataset.
+A **positional layer** then assigns everything the vocabulary layer didn't
+claim, based purely on where it sits: the first unclaimed word is the first
+name, the last one is the last name, and anything between them is a middle
+name. There is no semantic understanding — "Dr" is a title when it comes
+before a name and a suffix when it comes after ("pre-nominal" and
+"post-nominal" would probably be better names) — and no attempt to correct
+mistakes in the input.
+It attempts the best guess that can be made with a simple, deterministic,
+rule-based approach — no statistical models or machine learning; the same
+input always parses the same way. The positional layer assumes Western name
+order (given name first), so the main use case is English and other
+languages that share that structure. It can also try to correct the
+capitalization of names that are all upper- or lowercase. It's not perfect,
+but it gets you pretty far.
 Installation
 ------------
@@ -65,17 +85,18 @@ Quick Start Example
     >>> name = HumanName("Dr. Juan Q. Xavier de la Vega III (Doc Vega)")
     >>> name
     <HumanName : [
-    	title: 'Dr.'
-    	first: 'Juan'
-    	middle: 'Q. Xavier'
-    	last: 'de la Vega'
-    	suffix: 'III'
-    	nickname: 'Doc Vega'
+        title: 'Dr.'
+        first: 'Juan'
+        middle: 'Q. Xavier'
+        last: 'de la Vega'
+        suffix: 'III'
+        nickname: 'Doc Vega'
+        maiden: ''
     ]>
     >>> name.last
     'de la Vega'
     >>> name.as_dict()
-    {'last': 'de la Vega', 'suffix': 'III', 'title': 'Dr.', 'middle': 'Q. Xavier', 'nickname': 'Doc Vega', 'first': 'Juan'}
+    {'title': 'Dr.', 'first': 'Juan', 'middle': 'Q. Xavier', 'last': 'de la Vega', 'suffix': 'III', 'nickname': 'Doc Vega', 'maiden': ''}
     >>> str(name)
     'Dr. Juan Q. Xavier de la Vega III (Doc Vega)'
     >>> name.string_format = "{first} {last}"
@@ -83,32 +104,31 @@ Quick Start Example
     'Juan de la Vega'
-The parser does not attempt to correct mistakes in the input. It mostly just splits on white
-space and puts things in buckets based on their position in the string. This also means
-the difference between 'title' and 'suffix' is positional, not semantic. "Dr" is a title
-when it comes before the name and a suffix when it comes after. ("Pre-nominal"
-and "post-nominal" would probably be better names.)
+Because the positional layer has no semantic understanding, position is
+everything:
 ::
     >>> name = HumanName("1 & 2, 3 4 5, Mr.")
     >>> name
     <HumanName : [
-    	title: ''
-    	first: '3'
-    	middle: '4 5'
-    	last: '1 & 2'
-    	suffix: 'Mr.'
-    	nickname: ''
+        title: ''
+        first: '3'
+        middle: '4 5'
+        last: '1 & 2'
+        suffix: 'Mr.'
+        nickname: ''
+        maiden: ''
     ]>
 Customization
 -------------
-Your project may need some adjustment for your dataset. You can
-do this in your own pre- or post-processing, by `customizing the configured pre-defined
-sets`_ of titles, prefixes, etc., or by subclassing the `HumanName` class. See the
-`full documentation`_ for more information.
+Your project may need some adjustment for your dataset. Most customization
+is vocabulary — `customizing the configured pre-defined sets`_ of titles,
+prefixes, etc. that the vocabulary layer matches against. You can also do
+your own pre- or post-processing, or subclass the `HumanName` class for
+deeper changes. See the `full documentation`_ for more information.
 `Full documentation`_
@@ -144,3 +164,9 @@ https://github.com/derek73/python-nameparser
    :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-1.2.1 → nameparser-1.3.1}/nameparser/_version.py RENAMED Viewed

@@ -1,2 +1,2 @@
-VERSION = (1, 2, 1)
+VERSION = (1, 3, 1)
 __version__ = '.'.join(map(str, VERSION))

nameparser 1.2.1__tar.gz → 1.3.1__tar.gz

nameparser 1.2.1tar.gz → 1.3.1tar.gz