0
# Styles and Formatting
1

2
Comprehensive style system controlling pinyin output format including tones, initials/finals separation, alternative notation systems, and specialized romanization schemes.
3

4
## Capabilities
5

6
### Style Enumeration
7

8
The Style enum provides all available output format options for pinyin conversion.
9

10
```python { .api }
11
class Style(IntEnum):
12
    """Enumeration of all available pinyin output styles."""
13
    NORMAL = 0           # Normal pinyin without tones
14
    TONE = 1             # Standard tone marks (default)
15
    TONE2 = 2            # Tone numbers after vowels
16
    INITIALS = 3         # Initial consonants only
17
    FIRST_LETTER = 4     # First letter only
18
    FINALS = 5           # Final vowels/consonants without tones
19
    FINALS_TONE = 6      # Finals with standard tone marks
20
    FINALS_TONE2 = 7     # Finals with tone numbers after vowels
21
    TONE3 = 8            # Tone numbers after complete pinyin
22
    FINALS_TONE3 = 9     # Finals with tone numbers after finals
23
    BOPOMOFO = 10        # Bopomofo (Zhuyin) notation
24
    BOPOMOFO_FIRST = 11  # First Bopomofo character
25
    CYRILLIC = 12        # Cyrillic transliteration
26
    CYRILLIC_FIRST = 13  # First Cyrillic character
27
    WADEGILES = 14       # Wade-Giles romanization
28
    GWOYEU = 15          # Gwoyeu Romatzyh (National Romanization)
29
    BRAILLE_MAINLAND = 16     # Mainland Chinese Braille
30
    BRAILLE_MAINLAND_TONE = 17  # Mainland Chinese Braille with tones
31
```
32

33
### Standard Tone Styles
34

35
Core pinyin styles with different tone representation methods.
36

37
#### Normal Style (No Tones)
38

39
```python { .api }
40
STYLE_NORMAL = 0
41
NORMAL = 0
42
```
43

44
Plain pinyin without tone markers.
45

46
```python
47
from pypinyin import lazy_pinyin, Style, NORMAL
48

49
result = lazy_pinyin('中国', style=Style.NORMAL)
50
print(result)  # ['zhong', 'guo']
51

52
result = lazy_pinyin('中国', style=NORMAL)
53
print(result)  # ['zhong', 'guo']
54
```
55

56
#### Tone Style (Standard Diacritical Marks)
57

58
```python { .api }
59
STYLE_TONE = 1  
60
TONE = 1
61
```
62

63
Standard pinyin with diacritical tone marks (default style).
64

65
```python
66
from pypinyin import lazy_pinyin, Style, TONE
67

68
result = lazy_pinyin('中国', style=Style.TONE)
69
print(result)  # ['zhōng', 'guó']
70

71
result = lazy_pinyin('中国', style=TONE)
72
print(result)  # ['zhōng', 'guó']
73
```
74

75
#### Tone2 Style (Numbers After Vowels)
76

77
```python { .api }
78
STYLE_TONE2 = 2
79
TONE2 = 2
80
```
81

82
Tone numbers placed after the vowel carrying the tone.
83

84
```python
85
from pypinyin import lazy_pinyin, Style, TONE2
86

87
result = lazy_pinyin('中国', style=Style.TONE2)
88
print(result)  # ['zho1ng', 'guo2']
89

90
result = lazy_pinyin('中国', style=TONE2)
91
print(result)  # ['zho1ng', 'guo2']
92
```
93

94
#### Tone3 Style (Numbers After Complete Pinyin)
95

96
```python { .api }
97
STYLE_TONE3 = 8
98
TONE3 = 8
99
```
100

101
Tone numbers appended to complete pinyin syllables.
102

103
```python
104
from pypinyin import lazy_pinyin, Style, TONE3
105

106
result = lazy_pinyin('中国', style=Style.TONE3)
107
print(result)  # ['zhong1', 'guo2']
108

109
result = lazy_pinyin('中国', style=TONE3)
110
print(result)  # ['zhong1', 'guo2']
111
```
112

113
### Initials and Finals Styles
114

115
Styles that separate or extract specific parts of pinyin syllables.
116

117
#### Initials Only
118

119
```python { .api }
120
STYLE_INITIALS = 3
121
INITIALS = 3
122
```
123

124
Extract only initial consonants from pinyin syllables.
125

