.. _develop: 开发文档 ======== 准备开发环境 ------------- :: $ virtualenv venv $ . venv/bin/activate (venv) $ pip install -U -r requirements_dev.txt (venv) $ pip install -e . (venv) $ pre-commit install TODO: 把这个步骤放到一个 make 命令中。 .. note:: 推荐在 Python 3.6+ 环境下进行开发。 测试 ------ 可以通过 ``make test`` 命令在当前 Python 版本下运行单元测试: :: (venv) $ make test 可以通过 ``tox`` 测试程序在多个 Python 版本下的单元测试结果(这一步也可以在提 PR 的时候通过 CI 来运行): :: (venv) $ tox .. note:: 如果对测试有疑问或者有些测试实在无法通过,可以先提交 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 实现思路/主逻辑 ---------------- 主逻辑: 1. 对输入的字符串按是否是汉字进行分词(``seg``) 2. 对分词结果的每个词条进行获取词条拼音的逻辑 1. 检查词条是否是汉字,不是汉字则走处理没有拼音数据的逻辑(``handle_nopinyin``) 2. 检查词条是否在 ``PHRASES_DICT`` 中,如果在直接取 ``PHRASES_DICT`` 中这个词条的拼音数据 3. 如果词条不在 ``PHRASES_DICT`` 中,遍历词条包含的字符,每个字符进行 ``single_pinyin`` 逻辑处理 3. ``single_pinyin`` 的逻辑: 1. 检查字符是否在 ``PINYIN_DICT`` 中,如果在的话,取 ``PINYIN_DICT`` 中这个字符的拼音数据 2. 如果不在的话,走 ``handle_nopinyin`` 逻辑 4. ``handle_nopinyin`` 逻辑: 根据 ``errors`` 参数的值返回不同的结果。 5. 对上面的步骤获得的拼音数据按指定的拼音风格进行转换。 * ``PHRASES_DICT``:词组拼音数据 * ``PINYIN_DICT``: 单个汉字的拼音数据 TODO: 画流程图 发布新版本 ---------- 1. 切分到 develop 分支 2. rebase master 分支的代码: ``make rebase_master`` 3. 通过 ``make gen_data`` 生成最新的数据文件 4. 通过 ``make test`` 跑测试 5. 更新 CHANGELOG 6. 提交代码 7. 检查 develop 分支的 CI 结果 8. 切换到 master 分支 9. 合并 develop 分支代码: ``make merge_dev`` 10. 更新版本号: * 大改动(1.1.x -> 1.2.x):``make bump_minor`` * 小改动(1.1.1 -> 1.1.2):``make bump_patch`` 11. 发布到 test pypi: ``make publish_test`` 12. 安装和测试发布到 test pypi 上的版本 13. 发布到 pypi: ``make publish`` 14. 安装和测试发布到 pypi 上的版本 15. 提交 master 分支代码,更新 develop 分支代码,进入下一个开发阶段:``make start_next``