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

Build Coverage PyPI version

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

基于 hotoo/pinyin 开发。

特性

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

Contents

安装

可以使用 pip 进行安装:

$ pip install pypinyin

easy_install 安装:

$ easy_install pypinyin

源码安装:

$ python setup.py install

使用

示例

>>> from pypinyin import pinyin, lazy_pinyin
>>> import pypinyin
>>> pinyin(u'中心')
[[u'zh\u014dng'], [u'x\u012bn']]
>>> pinyin(u'中心', heteronym=True)  # 启用多音字模式
[[u'zh\u014dng', u'zh\xf2ng'], [u'x\u012bn']]
>>> pinyin(u'中心', style=pypinyin.FIRST_LETTER)  # 设置拼音风格
[['z'], ['x']]
>>> pinyin('中心', style=pypinyin.TONE2, heteronym=True)
[['zho1ng', 'zho4ng'], ['xi1n']]
>>> lazy_pinyin(u'中心')  # 不考虑多音字的情况
['zhong', 'xin']

命令行工具

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

处理不包含拼音的字符

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

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

    lazy_pinyin(u'你好☆')
[u'ni', u'hao', u'\u2606']

  • ignore : 忽略该字符

    lazy_pinyin(u'你好☆', errors='ignore')
[u'ni', u'hao']

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

    lazy_pinyin(u'你好☆', errors='replace')
[u'ni', u'hao', u'2606']

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

    可参考 单元测试代码

    lazy_pinyin(u'你好☆', errors=lambda x: u'star')
[u'ni', u'hao', u'star']

分词处理(用于处理多音字和非中文字符)

  • 内置了简单的分词功能，对字符串按是否是中文字符进行分词。

    >> from pypinyin import lazy_pinyin
>> lazy_pinyin(u'你好abcこんにちは')
[u'ni', u'hao', u'abc\u3053\u3093\u306b\u3061\u306f']

    如果需要处理多音字问题，推荐同时安装其他分词模块。

  • 如果安装了 jieba 分词模块，程序会自动调用，
    也可以使用经过 jieba 分词处理的 字符串列表 作参数。

  • 使用其他分词模块：

    1. 安装分词模块，比如 pip install snownlp ；

    2. 使用经过分词处理的 字符串列表 作参数：

      >> from pypinyin import lazy_pinyin, TONE2
>> from snownlp import SnowNLP
>> hans = u'音乐123'
>> hans_seg = SnowNLP(hans).words  # 分词处理
>> hans_seg
[u'\u97f3\u4e50', u'123']
>> lazy_pinyin(hans_seg, style=TONE2)
[u'yi1n', u'yue4', u'123']

自定义拼音库

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

安装了 jieba 分词模块并且支持分词的词组

>> from pypinyin import lazy_pinyin, load_phrases_dict, TONE2
>> hans = u'桔子'
>> lazy_pinyin(hans, style=TONE2)
[u'jie2', u'zi3']
>> load_phrases_dict({u'桔子': [[u'jú'], [u'zǐ']]})
>> lazy_pinyin(hans, style=TONE2)
[u'ju2', u'zi3']

未安装 jieba 分词模块 and/or 不支持分词的词组

>> from pypinyin import lazy_pinyin, load_phrases_dict, TONE2, load_single_dict
>> hans = u'还没'
>> lazy_pinyin(hans, style=TONE2)
['hua2n', 'me2i']
>>>  # 第一种自定义词组的方法
>> load_phrases_dict({u'还没': [[u'hái'], [u'méi']]})
>>> lazy_pinyin(u'还没', style=TONE2)})
['hua2n', 'me2i']
>>> lazy_pinyin([u'还没'], style=TONE2)  # 手动指定 "还没" 为一个词组
['ha2i', 'me2i']
>>>  # 第二种自定义词组的方法
>> load_single_dict({ord(u'还'): u'hái,huán'})  # 调整 "还" 字的拼音顺序
>>> lazy_pinyin(u'还没', style=TONE2)
['ha2i', 'me2i']

API

拼音风格:

风格 值 含义
pypinyin.NORMAL 0 普通风格，不带声调。如： 中国 -> zhong guo
pypinyin.TONE 1 声调风格1，拼音声调在韵母第一个字母上（默认风格）。如： 中国 -> zhōng guó
pypinyin.TONE2 2 声调风格2，即拼音声调在各个韵母之后，用数字 [1-4] 进行表示。如： 中国 -> zho1ng guo2
pypinyin.TONE3 8 声调风格3，即拼音声调在各个拼音之后，用数字 [1-4] 进行表示。如： 中国 -> zhong1 guo2
pypinyin.INITIALS 3 声母风格，只返回各个拼音的声母部分。如： 中国 -> zh g
pypinyin.FIRST_LETTER 4 首字母风格，只返回拼音的首字母部分。如： 中国 -> z g
pypinyin.FINALS 5 韵母风格1，只返回各个拼音的韵母部分，不带声调。如： 中国 -> ong uo
pypinyin.FINALS_TONE 6 韵母风格2，带声调，声调在韵母第一个字母上。如：中国 -> ōng uó
pypinyin.FINALS_TONE2 7 韵母风格2，带声调，声调在各个韵母之后，用数字 [1-4] 进行表示。如： 中国 -> o1ng uo2
pypinyin.FINALS_TONE3 9 韵母风格3，带声调，声调在各个拼音之后，用数字 [1-4] 进行表示。如： 中国 -> o1ng uo2
pypinyin.BOPOMOFO 10 注音风格，带声调，阴平（第一声）不标。如： 中国 -> ㄓㄨㄥ ㄍㄨㄛˊ
pypinyin.BOPOMOFO_FIRST 11 注音风格，仅首字母。如： 中国 -> ㄓ ㄍ
pypinyin.pinyin(hans, style=1, heteronym=False, errors=u'default')[源代码]

