汉字拼音转换工具（Python 版）¶

将汉字转为拼音。可以用于汉字注音、排序、检索(Russian translation) 。

最初版本的代码参考了 hotoo/pinyin 的实现。

Documentation: http://pypinyin.rtfd.io
GitHub: https://github.com/mozillazg/python-pinyin
License: MIT license
PyPI: https://pypi.org/project/pypinyin
Python version: 2.7, pypy, pypy3, 3.4, 3.5, 3.6, 3.7, 3.8, 3.9

特性¶

根据词组智能匹配最正确的拼音。
支持多音字。
简单的繁体支持, 注音支持。
支持多种不同拼音风格。

Contents¶

安装¶

可以使用 pip 进行安装:

$ pip install pypinyin

easy_install 安装:

$ easy_install pypinyin

源码安装:

$ python setup.py install

使用¶

示例¶

>>> from pypinyin import pinyin, lazy_pinyin, Style
>>> pinyin('中心')  # or pinyin(['中心'])，参数值为列表时表示输入的是已分词后的数据
[['zhōng'], ['xīn']]
>>> pinyin('中心', heteronym=True)  # 启用多音字模式
[['zhōng', 'zhòng'], ['xīn']]
>>> pinyin('中心', style=Style.FIRST_LETTER)  # 设置拼音风格
[['z'], ['x']]
>>> pinyin('中心', style=Style.TONE2, heteronym=True)
[['zho1ng', 'zho4ng'], ['xi1n']]
>>> pinyin('中心', style=Style.TONE3, heteronym=True)
[['zhong1', 'zhong4'], ['xin1']]
>>> pinyin('中心', style=Style.BOPOMOFO)  # 注音风格
[['ㄓㄨㄥ'], ['ㄒㄧㄣ']]
>>> lazy_pinyin('威妥玛拼音', style=Style.WADEGILES)
['wei', "t'o", 'ma', "p'in", 'yin']
>>> lazy_pinyin('中心')  # 不考虑多音字的情况
['zhong', 'xin']
>>> lazy_pinyin('战略', v_to_u=True)  # 不使用 v 表示 ü
['zhan', 'lüe']
# 使用 5 标识轻声
>>> lazy_pinyin('衣裳', style=Style.TONE3, neutral_tone_with_five=True)
['yi1', 'shang5']
# 变调  nǐ hǎo -> ní hǎo
>>> lazy_pinyin('你好', style=Style.TONE2, tone_sandhi=True)
['ni2', 'ha3o']

注意事项 ：

默认情况下拼音结果不会标明哪个韵母是轻声，轻声的韵母没有声调或数字标识（可以通过参数 neutral_tone_with_five=True 开启使用 5 标识轻声）。
默认情况下无声调相关拼音风格下的结果会使用 v 表示 ü （可以通过参数 v_to_u=True 开启使用 ü 代替 v ）。
默认情况下会原样输出没有拼音的字符（自定义处理没有拼音的字符的方法见文档）。

处理不包含拼音的字符¶

当程序遇到不包含拼音的字符(串)时，会根据 errors 参数的值做相应的处理:

default (默认行为): 不做任何处理，原样返回:

pinyin('你好☆☆')
[['nǐ'], ['hǎo'], ['☆☆']]

ignore : 忽略该字符

pinyin('你好☆☆', errors='ignore')
[['nǐ'], ['hǎo']]

replace : 替换为去掉 \u 的 unicode 编码:

pinyin('你好☆☆', errors='replace')
[['nǐ'], ['hǎo'], ['26062606']]

callable 对象 : 提供一个回调函数，接受无拼音字符(串)作为参数, 支持的返回值类型: unicode 或 list 或 None 。:

pinyin('你好☆☆', errors=lambda x: 'star')
[['nǐ'], ['hǎo'], ['star']]

pinyin('你好☆☆', errors=lambda x: None)
[['nǐ'], ['hǎo']]

返回值类型为 list 时，会自动 expend list

pinyin('你好☆☆', errors=lambda x: ['star' for _ in x])
[['nǐ'], ['hǎo'], ['star'], ['star']]

# 指定多音字
pinyin('你好☆☆', heteronym=True, errors=lambda x: [['star', '☆'] for _ in x])
[['nǐ'], ['hǎo'], ['star', '☆'], ['star', '☆']]

自定义拼音库¶

如果对结果不满意，可以通过 load_single_dict() 或 load_phrases_dict() 以自定义拼音库的方式修正结果：

>> from pypinyin import lazy_pinyin, load_phrases_dict, Style, load_single_dict
>> hans = '桔子'
>> lazy_pinyin(hans, style=Style.TONE2)
['jie2', 'zi3']
>> load_phrases_dict({'桔子': [['jú'], ['zǐ']]})  # 增加 "桔子" 词组
>> lazy_pinyin(hans, style=Style.TONE2)
['ju2', 'zi3']

>> hans = '还没'
>> lazy_pinyin(hans, style=Style.TONE2)
['hua2n', 'me2i']
>> load_single_dict({ord('还'): 'hái,huán'})  # 调整 "还" 字的拼音顺序或覆盖默认拼音
>>> lazy_pinyin('还没', style=Style.TONE2)
['ha2i', 'me2i']

或者使用 pypinyin-dict 项目提供的自定义拼音库来纠正结果:

>>> from pypinyin import pinyin
>>> pinyin('枯萎')
[['kū'], ['wēi']]

# 使用 phrase-pinyin-data 项目中 cc_cedict.txt 文件中的拼音数据优化结果
>>> from pypinyin_dict.phrase_pinyin_data import cc_cedict
>>> cc_cedict.load()

>>> pinyin('枯萎')
[['kū'], ['wěi']]


>>> pinyin('扔', heteronym=True)
[['rēng', 'rèng']]

# 使用 pinyin-data 项目中 cc_cedict.txt 文件中的拼音数据优化结果
>>> from pypinyin_dict.pinyin_data import kxhc1983
>>> kxhc1983.load()

>>> pinyin('扔', heteronym=True)
[['rēng']]

自定义拼音风格¶

可以通过 register() 来实现自定义拼音风格的需求：

In [1]: from pypinyin import lazy_pinyin

In [2]: from pypinyin.style import register

In [3]: @register('kiss')
   ...: def kiss(pinyin, **kwargs):     # 必须包含 **kwargs 用于接收未来新增的关键字参数
   ...:     return '😘 {0}'.format(pinyin)
   ...:

In [4]: lazy_pinyin('么么', style='kiss')
Out[4]: ['😘 me', '😘 me']

`strict` 参数的影响¶

strict 参数用于控制处理声母和韵母时是否严格遵循《汉语拼音方案》标准：

In [1]: from pypinyin import Style, lazy_pinyin

In [2]: lazy_pinyin('乌', style=Style.TONE)
Out[2]: ['wū']

In [3]: lazy_pinyin('乌', style=Style.INITIALS)
Out[3]: ['']

In [4]: lazy_pinyin('乌', style=Style.INITIALS, strict=False)
Out[4]: ['w']

In [5]: lazy_pinyin('迂', style=Style.TONE)
Out[5]: ['yū']

In [6]: lazy_pinyin('迂', style=Style.FINALS_TONE)
Out[6]: ['ǖ']

In [7]: lazy_pinyin('迂', style=Style.FINALS_TONE, strict=False)
Out[7]: ['ū']

当 strict=True 时根据《汉语拼音方案》的如下规则处理声母、在韵母相关风格下还原正确的韵母（只对只获取声母或只获取韵母相关拼音风格有效，不影响其他获取完整拼音信息的拼音风格的结果）：

21 个声母： b p m f d t n l g k h j q x zh ch sh r z c s （y, w 不是声母）
i行的韵母，前面没有声母的时候，写成yi(衣)，ya(呀)，ye(耶)，yao(腰)，you(忧)，yan(烟)， yin(因)，yang(央)，ying(英)，yong(雍)。（y 不是声母）
u行的韵母，前面没有声母的时候，写成wu(乌)，wa(蛙)，wo(窝)，wai(歪)，wei(威)，wan(弯)， wen(温)，wang(汪)，weng(翁)。（w 不是声母）
ü行的韵母，前面没有声母的时候，写成yu(迂)，yue(约)，yuan(冤)，yun(晕)；ü上两点省略。（韵母相关风格下还原正确的韵母 ü）
ü行的韵跟声母j，q，x拼的时候，写成ju(居)，qu(区)，xu(虚)，ü上两点也省略；但是跟声母n，l拼的时候，仍然写成nü(女)，lü(吕)。（韵母相关风格下还原正确的韵母 ü）
iou，uei，uen前面加声母的时候，写成iu，ui，un。例如niu(牛)，gui(归)，lun(论)。（韵母相关风格下还原正确的韵母 iou，uei，uen）

