开发文档

准备开发环境

$ virtualenv venv
$ . venv/bin/activate
(venv) $ pip install -U -r requirements_dev.txt
(venv) $ pip install -e .
(venv) $ pre-commit install

TODO: 把这个步骤放到一个 make 命令中。

备注

推荐在 Python 3.6+ 环境下进行开发。

测试

可以通过 make test 命令在当前 Python 版本下运行单元测试:

(venv) $ make test

可以通过 tox 测试程序在多个 Python 版本下的单元测试结果(这一步也可以在提 PR 的时候通过 CI 来运行):

(venv) $ tox

备注

如果对测试有疑问或者有些测试实在无法通过,可以先提交 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