fix: restore CONSTANTS singleton identity across pickle/deepcopy (closes #169)

A default HumanName shares the module-level CONSTANTS singleton as its .C.
pickle and copy.deepcopy cannot preserve object identity, so without custom
hooks .C was serialized by value — causing has_own_config to flip to True
and bloating every serialized default name with a full Constants copy.

__getstate__ replaces .C with None as a sentinel when it is the shared
singleton; __setstate__ restores the CONSTANTS reference from that sentinel.
None is a safe sentinel because the constructor always replaces a None
constants argument with a fresh Constants().

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: derek73

nameparser/parser.py

@@ -121,6 +121,17 @@ def __init__(
             # full_name setter triggers the parse
             self.full_name = full_name
 
+    def __getstate__(self) -> dict:
+        state = self.__dict__.copy()
+        if state.get('C') is CONSTANTS:
+            state['C'] = None  # sentinel: restore shared singleton on load
+        return state
+
+    def __setstate__(self, state: dict) -> None:
+        if state.get('C') is None:
+            state['C'] = CONSTANTS
+        self.__dict__.update(state)
+
     def __iter__(self) -> Iterator[str]:
         return self
 

tests/test_python_api.py

@@ -92,6 +92,32 @@ def test_name_instance_deepcopy_isolates_instance_config(self) -> None:
         self.assertIn('chancellor', dup.C.titles)
         self.assertNotIn('marker', hn.C.titles)
 
+    def test_pickle_default_name_preserves_singleton_identity(self) -> None:
+        """A default HumanName must re-attach to CONSTANTS after a pickle round-trip.
+
+        Without __getstate__/__setstate__, pickle serializes .C by value, so the
+        restored name gets a detached copy — has_own_config flips to True and
+        every pickled default name carries a full Constants copy.
+        """
+        hn = HumanName("John Doe")
+        self.assertFalse(hn.has_own_config)
+        self.assertIs(hn.C, CONSTANTS)
+
+        # Safe: round-tripping an object we just built, not untrusted data.
+        restored = pickle.loads(pickle.dumps(hn))
+
+        self.assertIs(restored.C, CONSTANTS)
+        self.assertFalse(restored.has_own_config)
+
+    def test_deepcopy_default_name_preserves_singleton_identity(self) -> None:
+        """copy.deepcopy of a default HumanName must re-attach to CONSTANTS."""
+        hn = HumanName("John Doe")
+
+        dup = copy.deepcopy(hn)
+
+        self.assertIs(dup.C, CONSTANTS)
+        self.assertFalse(dup.has_own_config)
+
     def test_comparison(self) -> None:
         hn1 = HumanName("Doe-Ray, Dr. John P., CLU, CFP, LUTC")
         hn2 = HumanName("Dr. John P. Doe-Ray, CLU, CFP, LUTC")