当 strict=False 时就是不遵守上面的规则来处理声母和韵母，比如：y, w 会被当做声母，yu(迂) 的韵母就是一般认为的 u 等。

具体差异可以查看 tests/test_standard.py 中的对比结果测试用例

命令行工具¶

程序内置了一个命令行工具 pypinyin :

$ pypinyin 音乐
yīn yuè
$ pypinyin -h

命令行工具支持如下参数：

$ pypinyin -h
usage: pypinyin [-h] [-V] [-f {pinyin,slug}]
                [-s {NORMAL,zhao,TONE,zh4ao,TONE2,zha4o,TONE3,zhao4,INITIALS,zh,FIRST_LETTER,z,FINALS,ao,FINALS_TONE,4ao,FINALS_TONE2,a4o,FINALS_TONE3,ao4,BOPOMOFO,BOPOMOFO_FIRST,CYRILLIC,CYRILLIC_FIRST}]
                [-p SEPARATOR] [-e {default,ignore,replace}] [-m]
                hans

convert chinese to pinyin.

positional arguments:
  hans                  chinese string

optional arguments:
  -h, --help            show this help message and exit
  -V, --version         show program's version number and exit
  -f {pinyin,slug}, --func {pinyin,slug}
                        function name (default: "pinyin")
  -s {NORMAL,zhao,TONE,zh4ao,TONE2,zha4o,TONE3,zhao4,INITIALS,zh,FIRST_LETTER,z,FINALS,ao,FINALS_TONE,4ao,FINALS_TONE2,a4o,FINALS_TONE3,ao4,BOPOMOFO,BOPOMOFO_FIRST,CYRILLIC,CYRILLIC_FIRST}, --style {NORMAL,zhao,TONE,zh4ao,TONE2,zha4o,TONE3,zhao4,INITIALS,zh,FIRST_LETTER,z,FINALS,ao,FINALS_TONE,4ao,FINALS_TONE2,a4o,FINALS_TONE3,ao4,BOPOMOFO,BOPOMOFO_FIRST,CYRILLIC,CYRILLIC_FIRST}
                        pinyin style (default: "zh4ao")
  -p SEPARATOR, --separator SEPARATOR
                        slug separator (default: "-")
  -e {default,ignore,replace}, --errors {default,ignore,replace}
                        how to handle none-pinyin string (default: "default")
  -m, --heteronym       enable heteronym

-s, --style 参数可以选值的含义如下：

-s 或 –style 的值	对应的拼音风格
zhao	`NORMAL`
zh4ao	`TONE`
zha4o	`TONE2`
zhao4	`TONE3`
zh	`INITIALS`
z	`FIRST_LETTER`
ao	`FINALS`
4ao	`FINALS_TONE`
a4o	`FINALS_TONE2`
ao4	`FINALS_TONE3`
NORMAL	`NORMAL`
TONE	`TONE`
TONE2	`TONE2`
TONE3	`TONE3`
INITIALS	`INITIALS`
FIRST_LETTER	`FIRST_LETTER`
FINALS	`FINALS`
FINALS_TONE	`FINALS_TONE`
FINALS_TONE2	`FINALS_TONE2`
FINALS_TONE3	`FINALS_TONE3`
BOPOMOFO	`BOPOMOFO`
BOPOMOFO_FIRST	`BOPOMOFO_FIRST`
CYRILLIC	`CYRILLIC`
CYRILLIC_FIRST	`CYRILLIC_FIRST`

API¶

拼音风格¶

class pypinyin.Style(value)[源代码]¶

拼音风格

NORMAL = 0¶: 普通风格，不带声调。如：中国 -> zhong guo

TONE = 1¶: 标准声调风格，拼音声调在韵母第一个字母上（默认风格）。如：中国 -> zhōng guó

TONE2 = 2¶: 声调风格2，即拼音声调在各个韵母之后，用数字 [1-4] 进行表示。如：中国 -> zho1ng guo2

TONE3 = 8¶: 声调风格3，即拼音声调在各个拼音之后，用数字 [1-4] 进行表示。如：中国 -> zhong1 guo2

INITIALS = 3¶: 声母风格，只返回各个拼音的声母部分（注：有的拼音没有声母，详见 #27）。如：中国 -> zh g

FIRST_LETTER = 4¶: 首字母风格，只返回拼音的首字母部分。如：中国 -> z g

FINALS = 5¶: 韵母风格，只返回各个拼音的韵母部分，不带声调。如：中国 -> ong uo

FINALS_TONE = 6¶: 标准韵母风格，带声调，声调在韵母第一个字母上。如：中国 -> ōng uó

FINALS_TONE2 = 7¶: 韵母风格2，带声调，声调在各个韵母之后，用数字 [1-4] 进行表示。如：中国 -> o1ng uo2

FINALS_TONE3 = 9¶: 韵母风格3，带声调，声调在各个拼音之后，用数字 [1-4] 进行表示。如：中国 -> ong1 uo2

BOPOMOFO = 10¶: 注音风格，带声调，阴平（第一声）不标。如：中国 -> ㄓㄨㄥㄍㄨㄛˊ

BOPOMOFO_FIRST = 11¶: 注音风格，仅首字母。如：中国 -> ㄓㄍ

CYRILLIC = 12¶: 汉语拼音与俄语字母对照风格，声调在各个拼音之后，用数字 [1-4] 进行表示。如：中国 -> чжун1 го2

CYRILLIC_FIRST = 13¶: 汉语拼音与俄语字母对照风格，仅首字母。如：中国 -> ч г

WADEGILES = 14¶: 威妥玛拼音/韦氏拼音/威式拼音风格，无声调

核心 API¶

pypinyin.pinyin(hans, style=Style.TONE, heteronym=False, errors='default', strict=True, v_to_u=False, neutral_tone_with_five=False)[源代码]¶

将汉字转换为拼音，返回汉字的拼音列表。

参数

hans (unicode 字符串或字符串列表) – 汉字字符串( '你好吗' )或列表( ['你好', '吗'] ). 可以使用自己喜爱的分词模块对字符串进行分词处理, 只需将经过分词处理的字符串列表传进来就可以了。
style – 指定拼音风格，默认是 TONE 风格。更多拼音风格详见 Style
errors –
指定如何处理没有拼音的字符。详见处理不包含拼音的字符
- 'default': 保留原始字符
- 'ignore': 忽略该字符
- 'replace': 替换为去掉 \u 的 unicode 编码字符串 ('\u90aa' => '90aa')
- callable 对象: 回调函数之类的可调用对象。
heteronym – 是否启用多音字
strict – 只获取声母或只获取韵母相关拼音风格的返回结果是否严格遵照《汉语拼音方案》来处理声母和韵母，详见 strict 参数的影响
v_to_u (bool) – 无声调相关拼音风格下的结果是否使用 ü 代替原来的 v 当为 False 时结果中将使用 v 表示 ü
neutral_tone_with_five (bool) – 声调使用数字表示的相关拼音风格下的结果是否使用 5 标识轻声

返回

拼音列表

返回类型

list

抛出

AssertionError – 当传入的字符串不是 unicode 字符时会抛出这个异常

Usage:

>>> from pypinyin import pinyin, Style
>>> import pypinyin
>>> pinyin('中心')
[['zhōng'], ['xīn']]
>>> pinyin('中心', heteronym=True)  # 启用多音字模式
[['zhōng', 'zhòng'], ['xīn']]
>>> pinyin('中心', style=Style.FIRST_LETTER)  # 设置拼音风格
[['z'], ['x']]
>>> pinyin('中心', style=Style.TONE2)
[['zho1ng'], ['xi1n']]
>>> pinyin('中心', style=Style.CYRILLIC)
[['чжун1'], ['синь1']]
>>> pinyin('战略', v_to_u=True, style=Style.NORMAL)
[['zhan'], ['lüe']]
>>> pinyin('衣裳', style=Style.TONE3, neutral_tone_with_five=True)
[['yi1'], ['shang5']]

pypinyin.lazy_pinyin(hans, style=Style.NORMAL, errors='default', strict=True, v_to_u=False, neutral_tone_with_five=False, tone_sandhi=False)[源代码]¶

将汉字转换为拼音，返回不包含多音字结果的拼音列表.

与 pinyin() 的区别是返回的拼音是个字符串，并且每个字只包含一个读音.

参数

