Fix stacklevel misattribution on delegated bytes-deprecation warnings

SetManager.add()/add_with_encoding() and HumanName's constructor/full_name
setter each had a fixed stacklevel that only pointed at the real caller
when the bytes-deprecation warning fired on the direct-call path. Going
through the wrapper (add() -> add_with_encoding(), __init__ -> setter)
added a stack frame, so the warning was misattributed to nameparser's
own internals instead of the caller's code.

Extract the shared decode+warn logic into a private helper
(_add_normalized / _apply_full_name) that each public entry point calls
directly with its own correct stacklevel, verified empirically that both
call paths now attribute to the user's line. Also add the missing
.. deprecated:: note to add()'s docstring, tighten a weak match= test
assertion, fix present-tense wording in test comments, and add a test
for remove()/discard() with mixed present+missing members in one call.

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

Author: derek73

nameparser/config/__init__.py

@@ -208,16 +208,11 @@ def __xor__(self, other: Iterable[str]) -> 'SetManager':  # type: ignore[overrid
 
     __rxor__ = __xor__
 
-    def add_with_encoding(self, s: str | bytes, encoding: str | None = None) -> None:
-        """
-        Add the lowercased, leading/trailing-periods-stripped version of the string to the set. Pass an
-        explicit `encoding` parameter to specify the encoding of binary strings that
-        are not DEFAULT_ENCODING (UTF-8).
-
-        .. deprecated:: 1.3.0
-            ``bytes`` arguments will raise ``TypeError`` in 2.0 (see issue
-            #245); decode before adding.
-        """
+    def _add_normalized(self, s: str | bytes, encoding: str | None, *, stacklevel: int) -> None:
+        # Shared by add() and add_with_encoding() so each can call it
+        # directly with a stacklevel that attributes the warning to *its own*
+        # caller -- add() delegating to add_with_encoding() would otherwise
+        # add a frame and misattribute the warning to this module.
         stdin_encoding = None
         if sys.stdin:
             stdin_encoding = sys.stdin.encoding
@@ -229,7 +224,7 @@ def add_with_encoding(self, s: str | bytes, encoding: str | None = None) -> None
                 "first, e.g. value.decode('utf-8'). See "
                 "https://github.com/derek73/python-nameparser/issues/245",
                 DeprecationWarning,
-                stacklevel=2,
+                stacklevel=stacklevel,
             )
             s = s.decode(encoding)
         normalized = lc(s)
@@ -238,13 +233,29 @@ def add_with_encoding(self, s: str | bytes, encoding: str | None = None) -> None
             if self._on_change:
                 self._on_change()
 
+    def add_with_encoding(self, s: str | bytes, encoding: str | None = None) -> None:
+        """
+        Add the lowercased, leading/trailing-periods-stripped version of the string to the set. Pass an
+        explicit `encoding` parameter to specify the encoding of binary strings that
+        are not DEFAULT_ENCODING (UTF-8).
+
+        .. deprecated:: 1.3.0
+            ``bytes`` arguments will raise ``TypeError`` in 2.0 (see issue
+            #245); decode before adding.
+        """
+        self._add_normalized(s, encoding, stacklevel=3)
+
     def add(self, *strings: str) -> Self:
         """
         Add the lowercased, leading/trailing-periods-stripped version of the string arguments to the set.
         Returns ``self`` for chaining.
+
+        .. deprecated:: 1.3.0
+            ``bytes`` arguments will raise ``TypeError`` in 2.0 (see issue
+            #245); decode before adding.
         """
         for s in strings:
-            self.add_with_encoding(s)
+            self._add_normalized(s, None, stacklevel=3)
 
         return self
 

nameparser/parser.py

