Reject given_name_titles entries that are not titles

Lexicon guarded two of its three marker-over-base relationships:
particles_ambiguous <= particles and suffix_acronyms_ambiguous <=
suffix_acronyms both raised ValueError, while given_name_titles <=
titles was unchecked. An entry present only in given_name_titles is
never consulted by any rule, so the misconfiguration did nothing and
said nothing -- the silent-degradation failure mode #256 was deprecated
for. Found while writing the locales.rst example: the doctest failed
because the honorific was added to given_name_titles alone.

Fold all three checks into one _SUBSET_FIELDS loop; the messages are
unchanged.

v1 compatibility is preserved by intersecting at the shim boundary.
v1 treats titles and first_name_titles as independent sets and only
consults first_name_titles for a word already recognized as a title, so
an entry missing from titles was unreachable in v1 too -- dropping it
changes no v1 behavior while satisfying the invariant. Verified against
a live 1.4.0 with a word absent from the defaults: first_name_titles
alone yields no title on both 1.4 and the 2.0 facade; both fields yield
the title on both. Without this the guard broke six compat tests, since
Constants(titles=[...]) replaces titles wholesale while first_name_titles
keeps its defaults.

(An earlier check of the same question used "sheikh", which is already
in the default TITLES, so it proved nothing -- the retest with a novel
word reversed the conclusion.)

Docs: customize.rst states the subset rule for all three pairs, and its
remove() example moves from "sir" to "professor" -- "sir" is itself a
given_name_title, so removing it now correctly raises.

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

Author: derek73

docs/customize.rst

@@ -29,10 +29,17 @@ Removing works the same way, and drops the word from recognition:
 
 .. doctest::
 
-    >>> lean = Lexicon.default().remove(titles={"sir"})
-    >>> Parser(lexicon=lean).parse("Sir Robert Johns").title
+    >>> lean = Lexicon.default().remove(titles={"professor"})
+    >>> Parser(lexicon=lean).parse("Professor Robert Johns").title
     ''
 
+A few fields mark a subset of another — ``given_name_titles`` over
+``titles``, ``particles_ambiguous`` over ``particles``,
+``suffix_acronyms_ambiguous`` over ``suffix_acronyms``. Entries must
+appear in the base field too, so add to both and remove from the marker
+first; anything else raises ``ValueError`` naming the orphans rather
+than leaving a marker entry that no rule will ever consult.
+
 Whole lexicons compose with ``|``, which unions field by field — handy
 for keeping a shared house vocabulary separate from a per-source one
 and combining them at parser construction:

docs/locales.rst

@@ -49,8 +49,8 @@ Both fields, because ``given_name_titles`` is a marker over ``titles``
 rather than a separate vocabulary: ``titles`` makes the word a title at
 all, and listing it in ``given_name_titles`` says the honorific
 precedes the *given* name — as Arabic ones do — so the word after it
-isn't read as a family name. Adding it to ``given_name_titles`` alone
-has no effect.
+isn't read as a family name. Listing it in ``given_name_titles`` alone
+raises ``ValueError`` rather than quietly doing nothing.
 
 A pack is for something different: a *structural* rule, like reordering
 a patronymic, that vocabulary alone can't express.

nameparser/_config_shim.py

@@ -933,11 +933,19 @@ def _build_snapshot(self) -> tuple[Lexicon, Policy, _RenderDefaults]:
         """
         from nameparser.config.maiden_markers import MAIDEN_MARKERS
         acronyms = frozenset(self.suffix_acronyms)
+        titles = frozenset(self.titles)
         # keep in sync with _lexicon._default_lexicon() (pinned by the
         # default-Constants equality test in tests/v2/test_config_shim.py)
         lexicon = Lexicon(
-            titles=frozenset(self.titles),
-            given_name_titles=frozenset(self.first_name_titles),
+            titles=titles,
+            # intersect, same reasoning as suffix_acronyms_ambiguous
+            # below: v1 treats titles and first_name_titles as
+            # independent sets, and only consults first_name_titles for
+            # a word already recognized as a title -- so an entry
+            # missing from titles was never reachable in v1 either, and
+            # dropping it preserves v1 behavior exactly while
+            # satisfying Lexicon's subset invariant
+            given_name_titles=frozenset(self.first_name_titles) & titles,
             suffix_acronyms=acronyms,
             suffix_words=frozenset(self.suffix_not_acronyms),
             # intersect: Lexicon enforces ambiguous <= acronyms; v1

nameparser/_lexicon.py

@@ -23,6 +23,18 @@
     "conjunctions", "bound_given_names", "maiden_markers",
 )
 
+#: (marker, base) pairs: each marker field narrows how entries of its
+#: base vocabulary are read, and carries no vocabulary of its own. An
+#: entry present in the marker but absent from the base is never
+#: consulted by any rule, so it is rejected rather than silently
+#: ignored -- a no-op configuration is the failure mode these fields
+#: are most likely to be misused into.
+_SUBSET_FIELDS = (
+    ("particles_ambiguous", "particles"),
+    ("suffix_acronyms_ambiguous", "suffix_acronyms"),
+    ("given_name_titles", "titles"),
+)
+
 
 def _normalize(word: str) -> str:
     """Lowercase, strip whitespace and EDGE periods -- v1's lc()
@@ -215,19 +227,13 @@ def __post_init__(self) -> None:
         canonical = _normpairs(self.capitalization_exceptions)
         object.__setattr__(self, "capitalization_exceptions", canonical)
         object.__setattr__(self, "_cap_map", MappingProxyType(dict(canonical)))
-        if not self.particles_ambiguous <= self.particles:
-            extra = ", ".join(sorted(self.particles_ambiguous - self.particles))
-            raise ValueError(
-                f"particles_ambiguous must be a subset of particles; "
-                f"not in particles: {extra}"
-            )
-        if not self.suffix_acronyms_ambiguous <= self.suffix_acronyms:
-            extra = ", ".join(sorted(
-                self.suffix_acronyms_ambiguous - self.suffix_acronyms))
-            raise ValueError(
-                f"suffix_acronyms_ambiguous must be a subset of "
-                f"suffix_acronyms; not in suffix_acronyms: {extra}"
-            )
+        for marker, base in _SUBSET_FIELDS:
+            orphans = getattr(self, marker) - getattr(self, base)
+            if orphans:
+                raise ValueError(
+                    f"{marker} must be a subset of {base}; "
+                    f"not in {base}: {', '.join(sorted(orphans))}"
+                )
 
     # -- constructors ----------------------------------------------------
 

tests/v2/test_lexicon.py

@@ -227,3 +227,19 @@ def test_suffix_ambiguous_must_be_subset_of_acronyms() -> None:
     # depends on the membership tests agreeing about it
     with pytest.raises(ValueError, match="subset"):
         Lexicon(suffix_acronyms_ambiguous=frozenset({"ma"}))
+
+
+def test_given_name_titles_must_be_subset_of_titles() -> None:
+    # third marker-over-base pair, same rule: given_name_titles marks
+    # which TITLES precede the given name rather than the family name,
+    # so an entry missing from titles is never consulted -- a silent
+    # no-op is exactly the failure mode the other two guards prevent
+    with pytest.raises(ValueError, match="subset"):
+        Lexicon(given_name_titles=frozenset({"sheikh"}))
+
+
+def test_remove_orphaning_given_name_titles_raises() -> None:
+    lex = Lexicon(titles=frozenset({"sheikh"}),
+                  given_name_titles=frozenset({"sheikh"}))
+    with pytest.raises(ValueError, match="subset"):
+        lex.remove(titles={"sheikh"})