fix: point patronymic_rules=True at the v1 migration path

v1's patronymic_name_order was a bool flag, so True is the likeliest
wrong value a migrator passes to the 2.0 field; it failed loudly but
with the raw "'bool' object is not iterable". Probe with iter() --
NOT a try/except around tuple()/frozenset(), which would also rewrite
exceptions raised inside a caller's generator (pinned property) -- and
raise a message naming the v1 flag and both working replacements.
Same guard on PolicyPatch's union fields, with the v1 hint only where
it applies.

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

Author: derek73

nameparser/_policy.py

@@ -85,12 +85,24 @@ def __post_init__(self) -> None:
                 f"patronymic_rules must be an iterable of rule names, "
                 f"not a bare string: {self.patronymic_rules!r}"
             )
-        # Materialize before converting (the _normset pattern): a
-        # non-iterable raises its natural TypeError here, and an exception
-        # raised inside a caller's generator propagates untouched instead
-        # of being rewritten as an unknown-rule error. Only the enum
-        # lookup itself gets the enriched message, naming the offender.
-        items = tuple(self.patronymic_rules)
+        # Probe with iter() rather than wrapping tuple(): non-iterables
+        # (True especially -- v1's patronymic_name_order was a bool flag,
+        # so it's the likeliest wrong value here) get the migration-
+        # pointing message, while an exception raised inside a caller's
+        # generator still propagates untouched from the tuple() below
+        # instead of being rewritten. Only the enum lookup itself gets
+        # the unknown-rule message, naming the offender.
+        try:
+            rule_iter = iter(self.patronymic_rules)
+        except TypeError:
+            raise TypeError(
+                f"patronymic_rules must be an iterable of PatronymicRule "
+                f"names, got {self.patronymic_rules!r}; v1's "
+                f"patronymic_name_order=True becomes "
+                f"patronymic_rules={{PatronymicRule.EAST_SLAVIC}} "
+                f"(or parser_for(locales.RU))"
+            ) from None
+        items = tuple(rule_iter)
         rules = set()
         for r in items:
             try:
@@ -232,6 +244,21 @@ def __post_init__(self) -> None:
                     f"{f.name} must be an iterable, "
                     f"not a bare string: {value!r}"
                 )
+            # same iter() probe as Policy: curated message for
+            # non-iterables (with the v1-flag hint where it applies),
+            # caller-generator exceptions propagate from frozenset()
+            try:
+                iter(value)
+            except TypeError:
+                hint = (
+                    "; v1's patronymic_name_order=True becomes "
+                    "patronymic_rules={PatronymicRule.EAST_SLAVIC} "
+                    "(or parser_for(locales.RU))"
+                    if f.name == "patronymic_rules" else ""
+                )
+                raise TypeError(
+                    f"{f.name} must be an iterable, got {value!r}{hint}"
+                ) from None
             object.__setattr__(self, f.name, frozenset(value))
 
 

tests/v2/test_policy.py

@@ -76,6 +76,20 @@ def test_patronymic_rules_rejects_bare_string_and_non_iterable() -> None:
         Policy(patronymic_rules=5)  # type: ignore[arg-type]
 
 
+def test_patronymic_rules_true_points_at_the_v1_migration() -> None:
+    # v1's patronymic_name_order was a BOOL flag, so True is the single
+    # likeliest wrong value a migrator passes here -- the message must
+    # name the v1 flag and the working replacements, not just say
+    # "not iterable". Same guard on the PolicyPatch path (packs).
+    with pytest.raises(TypeError, match="patronymic_name_order"):
+        Policy(patronymic_rules=True)  # type: ignore[arg-type]
+    with pytest.raises(TypeError, match="patronymic_name_order"):
+        PolicyPatch(patronymic_rules=True)  # type: ignore[arg-type]
+    # non-patronymic union fields get the generic curated message
+    with pytest.raises(TypeError, match="extra_suffix_delimiters"):
+        PolicyPatch(extra_suffix_delimiters=True)  # type: ignore[arg-type]
+
+
 def test_policy_delimiters_coerce_to_frozensets() -> None:
     p = Policy(nickname_delimiters=[("(", ")")])  # type: ignore[arg-type]
     assert isinstance(p.nickname_delimiters, frozenset)