hans (unicode 字符串或字符串列表) – 汉字字符串( '你好吗' )或列表( ['你好', '吗'] ). 可以使用自己喜爱的分词模块对字符串进行分词处理, 只需将经过分词处理的字符串列表传进来就可以了。
style – 指定拼音风格，默认是 NORMAL 风格。更多拼音风格详见 Style。
errors – 指定如何处理没有拼音的字符，详情请参考 pinyin()
strict – 只获取声母或只获取韵母相关拼音风格的返回结果是否严格遵照《汉语拼音方案》来处理声母和韵母，详见 strict 参数的影响
v_to_u (bool) – 无声调相关拼音风格下的结果是否使用 ü 代替原来的 v 当为 False 时结果中将使用 v 表示 ü
neutral_tone_with_five (bool) – 声调使用数字表示的相关拼音风格下的结果是否使用 5 标识轻声
tone_sandhi (bool) – 是否按照声调变调规则对拼音进行处理（使用预先通过分词库进行过分词后的结果作为 hans 参数的值效果会更好，因为变调效果依赖分词效果）

返回

拼音列表(e.g. ['zhong', 'guo', 'ren'])

返回类型

list

抛出

AssertionError – 当传入的字符串不是 unicode 字符时会抛出这个异常

Usage:

>>> from pypinyin import lazy_pinyin, Style
>>> import pypinyin
>>> lazy_pinyin('中心')
['zhong', 'xin']
>>> lazy_pinyin('中心', style=Style.TONE)
['zhōng', 'xīn']
>>> lazy_pinyin('中心', style=Style.FIRST_LETTER)
['z', 'x']
>>> lazy_pinyin('中心', style=Style.TONE2)
['zho1ng', 'xi1n']
>>> lazy_pinyin('中心', style=Style.CYRILLIC)
['чжун1', 'синь1']
>>> lazy_pinyin('战略', v_to_u=True)
['zhan', 'lüe']
>>> lazy_pinyin('衣裳', style=Style.TONE3, neutral_tone_with_five=True)
['yi1', 'shang5']
>>> lazy_pinyin('你好', style=Style.TONE2, tone_sandhi=True)
['ni2', 'ha3o']

pypinyin.load_single_dict(pinyin_dict, style='default')[源代码]¶

载入用户自定义的单字拼音库

参数

pinyin_dict (dict) – 单字拼音库。比如： {0x963F: u"ā,ē"}
style – pinyin_dict 参数值的拼音库风格. 支持 ‘default’, ‘tone2’

pypinyin.load_phrases_dict(phrases_dict, style='default')[源代码]¶

载入用户自定义的词语拼音库

参数

phrases_dict (dict) – 词语拼音库。比如： {u"阿爸": [[u"ā"], [u"bà"]]}
style – phrases_dict 参数值的拼音库风格. 支持 ‘default’, ‘tone2’

pypinyin.slug(hans, style=Style.NORMAL, heteronym=False, separator='-', errors='default', strict=True)[源代码]¶

将汉字转换为拼音，然后生成 slug 字符串.

参数

hans (unicode 字符串或字符串列表) – 汉字字符串( '你好吗' )或列表( ['你好', '吗'] ). 可以使用自己喜爱的分词模块对字符串进行分词处理, 只需将经过分词处理的字符串列表传进来就可以了。
style – 指定拼音风格，默认是 NORMAL 风格。更多拼音风格详见 Style
heteronym – 是否启用多音字
separator – 两个拼音间的分隔符/连接符
errors – 指定如何处理没有拼音的字符，详情请参考 pinyin()
strict – 只获取声母或只获取韵母相关拼音风格的返回结果是否严格遵照《汉语拼音方案》来处理声母和韵母，详见 strict 参数的影响

返回

slug 字符串.

抛出

AssertionError – 当传入的字符串不是 unicode 字符时会抛出这个异常

>>> import pypinyin
>>> from pypinyin import Style
>>> pypinyin.slug('中国人')
'zhong-guo-ren'
>>> pypinyin.slug('中国人', separator=' ')
'zhong guo ren'
>>> pypinyin.slug('中国人', style=Style.FIRST_LETTER)
'z-g-r'
>>> pypinyin.slug('中国人', style=Style.CYRILLIC)
'чжун1-го2-жэнь2'

注册新的拼音风格¶

pypinyin.style.register(style, func=None)[源代码]¶

注册一个拼音风格实现。自定义的函数应当使用 **kwargs 来兼容后续可能会新增的关键字参数，当前默认会传递如下参数：

pinyin: 原始有声调的单个拼音
strict: 是否开启 strict 模式
han: 当前拼音对应的原始汉字

@register('echo')
def echo(pinyin, **kwargs):
    return pinyin

# or
register('echo', echo)

contrib¶

拼音转换¶

pypinyin.contrib.tone_convert.to_normal(pinyin, v_to_u=False)[源代码]¶

将 TONE、 TONE2 或 TONE3 风格的拼音转换为 NORMAL 风格的拼音

参数

pinyin – TONE、 TONE2 或 TONE3 风格的拼音
v_to_u – 是否使用 ü 代替原来的 v，当为 False 时结果中将使用 v 表示 ü

返回

NORMAL 风格的拼音

Usage:

>>> from pypinyin.contrib.tone_convert import to_normal
>>> to_normal('zhōng')
'zhong'
>>> to_normal('zho1ng')
'zhong'
>>> to_normal('zhong1')
'zhong'
>>> to_normal('lüè')
'lve'
>>> to_normal('lüè', v_to_u=True)
'lüe'

pypinyin.contrib.tone_convert.to_tone(pinyin)[源代码]¶

将 TONE2 或 TONE3 风格的拼音转换为 TONE 风格的拼音

参数: pinyin – TONE2 或 TONE3 风格的拼音
返回: TONE 风格的拼音

Usage:

>>> from pypinyin.contrib.tone_convert import to_tone
>>> to_tone('zho1ng')
'zhōng'
>>> to_tone('zhong1')
'zhōng'

pypinyin.contrib.tone_convert.to_tone2(pinyin, v_to_u=False, neutral_tone_with_five=False, **kwargs)[源代码]¶

将 TONE 或 TONE3 风格的拼音转换为 TONE2 风格的拼音

参数

pinyin – TONE 或 TONE3 风格的拼音
v_to_u – 是否使用 ü 代替原来的 v，当为 False 时结果中将使用 v 表示 ü
neutral_tone_with_five – 是否使用 5 标识轻声
kwargs – 用于兼容老版本的 neutral_tone_with_5 参数，当传入 neutral_tone_with_5 参数时，将覆盖 neutral_tone_with_five 的值。

返回

TONE2 风格的拼音

Usage:

>>> from pypinyin.contrib.tone_convert import to_tone2
>>> to_tone2('zhōng')
'zho1ng'
>>> to_tone2('zhong1')
'zho1ng'
>>> to_tone2('shang')
'shang'
>>> to_tone2('shang', neutral_tone_with_five=True)
'sha5ng'
>>> to_tone2('lüè')
'lve4'
>>> to_tone2('lüè', v_to_u=True)
'lüe4'

pypinyin.contrib.tone_convert.to_tone3(pinyin, v_to_u=False, neutral_tone_with_five=False, **kwargs)[源代码]¶

将 TONE 或 TONE2 风格的拼音转换为 TONE3 风格的拼音

参数

pinyin – TONE 或 TONE2 风格的拼音
v_to_u – 是否使用 ü 代替原来的 v，当为 False 时结果中将使用 v 表示 ü
neutral_tone_with_five – 是否使用 5 标识轻声
kwargs – 用于兼容老版本的 neutral_tone_with_5 参数，当传入 neutral_tone_with_5 参数时，将覆盖 neutral_tone_with_five 的值。

返回

TONE2 风格的拼音

Usage:

>>> from pypinyin.contrib.tone_convert import to_tone3
>>> to_tone3('zhōng')
'zhong1'
>>> to_tone3('zho1ng')
'zhong1'
>>> to_tone3('shang')
'shang'
>>> to_tone3('shang', neutral_tone_with_five=True)
'shang5'
>>> to_tone3('lüè')
'lve4'
>>> to_tone3('lüè', v_to_u=True)
'lüe4'

pypinyin.contrib.tone_convert.to_initials(pinyin, strict=True)[源代码]¶

将 TONE、 TONE2 、 TONE3 或 NORMAL 风格的拼音转换为 INITIALS 风格的拼音

参数

pinyin – TONE、 TONE2 、 TONE3 或 NORMAL 风格的拼音
strict – 返回结果是否严格遵照《汉语拼音方案》来处理声母和韵母，详见 strict 参数的影响

返回

INITIALS 风格的拼音

Usage:

>>> from pypinyin.contrib.tone_convert import to_initials
>>> to_initials('zhōng')
'zh'

pypinyin.contrib.tone_convert.to_finals(pinyin, strict=True, v_to_u=False)[源代码]¶

将 TONE、 TONE2 、 TONE3 或 NORMAL 风格的拼音转换为 FINALS 风格的拼音

