|
|
.. _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``
|
