改为使用 enum 来定义各个拼音风格

Makefile

@@ -3,6 +3,7 @@ help:
 	@echo "publish          publish to PyPI"
 	@echo "publish_test     publish to TestPyPI"
 	@echo "docs_html        make html docs"
+	@echo "docs_serve       serve docs"
 	@echo "gen_data         gen pinyin data"
 	@echo "gen_pinyin_dict  gen single hanzi pinyin dict"
 	@echo "gen_phrases_dict gen phrase hanzi pinyin dict"
@@ -28,6 +29,10 @@ publish_test:
 docs_html:
 	cd docs && make html
 
+.PHONY: docs_serve
+docs_serve: docs_html
+	cd docs/_build/html && python -m http.server
+
 .PHONY: gen_data
 gen_data: gen_pinyin_dict gen_phrases_dict
 

docs/api.rst

@@ -2,27 +2,10 @@ 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      声母风格，只返回各个拼音的声母部分（注：有的拼音没有声母，详见 `#27`_）。如： 中国 -> ``zh g``
-pypinyin.FIRST_LETTER    4      首字母风格，只返回拼音的首字母部分。如： 中国 -> ``z g``
-pypinyin.FINALS          5      韵母风格，只返回各个拼音的韵母部分，不带声调。如： 中国 -> ``ong uo``
-pypinyin.FINALS_TONE     6      韵母风格1，带声调，声调在韵母第一个字母上。如：中国 -> ``ōng uó``
-pypinyin.FINALS_TONE2    7      韵母风格2，带声调，声调在各个韵母之后，用数字 [1-4] 进行表示。如： 中国 -> ``o1ng uo2``
-pypinyin.FINALS_TONE3    9      韵母风格3，带声调，声调在各个拼音之后，用数字 [1-4] 进行表示。如： 中国 -> ``ong1 uo2``
-pypinyin.BOPOMOFO        10     注音风格，带声调，阴平（第一声）不标。如： 中国 -> ``ㄓㄨㄥ ㄍㄨㄛˊ``
-pypinyin.BOPOMOFO_FIRST  11     注音风格，仅首字母。如： 中国 -> ``ㄓ ㄍ``
-pypinyin.CYRILLIC        12     汉语拼音与俄语字母对照风格，声调在各个拼音之后，用数字 [1-4] 进行表示。如： 中国 -> ``чжун1 го2``
-pypinyin.CYRILLIC_FIRST  13     汉语拼音与俄语字母对照风格，仅首字母。如： 中国 -> ``ч г``
-=======================  ====   =========================================================================================
-
+.. autoclass:: pypinyin.Style
+   :members:
+   :undoc-members:
+   :member-order: bysource
 
 .. autofunction:: pypinyin.pinyin
 

pypinyin/__init__.py