参数

pinyin – TONE、 TONE2 、 TONE3 或 NORMAL 风格的拼音
strict – 返回结果是否严格遵照《汉语拼音方案》来处理声母和韵母，详见 strict 参数的影响
v_to_u – 是否使用 ü 代替原来的 v，当为 False 时结果中将使用 v 表示 ü

返回

FINALS 风格的拼音

Usage:

>>> from pypinyin.contrib.tone_convert import to_finals
>>> to_finals('zhōng')
'ong'

pypinyin.contrib.tone_convert.to_finals_tone(pinyin, strict=True)[源代码]¶

将 TONE、 TONE2 或 TONE3 风格的拼音转换为 FINALS_TONE 风格的拼音

参数

pinyin – TONE、 TONE2 或 TONE3 风格的拼音
strict – 返回结果是否严格遵照《汉语拼音方案》来处理声母和韵母，详见 strict 参数的影响

返回

FINALS_TONE 风格的拼音

Usage:

>>> from pypinyin.contrib.tone_convert import to_finals_tone
>>> to_finals_tone('zhōng')
'ōng'

pypinyin.contrib.tone_convert.to_finals_tone2(pinyin, strict=True, v_to_u=False, neutral_tone_with_five=False)[源代码]¶

将 TONE、 TONE2 或 TONE3 风格的拼音转换为 FINALS_TONE2 风格的拼音

参数

pinyin – TONE、 TONE2 或 TONE3 风格的拼音
strict – 返回结果是否严格遵照《汉语拼音方案》来处理声母和韵母，详见 strict 参数的影响
v_to_u – 是否使用 ü 代替原来的 v，当为 False 时结果中将使用 v 表示 ü
neutral_tone_with_five – 是否使用 5 标识轻声

返回

FINALS_TONE2 风格的拼音

Usage:

>>> from pypinyin.contrib.tone_convert import to_finals_tone2
>>> to_finals_tone2('zhōng')
'o1ng'

pypinyin.contrib.tone_convert.to_finals_tone3(pinyin, strict=True, v_to_u=False, neutral_tone_with_five=False)[源代码]¶

将 TONE、 TONE2 或 TONE3 风格的拼音转换为 FINALS_TONE3 风格的拼音

参数

pinyin – TONE、 TONE2 或 TONE3 风格的拼音
strict – 返回结果是否严格遵照《汉语拼音方案》来处理声母和韵母，详见 strict 参数的影响
v_to_u – 是否使用 ü 代替原来的 v，当为 False 时结果中将使用 v 表示 ü
neutral_tone_with_five – 是否使用 5 标识轻声

返回

FINALS_TONE3 风格的拼音

Usage:

>>> from pypinyin.contrib.tone_convert import to_finals_tone3
>>> to_finals_tone3('zhōng')
'ong1'

开发文档¶

准备开发环境¶

$ virtualenv venv
$ . venv/bin/activate
(venv) $ pip install -U -r requirements_dev.txt
(venv) $ pip install -e .
(venv) $ pre-commit install

TODO: 把这个步骤放到一个 make 命令中。

备注

推荐在 Python 3.6+ 环境下进行开发。

测试¶

可以通过 make test 命令在当前 Python 版本下运行单元测试:

(venv) $ make test

可以通过 tox 测试程序在多个 Python 版本下的单元测试结果（这一步也可以在提 PR 的时候通过 CI 来运行）:

(venv) $ tox

备注

如果对测试有疑问或者有些测试实在无法通过，可以先提交 PR 大家一起来看看。

目录结构¶

关键文件和目录

$ tree -L 2
.
├── CHANGELOG.rst        # 更新日志
├── Makefile
├── README.rst
├── docs                 # 文档
├── gen_phrases_dict.py  # 生成 phrases_dict.py 的脚本
├── gen_pinyin_dict.py   # 生成 pinyin_dict.py 的脚本
├── phrase-pinyin-data   # gen_phrases_dict.py 使用的数据源
├── pinyin-data          # gen_pinyin_dict.py 使用的数据源
├── pypinyin             # pypinyin 模块源代码
│   ├── __init__.py
│   ├── __main__.py      # 命令行程序的入口
│   ├── compat.py
│   ├── constants.py
│   ├── contrib          # 目前包含了一个分词模块
│   ├── core.py          # pypinyin 模块的核心逻辑
│   ├── phonetic_symbol.py
│   ├── phrases_dict.py   # 词组的拼音数据，由 gen_phrases_dict.py 生成
│   ├── pinyin_dict.py    # 单个汉字的拼音数据，由 gen_pinyin_dict.py 生成
│   ├── runner.py         # 命令行程序的主逻辑
│   ├── standard.py       # strict=True 时的拼音转换逻辑
│   ├── style             # 各种拼音风格在 style 目录下实现
│   ├── utils.py
├── pytest.ini
├── requirements_dev.txt
├── setup.cfg
├── setup.py
├── tests
├── tox.ini

实现思路/主逻辑¶

主逻辑:

对输入的字符串按是否是汉字进行分词（seg）
对分词结果的每个词条进行获取词条拼音的逻辑
1. 检查词条是否是汉字，不是汉字则走处理没有拼音数据的逻辑（handle_nopinyin）
2. 检查词条是否在 PHRASES_DICT 中，如果在直接取 PHRASES_DICT 中这个词条的拼音数据
3. 如果词条不在 PHRASES_DICT 中，遍历词条包含的字符，每个字符进行 single_pinyin 逻辑处理
single_pinyin 的逻辑：
1. 检查字符是否在 PINYIN_DICT 中，如果在的话，取 PINYIN_DICT 中这个字符的拼音数据
2. 如果不在的话，走 handle_nopinyin 逻辑
handle_nopinyin 逻辑: 根据 errors 参数的值返回不同的结果。
对上面的步骤获得的拼音数据按指定的拼音风格进行转换。

PHRASES_DICT：词组拼音数据
PINYIN_DICT: 单个汉字的拼音数据

TODO: 画流程图

发布新版本¶

切分到 develop 分支
rebase master 分支的代码: make rebase_master
通过 make gen_data 生成最新的数据文件
通过 make test 跑测试
更新 CHANGELOG
提交代码
检查 develop 分支的 CI 结果
切换到 master 分支
合并 develop 分支代码: make merge_dev
更新版本号:
- 大改动(1.1.x -> 1.2.x)：make bump_minor
- 小改动(1.1.1 -> 1.1.2)：make bump_patch
发布到 test pypi: make publish_test
安装和测试发布到 test pypi 上的版本
发布到 pypi: make publish
安装和测试发布到 pypi 上的版本
提交 master 分支代码，更新 develop 分支代码，进入下一个开发阶段：make start_next

FAQ¶

拼音有误？¶

可以通过下面的方法提高拼音准确性：

可以通过自定义词组拼音库或者单字拼音库的方式修正拼音结果，详见文档。

>> from pypinyin import load_phrases_dict, load_single_dict

>> load_phrases_dict({'桔子': [['jú'], ['zǐ']]})  # 增加 "桔子" 词组

>> load_single_dict({ord('还'): 'hái,huán'})  # 调整 "还" 字的拼音顺序或覆盖默认拼音

也可以使用 pypinyin-dict 项目提供的自定义拼音库来纠正结果。

# 使用 phrase-pinyin-data 项目中 cc_cedict.txt 文件中的拼音数据优化结果
>>> from pypinyin_dict.phrase_pinyin_data import cc_cedict
>>> cc_cedict.load()

# 使用 pinyin-data 项目中 cc_cedict.txt 文件中的拼音数据优化结果
>>> from pypinyin_dict.pinyin_data import kxhc1983
>>> kxhc1983.load()

如果是分词导致的拼音有误的话，可以先使用其他的分词模块对数据进行分词处理，然后将分词后的词组结果列表作为函数的参数即可:

>>> # 使用其他分词模块分词，比如 jieba 之类，
>>> #或者基于 phrases_dict.py 里的词语数据使用其他分词算法分词
>>> words = list(jieba.cut('每股24.67美元的确定性协议'))
>>> pinyin(words)

如果你希望能通过训练模型的方式提高拼音准确性的话，可以看一下 pypinyin-g2pW 这个项目。

如何禁用内置的“词组拼音库”¶

设置环境变量 PYPINYIN_NO_PHRASES=true 即可

如何禁用默认的“拼音库”copy 操作¶

设置环境变量 PYPINYIN_NO_DICT_COPY=true 即可.

副作用: 用户的自定义拼音库出现问题时, 无法回退到自带的拼音库.

如何减少内存占用¶

如果对拼音正确性不在意的话，可以按照上面所说的设置环境变量 PYPINYIN_NO_PHRASES 和 PYPINYIN_NO_DICT_COPY 详见 #13

