1.1 pypinyin.pinyin

pypinyin的常用函数为pinyin，即将汉字转换为拼音，返回汉字的拼音列表。

pypinyin.pinyin(hans, style=Style.TONE, heteronym=False, errors=‘default’, strict=True, v_to_u=False, neutral_tone_with_five=False)

pinyin的参数介绍如下：

参数
hans：(unicode 字符串或字符串列表) – 汉字字符串( '你好吗' )或列表( ['你好', '吗'] )。

style：指定拼音风格，默认是 TONE（标注拼音） 风格。 

errors：指定如何处理没有拼音的字符。

heteronym： 是否启用多音字。

strict ：只获取声母或只获取韵母相关拼音风格的返回结果时，是否严格遵照《汉语拼音方案》来处理声母和韵母。

v_to_u (bool)：无声调相关拼音风格下的结果是否使用 ü 代替原来的 v ，当为False时结果中将使用 v 表示 ü。

neutral_tone_with_five (bool)：声调风格下是否用5表示轻声。

返回：拼音列表。

返回类型：list。

拼音风格style的可选参数列表如下：

#: 普通风格，不带声调。如： 中国 -> ``zhong guo``
NORMAL = 0
#: 标准声调风格，拼音声调在韵母第一个字母上（默认风格）。如： 中国 -> ``zhōng guó``
TONE = 1
#: 声调风格2，即拼音声调在各个韵母之后，用数字 [1-4] 进行表示。如： 中国 -> ``zho1ng guo2``
TONE2 = 2
#: 声调风格3，即拼音声调在各个拼音之后，用数字 [1-4] 进行表示。如： 中国 -> ``zhong1 guo2``
TONE3 = 8
#: 声母风格，只返回各个拼音的声母部分（注：有的拼音没有声母，详见 `#27`_）。如： 中国 -> ``zh g``
INITIALS = 3
#: 首字母风格，只返回拼音的首字母部分。如： 中国 -> ``z g``
FIRST_LETTER = 4
#: 韵母风格，只返回各个拼音的韵母部分，不带声调。如： 中国 -> ``ong uo``
FINALS = 5
#: 标准韵母风格，带声调，声调在韵母第一个字母上。如：中国 -> ``ōng uó``
FINALS_TONE = 6
#: 韵母风格2，带声调，声调在各个韵母之后，用数字 [1-4] 进行表示。如： 中国 -> ``o1ng uo2``
FINALS_TONE2 = 7
#: 韵母风格3，带声调，声调在各个拼音之后，用数字 [1-4] 进行表示。如： 中国 -> ``ong1 uo2``
FINALS_TONE3 = 9
#: 注音风格，带声调，阴平（第一声）不标。如： 中国 -> ``ㄓㄨㄥ ㄍㄨㄛˊ``
BOPOMOFO = 10
#: 注音风格，仅首字母。如： 中国 -> ``ㄓ ㄍ``
BOPOMOFO_FIRST = 11
#: 汉语拼音与俄语字母对照风格，声调在各个拼音之后，用数字 [1-4] 进行表示。如： 中国 -> ``чжун1 го2``
CYRILLIC = 12
#: 汉语拼音与俄语字母对照风格，仅首字母。如： 中国 -> ``ч г``
CYRILLIC_FIRST = 13
#: 威妥玛拼音/韦氏拼音/威式拼音风格，无声调
WADEGILES = 14

errors处理方式如下：

'default': 保留原始字符

'ignore': 忽略该字符

'replace': 替换为去掉 \u 的 unicode 编码字符串 ('\u90aa' => '90aa')

callable对象: 回调函数之类的可调用对象。

具体函数和参数使用如下：

基础使用

from pypinyin import pinyin
result = pinyin('中心')
print(type(result))
print(result)
result = pinyin('中毒')
print(result)

<class 'list'>
[['zhōng'], ['xīn']]
[['zhòng'], ['dú']]

启用多音字模式

result = pinyin('中心', heteronym=True) 
print(result)
result = pinyin('中毒', heteronym=True) 
print(result)

[['zhōng', 'zhòng'], ['xīn']]
[['zhòng'], ['dú']]

设置拼音风格

from pypinyin import pinyin, Style
result = pinyin('中心', style=Style.INITIALS) # 声母风格
print(result)
result = pinyin('中心', style=Style.FIRST_LETTER) # 首字母风格
print(result)
result = pinyin('中心', style=5) # 韵母风格
print(result)

[['zh'], ['x']]
[['z'], ['x']]
[['ong'], ['in']]

v_to_u

# 使用 ü 代替原来的 v
result = pinyin('战略', v_to_u=True, style=Style.NORMAL)
print(result)
result = pinyin('战略', v_to_u=False, style=Style.NORMAL)
print(result)

[['zhan'], ['lüe']]
[['zhan'], ['lve']]

neutral_tone_with_five

# 声调风格下是否用5表示轻声
result = pinyin('衣裳', style=Style.TONE3, neutral_tone_with_five=True)
print(result)
result = pinyin('衣裳', style=Style.TONE3, neutral_tone_with_five=False)
print(result)

[['yi1'], ['shang5']]
[['yi1'], ['shang']]

处理不包含拼音的字符

根据errors 参数的值做相应的处理即可。

# default (默认行为): 不做任何处理，原样返回:
result = pinyin('中心center')
print(result)