将汉字转换为拼音.

参数:
  • hans (unicode 字符串或字符串列表) –

    汉字字符串( u'你好吗' )或列表( [u'你好', u'吗'] ).

    如果用户安装了 jieba , 将使用 jieba 对字符串进行 分词处理。可以通过传入列表的方式禁用这种行为。

    也可以使用自己喜爱的分词模块对字符串进行分词处理, 只需将经过分词处理的字符串列表传进来就可以了。

  • style – 指定拼音风格
  • errors –

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

    • 'default': 保留原始字符
    • 'ignore': 忽略该字符
    • 'replace': 替换为去掉 \u 的 unicode 编码字符串 (u'\u90aa' => u'90aa')
    • callable 对象: 回调函数之类的可调用对象。如果 erros 参数 的值是个可调用对象，那么程序会回调这个函数: func(char):
      def foobar(char):
    return 'a'
pinyin(u'あ', errors=foobar)
  • heteronym – 是否启用多音字
返回:

拼音列表
返回类型:

list

Usage:

>>> from pypinyin import pinyin
>>> import pypinyin
>>> pinyin(u'中心')
[[u'zhōng'], [u'xīn']]
>>> pinyin(u'中心', heteronym=True)  # 启用多音字模式
[[u'zhōng', u'zhòng'], [u'xīn']]
>>> pinyin(u'中心', style=pypinyin.FIRST_LETTER)  # 设置拼音风格
[[u'z'], [u'x']]
>>> pinyin(u'中心', style=pypinyin.TONE2)
[[u'zho1ng'], [u'xi1n']]
pypinyin.lazy_pinyin(hans, style=0, errors=u'default')[源代码]

不包含多音字的拼音列表.

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

参数:
  • hans (unicode or list) – 汉字
  • style – 指定拼音风格
  • errors – 指定如何处理没有拼音的字符，详情请参考 pinyin()
返回:

拼音列表(e.g. ['zhong', 'guo', 'ren'])
返回类型:

list

Usage:

>>> from pypinyin import lazy_pinyin
>>> import pypinyin
>>> lazy_pinyin(u'中心')
[u'zhong', u'xin']
>>> lazy_pinyin(u'中心', style=pypinyin.TONE)
[u'zhōng', u'xīn']
>>> lazy_pinyin(u'中心', style=pypinyin.FIRST_LETTER)
[u'z', u'x']
>>> lazy_pinyin(u'中心', style=pypinyin.TONE2)
[u'zho1ng', u'xi1n']
pypinyin.load_single_dict(pinyin_dict, style=u'default')[源代码]

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

参数:
  • pinyin_dict (dict) – 单字拼音库。比如： {0x963F: u"ā,ē"}
  • style – pinyin_dict 参数值的拼音库风格. 支持 ‘default’, ‘tone2’
pypinyin.load_phrases_dict(phrases_dict, style=u'default')[源代码]

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

参数:
  • phrases_dict (dict) – 词语拼音库。比如： {u"阿爸": [[u"ā"], [u"bà"]]}
  • style – phrases_dict 参数值的拼音库风格. 支持 ‘default’, ‘tone2’
pypinyin.slug(hans, style=0, heteronym=False, separator=u'-', errors=u'default')[源代码]

生成 slug 字符串.

参数:
  • hans (unicode or list) – 汉字
  • style – 指定拼音风格
  • heteronym – 是否启用多音字
  • separstor – 两个拼音间的分隔符/连接符
  • errors – 指定如何处理没有拼音的字符，详情请参考 pinyin()
返回:

slug 字符串.

 
>>> import pypinyin
>>> pypinyin.slug(u'中国人')
u'zhong-guo-ren'
>>> pypinyin.slug(u'中国人', separator=u' ')
u'zhong guo ren'
>>> pypinyin.slug(u'中国人', style=pypinyin.FIRST_LETTER)
u'z-g-r'

FAQ

  • Q: 如何禁用“自动调用结巴分词模块”功能：
    A: 设置环境变量 PYPINYIN_NO_JIEBA=true
  • Q: 如何禁用内置的“词组拼音库”：
    A: 设置环境变量 PYPINYIN_NO_PHRASES=true
  • Q: INITIALS 声母风格下，以 y, w, yu 开头的汉字返回空字符串，例如：
    pinyin(u'火影忍者', style=pypinyin.INITIALS)
[[u'h'], [u''], [u'r'], [u'zh']]
    A: 因为 y, w, yu 都不是声母。参考: hotoo/pinyin#57, #22, #27, #44

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

Changelog

0.15.0 (2016-10-18)

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)

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

Indices and tables