Make HumanName.C a property so post-construction assignment is validated

#226 validated the `constants` argument in HumanName.__init__, but `C` was a
plain attribute, so `hn.C = 'garbage'` bypassed validation entirely and only
surfaced as an unrelated AttributeError deep inside parsing. Extract
_validate_constants as a shared staticmethod used by both the constructor and
the new C property setter, so both paths raise the same immediate TypeError.

__getstate__/__setstate__ are updated to translate the internal _C storage
attribute to/from the same 'C' key they always pickled, so the on-disk pickle
format (and the CONSTANTS-singleton sentinel) is unchanged.

Fixes #239

Author: derek73

nameparser/parser.py

@@ -68,14 +68,6 @@ class HumanName:
     :param str maiden: Maiden name
     """
 
-    C = CONSTANTS
-    """
-    A reference to the configuration for this instance, which may or may not be
-    a reference to the shared, module-wide instance at
-    :py:mod:`~nameparser.config.CONSTANTS`. See `Customizing the Parser
-    <customize.html>`_.
-    """
-
     original: str | bytes = ''
     """
     The original string, untouched by the parser.
@@ -111,17 +103,6 @@ def __init__(
         nickname: str | list[str] | None = None,
         maiden: str | list[str] | None = None,
     ) -> None:
-        if constants is None:
-            constants = Constants()
-        elif not isinstance(constants, Constants):
-            # passing the class itself is the likeliest mistake, and
-            # reporting it as "got type" would only add confusion
-            hint = (" (a class was passed; did you mean Constants()?)"
-                    if isinstance(constants, type) else "")
-            raise TypeError(
-                "constants must be a Constants instance or None, "
-                f"got {type(constants).__name__}{hint}"
-            )
         self.C = constants
 
         # Lookup entries derived while parsing this instance (period-joined
@@ -156,15 +137,52 @@ def __init__(
             # full_name setter triggers the parse
             self.full_name = full_name
 
+    @staticmethod
+    def _validate_constants(constants: 'Constants | None') -> 'Constants':
+        # Shared by the constructor and the C setter so both assignment paths
+        # give the same immediate TypeError instead of one bypassing the
+        # other and failing far from the cause (#239).
+        if constants is None:
+            return Constants()
+        if not isinstance(constants, Constants):
+            # passing the class itself is the likeliest mistake, and
+            # reporting it as "got type" would only add confusion
+            hint = (" (a class was passed; did you mean Constants()?)"
+                    if isinstance(constants, type) else "")
+            raise TypeError(
+                "constants must be a Constants instance or None, "
+                f"got {type(constants).__name__}{hint}"
+            )
+        return constants
+
+    @property
+    def C(self) -> 'Constants':
+        """
+        A reference to the configuration for this instance, which may or may not be
+        a reference to the shared, module-wide instance at
+        :py:mod:`~nameparser.config.CONSTANTS`. See `Customizing the Parser
+        <customize.html>`_.
+
+        Assigning a non-``Constants`` value (besides ``None``, which builds a
+        fresh private ``Constants()``) raises the same ``TypeError`` as passing
+        an invalid ``constants`` argument to the constructor (#239).
+        """
+        return self._C
+
+    @C.setter
+    def C(self, constants: 'Constants | None') -> None:
+        self._C = self._validate_constants(constants)
+
     def __getstate__(self) -> dict:
         state = self.__dict__.copy()
-        if state.get('C') is CONSTANTS:
-            state['C'] = None  # sentinel: restore shared singleton on load
+        c = state.pop('_C')
+        state['C'] = None if c is CONSTANTS else c  # sentinel: restore shared singleton on load
         return state
 
     def __setstate__(self, state: dict) -> None:
-        if state.get('C') is None:
-            state['C'] = CONSTANTS
+        state = dict(state)
+        c = state.pop('C', None)
+        self._C = CONSTANTS if c is None else c
         self.__dict__.update(state)
         # pickles from before the per-parse derived sets existed lack them;
         # backfill so the is_* predicates work without a re-parse

tests/test_constants.py

@@ -6,7 +6,7 @@
 import pytest
 
 from nameparser import HumanName
-from nameparser.config import Constants, RegexTupleManager, SetManager, TupleManager
+from nameparser.config import CONSTANTS, Constants, RegexTupleManager, SetManager, TupleManager
 from nameparser.config.regexes import EMPTY_REGEX
 from nameparser.config.titles import TITLES
 
@@ -46,6 +46,25 @@ def test_constants_class_instead_of_instance_raises_with_hint(self) -> None:
         with pytest.raises(TypeError, match=r"did you mean Constants\(\)"):
             HumanName("John Doe", constants=Constants)  # type: ignore[arg-type]
 
+    def test_assigning_invalid_constants_after_construction_raises(self) -> None:
+        # #226 validated the constructor's `constants` argument, but `hn.C = ...`
+        # bypassed it entirely: the bad value was accepted silently and only
+        # surfaced far later, deep inside parsing, with no mention of `C` (#239)
+        hn = HumanName("John Doe")
+        with pytest.raises(TypeError, match="constants must be"):
+            hn.C = "garbage"  # type: ignore[assignment]
+
+    def test_assigning_constants_class_after_construction_raises_with_hint(self) -> None:
+        hn = HumanName("John Doe")
+        with pytest.raises(TypeError, match=r"did you mean Constants\(\)"):
+            hn.C = Constants  # type: ignore[assignment]
+
+    def test_assigning_none_to_constants_after_construction_builds_new_instance(self) -> None:
+        hn = HumanName("John Doe")
+        hn.C = None
+        self.assertIsNot(hn.C, CONSTANTS)
+        self.assertTrue(isinstance(hn.C, Constants))
+
     def test_constants_bare_string_kwarg_raises_typeerror(self) -> None:
         # a bare string is an iterable of its characters, so set('dr') would
         # silently replace the default titles with {'d', 'r'} (#238); the