0
# pypinyin
1
2
A comprehensive Chinese character to Pinyin conversion library for Python that provides intelligent word segmentation to match accurate pronunciation for multi-character phrases. It supports polyphonic characters with heteronym detection, multiple Pinyin output styles including tone marks, tone numbers, first letters, initials/finals separation, and Bopomofo notation.
3
4
## Package Information
5
6
- **Package Name**: pypinyin
7
- **Language**: Python
8
- **Installation**: `pip install pypinyin`
9
- **Documentation**: https://pypinyin.readthedocs.io/
10
11
## Core Imports
12
13
```python
14
import pypinyin
15
```
16
17
Common imports for core functionality:
18
19
```python
20
from pypinyin import pinyin, lazy_pinyin, slug, Style
21
```
22
23
For style constants:
24
25
```python
26
from pypinyin import (
27
NORMAL, TONE, TONE2, TONE3,
28
INITIALS, FIRST_LETTER, FINALS, FINALS_TONE, FINALS_TONE2, FINALS_TONE3,
29
BOPOMOFO, BOPOMOFO_FIRST, CYRILLIC, CYRILLIC_FIRST,
30
WADEGILES, GWOYEU, BRAILLE_MAINLAND, BRAILLE_MAINLAND_TONE
31
)
32
```
33
34
## Basic Usage
35
36
```python
37
from pypinyin import pinyin, lazy_pinyin, slug, Style
38
39
# Basic pinyin conversion with tone marks
40
text = "中国"
41
result = pinyin(text)
42
print(result) # [['zhōng'], ['guó']]
43
44
# Simple pinyin without tone marks
45
result = lazy_pinyin(text)
46
print(result) # ['zhong', 'guo']
47
48
# Different output styles
49
result = pinyin(text, style=Style.TONE3)
50
print(result) # [['zhong1'], ['guo2']]
51
52
result = pinyin(text, style=Style.FIRST_LETTER)
53
print(result) # [['z'], ['g']]
54
55
# Generate URL-friendly slugs
56
slug_text = slug(text)
57
print(slug_text) # zhong-guo
58
59
# Handle polyphonic characters (heteronyms)
60
text = "银行" # can be pronounced different ways
61
result = pinyin(text, heteronym=True)
62
print(result) # [['yín'], ['háng', 'xíng']]
63
```
64
65
## Architecture
66
67
pypinyin is built around a modular architecture:
68
69
- **Core conversion functions**: Main API functions for different use cases (pinyin, lazy_pinyin, slug)
70
- **Style system**: Comprehensive output format control through Style enum and constants
71
- **Converter backends**: Pluggable converter implementations (DefaultConverter, UltimateConverter)
72
- **Segmentation modules**: Word boundary detection for accurate pronunciation (mmseg, simpleseg)
73
- **Contrib modules**: Advanced features like tone sandhi, character variants, and specialized processing
74
75
## Capabilities
76
77
### Core Conversion Functions
78
79
Primary functions for converting Chinese characters to pinyin with various output options, heteronym support, and customization.
80
81
```python { .api }
82
def pinyin(hans, style=Style.TONE, heteronym=False, errors='default', strict=True, v_to_u=False, neutral_tone_with_five=False): ...
83
def lazy_pinyin(hans, style=Style.NORMAL, errors='default', strict=True, v_to_u=False, neutral_tone_with_five=False, tone_sandhi=False): ...
84
def slug(hans, style=Style.NORMAL, heteronym=False, separator='-', errors='default', strict=True): ...
85
```
86
87
[Core Functions](./core-functions.md)
88
89
### Output Styles and Formatting
90
91
Comprehensive style system controlling pinyin output format including tones, initials/finals, alternative notation systems, and specialized styles.
92
93
```python { .api }
94
class Style(IntEnum):
95
NORMAL = 0
96
TONE = 1
97
TONE2 = 2
98
INITIALS = 3
99
FIRST_LETTER = 4
100
FINALS = 5
101
FINALS_TONE = 6
102
FINALS_TONE2 = 7
103
TONE3 = 8
104
FINALS_TONE3 = 9
105
BOPOMOFO = 10
106
BOPOMOFO_FIRST = 11
107
CYRILLIC = 12
108
CYRILLIC_FIRST = 13
109
WADEGILES = 14
110
GWOYEU = 15
111
BRAILLE_MAINLAND = 16
112
BRAILLE_MAINLAND_TONE = 17
113
```
114
115
[Styles and Formatting](./styles-formatting.md)
116
117
### Dictionary Customization
118
119
Functions for loading custom pronunciation dictionaries to override default pinyin mappings for specific characters or phrases.
120
121
```python { .api }
122
def load_single_dict(pinyin_dict, style='default'): ...
123
def load_phrases_dict(phrases_dict, style='default'): ...
124
```
125
126
[Dictionary Customization](./dictionary-customization.md)
127
128
### Command-line Interface
129
130
Command-line tools for batch processing and format conversion.
131
132
```bash
133
pypinyin [options] [input_text]
134
python -m pypinyin.tools.toneconvert [action] [input]
135
```
136
137
[Command-line Tools](./command-line-tools.md)
138
139
### Advanced Features
140
141
Extended functionality including custom converters, tone sandhi processing, segmentation control, and specialized mixins.
142
143
```python { .api }
144
class Pinyin:
145
def __init__(self, converter=None): ...
146
147
class DefaultConverter: ...
148
class UltimateConverter: ...
149
```
150
151
[Advanced Features](./advanced-features.md)
152
153
## Exception Handling
154
155
```python { .api }
156
class PinyinNotFoundException(Exception):
157
"""
158
Raised when no pinyin pronunciation found for input characters.
159
160
Attributes:
161
- message (str): Exception message
162
- chars (str): Characters that caused the exception
163
"""
164
165
def __init__(self, chars):
166
"""Initialize exception with problematic characters."""
167
self.message = 'No pinyin found for character "{}"'.format(chars)
168
self.chars = chars
169
super(PinyinNotFoundException, self).__init__(self.message)
170
```
171
172
Common error handling patterns:
173
174
```python
175
from pypinyin import pinyin, PinyinNotFoundException
176
177
try:
178
result = pinyin("some text", errors='exception')
179
except PinyinNotFoundException as e:
180
print(f"No pinyin found: {e.message}")
181
print(f"Problematic characters: {e.chars}")
182
```