`INITIALS` 声母风格下，以 `y`, `w`, `yu` 开头的汉字返回空字符串¶

比如：

pinyin('火影忍者', style=Style.INITIALS)
[['h'], [''], ['r'], ['zh']]

因为 y, w, yu 都不是声母。参考: hotoo/pinyin#57, #22, #27, #44

声母风格（INITIALS）下，“雨”、“我”、“圆”等汉字返回空字符串，因为根据《汉语拼音方案》， y，w，ü (yu) 都不是声母，在某些特定韵母无声母时，才加上 y 或 w，而 ü 也有其特定规则。如果你觉得这个给你带来了麻烦，那么也请小心一些无声母的汉字（如“啊”、“饿”、“按”、“昂”等）。这时候你也许需要的是首字母风格（FIRST_LETTER）。 —— @hotoo

如果觉得这个行为不是你想要的，就是想把 y 当成声母的话，可以指定 strict=False ，这个可能会符合你的预期。详见 strict 参数的影响

存在既没有声母也没有韵母的拼音？¶

是的，strict=True 模式下存在极少数既没有声母也没有韵母的拼音。比如下面这些拼音（来自汉字 嗯、呒、呣、唔）:

ń ńg ňg ǹg ň ǹ m̄ ḿ m̀

尤其需要注意的是 嗯 的所有拼音都既没有声母也没有韵母，呣 的默认拼音既没有声母也没有韵母。详见 #109 #259 #284 。

如何将某一风格的拼音转换为其他风格的拼音？¶

可以通过 pypinyin.contrib.tone_convert 模块提供的辅助函数对标准拼音进行转换，得到不同风格的拼音。比如将 zhōng 转换为 zhong，或者获取拼音中的声母或韵母数据：

>>> from pypinyin.contrib.tone_convert import to_normal, to_tone, to_initials, to_finals
>>> to_normal('zhōng')
'zhong'
>>> to_tone('zhong1')
'zhōng'
>>> to_initials('zhōng')
'zh'
>>> to_finals('zhōng')
'ong'

更多拼音转换的辅助函数，详见 pypinyin.contrib.tone_convert 模块的文档。

Changelog¶

0.49.0 (2023-05-14)¶

[Improved] 使用 phrase-pinyin-data v0.15.0 的词语拼音数据。

0.48.0 (2023-01-15)¶

[Bugfixed] 修复 pypinyin.contrib.tone_convert 中 to_ 开头的转换函数没有正确处理输入的拼音包含 5 的场景（当包含 5 时会导致返回的格式不符合函数预期的返回格式）以及修复没有正确处理部分拼音中的 ü 或 v 的问题（当 v_to_u=False 时返回结果需要将 ü 替换为 v） Fixed #290 :

# 修复前
>>> to_tone('lve')
'lve'
>>> to_tone2('lün5')
'lv5n'
>>> to_tone3('lün5')
'lv5n'
>>> to_tone2('lvn5')
'lv5n'
>>> to_tone3('lvn5')
'lv5n'

# 修复后
>>> to_tone('lve')
'lüe'
>>> to_tone2('lün5')
'lvn'
>>> to_tone3('lün5')
'lvn'
>>> to_tone2('lvn5')
'lvn'
>>> to_tone3('lvn5')
'lvn'
>>> to_tone2('lvn5', v_to_u=True)
'lün'
>>> to_tone3('lvn5', v_to_u=True)
'lün'
>>> to_tone2('lvn', neutral_tone_with_five=True)
'lv5n'
>>> to_tone3('lvn', neutral_tone_with_five=True)
'lvn5'

[Bugfixed] 修复 Style.BOPOMOFO 风格下未处理 ê 的问题。Fixed #291
[Improved] 使用 phrase-pinyin-data v0.14.0 的词语拼音数据。

0.47.1 (2022-08-21)¶

[Bugfixed] 修复在处理既没有声母也没有韵母的拼音时，指定 neutral_tone_with_five=True 会返回 5 作为拼音的问题（#284）:

# 修复前
>>> lazy_pinyin('嗯', style=Style.FINALS_TONE3, neutral_tone_with_five=True)
['5']
# 修复后
>>> lazy_pinyin('嗯', style=Style.FINALS_TONE3, neutral_tone_with_five=True)
['']

0.47.0 (2022-07-30)¶

[New] [Changed] 自定义拼音风格的回调函数新增关键字参数 han ，用于接收对应的原始汉字:

@register('new_style')
def new_style_func(pinyin, **kwargs):
    return kwargs.get('han', '') + pinyin

pinyin('北京', style='new_style')  # output: [['北běi'], ['京jīng']]

[Improved] 使用 phrase-pinyin-data v0.13.0 的词语拼音数据。
[Improved] 使用 pinyin-data v0.13.0 的拼音数据。
[Bugfixed] 修复 tone_to_tone3 函数对空字符串的处理 via #279

0.46.0 (2022-02-12)¶

[New] pypinyin.contrib.tone_convert 模块新增 to_finals_tone 、to_finals_tone2 以及 to_finals_tone3 函数，用于将拼音转换为 Style.FINALS_TONE 、 Style.FINALS_TONE2 以及 Style.FINALS_TONE3 风格的结果。
[Changed] 将 pypinyin.contrib.tone_convert 模块中 to_tone2 、 to_tone3、 tone_to_tone2 及 tone_to_tone3 函数的 neutral_tone_with_5 参数重命名为统一的 neutral_tone_with_five 参数名称，兼容已有代码传入的 neutral_tone_with_5 参数。建议升级版本后择期修改为使用新的 neutral_tone_with_five 参数名称。

0.45.0 (2022-01-23)¶