[['zhōng'], ['xīn'], ['center']]

# ignore : 忽略该字符
result = pinyin('中心center', errors='ignore')
print(result)

[['zhōng'], ['xīn']]

# replace : 替换为去掉 \u 的 unicode 编码:
result = pinyin('中心center', errors='replace')
print(result)

[['zhōng'], ['xīn'], ['63656e746572']]

# callable 对象 : 提供一个回调函数，接受无拼音字符(串)作为参数, 支持的返回值类型: unicode 或 list 或 None 。
result =pinyin('中心center', errors=lambda x: 'other')
print(result)

[['zhōng'], ['xīn'], ['other']]

strict参数的影响

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

result = pinyin('迂', style=Style.FINALS_TONE,strict=False)
print(result)
result = pinyin('迂', style=Style.FINALS_TONE,strict=True)
print(result)

[['ū']]
[['ǖ']]

1.2 pypinyin.lazy_pinyin

lazy_pinyin()将汉字转换为拼音，返回不包含多音字结果的拼音列表，与 pinyin()的区别是返回的拼音是个字符串， 并且每个字只包含一个读音。

pypinyin.lazy_pinyin(hans, style=Style.NORMAL, errors=‘default’, strict=True, v_to_u=False, neutral_tone_with_five=False, tone_sandhi=False)

lazy_pinyin与pinyin大部分参数是一样的，除了tone_sandhi。tone_sandhi表示是否按照声调变调规则对拼音进行处理。

示例

# 注意返回的是读音字符串
from pypinyin import lazy_pinyin, Style
result = lazy_pinyin('中心') 
print(result)
result = lazy_pinyin('中毒') 
print(result)

['zhong', 'xin']
['zhong', 'du']

# 是否按照声调变调规则对拼音进行处理
result = lazy_pinyin('你好', style=Style.TONE2, tone_sandhi=True)
print(result)
result = lazy_pinyin('你好', style=Style.TONE2, tone_sandhi=False)
print(result)

['ni2', 'ha3o']
['ni3', 'ha3o']

1.3 load_single_dict和load_phrases_dict

pypinyin.load_single_dict用于载入用户自定义的单字拼音库。

pypinyin.load_single_dict(pinyin_dict, style=‘default’)

pypinyin.load_single_dict的参数介绍如下：

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

pypinyin.load_phrases_dict用于载入用户自定义的词语拼音库。

pypinyin.load_phrases_dict(phrases_dict, style=‘default’)

pypinyin.load_phrases_dict的参数介绍如下：

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

具体函数和参数使用如下：

增加单字

from pypinyin import lazy_pinyin, load_phrases_dict, Style, load_single_dict
hans = '还没'
result = lazy_pinyin(hans, style=Style.TONE3)
print(result)
load_single_dict({ord('还'): 'huán, hái'})  # 调整 "还" 字的拼音顺序或覆盖默认拼音
result = lazy_pinyin('还没', style=Style.TONE3)
print(result)

['hai2', 'mei2']
['huan2', 'mei2']

增加词组

from pypinyin import lazy_pinyin, load_phrases_dict, Style, load_single_dict

hans = '桔子'
result = lazy_pinyin(hans, style=Style.TONE2)
print(result)
load_phrases_dict({'桔子': [['jú'], ['zǐ']]})  # 增加 "桔子" 词组
result = lazy_pinyin(hans, style=Style.TONE2)
print(result)

['ju2', 'zi']
['ju2', 'zi3']

pypinyin-dict

使用pypinyin-dict项目提供的自定义拼音库可以纠正结果。但是需要安装该自定义拼音库。

pip install pypinyin-dict

示例

from pypinyin import pinyin
result = pinyin('中心',heteronym=True)
print(result)

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

result = pinyin('中心',heteronym=True)
print(result)

[['zhōng', 'zhòng'], ['xīn']]
[['zhōng'], ['xīn']]

from pypinyin import pinyin

result = pinyin('扔', heteronym=True)
print(result)

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

result = pinyin('扔', heteronym=True)
print(result)

[['rēng', 'rèng']]
[['rēng']]

1.4 pypinyin.slug

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

pypinyin.slug(hans, style=Style.NORMAL, heteronym=False, separator=‘-’, errors=‘default’, strict=True)

pypinyin.slug的参数介绍如下：

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

返回：slug字符串.

示例

import pypinyin
from pypinyin import Style
result = pypinyin.slug('你我他')
print(result)
print(type(result))

result = pypinyin.slug('你我他', separator='|')
print(result)

result = pypinyin.slug('你我他', style=Style.FIRST_LETTER)
print(result)

ni-wo-ta
<class 'str'>
ni|wo|ta
n-w-t

1.5 pypinyin.style.register

pypinyin.style.register用于注册一个拼音风格实现。示例注册方式如下：

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

# or
register('echo', echo)

具体使用看示例代码理解：

from pypinyin import lazy_pinyin
from pypinyin.style import register

@register('kiss')
def kiss(pinyin, **kwargs):
    return '😘 {0}'.format(pinyin)

result = lazy_pinyin('么么')
print(result)
result = lazy_pinyin('么么', style='kiss')
print(result)

['me', 'me']
['😘 me', '😘 me']

2 参考

• python-pinyin

• pypinyin文档

• pypinyin-dict