fix: guard _on_change in add_with_encoding/clear against no-op mutations; correct lc() docstrings

- add_with_encoding and clear now only fire _on_change when the set
  actually changes, consistent with remove()'s existing changed guard
- Correct 'no periods' to 'leading/trailing-periods-stripped' in lc(),
  is_prefix, is_first_name_prefix, and add_with_encoding docstrings

Author: derek73

nameparser/config/__init__.py

@@ -87,7 +87,7 @@ def __len__(self) -> int:
 
     def add_with_encoding(self, s: str, encoding: str | None = None) -> None:
         """
-        Add the lower case and no-period version of the string to the set. Pass an
+        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).
         """
@@ -97,13 +97,15 @@ def add_with_encoding(self, s: str, encoding: str | None = None) -> None:
         encoding = encoding or stdin_encoding or DEFAULT_ENCODING
         if isinstance(s, bytes):
             s = s.decode(encoding)
-        self.elements.add(lc(s))
-        if self._on_change:
-            self._on_change()
+        normalized = lc(s)
+        if normalized not in self.elements:
+            self.elements.add(normalized)
+            if self._on_change:
+                self._on_change()
 
     def add(self, *strings: str) -> Self:
         """
-        Add the lower case and no-period version of the string arguments to the set.
+        Add the lowercased, leading/trailing-periods-stripped version of the string arguments to the set.
         Can pass a list of strings. Returns ``self`` for chaining.
         """
         for s in strings:
@@ -127,9 +129,10 @@ def remove(self, *strings: str) -> Self:
 
     def clear(self) -> Self:
         """Remove all entries from the set. Returns ``self`` for chaining."""
-        self.elements.clear()
-        if self._on_change:
-            self._on_change()
+        if self.elements:
+            self.elements.clear()
+            if self._on_change:
+                self._on_change()
         return self
 
 

nameparser/parser.py

@@ -551,7 +551,7 @@ def is_conjunction(self, piece: str) -> bool:
 
     def is_prefix(self, piece: str) -> bool:
         """
-        Lowercase and no periods version of piece is in the
+        Lowercased, leading/trailing-periods-stripped version of piece is in the
         :py:data:`~nameparser.config.prefixes.PREFIXES` set.
         """
         if isinstance(piece, list):
@@ -562,7 +562,7 @@ def is_prefix(self, piece: str) -> bool:
             return lc(piece) in self.C.prefixes
 
     def is_first_name_prefix(self, piece: str) -> bool:
-        """Lowercase and no periods version of piece is in :py:attr:`~nameparser.config.Constants.first_name_prefixes`."""
+        """Lowercased, leading/trailing-periods-stripped version of piece is in :py:attr:`~nameparser.config.Constants.first_name_prefixes`."""
         return lc(piece) in self.C.first_name_prefixes
 
     def _join_first_name_prefix(self, pieces: list[str], reserve_last: bool) -> list[str]:

nameparser/util.py

@@ -11,7 +11,7 @@
 
 
 def lc(value: str) -> str:
-    """Lower case and remove any periods to normalize for comparison."""
+    """Lowercase and strip leading/trailing periods to normalize for comparison."""
     if not value:
         return ''
     return value.lower().strip('.')