使用 ====== .. _example: 示例 ------- .. code-block:: python >>> from pypinyin import pinyin, lazy_pinyin, Style >>> 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']] >>> lazy_pinyin('中心') # 不考虑多音字的情况 ['zhong', 'xin'] **注意事项** : * 拼音结果不会标明哪个韵母是轻声,轻声的韵母没有声调或数字标识(使用 ``5`` 标识轻声的方法见 `文档 `__ )。 * 无声调相关拼音风格下的结果会使用 ``v`` 表示 ``ü`` (使用 ``ü`` 代替 ``v`` 的方法见 `文档 `__ )。 .. _handle_no_pinyin: 处理不包含拼音的字符 --------------------- 当程序遇到不包含拼音的字符(串)时,会根据 ``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', '☆']] .. _custom_dict: 自定义拼音库 ------------ 如果对结果不满意,可以通过 :py:func:`~pypinyin.load_single_dict` 或 :py:func:`~pypinyin.load_phrases_dict` 以自定义拼音库的方式修正结果: .. code-block:: python >> 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'] .. _custom_style: 自定义拼音风格 ---------------- 可以通过 :py:func:`~pypinyin.style.register` 来实现自定义拼音风格的需求: .. code-block:: python In [1]: from pypinyin import lazy_pinyin In [2]: from pypinyin.style import register In [3]: @register('kiss') ...: def kiss(pinyin, **kwargs): ...: return '😘 {0}'.format(pinyin) ...: In [4]: lazy_pinyin('么么', style='kiss') Out[4]: ['😘 me', '😘 me'] .. _strict: ``strict`` 参数的影响 ------------------------------- ``strict`` 参数用于控制处理声母和韵母时是否严格遵循 `《汉语拼音方案》`_ 标准: .. code-block:: python 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 `_ 中的对比结果测试用例 .. _cli: 命令行工具 ------------ 程序内置了一个命令行工具 ``pypinyin`` : .. code-block:: console $ pypinyin 音乐 yīn yuè $ pypinyin -h 命令行工具支持如下参数: .. code-block:: console $ 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 :py:attr:`~pypinyin.Style.NORMAL` zh4ao :py:attr:`~pypinyin.Style.TONE` zha4o :py:attr:`~pypinyin.Style.TONE2` zhao4 :py:attr:`~pypinyin.Style.TONE3` zh :py:attr:`~pypinyin.Style.INITIALS` z :py:attr:`~pypinyin.Style.FIRST_LETTER` ao :py:attr:`~pypinyin.Style.FINALS` 4ao :py:attr:`~pypinyin.Style.FINALS_TONE` a4o :py:attr:`~pypinyin.Style.FINALS_TONE2` ao4 :py:attr:`~pypinyin.Style.FINALS_TONE3` NORMAL :py:attr:`~pypinyin.Style.NORMAL` TONE :py:attr:`~pypinyin.Style.TONE` TONE2 :py:attr:`~pypinyin.Style.TONE2` TONE3 :py:attr:`~pypinyin.Style.TONE3` INITIALS :py:attr:`~pypinyin.Style.INITIALS` FIRST_LETTER :py:attr:`~pypinyin.Style.FIRST_LETTER` FINALS :py:attr:`~pypinyin.Style.FINALS` FINALS_TONE :py:attr:`~pypinyin.Style.FINALS_TONE` FINALS_TONE2 :py:attr:`~pypinyin.Style.FINALS_TONE2` FINALS_TONE3 :py:attr:`~pypinyin.Style.FINALS_TONE3` BOPOMOFO :py:attr:`~pypinyin.Style.BOPOMOFO` BOPOMOFO_FIRST :py:attr:`~pypinyin.Style.BOPOMOFO_FIRST` CYRILLIC :py:attr:`~pypinyin.Style.CYRILLIC` CYRILLIC_FIRST :py:attr:`~pypinyin.Style.CYRILLIC_FIRST` ================== ========================================= .. _《汉语拼音方案》: http://www.moe.edu.cn/s78/A19/yxs_left/moe_810/s230/195802/t19580201_186000.html