126
```python
127
from pypinyin import lazy_pinyin, Style, INITIALS
128

129
result = lazy_pinyin('中华', style=Style.INITIALS)
130
print(result)  # ['zh', 'h']
131

132
result = lazy_pinyin('安全', style=INITIALS)
133
print(result)  # ['', 'q']  # 安 has no initial consonant
134
```
135

136
#### First Letter Only
137

138
```python { .api }
139
STYLE_FIRST_LETTER = 4
140
FIRST_LETTER = 4  
141
```
142

143
Extract only the first letter of each pinyin syllable.
144

145
```python
146
from pypinyin import lazy_pinyin, Style, FIRST_LETTER
147

148
result = lazy_pinyin('中华人民共和国', style=Style.FIRST_LETTER)
149
print(result)  # ['z', 'h', 'r', 'm', 'g', 'h', 'g']
150

151
result = lazy_pinyin('中华人民共和国', style=FIRST_LETTER)
152
print(result)  # ['z', 'h', 'r', 'm', 'g', 'h', 'g']
153
```
154

155
#### Finals Without Tones
156

157
```python { .api }
158
STYLE_FINALS = 5
159
FINALS = 5
160
```
161

162
Extract final vowels and consonants without tone markers.
163

164
```python
165
from pypinyin import lazy_pinyin, Style, FINALS
166

167
result = lazy_pinyin('中华', style=Style.FINALS)
168
print(result)  # ['ong', 'ua']
169

170
result = lazy_pinyin('中华', style=FINALS)
171
print(result)  # ['ong', 'ua']
172
```
173

174
#### Finals With Tone Marks
175

176
```python { .api }
177
STYLE_FINALS_TONE = 6
178
FINALS_TONE = 6
179
```
180

181
Finals with standard diacritical tone marks.
182

183
```python
184
from pypinyin import lazy_pinyin, Style, FINALS_TONE
185

186
result = lazy_pinyin('中华', style=Style.FINALS_TONE)
187
print(result)  # ['ōng', 'uá']
188

189
result = lazy_pinyin('中华', style=FINALS_TONE)
190
print(result)  # ['ōng', 'uá']
191
```
192

193
#### Finals With Tone Numbers
194

195
```python { .api }
196
STYLE_FINALS_TONE2 = 7
197
FINALS_TONE2 = 7
198

199
STYLE_FINALS_TONE3 = 9  
200
FINALS_TONE3 = 9
201
```
202

203
Finals with tone numbers in different positions.
204

205
```python
206
from pypinyin import lazy_pinyin, Style, FINALS_TONE2, FINALS_TONE3
207

208
# Tone numbers after vowels
209
result = lazy_pinyin('中华', style=Style.FINALS_TONE2)
210
print(result)  # ['o1ng', 'ua2']
211

212
# Tone numbers after complete finals
213
result = lazy_pinyin('中华', style=FINALS_TONE3)
214
print(result)  # ['ong1', 'ua2']
215
```
216

217
### Alternative Notation Systems
218

219
Styles providing alternative phonetic notation systems beyond standard pinyin.
220

221
#### Bopomofo (Zhuyin) Notation
222

223
```python { .api }
224
STYLE_BOPOMOFO = 10
225
BOPOMOFO = 10
226

227
STYLE_BOPOMOFO_FIRST = 11
228
BOPOMOFO_FIRST = 11
229
```
230

231
Traditional Chinese phonetic notation system.
232

233
```python
234
from pypinyin import lazy_pinyin, Style, BOPOMOFO, BOPOMOFO_FIRST
235

236
# Full Bopomofo
237
result = lazy_pinyin('中国', style=Style.BOPOMOFO)
238
print(result)  # ['ㄓㄨㄥ', 'ㄍㄨㄛˊ']
239

240
# First Bopomofo character only
241
result = lazy_pinyin('中国', style=BOPOMOFO_FIRST)
242
print(result)  # ['ㄓ', 'ㄍ']
243
```
244

245
#### Cyrillic Transliteration
246

247
```python { .api }
248
STYLE_CYRILLIC = 12
249
CYRILLIC = 12
250

251
STYLE_CYRILLIC_FIRST = 13
252
CYRILLIC_FIRST = 13
253
```
254

255
Cyrillic-based transliteration system.
256

257
```python
258
from pypinyin import lazy_pinyin, Style, CYRILLIC, CYRILLIC_FIRST
259

260
# Full Cyrillic
261
result = lazy_pinyin('中国', style=Style.CYRILLIC)
262
print(result)  # ['чжун', 'го']
263

264
# First Cyrillic character only  
265
result = lazy_pinyin('中国', style=CYRILLIC_FIRST)
266
print(result)  # ['ч', 'г']
267
```
268