@@ -137,8 +137,10 @@ def __init__(
             self.nickname = nickname
             self.maiden = maiden
         else:
-            # full_name setter triggers the parse
-            self.full_name = full_name
+            # calls _apply_full_name directly (not the setter) so the
+            # deprecation warning below attributes to this constructor's
+            # caller rather than to the setter
+            self._apply_full_name(full_name, stacklevel=3)
 
     @staticmethod
     def _validate_constants(constants: 'Constants | None') -> 'Constants':
@@ -888,6 +890,13 @@ def full_name(self) -> str:
 
     @full_name.setter
     def full_name(self, value: str | bytes) -> None:
+        self._apply_full_name(value, stacklevel=3)
+
+    def _apply_full_name(self, value: str | bytes, *, stacklevel: int) -> None:
+        # Shared by the setter and the constructor so each can call it
+        # directly with a stacklevel that attributes the warning to *its own*
+        # caller -- the constructor going through the setter would otherwise
+        # add a frame and misattribute the warning to this module.
         self.original = value
 
         if isinstance(value, bytes):
@@ -898,7 +907,7 @@ def full_name(self, value: str | bytes) -> None:
                 "value.decode('utf-8'). See "
                 "https://github.com/derek73/python-nameparser/issues/245",
                 DeprecationWarning,
-                stacklevel=2,
+                stacklevel=stacklevel,
             )
             self._full_name = value.decode(self.encoding)
         else:

tests/test_constants.py

@@ -340,7 +340,7 @@ def test_add_constant_with_explicit_encoding(self) -> None:
         self.assertIn('béck', c.titles)
 
     def test_set_manager_add_bytes_emits_deprecation_warning(self) -> None:
-        # bytes elements are removed in 2.0 (#245); the caller should decode
+        # bytes elements will be removed in 2.0 (#245); the caller should decode
         sm = SetManager(['dr'])
         with pytest.deprecated_call(match="decode"):
             sm.add(b'esq')  # type: ignore[arg-type]  # deliberately deprecated input
@@ -355,9 +355,9 @@ def test_set_manager_add_str_does_not_warn(self) -> None:
 
     def test_set_manager_call_emits_deprecation_warning(self) -> None:
         # __call__ hands out the raw underlying set, bypassing normalization
-        # and cache invalidation; removed in 2.0 (#243)
+        # and cache invalidation; will be removed in 2.0 (#243)
         sm = SetManager(['dr'])
-        with pytest.deprecated_call(match="set"):
+        with pytest.deprecated_call(match="raw underlying set"):
             elements = sm()
         self.assertEqual(elements, {'dr'})
 
@@ -388,6 +388,24 @@ def test_set_manager_remove_missing_member_emits_deprecation_warning(self) -> No
             sm.remove('dr')
         self.assertEqual(len(sm), 0)
 
+    def test_set_manager_remove_mixed_present_and_missing_in_one_call(self) -> None:
+        # a single call mixing a present and a missing member must still warn
+        # (for the missing one) and still invalidate the cache (for the
+        # present one) -- not short-circuit either behavior
+        c = Constants()
+        self.assertIn('hon', c.suffixes_prefixes_titles)  # prime the cache
+        with pytest.deprecated_call(match="discard"):
+            c.titles.remove('hon', 'nope')
+        self.assertNotIn('hon', c.suffixes_prefixes_titles)
+
+    def test_set_manager_discard_mixed_present_and_missing_in_one_call(self) -> None:
+        sm = SetManager(['dr', 'mr'])
+        with warnings.catch_warnings():
+            warnings.simplefilter("error")
+            result = sm.discard('dr', 'nope')
+        self.assertIs(result, sm)
+        self.assertEqual(set(sm), {'mr'})
+
     def test_pickle_roundtrip_preserves_customizations(self) -> None:
         """A pickled Constants must restore its customized collections.
 

tests/test_python_api.py

@@ -35,7 +35,7 @@ def test_escaped_utf8_bytes(self) -> None:
         self.m(hn.last, "Böck", hn)
 
     def test_bytes_full_name_emits_deprecation_warning(self) -> None:
-        # bytes input is removed in 2.0 (#245); the caller should decode
+        # bytes input will be removed in 2.0 (#245); the caller should decode
         with pytest.deprecated_call(match="decode"):
             hn = HumanName(b'John Smith')
         self.m(hn.first, "John", hn)