0
# Name Formatting and Initials
1

2
Functionality for formatting names with custom templates, generating initials, and handling capitalization of name components.
3

4
## Capabilities
5

6
### Initials Generation
7

8
Generate initials from name components with customizable formatting and delimiters.
9

10
```python { .api }
11
def initials(self):
12
    """
13
    Return period-delimited initials of the first, middle and optionally last name.
14
    Uses the initials_format template and initials_delimiter.
15

16
    Returns:
17
        str: Formatted initials string based on initials_format template
18
    """
19

20
def initials_list(self):
21
    """
22
    Returns the initials as a list of individual letters.
23

24
    Returns:
25
        list: List of initial letters from first, middle, and last names
26
    """
27
```
28

29
**Usage Examples:**
30

31
```python
32
from nameparser import HumanName
33

34
# Basic initials
35
name = HumanName("John Michael Smith")
36
print(name.initials())      # 'J. M. S.'
37
print(name.initials_list()) # ['J', 'M', 'S']
38

39
# Custom initials format (first and middle only)
40
name = HumanName("Sir Bob Andrew Dole", initials_format="{first} {middle}")
41
print(name.initials())      # 'B. A.'
42

43
# Custom delimiter
44
name = HumanName("Jane Mary Johnson", initials_delimiter="-")
45
print(name.initials())      # 'J- M- J-'
46

47
# Names with prefixes and conjunctions
48
name = HumanName("Mary van der Berg")
49
print(name.initials())      # 'M. B.' (excludes conjunctions and prefixes)
50

51
# Titles are excluded from initials
52
name = HumanName("Dr. Robert James Wilson")
53
print(name.initials())      # 'R. J. W.' (excludes 'Dr.')
54
```
55

56
### Name Capitalization
57

58
Intelligent capitalization handling for names entered in all uppercase, lowercase, or mixed case.
59

60
```python { .api }
61
def capitalize(self, force=None):
62
    """
63
    Correct capitalization of names entered in all upper or lower case.
64
    By default, does not adjust mixed case names unless force=True.
65

66
    Args:
67
        force (bool): Forces capitalization of mixed case strings (overrides module config)
68
    """
69
```
70

71
**Usage Examples:**
72

73
```python
74
from nameparser import HumanName
75

76
# Automatic capitalization of all-caps names
77
name = HumanName('BOB V. DE LA MACDOLE-EISENHOWER PHD')
78
name.capitalize()
79
print(str(name))  # 'Bob V. de la MacDole-Eisenhower Ph.D.'
80

81
# Automatic capitalization of lowercase names
82
name = HumanName('john smith jr.')
83
name.capitalize()
84
print(str(name))  # 'John Smith Jr.'
85

86
# Mixed case names are preserved by default
87
name = HumanName('Shirley Maclaine')
88
name.capitalize()
89
print(str(name))  # 'Shirley Maclaine' (unchanged)
90

91
# Force capitalization of mixed case
92
name = HumanName('Shirley Maclaine')
93
name.capitalize(force=True)
94
print(str(name))  # 'Shirley MacLaine'
95

96
# Special handling for Irish/Scottish names
97
name = HumanName('mary o\'connor')
98
name.capitalize()
99
print(str(name))  # "Mary O'Connor"
100

101
name = HumanName('donald macdonald')
102
name.capitalize()
103
print(str(name))  # 'Donald MacDonald'
104
```
105

106
### String Formatting
107

108
Customize how names are displayed using Python string format templates.
109

110
```python { .api }
111
# String formatting properties
112
string_format: str  # Template for full name display
113
initials_format: str  # Template for initials display  
114
initials_delimiter: str  # Character between initials
115
```
116

117
**Usage Examples:**
118

119
```python
120
from nameparser import HumanName
121

122
name = HumanName("Dr. John Michael Smith Jr.")
123

124
# Default format
125
print(str(name))  # 'Dr. John Michael Smith Jr.'
126

127
# Custom format templates
128
name.string_format = "{title} {first} {last}"
129
print(str(name))  # 'Dr. John Smith'
130

131
name.string_format = "{last}, {first} {middle}"
132
print(str(name))  # 'Smith, John Michael'
133

134
name.string_format = "{first} {last} ({nickname})"
135
name.nickname = "Johnny"
136
print(str(name))  # 'John Smith (Johnny)'
137

138
# Format with conditionals handled automatically
139
name.string_format = "{title} {first} {middle} {last} {suffix} ({nickname})"
140
name.nickname = ""  # Empty nickname
141
print(str(name))  # 'Dr. John Michael Smith Jr.' (no empty parentheses)
142

143
# Multiple format styles
144
name.string_format = "{first} {last}"
145
formal = str(name)  # 'John Smith'
146

147
name.string_format = "{title} {last}, {first}"
148
business = str(name)  # 'Dr. Smith, John'
149
```
150

151
### Global Formatting Configuration
152

153
Set default formatting behavior for all HumanName instances through module-level constants.
154

155
```python { .api }
156
# Module-level configuration via CONSTANTS
157
from nameparser.config import CONSTANTS
158

159
CONSTANTS.string_format: str  # Default string format template
160
CONSTANTS.initials_format: str  # Default initials format template
161
CONSTANTS.initials_delimiter: str  # Default initials delimiter
162
CONSTANTS.empty_attribute_default: str  # Default value for empty attributes
163
CONSTANTS.capitalize_name: bool  # Auto-capitalize all names
164
CONSTANTS.force_mixed_case_capitalization: bool  # Force mixed case capitalization
165
```
166

167
**Usage Examples:**
168

169
```python
170
from nameparser import HumanName
171
from nameparser.config import CONSTANTS
172

173
# Set global formatting defaults
174
CONSTANTS.string_format = "{first} {last}"
175
CONSTANTS.initials_delimiter = "-"
176
CONSTANTS.capitalize_name = True
177

178
# All new instances use these defaults
179
name1 = HumanName("john doe")
180
print(str(name1))        # 'John Doe' (auto-capitalized)
181
print(name1.initials())  # 'J- D-' (custom delimiter)
182

183
name2 = HumanName("jane smith")
184
print(str(name2))        # 'Jane Smith' (uses global format)
185

186
# Override global settings per instance
187
name3 = HumanName("bob wilson", string_format="{title} {first} {middle} {last} {suffix}")
188
name3.title = "Mr."
189
print(str(name3))        # 'Mr. Bob Wilson' (uses instance format)
190
```
191

192
### Advanced Formatting Features
193

194
Handle complex formatting scenarios with empty attributes and special characters.
195

196
```python { .api }
197
def collapse_whitespace(self, string):
198
    """
199
    Collapse multiple spaces into single space and handle trailing commas.
200
    
201
    Args:
202
        string (str): String to clean up
203
    
204
    Returns:
205
        str: Cleaned string with normalized whitespace
206
    """
207
```
208

209
**Usage Examples:**
210

211
```python
212
from nameparser import HumanName
213

214
# Automatic cleanup of empty components in templates
215
name = HumanName("John Smith")  # No title or suffix
216
name.string_format = "{title} {first} {last} {suffix}"
217
print(str(name))  # 'John Smith' (no extra spaces for empty title/suffix)
218

219
# Custom empty attribute defaults
220
from nameparser.config import CONSTANTS
221
CONSTANTS.empty_attribute_default = "N/A"
222

223
name = HumanName("John Smith")
224
print(name.title)   # 'N/A' instead of empty string
225
print(name.suffix)  # 'N/A' instead of empty string
226

227
# Reset to default
228
CONSTANTS.empty_attribute_default = ""
229
```