[Bugfixed] 修复韵母相关拼音风格在 strict=True 时未按预期只返回拼音标准中定义过的韵母。 (Fixes #266, Closes #80)
[New] pypinyin.contrib.tone_convert 模块新增 to_initials 和 to_finals 函数，用于将拼音转换为 Style.INITIALS 和 Style.FINALS 风格的结果。

0.44.0 (2021-11-14)¶

[New] 增加 Python 3.10 下的测试，正式支持 Python 3.10 。
[New] tone2_to_tone3 、tone3_to_tone2 新增 v_to_u=False 参数
[Bugfixed] 修复 pypinyin.contrib.tone_convert 中无声调相关风格转换没有正确处理 v_to_u 参数的问题（Fixes #251 ）
[Improved] 使用 phrase-pinyin-data v0.12.0 的词语拼音数据。
[Improved] 使用 pinyin-data v0.12.0 的拼音数据。

0.43.0 (2021-10-06)¶

[New] lazy_pinyin 函数增加参数 tone_sandhi 用于控制是否对拼音结果按变调规则进行处理:

>>> lazy_pinyin('你好', style=Style.TONE2)
['ni3', 'ha3o']
>>> lazy_pinyin('你好', style=Style.TONE2, tone_sandhi=True)
['ni2', 'ha3o']

0.42.1 (2021-09-30)¶

[Improved] 使用 phrase-pinyin-data v0.11.0 的词语拼音数据。
[Improved] 使用 pinyin-data v0.11.0 的拼音数据。

0.42.0 (2021-06-14)¶

[New] 新增 Style.WADEGILES ：威妥玛拼音/韦氏拼音/威式拼音风格，无声调

>>> lazy_pinyin('威妥玛拼音', style=Style.WADEGILES)
['wei', "t'o", 'ma', "p'in", 'yin']

0.41.0 (2021-03-13)¶

[New] 新增 pypinyin.contrib.tone_convert 模块，用于 Style.TONE 、 Style.TONE2 、 Style.TONE3 、 Style.NORMAL 风格的拼音之间互相转换。详见文档
[Improved] 使用 pinyin-data v0.10.2 的拼音数据。

0.40.0 (2020-11-22)¶

[Improved] 精简 phrases_dict, 删除 phrases_dict 中凡是能通过 pinyin_dict 得到相同结果的数据。
[Improved] 使用 phrase-pinyin-data v0.10.5 的词语拼音数据。
[Improved] 使用 pinyin-data v0.10.1 的拼音数据。

0.39.1 (2020-10-08)¶

[Improved] 使用 phrase-pinyin-data v0.10.4 的词语拼音数据。
[Improved] 使用 pinyin-data v0.10.0 的拼音数据。

0.39.0 (2020-08-16)¶

[New] pinyin 和 lazy_pinyin 函数增加参数 v_to_u 和 neutral_tone_with_five:

v_to_u=True 时在无声调相关拼音风格下使用 ü 代替原来的 v

>>> lazy_pinyin('战略')
['zhan', 'lve']
>>> lazy_pinyin('战略', v_to_u=True)
['zhan', 'lüe']

neutral_tone_with_five=True 时在数字标识声调相关风格下使用 5 标识轻声

>>> lazy_pinyin('衣裳', style=Style.TONE3)
['yi1', 'shang']
>>> lazy_pinyin('衣裳', style=Style.TONE3, neutral_tone_with_five=True)
['yi1', 'shang5']

0.38.1 (2020-07-05)¶

[Improved] 优化内置分词，处理前缀匹配导致无法正确识别尾部词语的问题。 Fixed #205
[Improved] 使用 phrase-pinyin-data v0.10.3 的词语拼音数据。

0.38.0 (2020-06-07)¶

[Improved] 优化内置分词，严格按照是否是词语来分词。 Fixed #139
[Improved] 使用 pinyin-data v0.9.0 的拼音数据。

0.37.0 (2020-02-09)¶

[Bugfixed] 修复 NeutralToneWith5Mixin 在 TONE3 相关风格未把 5 标在预期的拼音末尾位置。
[New] 增加 Python 3.8 下的测试，正式支持 Python 3.8 。

0.36.0 (2019-10-27)¶

[New] 增加 V2UMixin 用于支持无声调相关拼音风格下的结果使用 ü 代替原来的 v 。详见文档。
[New] 增加 NeutralToneWith5Mixin 用于支持使用数字表示声调的拼音风格下使用 5 标识轻声。详见文档。
[New] 增加 Pinyin 和 DefaultConverter 类用于实现自定义处理过程和结果（实验性功能，绝大部分用户无需关心新增的这两个类）。
[Improved] 使用 phrase-pinyin-data v0.10.2 的词语拼音数据。
[Improved] 使用 pinyin-data v0.8.1 的拼音数据。

0.35.4 (2019-07-13)¶

[Bugfixed] 修复 m̄ ê̄ ế ê̌ ề 这几个音无法转换为不含声调结果的问题。
[Improved] 使用 phrase-pinyin-data v0.10.1 的词语拼音数据。 Fixed #174
[Improved] 使用 pinyin-data v0.8.0 的拼音数据。
[Improved] 修复一处参数注释错误。(via #176 Thanks @yangwe1)

0.35.3 (2019-05-11)¶

[Bugfixed] 修复鼻音 m̀ 无法转换为不含声调结果的问题。
[Improved] 使用 phrase-pinyin-data v0.10.0 的词语拼音数据。 Fixed #166 #167 #169 #170
[Improved] Windows CI 增加在 x64 下跑测试 (via #164 Thanks @hanabi1224)

0.35.2 (2019-04-06)¶

[Improved] 使用 phrase-pinyin-data v0.9.2 的词语拼音数据。 Fixed #159 #160
[Improved] 使用 pinyin-data v0.7.0 的拼音数据。

0.35.1 (2019-03-02)¶

[Bugfixed] 修复 朝阳 在 heteronym=False 时输出了多个音的情况。

0.35.0 (2019-02-24)¶

[Improved] 使用 phrase-pinyin-data v0.9.0 的词语拼音数据。 Fixed #154 #149
[New] 支持 朝阳 这种一个词多个音（ '朝阳': [['zhāo', 'cháo'], ['yáng']] ）在多音字模式下输出多个音。 Fixed #154

0.34.1 (2018-12-30)¶

[Improved] 使用 phrase-pinyin-data v0.8.5 的词语拼音数据。 Fixed #151

0.34.0 (2018-12-08)¶

不兼容旧版的变更¶

[Changed] 当 errors 参数的值是个回调对象并且返回值是个 list 时，会使用这个 list 来 extend 结果 list (via #147 . Thanks @howl-anderson )

# 更新前
>>> pinyin('你好☆☆', errors=lambda x: ['star' for _ in x])
[['nǐ'], ['hǎo'], ['star', 'star']]

# 更新后
>>> pinyin('你好☆☆', errors=lambda x: ['star' for _ in x])
[['nǐ'], ['hǎo'], ['star'], ['star']]

详见文档: https://pypinyin.readthedocs.io/zh_CN/develop/usage.html#handle-no-pinyin

0.33.2 (2018-11-03)¶

[Bugfixed] 修复 strict=True 时韵母相关风格下没有正确处理韵母 üan 的问题。

0.33.1 (2018-09-23)¶

[Improved] 使用 pinyin-data v0.6.2 的拼音数据。
[Improved] 使用 phrase-pinyin-data v0.8.4 的词语拼音数据。

0.33.0 (2018-08-05)¶

[Bugfixed] 修复命令行程序在 sys.stdin.encoding 为 None 时无法正常工作的问题。
[Improved] 使用 pinyin-data v0.6.1 的拼音数据。
[Improved] 使用 phrase-pinyin-data v0.8.3 的词语拼音数据。
- Fixed #137
[Changed] 不再测试 Python 2.6 和 Python 3.3，增加测试 Python 3.7 和 PyPy3 即不保证程序兼容 Python 2.6 和 Python 3.3。

0.32.0 (2018-07-28)¶

[Improved] 使用 pinyin-data v0.6.0 的拼音数据。
[Improved] 使用 phrase-pinyin-data v0.8.2 的词语拼音数据。

0.31.0 (2018-06-10)¶

[New] 增加 py.typed 标记文件，支持 PEP 561 (via #130)
[Changed] 使用 phrase-pinyin-data v0.7.3 的词语拼音数据。
- fixed #112 #117 #122 #131
- 精简词组拼音，删除部分数据有误的拼音数据

0.30.1 (2018-04-25)¶

[Improved] 更新文档和测试。(via 7fa0b87)
[Improved] 对用户传入的已进行分词处理的数据进行二次分词以便提高准确性。(via #126)
[Improved] 使用 pinyin-data v0.5.1 的拼音数据。(via #125)

0.30.0 (2018-02-03)¶

[New] 支持有拼音的非汉字字符 〇 (via #119)。
[Changed] 修复之前无意中把 pinyin 函数中的 strict 参数的默认值修改为了 False ，现在把 strict 参数的默认值恢复为预期的 True (via #121)。关于 strict 参数的影响详见文档： strict 参数的影响

0.29.0 (2018-01-14)¶

[New] 可以通过环境变量 PYPINYIN_NO_DICT_COPY 禁用代码内对 dict 的 copy 操作，节省内存(via #115 thanks @daya0576 )。

0.28.0 (2017-12-08)¶

[New] 给代码增加类型注解(via #110)。

0.27.0 (2017-10-28)¶

[New] 命令行工具支持通过更简便的方式指定参数及拼音风格。 (详见 #105, Thanks @wdscxsj )
[Improved] 增加说明 strict 参数对结果有什么影响的文档。

0.26.1 (2017-10-25)¶

[Improved] 使用 phrase-pinyin-data v0.5.1 的词语拼音数据。fixed #106

0.26.0 (2017-10-12)¶

[Changed] 不再自动调用 jieba 分词模块，改为自动调用内置的正向最大匹配分词模块来分词。 (via #102)

0.25.0 (2017-10-01)¶

[New] 内置一个正向最大匹配分词模块，使用内置的词语拼音库来训练这个分词模块，解决自定义词语库有时可能不生效的问题（因为这个词语在 jieba 等分词模块中不是可用词）。(via #81)

获取拼音或自定义词库后使用：

>>> from pypinyin import pinyin, load_phrases_dict
>>> load_phrases_dict({'了局': [['liǎo'], ['jú']]})
>>> pinyin('了局啊')   # 使用 jieba 分词
Building prefix dict from the default dictionary ...
Dumping model to file cache /var/folders/s6/z9r_07h53pj_d4x7qjszwmbw0000gn/T/jieba.cache
Loading model cost 1.175 seconds.
Prefix dict has been built succesfully.
[['le'], ['jú'], ['a']]

>>> from pypinyin.contrib.mmseg import seg, retrain
>>> retrain(seg)   # 没有使用 load_phrases_dict 时可以不调用这个函数
>>> pinyin(seg.cut('了局啊'))  # 使用内置的正向最大匹配分词
[['liǎo'], ['jú'], ['a']]
>>>

单独使用:

>>> from pypinyin.contrib.mmseg import seg
>>> text = '你好，我是中国人，我爱我的祖国'
>>> seg.cut(text)
<generator object Seg.cut at 0x10b2df2b0>
>>> list(seg.cut(text))
['你好', '，', '我', '是', '中国人', '，', '我', '爱',
 '我的', '祖', '国']
>>> seg.train(['祖国', '我是'])
>>> list(seg.cut(text))
['你好', '，', '我是', '中国人', '，', '我', '爱',
 '我的', '祖国']
>>>

0.24.0 (2017-09-17)¶

[New] 支持类似 pyinstaller 的打包工具对使用 pypinyin 的程序进行打包，不会出现跟打包前不一样的输出（比如： #92 ）（via #93 ）。

0.23.0 (2017-07-09)¶

[New] 使用 phrase-pinyin-data v0.5.0 的词语拼音数据。

0.22.0 (2017-06-14)¶

[New] 支持 IronPython (via #86). Thanks @LevyLession

0.21.1 (2017-05-29)¶

[Bugfixed] 修复在 Python 2 下通过 pip install 安装 wheel 格式的安装包后, 无法正常使用的问题。（Python 2 下没有自动安装依赖包）

0.21.0 (2017-05-14)¶

[New] 重构各拼音风格实现，支持自定义拼音风格或覆盖已有拼音风格的实现.

from pypinyin.style import register

@register('style1')
def func(pinyin, **kwargs):
    # pinyin = xxx   # convert to style1
    return pinyin

def func(pinyin, **kwargs):
    # pinyin = xxx   # convert to style2
    return pinyin
register('style2', func=func)

0.20.0 (2017-05-13)¶

[New] 增加 strict 参数来控制处理声母和韵母时是否严格遵循《汉语拼音方案》标准。

当 strict=True 时根据《汉语拼音方案》的如下规则处理声母、在韵母相关风格下还原正确的韵母：
- 21 个声母： b p m f d t n l g k h j q x zh ch sh r z c s （y, w 不是声母）
- i行的韵母，前面没有声母的时候，写成yi(衣)，ya(呀)，ye(耶)，yao(腰)，you(忧)，yan(烟)，yin(因)，yang(央)，ying(英)，yong(雍)。（y 不是声母）
- u行的韵母，前面没有声母的时候，写成wu(乌)，wa(蛙)，wo(窝)，wai(歪)，wei(威)，wan(弯)，wen(温)，wang(汪)，weng(翁)。（w 不是声母）
- ü行的韵母，前面没有声母的时候，写成yu(迂)，yue(约)，yuan(冤)，yun(晕)；ü上两点省略。（韵母相关风格下还原正确的韵母 ü）
- ü行的韵跟声母j，q，x拼的时候，写成ju(居)，qu(区)，xu(虚)，ü上两点也省略；但是跟声母n，l拼的时候，仍然写成nü(女)，lü(吕)。（韵母相关风格下还原正确的韵母 ü）
- iou，uei，uen前面加声母的时候，写成iu，ui，un。例如niu(牛)，gui(归)，lun(论)。（韵母相关风格下还原正确的韵母 iou，uei，uen）
具体差异可以查看 tests/test_standard.py 中的对比结果测试用例
[Changed] 改为使用 enum 定义拼音风格（兼容旧版本）

0.19.0 (2017-05-05)¶

[New] 韵母风格下根据汉语拼音方案还原原始的 iou , uei , uen 韵母。
iou，uei，uen前面加声母的时候，写成iu，ui，un。例如niu(牛)，gui(归)，lun(论)。即：
- niu 的韵母是 iou
- gui 的韵母是 uei
- lun 的韵母是 uen
[Fixed] 修复韵母相关风格下没有正确处理 wu 的韵母的问题 (比如: 无 在 FINALS_TONE 风格下的结果是 uú 的问题) 。
[Fixed] 修复漏了 ǖ -> v1 的转换。

0.18.2 (2017-04-25)¶

[Fixed] 使用 phrase-pinyin-data v0.4.1 的词语拼音数据, fixed #72 。

0.18.1 (2017-03-22)¶

[Improved] PyPI 上传过程中出了点问题。

0.18.0 (2017-03-22)¶

[Changed] 使用 phrase-pinyin-data v0.4.0 的词语拼音数据。

0.17.0 (2017-03-13)¶

[Changed] 词语拼音数据改为使用来自 phrase-pinyin-data v0.3.1 的拼音数据。
[Fixed] 修正 斯事体大 的拼音。

0.16.1 (2017-02-12)¶

[Improved] 使用 pinyin-data v0.4.1 的拼音数据. fixed #58
[Improved] 更新厦门的拼音. fixed #59

0.16.0 (2016-11-27)¶

[New] Added new pinyin styles - CYRILLIC (汉语拼音与俄语字母对照表) and CYRILLIC _FIRST (via #55 thanks @tyrbonit)

>>> pypinyin.pinyin('中心', style=pypinyin.CYRILLIC)
[['чжун1'], ['синь1']]
>>> pypinyin.pinyin('中心', style=pypinyin.CYRILLIC_FIRST)
[['ч'], ['с']]

[New] Added Russian translation README (README_ru.rst)
[New] Command-line tool supported the new pinyin styles: CYRILLIC, CYRILLIC_FIRST

0.15.0 (2016-10-18)¶

[Changed] 使用 pinyin-data v0.4.0 的拼音数据

0.14.0 (2016-09-24)¶

[New] 新增注音 BOPOMOFO 及注音首字母 BOPOMOFO_FIRST 风格(via #51 thanks @gumblex @Artoria2e5)

>>> pypinyin.pinyin('中心', style=pypinyin.BOPOMOFO)
[['ㄓㄨㄥ'], ['ㄒㄧㄣ']]
>>> pypinyin.pinyin('中心', style=pypinyin.BOPOMOFO_FIRST)
[['ㄓ'], ['ㄒ']]

[New] 新增音调在拼音后的 TONE3 以及 FINALS_TONE3 风格(via #51 thanks @gumblex @Artoria2e5 )

>>> pypinyin.pinyin('中心', style=pypinyin.TONE3)
[['zhong1'], ['xin1']]
>>> pypinyin.pinyin('中心', style=pypinyin.FINALS_TONE3)
[['ong1'], ['in1']]

[New] 命令行程序支持新增的四个风格: TONE3, FINALS_TONE3, BOPOMOFO, BOPOMOFO_FIRST
[Bugfixed] 修复 TONE2 中 ü 标轻声的问题（像侵略 -> qi1n lv0e4），以及去除文档中 0 表示轻声(via #51 thanks @gumblex)
[Changed] 不再使用 0 表示轻声，轻声时没有数字(via #51 thanks @gumblex)

0.13.0 (2016-08-19)¶

[Changed] 分离词组库中包含中文逗号的词语(via f097b6a)
[Changed] 使用 pinyin-data v0.3.0 的拼音数据

0.12.1 (2016-05-11)¶

[Bugfixed] 修复一些词语存在拼音粘连在一起的情况. (#41 thanks @jolly-tao )

0.12.0 (2016-03-12)¶

[Changed] 单个汉字的拼音数据改为使用来自 pinyin-data 的拼音数据。

[New] 命令行程序支持从标准输入读取汉字信息:

$ echo "你好" | pypinyin
nǐ hǎo
$ pypinyin < hello.txt
nǐ hǎo

0.11.1 (2016-02-17)¶

[Bugfixed] 更新 phrases_dict 修复类似 #36 的问题。thanks @someus

0.11.0 (2016-01-16)¶

[Changed] 分割 __init__.py 为 compat.py, constants.py， core.py 和 utils.py。影响: __init__.py 中只保留文档中提到过的 api, 如果使用了不在文档中的 api 则需要调整代码。

0.10.0 (2016-01-02)¶

[New] Python 3.3++++ 以上版本默认支持 U++++20000 ~ U++++2FA1F 区间内的汉字(详见 #33)

0.9.5 (2015-12-19)¶

[Bugfixed] 修复未正确处理鼻音（详见汉语拼音 - 维基百科）的问题(#31 thanks @xulin97 ):
- ḿ、ń、ň、ǹ 对应 “呒”、“呣”、“唔”、“嗯”等字。这些字之前在各种风格下都输出原始的汉字而不是拼音。

0.9.4 (2015-11-27)¶

[Improved] 细微调整，主要是更新文档

0.9.3 (2015-11-15)¶

[Bugfixed] Fixed Python 3 compatibility was broken.

0.9.2 (2015-11-15)¶

[New] load_single_dict 和 load_phrases_dict 增加 style 参数支持 TONE2 风格的拼音

load_single_dict({ord(u'啊'): 'a1'}, style='tone2')
load_phrases_dict({u"阿爸": [[u"a1"], [u"ba4"]]}, style='tone2'}

[Improved] Improved docs

0.9.1 (2015-10-17)¶

[Bugfixed][Changed] 修复 ju, qu, xu, yu, yi 和 wu 的韵母( #26 ). Thanks @MingStar :
- ju, qu, xu 的韵母应该是 v
- yi 的韵母是 i
- wu 的韵母是 u
- 从现在开始 y 既不是声母也不是韵母，详见汉语拼音方案

0.9.0 (2015-09-20)¶

[Changed] 将拼音词典库里的国际音标字母替换为 ASCII 字母. Thanks @MingStar :
- ɑ -> a
- ɡ -> g

0.8.5 (2015-08-23)¶

[Bugfixed] 修复 zh, ch, sh, z, c, s 顺序问题导致获取声母有误

0.8.4 (2015-08-23)¶

[Changed] y, w 也不是声母. (hotoo/pinyin#57):
- 以 y, w 开头的拼音在声母(INITIALS)模式下将返回 ['']

0.8.3 (2015-08-20)¶

[Improved] 上传到 PyPI 出了点问题，但是又没法重新上传，只好新增一个版本

0.8.2 (2015-08-20)¶

[Bugfixed][Changed] 修复误把 yu 放入声母列表里的 BUG(#22). Thanks @MingStar

0.8.1 (2015-07-04)¶

[Bugfixed] 重构内置的分词功能，修复“无法正确处理包含空格的字符串的问题”

0.8.0 (2015-06-27)¶

[New] 内置简单的分词功能，完善处理没有拼音的字符（如果不需要处理多音字问题, 现在可以不用安装 jieba 或其他分词模块了）:

# 之前, 安装了结巴分词模块
lazy_pinyin(u'你好abc☆☆')
[u'ni', u'hao', 'a', 'b', 'c', u'\u2606', u'\u2606']

# 现在, 无论是否安装结巴分词模块
lazy_pinyin(u'你好abc☆☆')
[u'ni', u'hao', u'abc\u2606\u2606']

[Changed] 当 errors 参数是回调函数时，函数的参数由 单个字符 变更为 单个字符或词组 。

即: 对于 abc 字符串, 之前将调用三次 errors 回调函数: func('a') ... func('b') ... func('abc')

现在只调用一次: func('abc') 。

[Changed] 将英文字符也纳入 errors 参数的处理范围:

# 之前
lazy_pinyin(u'abc', errors='ignore')
[u'abc']

# 现在
lazy_pinyin(u'abc', errors='ignore')
[]

0.7.0 (2015-06-20)¶

[Bugfixed] Python 2 下无法使用 from pypinyin import * 的问题
[New] 支持以下环境变量:
- PYPINYIN_NO_JIEBA=true: 禁用“自动调用结巴分词模块”
- PYPINYIN_NO_PHRASES=true: 禁用内置的“词组拼音库”

0.6.0 (2015-06-10)¶

[New] errors 参数支持回调函数(#17):

def foobar(char):
    return u'a'
pinyin(u'あ', errors=foobar)

0.5.7 (2015-05-17)¶

[Bugfixed] 纠正包含 “便宜” 的一些词组的读音

0.5.6 (2015-02-26)¶

[Bugfixed] “苹果” pinyin error. #11
[Bugfixed] 重复 import jieba 的问题
[Improved] 精简 phrases_dict
[Improved] 更新文档

0.5.5 (2015-01-27)¶

[Bugfixed] phrases_dict error

0.5.4 (2014-12-26)¶

[Bugfixed] 无法正确处理由分词模块产生的中英文混合词组（比如：B超，维生素C）的问题. #8

0.5.3 (2014-12-07)¶

[Improved] 更新拼音库

0.5.2 (2014-09-21)¶

[Improved] 载入拼音库时，改为载入其副本。防止内置的拼音库被破坏
[Bugfixed] 胜败乃兵家常事 的音标问题

0.5.1 (2014-03-09)¶

[New] 参数 errors 用来控制如何处理没有拼音的字符:
- 'default': 保留原始字符
- 'ignore': 忽略该字符
- 'replace': 替换为去掉 \u 的 unicode 编码字符串(u'\u90aa' => u'90aa')
只处理 [^a-zA-Z0-9_] 字符。

0.5.0 (2014-03-01)¶

[Changed] 使用新的单字拼音库内容和格式

新的格式：{0x963F: u"ā,ē"}

旧的格式：{u'啊': u"ā,ē"}

0.4.4 (2014-01-16)¶

[Improved] 清理命令行命令的输出结果，去除无关信息
[Bugfixed] “ImportError: No module named runner”

0.4.3 (2014-01-10)¶

[Bugfixed] 命令行工具在 Python 3 下的兼容性问题

0.4.2 (2014-01-10)¶

[Changed] 拼音风格前的 STYLE_ 前缀（兼容包含 STYLE_ 前缀的拼音风格）
[New] 命令行工具，具体用法请见： pypinyin -h

0.4.1 (2014-01-04)¶

[New] 支持自定义拼音库，方便用户修正程序结果(load_single_dict, load_phrases_dict)

0.4.0 (2014-01-03)¶

[Changed] 将 jieba 模块改为可选安装，用户可以选择使用自己喜爱的分词模块对汉字进行分词处理
[New] 支持 Python 3

0.3.1 (2013-12-24)¶

[New] lazy_pinyin

>>> lazy_pinyin(u'中心')
['zhong', 'xin']

0.3.0 (2013-09-26)¶

[Bugfixed] 首字母风格无法正确处理只有韵母的汉字
[New] 三个拼音风格:
- pypinyin.STYLE_FINALS ：韵母风格1，只返回各个拼音的韵母部分，不带声调。如： ong uo
- pypinyin.STYLE_FINALS_TONE ：韵母风格2，带声调，声调在韵母第一个字母上。如： ōng uó
- pypinyin.STYLE_FINALS_TONE2 ：韵母风格2，带声调，声调在各个拼音之后，用数字 [0-4] 进行表示。如： o1ng uo2

0.2.0 (2013-09-22)¶

[Improved] 完善对中英文混合字符串的支持:

>> pypinyin.pinyin(u'你好abc')
[[u'n\u01d0'], [u'h\u01ceo'], [u'abc']]

0.1.0 (2013-09-21)¶

[New] Initial Release

汉字拼音转换工具（Python 版）¶

特性¶

Contents¶

安装¶

使用¶

示例¶

处理不包含拼音的字符¶

自定义拼音库¶

自定义拼音风格¶

strict 参数的影响¶

命令行工具¶

API¶

拼音风格¶

核心 API¶

注册新的拼音风格¶

contrib¶

拼音转换¶

开发文档¶

准备开发环境¶

测试¶

目录结构¶

实现思路/主逻辑¶

发布新版本¶

FAQ¶

拼音有误？¶

如何禁用内置的“词组拼音库”¶

如何禁用默认的“拼音库”copy 操作¶

如何减少内存占用¶

INITIALS 声母风格下，以 y, w, yu 开头的汉字返回空字符串¶

存在既没有声母也没有韵母的拼音？¶

如何将某一风格的拼音转换为其他风格的拼音？¶

Related Projects¶

Changelog¶

0.49.0 (2023-05-14)¶

0.48.0 (2023-01-15)¶

0.47.1 (2022-08-21)¶

0.47.0 (2022-07-30)¶

0.46.0 (2022-02-12)¶

0.45.0 (2022-01-23)¶

0.44.0 (2021-11-14)¶

0.43.0 (2021-10-06)¶

0.42.1 (2021-09-30)¶

0.42.0 (2021-06-14)¶

0.41.0 (2021-03-13)¶

0.40.0 (2020-11-22)¶

0.39.1 (2020-10-08)¶

0.39.0 (2020-08-16)¶

0.38.1 (2020-07-05)¶

0.38.0 (2020-06-07)¶

0.37.0 (2020-02-09)¶

0.36.0 (2019-10-27)¶

0.35.4 (2019-07-13)¶

0.35.3 (2019-05-11)¶

0.35.2 (2019-04-06)¶

0.35.1 (2019-03-02)¶

0.35.0 (2019-02-24)¶

0.34.1 (2018-12-30)¶

0.34.0 (2018-12-08)¶

不兼容旧版的变更¶

0.33.2 (2018-11-03)¶

0.33.1 (2018-09-23)¶

0.33.0 (2018-08-05)¶

0.32.0 (2018-07-28)¶

0.31.0 (2018-06-10)¶

0.30.1 (2018-04-25)¶

0.30.0 (2018-02-03)¶

0.29.0 (2018-01-14)¶

0.28.0 (2017-12-08)¶

0.27.0 (2017-10-28)¶

0.26.1 (2017-10-25)¶

0.26.0 (2017-10-12)¶

0.25.0 (2017-10-01)¶

0.24.0 (2017-09-17)¶

0.23.0 (2017-07-09)¶

0.22.0 (2017-06-14)¶

0.21.1 (2017-05-29)¶

0.21.0 (2017-05-14)¶

0.20.0 (2017-05-13)¶

0.19.0 (2017-05-05)¶

0.18.2 (2017-04-25)¶

`strict` 参数的影响¶

`INITIALS` 声母风格下，以 `y`, `w`, `yu` 开头的汉字返回空字符串¶