0
# nameparser
1

2
A simple Python module for parsing human names into their individual components (title, first, middle, last, suffix, nickname). It uses a rule-based approach to classify name parts based on their position in the string and matches against known titles and suffixes, supporting various name formats and provides extensive customization capabilities.
3

4
## Package Information
5

6
- **Package Name**: nameparser
7
- **Package Type**: pypi
8
- **Language**: Python (2.6+ & 3.2+)
9
- **Installation**: `pip install nameparser`
10

11
## Core Imports
12

13
```python
14
from nameparser import HumanName
15
```
16

17
Advanced configuration:
18

19
```python
20
from nameparser import HumanName
21
from nameparser.config import CONSTANTS
22
```
23

24
## Basic Usage
25

26
The nameparser supports various name structures. The general supported format is "Title First Middle Last Suffix", where all pieces are optional. Comma-separated formats like "Last, First" are also supported.
27

28
```python
29
from nameparser import HumanName
30

31
# Standard format: Title First Middle Last Suffix
32
name = HumanName("Dr. Juan Q. Xavier de la Vega III")
33
print(name.title)    # 'Dr.'
34
print(name.first)    # 'Juan'
35
print(name.middle)   # 'Q. Xavier'
36
print(name.last)     # 'de la Vega'
37
print(name.suffix)   # 'III'
38

39
# Comma-separated format: Last, First Middle
40
name = HumanName("Smith, John Michael")
41
print(name.first)    # 'John'
42
print(name.middle)   # 'Michael'
43
print(name.last)     # 'Smith'
44

45
# Names with nicknames in quotes or parentheses
46
name = HumanName('Robert "Bob" Johnson')
47
print(name.first)    # 'Robert'
48
print(name.nickname) # 'Bob'
49
print(name.last)     # 'Johnson'
50

51
name = HumanName('William (Bill) Gates III')
52
print(name.first)    # 'William'
53
print(name.nickname) # 'Bill'
54
print(name.last)     # 'Gates'
55
print(name.suffix)   # 'III'
56

57
# Complex titles and prefixes
58
name = HumanName("The Right Honorable Jane van der Berg-Smith")
59
print(name.title)    # 'The Right Honorable'
60
print(name.first)    # 'Jane'
61
print(name.last)     # 'van der Berg-Smith'
62

63
# Get name as dictionary
64
name_dict = name.as_dict()
65
print(name_dict)     # Dictionary with all components
66

67
# Format names with custom templates
68
name.string_format = "{first} {last}"
69
print(str(name))     # Formatted output
70
```
71

72
## Architecture
73

74
The nameparser library is built around the `HumanName` class which provides a simple interface for parsing and accessing name components. The parser uses:
75

76
- **Rule-based classification**: Name parts are classified based on position and known word lists
77
- **Configurable constants**: Titles, suffixes, prefixes, and conjunctions can be customized
78
- **Multiple input formats**: Supports standard format and comma-separated lastname-first format
79
- **Unicode support**: Handles international characters with proper encoding
80

81
## Capabilities
82

83
### Core Name Parsing
84

85
Main functionality for parsing names into components and accessing parsed results as properties, dictionaries, or formatted strings.
86

87
```python { .api }
88
class HumanName:
89
    def __init__(self, full_name="", constants=CONSTANTS, encoding=DEFAULT_ENCODING,
90
                 string_format=None, initials_format=None, initials_delimiter=None,
91
                 first=None, middle=None, last=None, title=None, suffix=None,
92
                 nickname=None):
93
        """
94
        Parse a person's name into individual components.
95

96
        Args:
97
            full_name (str): The name string to be parsed
98
            constants: Constants instance for configuration (None for per-instance config)
99
            encoding (str): String encoding (default: UTF-8)
100
            string_format (str): Python string formatting template
101
            initials_format (str): Python initials string formatting template
102
            initials_delimiter (str): String delimiter for initials
103
            first (str): Pre-set first name (bypasses parsing)
104
            middle (str): Pre-set middle name (bypasses parsing)
105
            last (str): Pre-set last name (bypasses parsing)
106
            title (str): Pre-set title (bypasses parsing)
107
            suffix (str): Pre-set suffix (bypasses parsing)
108
            nickname (str): Pre-set nickname (bypasses parsing)
109
        """
110

111
    @property
112
    def title(self):
113
        """str: The person's titles."""
114
    
115
    @property
116
    def first(self):
117
        """str: The person's first name."""
118
    
119
    @property
120
    def middle(self):
121
        """str: The person's middle names."""
122
    
123
    @property
124
    def last(self):
125
        """str: The person's last name."""
126
    
127
    @property
128
    def suffix(self):
129
        """str: The person's suffixes."""
130
    
131
    @property
132
    def nickname(self):
133
        """str: The person's nicknames."""
134
    
135
    @property
136
    def surnames(self):
137
        """str: A string of all middle names followed by the last name."""
138
    
139
    @property
140
    def full_name(self):
141
        """str: The string output of the HumanName instance."""
142
    
143
    @property
144
    def original(self):
145
        """str: The original string, untouched by the parser."""
146
    
147
    @property
148
    def unparsable(self):
149
        """bool: Whether the name could be parsed successfully."""
150
    
151
    @property
152
    def has_own_config(self):
153
        """bool: True if using per-instance configuration."""
154
    
155
    def as_dict(self, include_empty=True):
156
        """
157
        Return the parsed name as a dictionary of its attributes.
158

159
        Args:
160
            include_empty (bool): Include keys for empty name attributes
161

162
        Returns:
163
            dict: Dictionary containing name components
164
        """
165
```
166

