Add type hints

This also required some refactoring:
* I removed some code that seemed dead.
* I created a subclass of TupleManager for regexes with a fallback.
  When accessing regexes previously, it was possible to get None.
* I had to move all setter next to their getters due to a bug in mypy.
  See python/mypy#1465

Author: v--

nameparser/config/__init__.py

@@ -27,8 +27,12 @@
 ``hn.C`` will be a reference to the module config, possibly yielding 
 unexpected results. See `Customizing the Parser <customize.html>`_.
 """
+import re
 import sys
-from collections.abc import Set
+from collections.abc import Iterable, Iterator, Mapping, Set
+from typing import Any, TypeVar
+
+from typing_extensions import Self
 
 from nameparser.util import lc
 from nameparser.config.prefixes import PREFIXES
@@ -38,7 +42,7 @@
 from nameparser.config.suffixes import SUFFIX_NOT_ACRONYMS
 from nameparser.config.titles import TITLES
 from nameparser.config.titles import FIRST_NAME_TITLES
-from nameparser.config.regexes import REGEXES
+from nameparser.config.regexes import EMPTY_REGEX, REGEXES
 
 DEFAULT_ENCODING = 'UTF-8'
 
@@ -55,25 +59,25 @@ class SetManager(Set):
 
     '''
 
-    def __init__(self, elements):
+    def __init__(self, elements: Iterable[str]) -> None:
         self.elements = set(elements)
 
-    def __call__(self):
+    def __call__(self) -> Set[str]:
         return self.elements
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return "SetManager({})".format(self.elements)  # used for docs
 
-    def __iter__(self):
+    def __iter__(self) -> Iterator[str]:
         return iter(self.elements)
 
-    def __contains__(self, value):
+    def __contains__(self, value: object) -> bool:
         return value in self.elements
 
-    def __len__(self):
+    def __len__(self) -> int:
         return len(self.elements)
 
-    def add_with_encoding(self, s, encoding=None):
+    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
         explicit `encoding` parameter to specify the encoding of binary strings that
@@ -87,44 +91,58 @@ def add_with_encoding(self, s, encoding=None):
             s = s.decode(encoding)
         self.elements.add(lc(s))
 
-    def add(self, *strings):
+    def add(self, *strings: str) -> Self:
         """
         Add the lower case and no-period version of the string arguments to the set.
         Can pass a list of strings. Returns ``self`` for chaining.
         """
-        [self.add_with_encoding(s) for s in strings]
+        for s in strings:
+            self.add_with_encoding(s)
+
         return self
 
-    def remove(self, *strings):
+    def remove(self, *strings: str) -> Self:
         """
         Remove the lower case and no-period version of the string arguments from the set.
         Returns ``self`` for chaining.
         """
-        [self.elements.remove(lc(s)) for s in strings if lc(s) in self.elements]
+        for s in strings:
+            if (lower := lc(s)) in self.elements:
+                self.elements.remove(lower)
+
         return self
 
 
-class TupleManager(dict):
+T = TypeVar('T')
+
+
+class TupleManager(dict[str, T]):
     '''
     A dictionary with dot.notation access. Subclass of ``dict``. Makes the tuple constants 
     more friendly.
     '''
 
-    def __getattr__(self, attr):
+    def __getattr__(self, attr: str) -> T | None:
         return self.get(attr)
+
     __setattr__ = dict.__setitem__
     __delattr__ = dict.__delitem__
 
-    def __getstate__(self):
+    def __getstate__(self) -> Mapping[str, T]:
         return dict(self)
 
-    def __setstate__(self, state):
-        self.__init__(state)
+    def __setstate__(self, state: Mapping[str, T]) -> None:
+        self.update(state)
 
-    def __reduce__(self):
+    def __reduce__(self) -> tuple[type, tuple[()], Mapping[str, T]]:
         return (TupleManager, (), self.__getstate__())
 
 
+class RegexTupleManager(TupleManager[re.Pattern[str]]):
+    def __getattr__(self, attr: str) -> re.Pattern[str]:
+        return self.get(attr, EMPTY_REGEX)
+
+
 class Constants:
     """
     An instance of this class hold all of the configuration constants for the parser.
