Explain why empty_attribute_default's type:ignores exist

Per code review: the AGENTS.md guidance added in this branch says to
widen an annotation rather than ignore when runtime already supports
the wider type, but empty_attribute_default is that exact case and
was left un-widened. Document the deliberate scope decision (avoids
cascading into ~8 public str-typed properties) at each ignore site
instead of leaving it unexplained.

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

Author: derek73

tests/test_constants.py

@@ -301,6 +301,12 @@ def test_clear_removes_all_entries(self) -> None:
 
     def test_empty_attribute_default(self) -> None:
         from nameparser.config import CONSTANTS
+        # empty_attribute_default has no explicit annotation (mypy infers str
+        # from the '' default), but None is documented/supported here -- see
+        # the doctest on the attribute's docstring in config/__init__.py.
+        # Not widened to str | None like string_format/suffix_delimiter
+        # because it cascades into ~8 public str-typed properties (title,
+        # first, middle, last, suffix, nickname, initials()).
         CONSTANTS.empty_attribute_default = None  # type: ignore[assignment]
         hn = HumanName("")
         self.m(hn.title, None, hn)
@@ -312,7 +318,7 @@ def test_empty_attribute_default(self) -> None:
 
     def test_empty_attribute_on_instance(self) -> None:
         hn = HumanName("", None)
-        hn.C.empty_attribute_default = None  # type: ignore[assignment]
+        hn.C.empty_attribute_default = None  # type: ignore[assignment]  # see test_empty_attribute_default above
         self.m(hn.title, None, hn)
         self.m(hn.first, None, hn)
         self.m(hn.middle, None, hn)
@@ -322,7 +328,7 @@ def test_empty_attribute_on_instance(self) -> None:
 
     def test_none_empty_attribute_string_formatting(self) -> None:
         hn = HumanName("", None)
-        hn.C.empty_attribute_default = None  # type: ignore[assignment]
+        hn.C.empty_attribute_default = None  # type: ignore[assignment]  # see test_empty_attribute_default above
         self.assertEqual('', str(hn), hn)
 
     def test_add_constant_with_explicit_encoding(self) -> None:
@@ -361,7 +367,7 @@ def test_pickle_roundtrip_preserves_customizations(self) -> None:
     def test_pickle_roundtrip_preserves_instance_scalar_override(self) -> None:
         """An instance-level scalar override must survive a pickle round-trip."""
         c = Constants()
-        c.empty_attribute_default = None  # type: ignore[assignment]
+        c.empty_attribute_default = None  # type: ignore[assignment]  # see test_empty_attribute_default above
 
         # Safe: round-tripping a Constants the test just built, not untrusted data.
         restored = pickle.loads(pickle.dumps(c))

tests/test_initials.py

@@ -25,6 +25,12 @@ def test_initials_empty_part_with_none_default_not_literal_none(self) -> None:
         # used to be interpolated by str.format as the literal "None" (e.g.
         # "John Doe" -> "J. None D."). Empty parts must render as ''.
         hn = HumanName("John Doe", constants=None)
+        # empty_attribute_default has no explicit annotation (mypy infers str
+        # from the '' default), but None is documented/supported here -- see
+        # the doctest on the attribute's docstring in config/__init__.py. Not
+        # widened to str | None like string_format/suffix_delimiter because
+        # it cascades into ~8 public str-typed properties (title, first,
+        # middle, last, suffix, nickname, initials()).
         hn.C.empty_attribute_default = None  # type: ignore[assignment]
         self.assertEqual(hn.initials(), "J. D.")
         self.assertTrue("None" not in hn.initials())
@@ -34,7 +40,7 @@ def test_initials_all_empty_returns_empty_attribute_default(self) -> None:
         # empty_attribute_default (here None), matching the first/last accessors,
         # rather than rendering the literal "None None None".
         hn = HumanName("", constants=None)
-        hn.C.empty_attribute_default = None  # type: ignore[assignment]
+        hn.C.empty_attribute_default = None  # type: ignore[assignment]  # see test above
         self.assertEqual(hn.initials(), None)
 
     def test_initials_middle_name_all_prefixes(self) -> None: