0
# Configuration and Customization
1

2
Comprehensive configuration system for customizing parsing behavior, including management of titles, suffixes, prefixes, conjunctions, and parsing rules.
3

4
## Capabilities
5

6
### Constants Class
7

8
Main configuration container that holds all parsing rules and behavior settings.
9

10
```python { .api }
11
class Constants:
12
    def __init__(self, prefixes=PREFIXES, suffix_acronyms=SUFFIX_ACRONYMS,
13
                 suffix_not_acronyms=SUFFIX_NOT_ACRONYMS, titles=TITLES,
14
                 first_name_titles=FIRST_NAME_TITLES, conjunctions=CONJUNCTIONS,
15
                 capitalization_exceptions=CAPITALIZATION_EXCEPTIONS, regexes=REGEXES):
16
        """
17
        Configuration container for parser behavior.
18

19
        Args:
20
            prefixes: Name prefixes like 'de', 'van', 'von'
21
            suffix_acronyms: Acronym suffixes like 'Ph.D.', 'M.D.'
22
            suffix_not_acronyms: Non-acronym suffixes like 'Jr.', 'Sr.'
23
            titles: Person titles like 'Dr.', 'Mr.', 'Hon.'
24
            first_name_titles: Special titles that indicate first names like 'Sir'
25
            conjunctions: Name conjunctions like 'and', 'of', 'the'
26
            capitalization_exceptions: Special capitalization rules
27
            regexes: Regular expression patterns for parsing
28
        """
29

30
    @property
31
    def suffixes_prefixes_titles(self):
32
        """Combined set of all suffixes, prefixes, and titles for lookups."""
33

34
    # Class-level formatting defaults
35
    string_format = "{title} {first} {middle} {last} {suffix} ({nickname})"
36
    initials_format = "{first} {middle} {last}"
37
    initials_delimiter = "."
38
    empty_attribute_default = ""
39
    capitalize_name = False
40
    force_mixed_case_capitalization = False
41
```
42

43
**Usage Examples:**
44

45
```python
46
from nameparser import HumanName
47
from nameparser.config import Constants
48

49
# Create custom configuration
50
custom_config = Constants()
51
custom_config.titles.add('Prof', 'Dean')
52
custom_config.suffixes.add('Esq')
53

54
# Use with HumanName instance
55
name = HumanName("Prof John Smith Esq", constants=custom_config)
56
print(name.title)   # 'Prof'
57
print(name.suffix)  # 'Esq'
58
```
59

60
### SetManager Class
61

62
Specialized set class for managing configuration word lists with normalization and method chaining.
63

64
```python { .api }
65
class SetManager:
66
    def __init__(self, elements):
67
        """
68
        Easily add and remove config variables per module or instance.
69
        Normalizes strings (lowercase, no periods) for comparison.
70

71
        Args:
72
            elements (set): Initial set of elements
73
        """
74

75
    def add(self, *strings):
76
        """
77
        Add normalized strings to the set. Can pass multiple strings.
78
        Normalizes by converting to lowercase and removing periods.
79

80
        Args:
81
            *strings (str): One or more strings to add
82

83
        Returns:
84
            SetManager: Self for method chaining
85
        """
86

87
    def remove(self, *strings):
88
        """
89
        Remove normalized strings from the set.
90

91
        Args:
92
            *strings (str): One or more strings to remove
93

94
        Returns:
95
            SetManager: Self for method chaining
96
        """
97

98
    def add_with_encoding(self, s, encoding=None):
99
        """
100
        Add string with explicit encoding specification.
101

102
        Args:
103
            s (str): String to add
104
            encoding (str): Character encoding (defaults to UTF-8)
105
        """
106
```
107

108
**Usage Examples:**
109

110
```python
111
from nameparser.config import CONSTANTS
112

113
# Method chaining for bulk updates
114
CONSTANTS.titles.remove('hon').add('chemistry', 'dean', 'provost')
115

116
# Add multiple items
117
CONSTANTS.suffixes.add('Esq', 'CPA', 'MBA')
118

119
# Remove multiple items
120
CONSTANTS.conjunctions.remove('and', 'or')
121

122
# Check membership (normalized)
123
print('dr' in CONSTANTS.titles)      # True (matches 'Dr.')
124
print('DR.' in CONSTANTS.titles)     # True (normalized to 'dr')
125
```
126