167
[Core Name Parsing](./core-parsing.md)
168

169
### Name Formatting and Initials
170

171
Format names with custom templates and generate initials from name components.
172

173
```python { .api }
174
def initials(self):
175
    """
176
    Return period-delimited initials of first, middle and optionally last name.
177
    
178
    Returns:
179
        str: Formatted initials string based on initials_format template
180
    """
181

182
def initials_list(self):
183
    """
184
    Returns the initials as a list of individual letters.
185
    
186
    Returns:
187
        list: List of initial letters from first, middle, and last names
188
    """
189

190
def capitalize(self, force=None):
191
    """
192
    Correct capitalization of names entered in all upper or lower case.
193
    
194
    Args:
195
        force (bool): Forces capitalization of mixed case strings
196
    """
197
```
198

199
[Name Formatting](./formatting.md)
200

201
### Configuration and Customization
202

203
Customize parsing behavior through configuration constants and per-instance settings.
204

205
```python { .api }
206
class Constants:
207
    def __init__(self, prefixes=PREFIXES, suffix_acronyms=SUFFIX_ACRONYMS,
208
                 suffix_not_acronyms=SUFFIX_NOT_ACRONYMS, titles=TITLES,
209
                 first_name_titles=FIRST_NAME_TITLES, conjunctions=CONJUNCTIONS,
210
                 capitalization_exceptions=CAPITALIZATION_EXCEPTIONS, regexes=REGEXES):
211
        """
212
        Configuration container for parser behavior.
213
        
214
        Args:
215
            prefixes: Name prefixes like 'de', 'van', 'von'
216
            suffix_acronyms: Acronym suffixes like 'Ph.D.', 'M.D.'  
217
            suffix_not_acronyms: Non-acronym suffixes like 'Jr.', 'Sr.'
218
            titles: Person titles like 'Dr.', 'Mr.', 'Hon.'
219
            first_name_titles: Special titles that indicate first names like 'Sir'
220
            conjunctions: Name conjunctions like 'and', 'of', 'the'
221
            capitalization_exceptions: Special capitalization rules
222
            regexes: Regular expression patterns for parsing
223
        """
224

225
    @property
226
    def suffixes_prefixes_titles(self):
227
        """set: Combined set of all suffixes, prefixes, and titles for lookups."""
228

229
class SetManager:
230
    def add(self, *strings):
231
        """
232
        Add normalized strings to the set. Returns self for chaining.
233
        
234
        Args:
235
            *strings: One or more strings to add
236
            
237
        Returns:
238
            SetManager: Self for method chaining
239
        """
240
    
241
    def remove(self, *strings):
242
        """
243
        Remove normalized strings from the set. Returns self for chaining.
244
        
245
        Args:
246
            *strings: One or more strings to remove
247
            
248
        Returns:
249
            SetManager: Self for method chaining
250
        """
251
```
252

253
[Configuration](./configuration.md)
254

255
## Types
256

257
```python { .api }
258
# Main class for name parsing
259
class HumanName:
260
    # Name component properties
261
    title: str
262
    first: str
263
    middle: str
264
    last: str
265
    suffix: str
266
    nickname: str
267
    surnames: str
268
    full_name: str
269
    original: str
270
    unparsable: bool
271
    has_own_config: bool
272
    
273
    # Internal list properties (accessible but primarily for advanced use)
274
    title_list: list
275
    first_list: list
276
    middle_list: list
277
    last_list: list
278
    suffix_list: list
279
    nickname_list: list
280
    surnames_list: list
281

282
# Configuration classes
283
class Constants:
284
    string_format: str
285
    initials_format: str
286
    initials_delimiter: str
287
    empty_attribute_default: str
288
    capitalize_name: bool
289
    force_mixed_case_capitalization: bool
290

291
class SetManager:
292
    elements: set
293

294
class TupleManager(dict):
295
    pass
296
```