0
# Core Name Parsing
1

2
Main functionality for parsing human names into individual components and accessing the parsed results through various interfaces.
3

4
## Capabilities
5

6
### HumanName Class
7

8
The primary class for parsing human names. Automatically parses names on instantiation or when the `full_name` property is set.
9

10
```python { .api }
11
class HumanName:
12
    def __init__(self, full_name="", constants=CONSTANTS, encoding=DEFAULT_ENCODING,
13
                 string_format=None, initials_format=None, initials_delimiter=None,
14
                 first=None, middle=None, last=None, title=None, suffix=None,
15
                 nickname=None):
16
        """
17
        Parse a person's name into individual components.
18

19
        Args:
20
            full_name (str): The name string to be parsed
21
            constants: Constants instance for configuration (None for per-instance config)
22
            encoding (str): String encoding (default: UTF-8)
23
            string_format (str): Python string formatting template
24
            initials_format (str): Python initials string formatting template
25
            initials_delimiter (str): String delimiter for initials
26
            first (str): Pre-set first name (bypasses parsing)
27
            middle (str): Pre-set middle name (bypasses parsing)
28
            last (str): Pre-set last name (bypasses parsing)
29
            title (str): Pre-set title (bypasses parsing)
30
            suffix (str): Pre-set suffix (bypasses parsing)
31
            nickname (str): Pre-set nickname (bypasses parsing)
32
        """
33
```
34

35
**Usage Examples:**
36

37
```python
38
from nameparser import HumanName
39

40
# Basic parsing
41
name = HumanName("Dr. Martin Luther King Jr.")
42
print(name.title)   # 'Dr.'
43
print(name.first)   # 'Martin'
44
print(name.middle)  # 'Luther'
45
print(name.last)    # 'King'
46
print(name.suffix)  # 'Jr.'
47

48
# Comma-separated format
49
name = HumanName("King Jr., Dr. Martin Luther")
50
print(name.title)   # 'Dr.'
51
print(name.first)   # 'Martin'
52
print(name.middle)  # 'Luther'
53
print(name.last)    # 'King'
54
print(name.suffix)  # 'Jr.'
55

56
# Name with nickname in quotes
57
name = HumanName('Robert "Bob" Johnson')
58
print(name.first)    # 'Robert'
59
print(name.nickname) # 'Bob'
60
print(name.last)     # 'Johnson'
61

62
# Name with nickname in parentheses
63
name = HumanName('William (Bill) Gates III')
64
print(name.first)    # 'William'
65
print(name.nickname) # 'Bill'
66
print(name.last)     # 'Gates'
67
print(name.suffix)   # 'III'
68

69
# Complex titles and prefixes
70
name = HumanName("The Right Honorable Jane van der Berg-Smith")
71
print(name.title)   # 'The Right Honorable'
72
print(name.first)   # 'Jane'
73
print(name.last)    # 'van der Berg-Smith'
74
```
75

76
### Name Component Properties
77

78
Access individual components of the parsed name as string properties.
79

80
```python { .api }
81
@property
82
def title(self) -> str:
83
    """
84
    The person's titles. Any string of consecutive pieces in titles or
85
    conjunctions at the beginning of full_name.
86
    """
87

88
@property
89
def first(self) -> str:
90
    """
91
    The person's first name. The first name piece after any known
92
    title pieces parsed from full_name.
93
    """
94

95
@property
96
def middle(self) -> str:
97
    """
98
    The person's middle names. All name pieces after the first name and
99
    before the last name parsed from full_name.
100
    """
101

102
@property
103
def last(self) -> str:
104
    """
105
    The person's last name. The last name piece parsed from full_name.
106
    """
107

108
@property
109
def suffix(self) -> str:
110
    """
111
    The person's suffixes. Pieces at the end of the name that are found in 
112
    suffixes, or pieces that are at the end of comma separated formats.
113
    """
114

115
@property
116
def nickname(self) -> str:
117
    """
118
    The person's nicknames. Any text found inside of quotes ("") or
119
    parenthesis (()).
120
    """
121

122
@property
123
def surnames(self) -> str:
124
    """
125
    A string of all middle names followed by the last name.
126
    """
127

128
@property
129
def full_name(self) -> str:
130
    """The string output of the HumanName instance."""
131

132
@property
133
def original(self) -> str:
134
    """The original string, untouched by the parser."""
135

136
@property
137
def unparsable(self) -> bool:
138
    """Whether the name could be parsed successfully."""
139

140
@property
141
def has_own_config(self) -> bool:
142
    """
143
    True if this instance is not using the shared module-level
144
    configuration.
145
    """
146
```
147

148
### Dictionary Conversion
149

150
Convert parsed names to dictionary format for serialization or processing.
151

152
```python { .api }
153
def as_dict(self, include_empty: bool = True) -> dict:
154
    """
155
    Return the parsed name as a dictionary of its attributes.
156

157
    Parameters:
158
    - include_empty: Include keys in the dictionary for empty name attributes
159

160
    Returns:
161
    Dictionary containing name components
162
    """
163
```
164

165
**Usage Examples:**
166

167
```python
168
name = HumanName("Bob Dole")
169
print(name.as_dict())
170
# {'last': 'Dole', 'suffix': '', 'title': '', 'middle': '', 'nickname': '', 'first': 'Bob'}
171

172
print(name.as_dict(False))
173
# {'last': 'Dole', 'first': 'Bob'}
174
```
175

176
### Name Component Setters
177

178
Set individual name components programmatically, with automatic list handling.
179