@@ -149,6 +167,17 @@ class Constants:
         :py:attr:`regexes`  wrapped with :py:class:`TupleManager`.
     """
 
+    prefixes: SetManager
+    suffix_acronyms: SetManager
+    suffix_not_acronyms: SetManager
+    titles: SetManager
+    first_name_titles: SetManager
+    conjunctions: SetManager
+    capitalization_exceptions: TupleManager[str]
+    regexes: RegexTupleManager
+
+    _pst: Set[str] | None
+
     string_format = "{title} {first} {middle} {last} {suffix} ({nickname})"
     """
     The default string format use for all new `HumanName` instances.
@@ -168,17 +197,17 @@ class Constants:
     empty_attribute_default = ''
     """
     Default return value for empty attributes.
-    
+
     .. doctest::
-    
+
         >>> from nameparser.config import CONSTANTS
         >>> CONSTANTS.empty_attribute_default = None
         >>> name = HumanName("John Doe")
         >>> name.title
         None
         >>>name.first
         'John'
-        
+
     """
 
     capitalize_name = False
@@ -213,38 +242,38 @@ class Constants:
     """
 
     def __init__(self,
-                 prefixes=PREFIXES,
-                 suffix_acronyms=SUFFIX_ACRONYMS,
-                 suffix_not_acronyms=SUFFIX_NOT_ACRONYMS,
-                 titles=TITLES,
-                 first_name_titles=FIRST_NAME_TITLES,
-                 conjunctions=CONJUNCTIONS,
-                 capitalization_exceptions=CAPITALIZATION_EXCEPTIONS,
-                 regexes=REGEXES
-                 ):
+                 prefixes: Iterable[str] = PREFIXES,
+                 suffix_acronyms: Iterable[str] = SUFFIX_ACRONYMS,
+                 suffix_not_acronyms: Iterable[str] = SUFFIX_NOT_ACRONYMS,
+                 titles: Iterable[str] = TITLES,
+                 first_name_titles: Iterable[str] = FIRST_NAME_TITLES,
+                 conjunctions: Iterable[str] = CONJUNCTIONS,
+                 capitalization_exceptions: TupleManager[str] | Iterable[tuple[str, str]] = CAPITALIZATION_EXCEPTIONS,
+                 regexes: RegexTupleManager | TupleManager[re.Pattern[str]] | Iterable[tuple[str, re.Pattern[str]]] = REGEXES
+                 ) -> None:
         self.prefixes = SetManager(prefixes)
         self.suffix_acronyms = SetManager(suffix_acronyms)
         self.suffix_not_acronyms = SetManager(suffix_not_acronyms)
         self.titles = SetManager(titles)
         self.first_name_titles = SetManager(first_name_titles)
         self.conjunctions = SetManager(conjunctions)
         self.capitalization_exceptions = TupleManager(capitalization_exceptions)
-        self.regexes = TupleManager(regexes)
+        self.regexes = RegexTupleManager(regexes)
         self._pst = None
 
     @property
-    def suffixes_prefixes_titles(self):
+    def suffixes_prefixes_titles(self) -> Set[str]:
         if not self._pst:
             self._pst = self.prefixes | self.suffix_acronyms | self.suffix_not_acronyms | self.titles
         return self._pst
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return "<Constants() instance>"
 
-    def __setstate__(self, state):
-        self.__init__(state)
+    def __setstate__(self, state: Mapping[str, Any]) -> None:
+        Constants.__init__(self, state)
 
-    def __getstate__(self):
+    def __getstate__(self) -> Mapping[str, Any]:
         attrs = [x for x in dir(self) if not x.startswith('_')]
         return dict([(a, getattr(self, a)) for a in attrs])
 

nameparser/config/regexes.py

@@ -16,6 +16,8 @@
         '[\u2600-\u26FF\u2700-\u27BF])+', 
         re.UNICODE)
 
+EMPTY_REGEX = re.compile('')
+
 REGEXES = set([
     ("spaces", re.compile(r"\s+", re.U)),
     ("word", re.compile(r"(\w|\.)+", re.U)),