Add type stubs

Author: v--

CONTRIBUTING.md

@@ -63,6 +63,10 @@ your names to `TEST_NAMES`. A test attempts to try the 3 different
 comma variations of these names automatically and make sure things
 don't blow up, so it can be a helpful regression indicator.
 
+Type Hints
+----------
+
+Make sure to update the [type stubs](https://typing.python.org/en/latest/guides/writing_stubs.html) (`.pyi` files) to reflect changes in the code. The repository contains a configuration for [mypy](https://mypy-lang.org/).
 
 New Releases
 ------------

nameparser/__init__.pyi

@@ -0,0 +1,6 @@
+from nameparser.parser import HumanName as HumanName
+
+VERSION: tuple[int]
+__version__: str
+__author_email__: str
+__url__: str

nameparser/config/__init__.pyi

@@ -0,0 +1,72 @@
+import re
+from collections.abc import Set
+from typing import Collection, Dict, Generic, Iterable, Iterator, Mapping, TypeVar
+
+from nameparser.config.capitalization import CAPITALIZATION_EXCEPTIONS as CAPITALIZATION_EXCEPTIONS
+from nameparser.config.conjunctions import CONJUNCTIONS as CONJUNCTIONS
+from nameparser.config.prefixes import PREFIXES as PREFIXES
+from nameparser.config.regexes import REGEXES as REGEXES
+from nameparser.config.suffixes import SUFFIX_ACRONYMS as SUFFIX_ACRONYMS
+from nameparser.config.suffixes import SUFFIX_NOT_ACRONYMS as SUFFIX_NOT_ACRONYMS
+from nameparser.config.titles import FIRST_NAME_TITLES as FIRST_NAME_TITLES
+from nameparser.config.titles import TITLES as TITLES
+
+DEFAULT_ENCODING: str
+
+
+T = TypeVar('T')
+
+
+class SetManager(Generic[T], Set):
+    elements: Set[T]
+    def __init__(self, elements: Iterable[T]) -> None: ...
+    def __call__(self) -> Set[T]: ...
+    def __iter__(self) -> Iterator[T]: ...
+    def __contains__(self, value: object) -> bool: ...
+    def __len__(self) -> int: ...
+    def next(self) -> T: ...
+    count: int
+    def __next__(self) -> T: ...
+    def add_with_encoding(self, s: T, encoding: str | None = None) -> None: ...
+    def add(self, *strings: str) -> None: ...
+    def remove(self, *strings: str) -> None: ...
+
+
+class TupleManager(Dict[str, T]):
+    def __getattr__(self, attr: str) -> T: ...
+    def __setattr__(self, attr: str, value: T) -> None: ...
+    def __delattr__(self, attr: str) -> None: ...
+    def __reduce__(self) -> tuple[type[TupleManager], tuple, Mapping[str, T]]: ...
+
+
+class Constants:
+    string_format: str
+    initials_format: str
+    initials_delimiter: str
+    empty_attribute_default: str
+    capitalize_name: bool
+    force_mixed_case_capitalization: bool
+    prefixes: SetManager[str]
+    suffix_acronyms: SetManager[str]
+    suffix_not_acronyms: SetManager[str]
+    titles: SetManager[str]
+    first_name_titles: SetManager[str]
+    conjunctions: SetManager[str]
+    capitalization_exceptions: TupleManager[str]
+    regexes: TupleManager[re.Pattern]
+    @property
+    def suffixes_prefixes_titles(self) -> SetManager[str]: ...
+    def __init__(
+        self,
+        prefixes: Collection[str] = PREFIXES,
+        suffix_acronyms: Collection[str] = SUFFIX_ACRONYMS,
+        suffix_not_acronyms: Collection[str] = SUFFIX_NOT_ACRONYMS,
+        titles: Collection[str] = TITLES,
+        first_name_titles: Collection[str] = FIRST_NAME_TITLES,
+        conjunctions: Collection[str] = CONJUNCTIONS,
+        capitalization_exceptions: Collection[tuple[str, str]] = CAPITALIZATION_EXCEPTIONS,
+        regexes: Collection[tuple[str, re.Pattern]] = REGEXES,
+     ) -> None: ...
+
+
+CONSTANTS: Constants

nameparser/config/capitalization.pyi

@@ -0,0 +1 @@
+CAPITALIZATION_EXCEPTIONS: set[tuple[str, str]]

nameparser/config/conjunctions.pyi

@@ -0,0 +1 @@
+CONJUNCTIONS: set[str]

nameparser/config/prefixes.pyi

@@ -0,0 +1 @@
+PREFIXES: set[str]

nameparser/config/regexes.pyi

@@ -0,0 +1,4 @@
+import re
+
+re_emoji: re.Pattern
+REGEXES: set[tuple[str, re.Pattern]]

nameparser/config/suffixes.pyi

@@ -0,0 +1,2 @@
+SUFFIX_NOT_ACRONYMS: set[str]
+SUFFIX_ACRONYMS: set[str]

nameparser/config/titles.pyi

@@ -0,0 +1,2 @@
+FIRST_NAME_TITLES: set[str]
+TITLES: set[str]

nameparser/parser.pyi

@@ -0,0 +1,107 @@
+from typing import Iterable, Iterator, Literal
+
+from nameparser.config import CONSTANTS, DEFAULT_ENCODING, Constants
+
+ENCODING: str
+
+
+def group_contiguous_integers(data: Iterable[int]) -> list[tuple[int, int]]:
+    ...
+
+
+class HumanName:
+    C: Constants
+    original: str
+    unparsable: bool
+    encoding: str
+    string_format: str
+    initials_format: str
+    initials_delimiter: str
+
+    def __init__(
+        self,
+        full_name: str = '',
+        constants: Constants = CONSTANTS,
+        encoding: str = DEFAULT_ENCODING,
+        string_format: str | None = None,
+        initials_format: str | None = None,
+        initials_delimiter: str | None = None,
+        first: str | None = None,
+        middle: str | None = None,
+        last: str | None = None,
+        title: str | None = None,
+        suffix: str | None = None,
+        nickname: str | None = None,
+    ) -> None: ...
+
+    def __iter__(self) -> Iterator[str]: ...
+    def __len__(self) -> int: ...
+    def __eq__(self, other: object) -> bool: ...
+    def __ne__(self, other: object) -> bool: ...
+    def __getitem__(self, key: str | slice[int, int, int | None]) -> str: ...
+    def __setitem__(self, key: str, value: str | Iterable[str]) -> None: ...
+    def next(self) -> str: ...
+    def __next__(self) -> str: ...
+    def __hash__(self) -> int: ...
+    def as_dict(self, include_empty: bool = True) -> dict[str, str]: ...
+    def initials_list(self) -> list[str]: ...
+    def initials(self) -> list[str]: ...
+    @property
+    def has_own_config(self) -> bool: ...
+    @property
+    def title(self) -> str: ...
+    @title.setter
+    def title(self, value: str) -> str: ...
+    @property
+    def first(self) -> str: ...
+    @first.setter
+    def first(self, value: str) -> str: ...
+    @property
+    def middle(self) -> str: ...
+    @middle.setter
+    def middle(self, value: str) -> str: ...
+    @property
+    def last(self) -> str: ...
+    @last.setter
+    def last(self, value: str) -> str: ...
+    @property
+    def suffix(self) -> str: ...
+    @suffix.setter
+    def suffix(self, value: str) -> str: ...
+    @property
+    def nickname(self) -> str: ...
+    @nickname.setter
+    def nickname(self, value: str) -> str: ...
+    @property
+    def surnames_list(self) -> list[str]: ...
+    @property
+    def surnames(self) -> str: ...
+    def is_title(self, value: str)-> bool: ...
+    def is_conjunction(self, piece: str)-> bool: ...
+    def is_prefix(self, piece: str)-> bool: ...
+    def is_roman_numeral(self, value: str)-> bool: ...
+    def is_suffix(self, piece: str)-> bool: ...
+    def are_suffixes(self, pieces: str)-> bool: ...
+    def is_rootname(self, piece: str)-> bool: ...
+    def is_an_initial(self, value: str)-> bool: ...
+    full_name: str
+    def collapse_whitespace(self, string: str) -> str: ...
+    def pre_process(self) -> None: ...
+    def post_process(self) -> None: ...
+    def fix_phd(self) -> None: ...
+    def parse_nicknames(self) -> None: ...
+    def squash_emoji(self) -> None: ...
+    def handle_firstnames(self) -> None: ...
+    title_list: list[str]
+    first_list: list[str]
+    middle_list: list[str]
+    last_list: list[str]
+    suffix_list: list[str]
+    nickname_list: list[str]
+    def parse_full_name(self) -> None: ...
+    def parse_pieces(self, parts: Iterable[str], additional_parts_count: int = 0) -> str: ...
+    def join_on_conjunctions(self, pieces: Iterable[str], additional_parts_count: int = 0) -> str: ...
+    def cap_word(self, word: str, attribute: Literal['title', 'first', 'middle', 'last', 'suffix', 'nickname', 'surnames']) -> str: ...
+    def cap_piece(self, piece: str, attribute: Literal['title', 'first', 'middle', 'last', 'suffix', 'nickname', 'surnames']) -> str: ...
+    def capitalize(self, force: bool | None = None) -> None: ...
+    def handle_capitalization(self) -> None: ...