127
### TupleManager Class
128

129
Dictionary subclass that provides dot-notation access for configuration dictionaries.
130

131
```python { .api }
132
class TupleManager(dict):
133
    """
134
    Dictionary with dot.notation access for configuration tuples.
135
    Makes tuple constants more user-friendly.
136
    """
137

138
    def __getattr__(self, attr):
139
        """Access dictionary keys as attributes."""
140

141
    def __setattr__(self, attr, value):
142
        """Set dictionary keys as attributes."""
143

144
    def __delattr__(self, attr):
145
        """Delete dictionary keys as attributes."""
146
```
147

148
**Usage Examples:**
149

150
```python
151
from nameparser.config import CONSTANTS
152

153
# Access regex patterns with dot notation
154
initial_pattern = CONSTANTS.regexes.initial
155
roman_pattern = CONSTANTS.regexes.roman_numeral
156

157
# Access capitalization exceptions
158
macdonald = CONSTANTS.capitalization_exceptions['macdonald']  # 'MacDonald'
159
```
160

161
### Module-Level Configuration
162

163
Global configuration instance shared by all HumanName instances by default.
164

165
```python { .api }
166
# Global configuration constant
167
from nameparser.config import CONSTANTS
168

169
# Configuration sets (SetManager instances)
170
CONSTANTS.prefixes: SetManager         # Name prefixes
171
CONSTANTS.titles: SetManager           # Person titles  
172
CONSTANTS.first_name_titles: SetManager  # Special first name titles
173
CONSTANTS.suffix_acronyms: SetManager     # Acronym suffixes
174
CONSTANTS.suffix_not_acronyms: SetManager # Non-acronym suffixes
175
CONSTANTS.conjunctions: SetManager        # Name conjunctions
176

177
# Configuration dictionaries (TupleManager instances)
178
CONSTANTS.capitalization_exceptions: TupleManager  # Special capitalization
179
CONSTANTS.regexes: TupleManager                    # Regex patterns
180

181
# Combined sets (computed properties)
182
CONSTANTS.suffixes_prefixes_titles: set  # Combined set for lookups
183
```
184

185
**Usage Examples:**
186

187
```python
188
from nameparser import HumanName
189
from nameparser.config import CONSTANTS
190

191
# Global configuration affects all instances
192
CONSTANTS.titles.add('Captain', 'Colonel')
193
CONSTANTS.suffixes.add('PE', 'RN')
194
CONSTANTS.capitalize_name = True
195

196
# All new instances use updated configuration
197
name1 = HumanName("captain john doe pe")
198
print(name1.title)   # 'Captain'
199
print(name1.suffix)  # 'PE'
200
print(str(name1))    # 'Captain John Doe PE' (auto-capitalized)
201

202
name2 = HumanName("colonel jane smith rn")
203
print(name2.title)   # 'Colonel'
204
print(name2.suffix)  # 'RN'
205
```
206

207
### Per-Instance Configuration
208

209
Create HumanName instances with custom configuration that doesn't affect other instances.
210

211
```python { .api }
212
# Per-instance configuration
213
name = HumanName("Full Name", constants=None)  # Creates new Constants instance
214
name = HumanName("Full Name", constants=custom_constants)  # Uses provided instance
215
```
216

217
**Usage Examples:**
218

219
```python
220
from nameparser import HumanName
221
from nameparser.config import Constants
222

223
# Create instance with isolated configuration
224
name = HumanName("Dean Robert Johns", None)
225
name.C.titles.add('dean')          # Only affects this instance
226
name.parse_full_name()             # Re-parse with new config
227

228
print(name.title)                  # 'Dean'
229
print(name.has_own_config)         # True
230

231
# Other instances unaffected
232
other_name = HumanName("Dean Mary Smith")
233
print(other_name.title)            # '' (Dean not recognized)
234
print(other_name.first)            # 'Dean'
235

236
# Custom Constants instance
237
academic_config = Constants()
238
academic_config.titles.add('Prof', 'Dean', 'Provost', 'Chancellor')
239
academic_config.suffixes.add('Ph.D', 'Ed.D', 'Sc.D')
240

241
name = HumanName("Prof Jane Smith Ph.D", constants=academic_config)
242
print(name.title)                  # 'Prof'
243
print(name.suffix)                 # 'Ph.D'
244
```
245