@@ -7,6 +7,7 @@
 
 from pypinyin.compat import PY2
 from pypinyin.constants import (  # noqa
+    Style,
     STYLE_NORMAL, NORMAL,
     STYLE_TONE, TONE,
     STYLE_TONE2, TONE2,
@@ -32,7 +33,9 @@
 __license__ = 'MIT'
 __copyright__ = 'Copyright (c) 2016 mozillazg, 闲耘'
 __all__ = [
-    'pinyin', 'lazy_pinyin', 'slug', 'load_single_dict', 'load_phrases_dict',
+    'pinyin', 'lazy_pinyin', 'slug',
+    'load_single_dict', 'load_phrases_dict',
+    'Style',
     'STYLE_NORMAL', 'NORMAL',
     'STYLE_TONE', 'TONE',
     'STYLE_TONE2', 'TONE2',

pypinyin/constants.py

@@ -6,6 +6,8 @@
 import os
 import re
 
+from enum import IntEnum, unique
+
 from pypinyin import phonetic_symbol, pinyin_dict
 from pypinyin.compat import SUPPORT_UCS4
 
@@ -52,50 +54,56 @@
         r'])+$'
     )
 
-# 拼音风格
-PINYIN_STYLE = {
-    'NORMAL': 0,          # 普通风格，不带声调
-    'TONE': 1,            # 标准风格，声调在韵母的第一个字母上
-    'TONE2': 2,           # 声调在韵母之后，使用数字 1~4 标识
-    'TONE3': 8,           # 声调在拼音之后，使用数字 1~4 标识
-    'INITIALS': 3,        # 仅保留声母部分
-    'FIRST_LETTER': 4,    # 仅保留首字母
-    'FINALS': 5,          # 仅保留韵母部分，不带声调
-    'FINALS_TONE': 6,     # 仅保留韵母部分，带声调
-    'FINALS_TONE2': 7,    # 仅保留韵母部分，声调在韵母之后，使用数字 1~4 标识
-    'FINALS_TONE3': 9,    # 仅保留韵母部分，声调在拼音之后，使用数字 1~4 标识
-    'BOPOMOFO': 10,       # 注音符号，带声调，阴平（第一声）不标
-    'BOPOMOFO_FIRST': 11,  # 注音符号首字母
-    'CYRILLIC': 12,
-    'CYRILLIC_FIRST': 13,
-}
-# 普通风格，不带声调
-NORMAL = STYLE_NORMAL = PINYIN_STYLE['NORMAL']
-# 标准风格，声调在韵母的第一个字母上
-TONE = STYLE_TONE = PINYIN_STYLE['TONE']
-# 声调在韵母之后，使用数字 1~4 标识
-TONE2 = STYLE_TONE2 = PINYIN_STYLE['TONE2']
-# 声调在拼音之后，使用数字 1~4 标识
-TONE3 = STYLE_TONE3 = PINYIN_STYLE['TONE3']
-# 仅保留声母部分
-INITIALS = STYLE_INITIALS = PINYIN_STYLE['INITIALS']
-# 仅保留首字母
-FIRST_LETTER = STYLE_FIRST_LETTER = PINYIN_STYLE['FIRST_LETTER']
-# 仅保留韵母部分，不带声调
-FINALS = STYLE_FINALS = PINYIN_STYLE['FINALS']
-# 仅保留韵母部分，带声调
-FINALS_TONE = STYLE_FINALS_TONE = PINYIN_STYLE['FINALS_TONE']
-# 仅保留韵母部分，声调在韵母之后，使用数字 1~4 标识
-FINALS_TONE2 = STYLE_FINALS_TONE2 = PINYIN_STYLE['FINALS_TONE2']
-# 仅保留韵母部分，声调在拼音之后，使用数字 1~4 标识
-FINALS_TONE3 = STYLE_FINALS_TONE3 = PINYIN_STYLE['FINALS_TONE3']
-# 注音符号，带声调，阴平（第一声）不标
-BOPOMOFO = STYLE_BOPOMOFO = PINYIN_STYLE['BOPOMOFO']
-# 注音符号首字母
-BOPOMOFO_FIRST = STYLE_BOPOMOFO_FIRST = PINYIN_STYLE['BOPOMOFO_FIRST']
-# 俄语
-CYRILLIC = STYLE_CYRILLIC = PINYIN_STYLE['CYRILLIC']
-CYRILLIC_FIRST = STYLE_CYRILLIC_FIRST = PINYIN_STYLE['CYRILLIC_FIRST']
+
+@unique
+class Style(IntEnum):
+    """拼音风格"""
+
+    #: 普通风格，不带声调。如： 中国 -> ``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
+
+
+NORMAL = STYLE_NORMAL = Style.NORMAL
+TONE = STYLE_TONE = Style.TONE
+TONE2 = STYLE_TONE2 = Style.TONE2
+TONE3 = STYLE_TONE3 = Style.TONE3
+INITIALS = STYLE_INITIALS = Style.INITIALS
+FIRST_LETTER = STYLE_FIRST_LETTER = Style.FIRST_LETTER
+FINALS = STYLE_FINALS = Style.FINALS
+FINALS_TONE = STYLE_FINALS_TONE = Style.FINALS_TONE
+FINALS_TONE2 = STYLE_FINALS_TONE2 = Style.FINALS_TONE2
+FINALS_TONE3 = STYLE_FINALS_TONE3 = Style.FINALS_TONE3
+BOPOMOFO = STYLE_BOPOMOFO = Style.BOPOMOFO
+BOPOMOFO_FIRST = STYLE_BOPOMOFO_FIRST = Style.BOPOMOFO_FIRST
+CYRILLIC = STYLE_CYRILLIC = Style.CYRILLIC
+CYRILLIC_FIRST = STYLE_CYRILLIC_FIRST = Style.CYRILLIC_FIRST
+
 # 注音转换表
 BOPOMOFO_REPLACE = (
     (re.compile('^m(\d)$'), 'mu\\1'),  # 呣
@@ -131,6 +139,7 @@
     'bpmfdtnlgkhjqxZCSrzcsiuvaoeEAIOUMNKGR2340',
     'ㄅㄆㄇㄈㄉㄊㄋㄌㄍㄎㄏㄐㄑㄒㄓㄔㄕㄖㄗㄘㄙㄧㄨㄩㄚㄛㄜㄝㄞㄟㄠㄡㄢㄣㄤㄥㄦˊˇˋ˙'
 ))
+
 # 俄语转换表
 CYRILLIC_REPLACE = (
     (re.compile('ong'), 'ung'),

setup.py

@@ -24,6 +24,8 @@
 requirements = []
 if sys.version_info[:2] < (2, 7):
     requirements.append('argparse')
+if sys.version_info[:2] < (3, 4):
+    requirements.append('enum34')
 
 
 def long_description():