269
#### Wade-Giles Romanization
270

271
```python { .api }
272
STYLE_WADEGILES = 14
273
WADEGILES = 14
274
```
275

276
Wade-Giles romanization system, commonly used for traditional Chinese transliteration.
277

278
```python
279
from pypinyin import lazy_pinyin, Style, WADEGILES
280

281
# Wade-Giles romanization
282
result = lazy_pinyin('威妥玛拼音', style=Style.WADEGILES)
283
print(result)  # ['wei', 'tʻo', 'ma', 'pʻin', 'yin']
284

285
result = lazy_pinyin('中国', style=WADEGILES) 
286
print(result)  # ['chung', 'kuo']
287
```
288

289
#### Gwoyeu Romatzyh (National Romanization)
290

291
```python { .api }
292
STYLE_GWOYEU = 15
293
GWOYEU = 15
294
```
295

296
National Romanization system where tones are indicated by spelling changes.
297

298
```python
299
from pypinyin import lazy_pinyin, Style, GWOYEU
300

301
# Gwoyeu Romatzyh
302
result = lazy_pinyin('中国', style=Style.GWOYEU)  
303
print(result)  # ['jong', 'gwo']
304

305
result = lazy_pinyin('中华人民共和国', style=GWOYEU)
306
print(result)  # ['jong', 'hwa', 'ren', 'min', 'gonq', 'her', 'gwo']
307
```
308

309
#### Chinese Braille Systems
310

311
```python { .api }
312
STYLE_BRAILLE_MAINLAND = 16
313
BRAILLE_MAINLAND = 16
314

315
STYLE_BRAILLE_MAINLAND_TONE = 17  
316
BRAILLE_MAINLAND_TONE = 17
317
```
318

319
Mainland Chinese Braille notation for accessibility applications.
320

321
```python
322
from pypinyin import lazy_pinyin, Style, BRAILLE_MAINLAND, BRAILLE_MAINLAND_TONE
323

324
# Mainland Chinese Braille without tones
325
result = lazy_pinyin('中国', style=Style.BRAILLE_MAINLAND)
326
print(result)  # ['⠌⠲', '⠛⠕']
327

328
# Mainland Chinese Braille with tone marks
329
result = lazy_pinyin('中国', style=BRAILLE_MAINLAND_TONE)
330
print(result)  # ['⠌⠲⠁', '⠛⠕⠂']
331

332
# Longer text example
333
result = lazy_pinyin('时间不早了', style=Style.BRAILLE_MAINLAND)
334
print(result)  # ['⠱⠊', '⠚⠔', '⠃⠥', '⠵⠦', '⠇⠔']
335
```
336

337

338
## Style Usage Patterns
339

340
### Common Style Applications
341

342
```python
343
from pypinyin import lazy_pinyin, Style
344

345
text = '北京大学'
346

347
# URL slugs - use NORMAL
348
slug_friendly = lazy_pinyin(text, style=Style.NORMAL)
349
print('-'.join(slug_friendly))  # 'bei-jing-da-xue'
350

351
# Search indexing - use FIRST_LETTER
352
search_index = lazy_pinyin(text, style=Style.FIRST_LETTER)
353
print(''.join(search_index))  # 'bjdx'
354

355
# Learning materials - use TONE3 (numbers are easier to type)
356
learning = lazy_pinyin(text, style=Style.TONE3)
357
print(' '.join(learning))  # 'bei3 jing1 da4 xue2'
358

359
# Phonetic analysis - use INITIALS and FINALS
360
initials = lazy_pinyin(text, style=Style.INITIALS)
361
finals = lazy_pinyin(text, style=Style.FINALS_TONE)
362
print('Initials:', initials)  # ['b', 'j', 'd', 'x']
363
print('Finals:', finals)      # ['ēi', 'īng', 'à', 'üé']
364
```
365

366
### Style Constant Aliases
367

368
Both long and short forms are available for all style constants:
369

370
```python
371
# These are equivalent
372
from pypinyin import STYLE_TONE, TONE
373
from pypinyin import STYLE_NORMAL, NORMAL
374
from pypinyin import STYLE_FIRST_LETTER, FIRST_LETTER
375

376
# All produce the same result
377
result1 = lazy_pinyin('中国', style=Style.TONE)
378
result2 = lazy_pinyin('中国', style=STYLE_TONE)
379
result3 = lazy_pinyin('中国', style=TONE)
380
```