Fix constants argument silently discarding Constants subclasses

__init__ validated the constants argument with an exact-type check
(type(self.C) is not type(CONSTANTS)), so an instance of a Constants
subclass failed the check and was silently replaced with fresh
defaults, discarding the caller's configuration without any error.

Validate explicitly instead: None means a private per-instance
Constants (unchanged), any Constants instance — including subclasses —
is used as given, and anything else raises TypeError rather than being
silently swapped for defaults. The signature annotation now admits
None, which was always accepted and documented.

Also fix stale prose in customize.rst: "pass something falsey" no
longer describes the behavior (only None gets per-instance config now),
and the keyword argument is `constants`, not `constant`.

Closes #226

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: derek73

docs/customize.rst

@@ -456,10 +456,11 @@ e.g. parsing names on multiple threads.
 
 
 If you'd prefer new instances to have their own config values, one shortcut is to pass
-``None`` as the second argument (or ``constant`` keyword argument) when
+``None`` as the second argument (or ``constants`` keyword argument) when
 instantiating ``HumanName``. Each instance always has a ``C`` attribute, but if
-you didn't pass something falsey to the ``constants`` argument then it's a
-reference to the module-level config values with the behavior described above.
+you didn't pass ``None`` (or your own :py:class:`~nameparser.config.Constants`
+instance) to the ``constants`` argument then it's a reference to the
+module-level config values with the behavior described above.
 
 .. doctest:: module config
     :options: +ELLIPSIS, +NORMALIZE_WHITESPACE

docs/release_log.rst

@@ -1,6 +1,7 @@
 Release Log
 ===========
 * 1.3.0 - Unreleased
+    - Fix the ``constants`` constructor argument silently discarding ``Constants`` *subclass* instances: the exact-type check replaced them with fresh defaults, throwing away the caller's configuration. Subclass instances are now used as given; anything that is neither ``None`` nor a ``Constants`` instance now raises ``TypeError`` instead of being silently swapped for defaults (closes #226)
     - Fix ``IndexError`` in ``initials()``/``initials_list()`` when a ``*_list`` attribute was assigned directly with an element containing unnormalized whitespace (e.g. ``name.middle_list = ['Q  R']``), bypassing the parser's whitespace normalization (closes #232)
     - Fix ``HumanName`` acting as its own iterator with a stored cursor: breaking out of a loop, iterating in nested loops, or calling ``len(name)`` mid-loop corrupted subsequent iteration; ``iter(name)`` now returns a fresh independent iterator each time. ``next(name)`` on the instance itself (undocumented) now raises ``TypeError`` — call ``next(iter(name))`` instead (closes #225)
     - Fix parsing writing back into the ``Constants`` it reads (usually the shared module-level ``CONSTANTS``): pieces derived while parsing a name — period-joined titles/suffixes like ``"Lt.Gov."`` and conjunction-joined pieces like ``"Mr. and Mrs."`` or ``"von und zu"`` — are now tracked per parse instead of being permanently ``add()``-ed to the config, so parse results no longer depend on which names were parsed earlier in the process and parsing no longer mutates shared state across threads

nameparser/parser.py

@@ -95,7 +95,7 @@ class HumanName:
     def __init__(
         self,
         full_name: str | bytes = "",
-        constants: Constants = CONSTANTS,
+        constants: Constants | None = CONSTANTS,
         encoding: str = DEFAULT_ENCODING,
         string_format: str | None = None,
         initials_format: str | None = None,
@@ -110,9 +110,14 @@ 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):
+            raise TypeError(
+                "constants must be a Constants instance or None, "
+                f"got {type(constants).__name__}"
+            )
         self.C = constants
-        if type(self.C) is not type(CONSTANTS):
-            self.C = Constants()
 
         # Lookup entries derived while parsing this instance (period-joined
         # titles/suffixes like "Lt.Gov.", conjunction-joined pieces like

tests/test_constants.py

@@ -25,6 +25,22 @@ def test_add_title(self) -> None:
         self.m(hn.first, "Awanui-a-Rangi", hn)
         self.m(hn.last, "Black", hn)
 
+    def test_constants_subclass_instance_is_used(self) -> None:
+        class CustomConstants(Constants):
+            pass
+
+        c = CustomConstants()
+        c.titles.add('chancellor')
+        hn = HumanName("Chancellor Jane Smith", constants=c)
+        self.assertIs(hn.C, c)
+        self.m(hn.title, "Chancellor", hn)
+        self.m(hn.first, "Jane", hn)
+        self.m(hn.last, "Smith", hn)
+
+    def test_constants_invalid_type_raises_typeerror(self) -> None:
+        with pytest.raises(TypeError):
+            HumanName("John Doe", constants="not a Constants")  # type: ignore[arg-type]
+
     def test_remove_title(self) -> None:
         hn = HumanName("Hon Solo", constants=None)
         start_len = len(hn.C.titles)