180
```python { .api }
181
@title.setter
182
def title(self, value: str | list | None) -> None:
183
    """Set the title component."""
184

185
@first.setter
186
def first(self, value: str | list | None) -> None:
187
    """Set the first name component."""
188

189
@middle.setter
190
def middle(self, value: str | list | None) -> None:
191
    """Set the middle name component."""
192

193
@last.setter
194
def last(self, value: str | list | None) -> None:
195
    """Set the last name component."""
196

197
@suffix.setter
198
def suffix(self, value: str | list | None) -> None:
199
    """Set the suffix component."""
200

201
@nickname.setter
202
def nickname(self, value: str | list | None) -> None:
203
    """Set the nickname component."""
204
```
205

206
**Usage Examples:**
207

208
```python
209
name = HumanName()
210
name.first = "John"
211
name.last = "Doe"
212
name.title = "Dr."
213
print(str(name))  # 'Dr. John Doe'
214

215
# Setting with lists
216
name.middle = ["James", "Robert"]
217
print(name.middle)  # 'James Robert'
218
```
219

220
### Parsing Control
221

222
Manual parsing control and re-parsing after configuration changes.
223

224
```python { .api }
225
def parse_full_name(self) -> None:
226
    """
227
    The main parse method. Run upon assignment to full_name or instantiation.
228
    Can be called manually after configuration changes.
229
    """
230
```
231

232
**Usage Examples:**
233

234
```python
235
from nameparser import HumanName
236
from nameparser.config import CONSTANTS
237

238
name = HumanName("Dean Robert Johns", None)  # Per-instance config
239
name.C.titles.add('dean')
240
name.parse_full_name()  # Re-parse after config change
241
```
242

243
### Magic Methods
244

245
Standard Python object interface methods for comparison, iteration, and indexing.
246

247
```python { .api }
248
def __str__(self) -> str:
249
    """String representation using string_format template."""
250

251
def __repr__(self) -> str:
252
    """Developer-friendly representation showing all components."""
253

254
def __eq__(self, other) -> bool:
255
    """Equality comparison (case-insensitive)."""
256

257
def __ne__(self, other) -> bool:
258
    """Inequality comparison."""
259

260
def __iter__(self):
261
    """Iterate over non-empty name components."""
262

263
def __len__(self) -> int:
264
    """Number of non-empty name components."""
265

266
def __getitem__(self, key: int | slice) -> str | list:
267
    """Access name components by index or slice."""
268

269
def __setitem__(self, key: str, value: str | list | None) -> None:
270
    """Set name components by key."""
271

272
def __hash__(self) -> int:
273
    """Hash based on string representation."""
274
```
275

276
**Usage Examples:**
277

278
```python
279
name1 = HumanName("John Doe")
280
name2 = HumanName("JOHN DOE")
281
print(name1 == name2)  # True (case-insensitive)
282

283
# Iteration
284
for component in name1:
285
    print(component)  # Prints non-empty components
286

287
# Length
288
print(len(name1))  # 2 (first and last)
289

290
# Indexing
291
print(name1[0])  # 'John' (first component)
292
print(name1[-1]) # 'Doe' (last component)
293

294
# Slicing
295
print(name1[0:2]) # ['John', 'Doe']
296
```
297

298
### Additional Parsing Methods
299

300
Methods for manual parsing control and parsing utilities.
301

302
```python { .api }
303
def parse_full_name(self):
304
    """
305
    The main parse method. Run upon assignment to full_name or instantiation.
306
    Can be called manually after configuration changes.
307
    """
308

309
def collapse_whitespace(self, string):
310
    """
311
    Collapse multiple spaces into single space and handle trailing commas.
312
    
313
    Args:
314
        string (str): String to clean up
315
        
316
    Returns:
317
        str: Cleaned string with normalized whitespace
318
    """
319
```
320

321
**Usage Examples:**
322

323
```python
324
from nameparser import HumanName
325
from nameparser.config import CONSTANTS
326

327
# Manual re-parsing after config changes
328
name = HumanName("Dean Robert Johns", None)  # Per-instance config
329
name.C.titles.add('dean')
330
name.parse_full_name()  # Re-parse after config change
331
print(name.title)  # 'Dean'
332

333
# Utility function for whitespace handling
334
name = HumanName("John Smith")
335
cleaned = name.collapse_whitespace("  John   Smith  ")
336
print(cleaned)  # 'John Smith'
337
```
338

339
### Name Classification Helpers
340

341
Methods for testing whether name components belong to specific categories.
342

343
```python { .api }
344
def is_title(self, value):
345
    """Check if value is in the titles set."""
346

347
def is_conjunction(self, piece):
348
    """Check if piece is a conjunction and not an initial."""
349

350
def is_prefix(self, piece):
351
    """Check if piece is in the prefixes set."""
352

353
def is_suffix(self, piece):
354
    """Check if piece is in the suffixes set and not an initial."""
355

356
def is_roman_numeral(self, value):
357
    """Check if value matches roman numeral pattern."""
358

359
def is_rootname(self, piece):
360
    """Check if piece is a core name part (not title, suffix, or prefix)."""
361

362
def is_an_initial(self, value):
363
    """Check if value is a single letter or letter with period."""
364

365
def are_suffixes(self, pieces):
366
    """Check if all pieces in list are suffixes."""
367
```
368

369
**Usage Examples:**
370

371
```python
372
from nameparser import HumanName
373

374
name = HumanName("Dr. John van der Berg III")
375

376
# Test individual components
377
print(name.is_title("Dr."))         # True
378
print(name.is_prefix("van"))        # True  
379
print(name.is_conjunction("der"))   # True
380
print(name.is_suffix("III"))        # True
381
print(name.is_roman_numeral("III")) # True
382
print(name.is_an_initial("J."))     # True
383
print(name.is_rootname("John"))     # True
384

385
# Test with lists
386
print(name.is_suffix(["Jr", "Sr"]))    # True
387
print(name.are_suffixes(["III", "Jr"])) # True
388
```