feat: add given_names attribute aggregating first and middle names (closes #157)

Adds given_names (and given_names_list), the first name followed by all
middle names, mirroring the existing surnames attribute (middle + last).
Reimplemented fresh on current master from the approach in #157, which was
based on a pre-refactor codebase and had drifted.

Co-Authored-By: fdesoye <fdesoye@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: 3 people

docs/release_log.rst

@@ -7,6 +7,7 @@ Release Log
     to 1.2.1 first (which includes a one-version compatibility shim), load and
     re-pickle under 1.2.1, then upgrade to 1.3.0.
 
+    - Add ``given_names`` (and ``given_names_list``) attribute as aggregate of first and middle names, mirroring ``surnames`` (closes #157)
     - Add ``suffix_delimiter`` to ``Constants`` and ``HumanName`` for parsing suffixes separated by arbitrary delimiters, e.g. ``"RN - CRNA"`` (#156)
     - Add ``initials_separator`` to ``Constants`` and ``HumanName`` to control spacing between consecutive initials within a name group (#171)
     - Fix ``Constants`` customizations, singleton identity, and ``TupleManager`` subclass being lost across ``pickle``/``deepcopy`` round-trips (#167, #168, #169)

docs/usage.rst

@@ -25,6 +25,8 @@ Requires Python 3.10+.
     'III'
     >>> name.surnames
     'Q. Xavier de la Vega'
+    >>> name.given_names
+    'Juan Q. Xavier'
     >>> name.full_name = "Juan Q. Xavier Velasquez y Garcia, Jr."
     >>> name
     <HumanName : [

nameparser/parser.py

@@ -44,6 +44,7 @@ class HumanName:
     * :py:attr:`suffix`
     * :py:attr:`nickname`
     * :py:attr:`surnames`
+    * :py:attr:`given_names`
 
     :param str full_name: The name string to be parsed.
     :param constants constants:
@@ -415,6 +416,20 @@ def surnames(self) -> str:
         """
         return " ".join(self.surnames_list) or self.C.empty_attribute_default
 
+    @property
+    def given_names_list(self) -> list[str]:
+        """
+        List of first name followed by middle names.
+        """
+        return self.first_list + self.middle_list
+
+    @property
+    def given_names(self) -> str:
+        """
+        A string of the first name followed by all middle names.
+        """
+        return " ".join(self.given_names_list) or self.C.empty_attribute_default
+
     # setter methods
 
     def _set_list(self, attr: str, value: str | list[str] | None) -> None:

tests/test_python_api.py

@@ -263,6 +263,14 @@ def test_surnames_attribute(self) -> None:
         hn = HumanName("John Edgar Casey Williams III")
         self.m(hn.surnames, "Edgar Casey Williams", hn)
 
+    def test_given_names_list_attribute(self) -> None:
+        hn = HumanName("John Edgar Casey Williams III")
+        self.m(hn.given_names_list, ["John", "Edgar", "Casey"], hn)
+
+    def test_given_names_attribute(self) -> None:
+        hn = HumanName("John Edgar Casey Williams III")
+        self.m(hn.given_names, "John Edgar Casey", hn)
+
     def test_is_prefix_with_list(self) -> None:
         hn = HumanName()
         items = ['firstname', 'lastname', 'del']