246
### Name Classification Helpers
247

248
Methods for testing whether name components belong to specific categories.
249

250
```python { .api }
251
def is_title(self, value: str) -> bool:
252
    """Check if value is in the titles set."""
253

254
def is_conjunction(self, piece: str | list) -> bool:
255
    """Check if piece is a conjunction and not an initial."""
256

257
def is_prefix(self, piece: str | list) -> bool:
258
    """Check if piece is in the prefixes set."""
259

260
def is_suffix(self, piece: str | list) -> bool:
261
    """Check if piece is in the suffixes set and not an initial."""
262

263
def is_roman_numeral(self, value: str) -> bool:
264
    """Check if value matches roman numeral pattern."""
265

266
def is_rootname(self, piece: str) -> bool:
267
    """Check if piece is a core name part (not title, suffix, or prefix)."""
268

269
def is_an_initial(self, value: str) -> bool:
270
    """Check if value is a single letter or letter with period."""
271

272
def are_suffixes(self, pieces: list) -> bool:
273
    """Check if all pieces in list are suffixes."""
274
```
275

276
**Usage Examples:**
277

278
```python
279
from nameparser import HumanName
280

281
name = HumanName("Dr. John van der Berg III")
282

283
# Test individual components
284
print(name.is_title("Dr."))         # True
285
print(name.is_prefix("van"))        # True  
286
print(name.is_conjunction("der"))   # True
287
print(name.is_suffix("III"))        # True
288
print(name.is_roman_numeral("III")) # True
289
print(name.is_an_initial("J."))     # True
290
print(name.is_rootname("John"))     # True
291

292
# Test with lists
293
print(name.is_suffix(["Jr", "Sr"]))    # True
294
print(name.are_suffixes(["III", "Jr"])) # True
295
```
296

297
### Default Configuration Data
298

299
Pre-loaded configuration sets covering common names, titles, and patterns.
300

301
```python { .api }
302
# Default configuration sets imported from config modules
303
from nameparser.config.prefixes import PREFIXES
304
from nameparser.config.titles import TITLES, FIRST_NAME_TITLES  
305
from nameparser.config.suffixes import SUFFIX_ACRONYMS, SUFFIX_NOT_ACRONYMS
306
from nameparser.config.conjunctions import CONJUNCTIONS
307
from nameparser.config.capitalization import CAPITALIZATION_EXCEPTIONS
308
from nameparser.config.regexes import REGEXES
309

310
# Encoding constant
311
from nameparser.config import DEFAULT_ENCODING  # 'UTF-8'
312
```
313

314
**Contents include:**
315

316
- **Prefixes**: de, van, von, del, della, da, du, le, la, etc.
317
- **Titles**: Dr, Mr, Mrs, Ms, Prof, Hon, Rev, etc.
318
- **Suffixes**: Jr, Sr, II, III, PhD, MD, Esq, etc.
319
- **Conjunctions**: and, or, nor, the, of, etc.
320
- **Capitalization**: McDonald, MacLeod, O'Connor, etc.
321
- **Regex patterns**: For initials, roman numerals, quotes, etc.
322

323
**Usage Examples:**
324

325
```python
326
from nameparser.config import CONSTANTS
327

328
# Explore default configuration
329
print(list(CONSTANTS.titles)[:10])        # First 10 titles
330
print(list(CONSTANTS.prefixes))           # All prefixes
331
print(list(CONSTANTS.suffix_acronyms)[:5]) # First 5 acronym suffixes
332

333
# Check what's included
334
print('dr' in CONSTANTS.titles)           # True
335
print('von' in CONSTANTS.prefixes)        # True  
336
print('phd' in CONSTANTS.suffix_acronyms) # True
337
```