nameparser 1.3.0__tar.gz → 1.3.1__tar.gz

{nameparser-1.3.0/nameparser.egg-info → nameparser-1.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nameparser
-Version: 1.3.0
+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
@@ -57,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
 ------------
@@ -116,11 +132,8 @@ 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:
 
 ::
 
@@ -139,10 +152,11 @@ and "post-nominal" would probably be better names.)
 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`_

{nameparser-1.3.0 → nameparser-1.3.1}/README.rst

@@ -29,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
 ------------
@@ -88,11 +104,8 @@ 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:
 
 ::
 
@@ -111,10 +124,11 @@ and "post-nominal" would probably be better names.)
 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`_

{nameparser-1.3.0 → nameparser-1.3.1}/nameparser/_version.py

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

{nameparser-1.3.0 → nameparser-1.3.1}/nameparser/config/regexes.py

@@ -6,6 +6,12 @@ re_emoji = re.compile('['  # lgtm[py/overly-large-range]
     '\U0001F680-\U0001F6FF'
     '\u2600-\u26FF\u2700-\u27BF]+')
 
+# Invisible bidirectional formatting characters: ALM, LRM, RLM, the
+# embedding/override marks (LRE/RLE/PDF/LRO/RLO) and the isolates
+# (LRI/RLI/FSI/PDI). Copy-pasted RTL names often carry these; they render
+# as nothing but stick to name parts and break equality/lookups.
+re_bidi = re.compile('[\u061C\u200E\u200F\u202A-\u202E\u2066-\u2069]+')
+
 EMPTY_REGEX = re.compile('')
 
 REGEXES = {
@@ -20,6 +26,7 @@ REGEXES = {
     "no_vowels": re.compile(r'^[^aeyiuo]+$', re.I),
     "period_not_at_end": re.compile(r'.*\..+$', re.I),
     "emoji": re_emoji,
+    "bidi": re_bidi,
     "phd": re.compile(r'\s(ph\.?\s+d\.?)', re.I),
     "space_before_comma": re.compile(r'\s+,'),
     "east_slavic_patronymic": re.compile(

{nameparser-1.3.0 → nameparser-1.3.1}/nameparser/parser.py

@@ -241,9 +241,14 @@ class HumanName:
     def __str__(self) -> str:
         if self.string_format is not None:
             # string_format = "{title} {first} {middle} {last} {suffix} ({nickname})"
-            _s = self.string_format.format(**self.as_dict())  # noqa: UP032
+            # Empty attributes must render as '' (not empty_attribute_default,
+            # which may be None) so str.format does not interpolate the
+            # literal "None" into the output, which cannot be scrubbed
+            # afterward without corrupting name text containing the same
+            # substring (#254).
+            _s = self.string_format.format(**{k: v or '' for k, v in self.as_dict().items()})
             # remove trailing punctuation from missing nicknames
-            _s = _s.replace(str(self.C.empty_attribute_default), '').replace(" ()", "").replace(" ''", "").replace(' ""', "")
+            _s = _s.replace(" ()", "").replace(" ''", "").replace(' ""', "")
             _s = self.C.regexes.space_before_comma.sub(',', _s)
             return self.collapse_whitespace(_s).strip(', ')
         return " ".join(self)
@@ -928,9 +933,11 @@ class HumanName:
         This method happens at the beginning of the :py:func:`parse_full_name`
         before any other processing of the string aside from unicode
         normalization, so it's a good place to do any custom handling in a
-        subclass. Runs :py:func:`parse_nicknames` and :py:func:`squash_emoji`.
+        subclass. Runs :py:func:`squash_bidi`, :py:func:`parse_nicknames` and
+        :py:func:`squash_emoji`.
 
         """
+        self.squash_bidi()
         self.fix_phd()
         self.parse_nicknames()
         self.squash_emoji()
@@ -1133,6 +1140,16 @@ class HumanName:
         if re_emoji and re_emoji.search(self._full_name):
             self._full_name = re_emoji.sub('', self._full_name)
 
+    def squash_bidi(self) -> None:
+        """
+        Remove invisible bidirectional control characters from the input
+        string. They carry no name content but stick to the parts they
+        surround, so parsed attributes stop comparing equal to the clean name.
+        """
+        re_bidi = self.C.regexes.bidi
+        if re_bidi and re_bidi.search(self._full_name):
+            self._full_name = re_bidi.sub('', self._full_name)
+
     def handle_firstnames(self) -> None:
         """
         If there are only two parts and one is a title, assume it's a last name

{nameparser-1.3.0 → nameparser-1.3.1/nameparser.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nameparser
-Version: 1.3.0
+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
@@ -57,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
 ------------
@@ -116,11 +132,8 @@ 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:
 
 ::
 
@@ -139,10 +152,11 @@ and "post-nominal" would probably be better names.)
 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`_

{nameparser-1.3.0 → nameparser-1.3.1}/pyproject.toml

@@ -42,6 +42,7 @@ dev = [
   "pytest (>=8)",
   "dill (>=0.2.5)",
   "sphinx (>=8)",
+  "furo",
   "mypy (>=2.1)",
   "ruff (>=0.15)",
   "pytest-timeout>=2.4.0",

{nameparser-1.3.0 → nameparser-1.3.1}/tests/test_output_format.py

@@ -99,6 +99,21 @@ class HumanNameOutputFormatTests(HumanNameTestBase):
         hn.nickname = ''
         self.assertEqual(str(hn), "Rev John A. Kenneth Doe III")
 
+    def test_name_containing_none_substring_with_none_empty_attribute_default(self) -> None:
+        # Regression for #254: with empty_attribute_default = None, __str__
+        # scrubbed the literal string 'None' from the formatted output,
+        # corrupting real name text containing that substring.
+        hn = HumanName("Nonez Smith", None)
+        hn.C.empty_attribute_default = None  # type: ignore[assignment]  # see test_constants.test_empty_attribute_default
+        self.assertEqual(str(hn), "Nonez Smith")
+
+    def test_name_none_as_literal_name_with_none_empty_attribute_default(self) -> None:
+        # Companion to the #254 regression: a name piece that is exactly
+        # 'None' must survive formatting in None-mode.
+        hn = HumanName("None Smith", None)
+        hn.C.empty_attribute_default = None  # type: ignore[assignment]  # see test_constants.test_empty_attribute_default
+        self.assertEqual(str(hn), "None Smith")
+
     def test_empty_field_drops_surrounding_whitespace(self) -> None:
         # issue #139: adjacent whitespace/punctuation should be dropped when a field is empty
         hn = HumanName("John Smith")
@@ -136,3 +151,27 @@ class HumanNameOutputFormatTests(HumanNameTestBase):
         self.m(hn.last, "Smith😊", hn)
         self.assertEqual(str(hn), "∫≜⩕ Smith😊")
         # test cleanup
+
+    def test_remove_bidi_control_chars(self) -> None:
+        # LRM/RLM and friends ride along with copy-pasted names and stick to
+        # the parts they surround. Covers every character in the bidi set.
+        for mark in ("\u200e", "\u200f", "\u061c", "\u202a", "\u202b",
+                     "\u202c", "\u202d", "\u202e", "\u2066", "\u2067",
+                     "\u2068", "\u2069"):
+            hn = HumanName(mark + "John" + mark + " Smith")
+            self.m(hn.first, "John", hn)
+            self.m(hn.last, "Smith", hn)
+
+    def test_bidi_stripped_name_compares_equal(self) -> None:
+        # The reported symptom: an invisible RLM around an RTL name makes the
+        # parsed part fail equality against the clean string (issue #266).
+        hn = HumanName("\u200fمحمد بن سلمان\u200f")
+        self.assertEqual(hn.first, "محمد")
+
+    def test_keep_bidi_control_chars(self) -> None:
+        from nameparser.config import Constants
+        constants = Constants()
+        constants.regexes.bidi = False  # type: ignore[assignment]
+        hn = HumanName("\u200fJohn\u200f Smith", constants)
+        self.m(hn.first, "\u200fJohn\u200f", hn)
+        self.m(hn.last, "Smith", hn)