Merge pull request #198 from derek73/feat/turkic-patronymics

Add Turkic patronymic detection to patronymic_name_order

Author: derek73

docs/customize.rst

@@ -87,7 +87,7 @@ Other editable attributes
 * :py:obj:`~nameparser.config.Constants.force_mixed_case_capitalization` - If set, forces the capitalization of mixed case strings when :py:meth:`~nameparser.parser.HumanName.capitalize` is called.
 * :py:obj:`~nameparser.config.Constants.suffix_delimiter` - additional delimiter used to split suffix groups after comma-splitting, e.g. ``" - "`` for names like ``"Jane Smith, RN - CRNA"``. Defaults to ``None`` (disabled).
 * :py:obj:`~nameparser.config.Constants.initials_separator` - string placed between consecutive initials within the same name group (after the delimiter). Defaults to ``" "``, so ``"A. K."``; set to ``""`` for compact ``"A.K."``.
-* :py:obj:`~nameparser.config.Constants.patronymic_name_order` - If set, detects Russian formal-order names (``Surname GivenName Patronymic``) via a trailing East-Slavic patronymic suffix and rotates the parts to Western order (``first=GivenName``, ``middle=Patronymic``, ``last=Surname``). Opt-in; see subsection below.
+* :py:obj:`~nameparser.config.Constants.patronymic_name_order` - If set, detects Russian formal-order names (``Surname GivenName Patronymic``) via a trailing East-Slavic patronymic suffix and rotates the parts to Western order (``first=GivenName``, ``middle=Patronymic``, ``last=Surname``). Also detects reversed-order Azerbaijani/Central-Asian Turkic patronymics (``Surname GivenName PatronymicRoot Marker``, e.g. ``oglu``/``qizi``). Opt-in; see subsections below.
 * :py:obj:`~nameparser.config.Constants.middle_name_as_last` - If set, folds middle names into the last name (``.last`` becomes what ``.surnames`` already was, ``.middle`` becomes empty). Opt-in; see subsection below.
 
 
@@ -118,6 +118,41 @@ patronymic-form surnames such as ``"David Michael Abramovich"``. Enable this
 flag only when your data is predominantly Russian formal-order names.
 
 
