Python 项目模版

开发

• 使用 $ virtualenv venv --python=python3 && source venv/bin/activate 创建并激活此 virtualenv;
• 使用 $ make install_dev 或者$ pip install -e .[dev] 安装项目依赖
• Coding

静态检查

项目已经配置好使用 flake8 做静态检查，执行$ make lint即可。

测试

单元测试位于 tests/ 目录中，使用 $ make test 可以运行单元测试。如何编写单元测试可以参考 pytest

默认会在 Python2.7/3.7 环境下运行单元测试，如果需要支持更多版本 Python，可以修改 tox.ini。

规范

代码规范

• 需要保证代码兼容 Python2.7，Python3.7+；
• 代码风格兼容 PEP8，除了代码最大宽度放宽到 120。

版本规范

• 版本需要遵循 Semver；
• 发布分支后，需要创建类似 v0.0.1 的 tag；
• 每次 Release，需要编辑 CHANGELOG.md，内容需要遵守 changelog 规范。

Tips

Makefile指南

makefile用于帮助开发者快速使用功能，目前支持的命令有

建议每次准备发布代码前，执行一次make或者make check来保证代码的规范性和健壮性。

Python2/3 兼容

每个 Python 文件头部都增加如下代码(尽量保证此import位于任何其他import之前)：

# coding: utf-8

from __future__ import absolute_import, division, print_function, unicode_literals

来保证代码在 Python2 和 Python3 下尽可能保持一致。

Python2 与 Python3 不兼容的代码，尽量使用 six 模块做兼容。比如 Python2 和 Python3 下 range 函数行为不一致，统一使用 six.moves.range 可以保证兼容性。

类型标注

Python PEP484 中新增了类型标注功能，可以给代码增加可选的类型标注，配合 mypy 可以静态的给代码做类型检查。

开发中给每个 .py 文件编写一个对应的 .pyi，编写好导出类型的函数签名。此项目已经配置好相关规则，包发布后，使用者就可以使用编写好的类型信息做静态类型检查、代码补全。

如果对导出函数写 docstring，除了按照 PEP8 的要求进行编写之外，还可以对传入传出数据类型做标注与注释。注释格式参考 PyCharm 的这篇文档的格式进行编写。PyCharm 以及 Jedi（vim / emacs / vscode 都是基于 jedi 进行自动补全）等等自动补全/静态检查工具都可以基于此格式的信息进行检查，Sphinx 生成的 API doc 也可以进行识别。

editorconfig

可以安装 editorconfig 编辑器插件，保持代码一致性。此项目已经默认配置。