+Turkic Patronymics
+~~~~~~~~~~~~~~~~~~
+
+Azerbaijani and Central-Asian formal names follow a different shape: a
+4-word ``[Given] [Father's given name] [Marker] [Family]``, where the
+marker is a standalone word (``oglu``/``oğlu`` "son of",
+``qizi``/``qızı`` "daughter of", and further variants — see below), not a
+bound suffix. The same ``patronymic_name_order`` flag also detects and
+rotates the reversed, no-comma form of this shape::
+
+    >>> from nameparser import HumanName
+    >>> from nameparser.config import Constants
+    >>> C = Constants(patronymic_name_order=True)
+    >>> hn = HumanName("Aliyev Vusal Said oglu", constants=C)
+    >>> hn.first, hn.middle, hn.last
+    ('Vusal', 'Said oglu', 'Aliyev')
+
+Natural order (``"Vusal Said oglu Aliyev"``) and comma order
+(``"Aliyev, Vusal Said oglu"``) already parse correctly without this flag
+and are left unchanged.
+
+Detection is scoped strictly to the 4-token shape (single-token first/last,
+exactly two middle tokens, last token a recognised marker) — matching the
+East-Slavic guard's token-count strictness above. Unlike that guard, there's
+no additional check on the given-name token, since Turkic markers are a
+small, closed set unlikely to coincide with an ordinary given name (whereas
+East-Slavic patronymic suffixes can coincide with real Western surnames).
+Recognised markers cover common transliterations and native orthographies:
+Latin ``oglu``, ``oğlu``, ``ogly``, ``ogli``, ``o'g'li`` (and its Uzbek
+modifier-apostrophe and right-single-quote variants), ``qizi``, ``qızı``,
+``kizi``, ``kyzy``, ``gyzy``, ``uly``, ``uulu``; and Cyrillic ``оглу``,
+``оглы``, ``оғлу``, ``ўғли``, ``угли``, ``кызы``, ``гызы``, ``қызы``,
+``қизи``, ``улы``, ``ұлы``, ``уулу``. Matching is case-insensitive.
+
+
 Suppressing Middle Names
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/release_log.rst

@@ -23,6 +23,7 @@ Release Log
     - Fix ``'apn aprn'`` split into separate ``suffix_acronyms`` entries so each is recognized independently (closes #155)
     - Add ``last_base``, ``last_prefixes`` (and ``_list`` variants) plus ``family`` / ``family_prefixes`` aliases for splitting last-name prefix particles (tussenvoegsels) from the core surname (#130, #132)
     - Add ``patronymic_name_order`` flag to ``Constants`` and ``HumanName`` for opt-in detection and reordering of Russian formal-order names (Surname GivenName Patronymic) (#85)
+    - Add Turkic (Azerbaijani/Central-Asian) patronymic detection to ``patronymic_name_order``, rotating the reversed 4-token formal shape (``Surname GivenName PatronymicRoot Marker``, e.g. ``oglu``/``qizi``) into Western order (#185)
     - Add ``first_name_prefixes`` set to ``Constants``; bound Arabic given-name
       prefixes (``abdul``, ``abu``, etc.) now join forward to form a single first
       name (e.g. ``"abdul salam ahmed salem"`` → ``first="abdul salam"``,

nameparser/config/__init__.py

@@ -370,6 +370,12 @@ class Constants:
     token in each of first, middle, and last; names with multi-part given names or
     multiple middle names are left unchanged.
 
+    Also detects reversed-order Azerbaijani/Central-Asian Turkic patronymics
+    (``Surname GivenName PatronymicRoot Marker``, e.g. ``oglu``/``qizi``), a
+    structurally different, standalone-marker-word patronymic family. Detection
+    requires exactly one token in each of first and last, exactly two tokens in
+    middle, and the last token a recognised Turkic marker.
+
     Opt-in because a Western person whose surname happens to end in a patronymic
     suffix (e.g. ``"David Michael Abramovich"``) will be reordered incorrectly
     when the flag is on. Enable only when your data is predominantly Russian
@@ -386,6 +392,9 @@ class Constants:
         >>> hn = HumanName("Ivanov Ivan Ivanovich", constants=C)
         >>> hn.first, hn.middle, hn.last
         ('Ivan', 'Ivanovich', 'Ivanov')
+        >>> hn2 = HumanName("Aliyev Vusal Said oglu", constants=C)
+        >>> hn2.first, hn2.middle, hn2.last
+        ('Vusal', 'Said oglu', 'Aliyev')
 
     """
 

nameparser/config/regexes.py

@@ -22,12 +22,22 @@
     ("emoji",re_emoji),
     ("phd", re.compile(r'\s(ph\.?\s+d\.?)', re.I)),
     ("space_before_comma", re.compile(r'\s+,')),
-    ("patronymic", re.compile(
+    ("east_slavic_patronymic", re.compile(
         r'(ovich|ovna|evich|evna|ichna|ilyich|kuzmich|lukich|fomich|fokich)$',
         re.I,
     )),
-    ("patronymic_cyrillic", re.compile(
+    ("east_slavic_patronymic_cyrillic", re.compile(
         r'(ович|овна|евич|евна|ична|ильич|кузьмич|лукич|фомич|фокич)$',
+        re.I,
+    )),
+    ("turkic_patronymic_marker", re.compile(
+        r"^(oglu|oğlu|ogly|ogli|o['’ʻ]g['’ʻ]li"
+        r"|qizi|qızı|kizi|kyzy|gyzy|uly|uulu)$",
+        re.I,
+    )),
+    ("turkic_patronymic_marker_cyrillic", re.compile(
+        r'^(оглу|оглы|оғлу|ўғли|угли|кызы|гызы|қызы|қизи|улы|ұлы|уулу)$',
+        re.I,
     )),
     ("period_abbreviation", re.compile(r'^[^\W\d_]{2,}\.$')),
 ])

nameparser/parser.py

@@ -692,7 +692,7 @@ def is_an_initial(self, value: str) -> bool:
         """
         return bool(self.C.regexes.initial.match(value))
 
-    def is_patronymic(self, piece: str) -> bool:
+    def is_east_slavic_patronymic(self, piece: str) -> bool:
         """
         Return True if ``piece`` ends with a recognised East-Slavic patronymic
         suffix, checked against both Latin-script and Cyrillic patterns in
@@ -702,8 +702,21 @@ def is_patronymic(self, piece: str) -> bool:
         by a separate pattern.
         """
         return bool(
-            self.C.regexes.patronymic.search(piece)
-            or self.C.regexes.patronymic_cyrillic.search(piece)
+            self.C.regexes.east_slavic_patronymic.search(piece)
+            or self.C.regexes.east_slavic_patronymic_cyrillic.search(piece)
+        )
+
+    def is_turkic_patronymic_marker(self, piece: str) -> bool:
+        """
+        Return True if ``piece`` is exactly a recognised Turkic patronymic
+        marker word (e.g. ``oglu``, ``qizi``, ``uly``), checked against both
+        Latin-script and Cyrillic patterns in ``self.C.regexes``. Unlike
+        East-Slavic patronymics, these are standalone marker words, not
+        suffixes, so the match is whole-word rather than a suffix search.
+        """
+        return bool(
+            self.C.regexes.turkic_patronymic_marker.match(piece)
+            or self.C.regexes.turkic_patronymic_marker_cyrillic.match(piece)
         )
 
     # full_name parser
@@ -744,7 +757,7 @@ def pre_process(self) -> None:
         self.parse_nicknames()
         self.squash_emoji()
 
-    def handle_patronymic_name_order(self) -> None:
+    def handle_east_slavic_patronymic_name_order(self) -> None:
         """
         When patronymic_name_order is enabled, detect Russian formal order
         (Surname GivenName Patronymic) and rotate to Western order.
@@ -758,15 +771,36 @@ def handle_patronymic_name_order(self) -> None:
             and len(self.first_list) == 1
             and len(self.middle_list) == 1
             and len(self.last_list) == 1
-            and self.is_patronymic(self.last_list[0])
-            and not self.is_patronymic(self.middle_list[0])
+            and self.is_east_slavic_patronymic(self.last_list[0])
+            and not self.is_east_slavic_patronymic(self.middle_list[0])
         ):
             self.first_list, self.middle_list, self.last_list = (
                 self.middle_list,
                 self.last_list,
                 self.first_list,
             )
 
+    def handle_turkic_patronymic_name_order(self) -> None:
+        """
+        When patronymic_name_order is enabled, detect the reversed Turkic
+        formal order (Surname GivenName PatronymicRoot Marker) and rotate to
+        Western order. Fires only for the strict 4-token, no-comma shape:
+        single-token first/last and exactly two middle tokens, where the last
+        token is a recognised Turkic patronymic marker.
+        """
+        if (
+            not self._had_comma
+            and len(self.first_list) == 1
+            and len(self.middle_list) == 2
+            and len(self.last_list) == 1
+            and self.is_turkic_patronymic_marker(self.last_list[0])
+        ):
+            self.first_list, self.middle_list, self.last_list = (
+                [self.middle_list[0]],
+                [self.middle_list[1], self.last_list[0]],
+                self.first_list,
+            )
+
     def handle_middle_name_as_last(self) -> None:
         """
         When middle_name_as_last is enabled, fold middle_list into last_list
@@ -784,7 +818,8 @@ def post_process(self) -> None:
         """
         self.handle_firstnames()
         if self.C.patronymic_name_order:
-            self.handle_patronymic_name_order()
+            self.handle_east_slavic_patronymic_name_order()
+            self.handle_turkic_patronymic_name_order()
         if self.C.middle_name_as_last:
             self.handle_middle_name_as_last()
         self.handle_capitalization()

tests/test_patronymic_order.py …sts/test_east_slavic_patronymic_order.pytests/test_patronymic_order.py renamed to tests/test_east_slavic_patronymic_order.py tests/test_patronymic_order.py renamed to tests/test_east_slavic_patronymic_order.py

@@ -6,34 +6,47 @@
 def test_latin_patronymic_matches() -> None:
     # One common suffix and one irregular — the integration tests cover the rest.
     C = Constants()
-    assert C.regexes.patronymic.search("Ivanovich")
-    assert C.regexes.patronymic.search("Ilyich")
+    assert C.regexes.east_slavic_patronymic.search("Ivanovich")
+    assert C.regexes.east_slavic_patronymic.search("Ilyich")
 
 
 def test_latin_patronymic_rejects_non_patronymic() -> None:
     # EMPTY_REGEX (the default for missing keys) matches everything,
     # so this test is red until the real pattern is in place.
     C = Constants()
-    assert not C.regexes.patronymic.search("Smith")
+    assert not C.regexes.east_slavic_patronymic.search("Smith")
 
 
 def test_latin_patronymic_end_anchored() -> None:
     # A surname ending in a patronymic suffix matches; the end-anchor does not
     # prevent this. The parser guard tests verify reordering is suppressed.
     C = Constants()
-    assert C.regexes.patronymic.search("Abramovich")
+    assert C.regexes.east_slavic_patronymic.search("Abramovich")
 
 
 def test_cyrillic_patronymic_matches() -> None:
     # One common suffix and one irregular.
     C = Constants()
-    assert C.regexes.patronymic_cyrillic.search("Иванович")
-    assert C.regexes.patronymic_cyrillic.search("ильич")
+    assert C.regexes.east_slavic_patronymic_cyrillic.search("Иванович")
+    assert C.regexes.east_slavic_patronymic_cyrillic.search("ильич")
+
+
+def test_cyrillic_patronymic_matches_capitalized_irregular_forms() -> None:
+    # The irregular forms (Ильич, Кузьмич, ...) are short enough that the
+    # capitalized first letter falls within the matched suffix itself, unlike
+    # the common suffixes (-ович, -евна, ...) where only the surname root is
+    # capitalized. Case-insensitivity is required for these to match.
+    C = Constants()
+    assert C.regexes.east_slavic_patronymic_cyrillic.search("Ильич")
+    assert C.regexes.east_slavic_patronymic_cyrillic.search("Кузьмич")
+    assert C.regexes.east_slavic_patronymic_cyrillic.search("Лукич")
+    assert C.regexes.east_slavic_patronymic_cyrillic.search("Фомич")
+    assert C.regexes.east_slavic_patronymic_cyrillic.search("Фокич")
 
 
 def test_cyrillic_patronymic_rejects_non_patronymic() -> None:
     C = Constants()
-    assert not C.regexes.patronymic_cyrillic.search("Иванов")
+    assert not C.regexes.east_slavic_patronymic_cyrillic.search("Иванов")
 
 
 class PatronymicNameOrderReorderTests(HumanNameTestBase):
@@ -77,6 +90,14 @@ def test_cyrillic(self) -> None:
         assert n.middle == "Иванович"
         assert n.last == "Иванов"
 
+    def test_cyrillic_capitalized_irregular_form(self) -> None:
+        # "Ильич" is short enough that the capitalized first letter falls
+        # within the irregular suffix itself; requires case-insensitive match.
+        n = self.hn("Иванов Иван Ильич")
+        assert n.first == "Иван"
+        assert n.middle == "Ильич"
+        assert n.last == "Иванов"
+
     def test_title_preserved(self) -> None:
         n = self.hn("Dr. Ivanov Ivan Ivanovich")
         assert n.title == "Dr."