# 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](https://github.com/pytest-dev/pytest)
默认会在 Python2.7/3.7 环境下运行单元测试，如果需要支持更多版本 Python，可以修改 `tox.ini`。
## 规范
### 代码规范
* 需要保证代码兼容 Python2.7，Python3.7+；
* 代码风格兼容 [PEP8](https://www.python.org/dev/peps/pep-0008/)，除了代码最大宽度放宽到 120。
### 版本规范
* 版本需要遵循 [Semver](https://semver.org/lang/zh-CN/)；
* 发布分支后，需要创建类似 `v0.0.1` 的 tag；
* 每次 Release，需要编辑 CHANGELOG.md，内容需要遵守 [changelog 规范](https://keepachangelog.com/zh-CN/1.0.0/)。
## Tips
### Makefile指南
makefile用于帮助开发者快速使用功能，目前支持的命令有
| 指令 | 作用 |
| :--------------: | :----------------------------------------------------------: |
| make | 按顺序执行 install_dev、isort、isort_check、lint、test(**操作更改代码!**) |
| make check | 按顺序执行 install_dev、isort_check、lint、test |
| make install_dev | 安装测试所需依赖(位于setup.py的DEV_REQUIRES) |
| make isort | 执行isort，规范化import顺序(**操作更改代码!**) |
| make isort_check | 执行import顺序规范性检查 |
| make lint | 执行flake8，检查你的代码规范性 |
| make test | 执行tox，检测单元测试的正确性 |
| make clean | 清除测试和检查产物 |
建议每次准备发布代码前，执行一次make或者make check来保证代码的规范性和健壮性。
### Python2/3 兼容
**每个** Python 文件头部都增加如下代码(尽量保证此import位于任何其他import之前)：
```python
# coding: utf-8
from __future__ import absolute_import, division, print_function, unicode_literals
```
来保证代码在 Python2 和 Python3 下尽可能保持一致。
Python2 与 Python3 不兼容的代码，尽量使用 [six](https://pythonhosted.org/six/) 模块做兼容。比如 Python2 和 Python3 下 `range` 函数行为不一致，统一使用 `six.moves.range` 可以保证兼容性。
### 类型标注
Python [PEP484](https://www.python.org/dev/peps/pep-0484/) 中新增了类型标注功能，可以给代码增加可选的类型标注，配合 [mypy](http://mypy-lang.org/) 可以静态的给代码做类型检查。
开发中给每个 `.py` 文件编写一个对应的 `.pyi`，编写好导出类型的函数签名。此项目已经配置好相关规则，包发布后，使用者就可以使用编写好的类型信息做静态类型检查、代码补全。
如果对导出函数写 docstring，除了按照 PEP8 的要求进行编写之外，还可以对传入传出数据类型做标注与注释。注释格式参考 PyCharm 的[这篇文档](https://www.jetbrains.com/help/pycharm/using-docstrings-to-specify-types.html)的格式进行编写。PyCharm 以及 Jedi（vim / emacs / vscode 都是基于 jedi 进行自动补全）等等自动补全/静态检查工具都可以基于此格式的信息进行检查，Sphinx 生成的 API doc 也可以进行识别。
### editorconfig
可以安装 [editorconfig](https://editorconfig.org/) 编辑器插件，保持代码一致性。此项目已经默认配置。
Raw data
{
"_id": null,
"home_page": "https://code.byted.org/liuzhe.inf/test_pip",
"name": "zxy-Test",
"maintainer": "",
"docs_url": null,
"requires_python": ">=2.7,!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*",
"maintainer_email": "",
"keywords": "boilerplate",
"author": "liuzhe.inf",
"author_email": "liuzhe.inf@bytedance.com",
"download_url": "https://files.pythonhosted.org/packages/84/f4/cedd40608c6444c15d5707564e058655f399f4b492d8d888c2df10e3f851/zxy_Test-0.3.tar.gz",
"platform": null,
"description": "# Python \u9879\u76ee\u6a21\u7248\n\n\n## \u5f00\u53d1\n\n* \u4f7f\u7528 `$ virtualenv venv --python=python3 && source venv/bin/activate` \u521b\u5efa\u5e76\u6fc0\u6d3b\u6b64 `virtualenv`;\n* \u4f7f\u7528 `$ make install_dev` \u6216\u8005`$ pip install -e .[dev]` \u5b89\u88c5\u9879\u76ee\u4f9d\u8d56\n* Coding\n\n\n\n## \u9759\u6001\u68c0\u67e5\n\n\u9879\u76ee\u5df2\u7ecf\u914d\u7f6e\u597d\u4f7f\u7528 `flake8` \u505a\u9759\u6001\u68c0\u67e5\uff0c\u6267\u884c`$ make lint`\u5373\u53ef\u3002\n\n\n\n## \u6d4b\u8bd5\n\n\u5355\u5143\u6d4b\u8bd5\u4f4d\u4e8e `tests/` \u76ee\u5f55\u4e2d\uff0c\u4f7f\u7528 `$ make test` \u53ef\u4ee5\u8fd0\u884c\u5355\u5143\u6d4b\u8bd5\u3002\u5982\u4f55\u7f16\u5199\u5355\u5143\u6d4b\u8bd5\u53ef\u4ee5\u53c2\u8003 [pytest](https://github.com/pytest-dev/pytest) \n\n\u9ed8\u8ba4\u4f1a\u5728 Python2.7/3.7 \u73af\u5883\u4e0b\u8fd0\u884c\u5355\u5143\u6d4b\u8bd5\uff0c\u5982\u679c\u9700\u8981\u652f\u6301\u66f4\u591a\u7248\u672c Python\uff0c\u53ef\u4ee5\u4fee\u6539 `tox.ini`\u3002\n\n\n\n## \u89c4\u8303\n\n### \u4ee3\u7801\u89c4\u8303\n\n* \u9700\u8981\u4fdd\u8bc1\u4ee3\u7801\u517c\u5bb9 Python2.7\uff0cPython3.7+\uff1b\n* \u4ee3\u7801\u98ce\u683c\u517c\u5bb9 [PEP8](https://www.python.org/dev/peps/pep-0008/)\uff0c\u9664\u4e86\u4ee3\u7801\u6700\u5927\u5bbd\u5ea6\u653e\u5bbd\u5230 120\u3002\n\n### \u7248\u672c\u89c4\u8303\n\n* \u7248\u672c\u9700\u8981\u9075\u5faa [Semver](https://semver.org/lang/zh-CN/)\uff1b\n* \u53d1\u5e03\u5206\u652f\u540e\uff0c\u9700\u8981\u521b\u5efa\u7c7b\u4f3c `v0.0.1` \u7684 tag\uff1b\n* \u6bcf\u6b21 Release\uff0c\u9700\u8981\u7f16\u8f91 CHANGELOG.md\uff0c\u5185\u5bb9\u9700\u8981\u9075\u5b88 [changelog \u89c4\u8303](https://keepachangelog.com/zh-CN/1.0.0/)\u3002\n\n\n\n## Tips\n\n### Makefile\u6307\u5357\n\nmakefile\u7528\u4e8e\u5e2e\u52a9\u5f00\u53d1\u8005\u5feb\u901f\u4f7f\u7528\u529f\u80fd\uff0c\u76ee\u524d\u652f\u6301\u7684\u547d\u4ee4\u6709\n\n| \u6307\u4ee4 | \u4f5c\u7528 |\n| :--------------: | :----------------------------------------------------------: |\n| make | \u6309\u987a\u5e8f\u6267\u884c install_dev\u3001isort\u3001isort_check\u3001lint\u3001test(**\u64cd\u4f5c\u66f4\u6539\u4ee3\u7801!**) |\n| make check | \u6309\u987a\u5e8f\u6267\u884c install_dev\u3001isort_check\u3001lint\u3001test |\n| make install_dev | \u5b89\u88c5\u6d4b\u8bd5\u6240\u9700\u4f9d\u8d56(\u4f4d\u4e8esetup.py\u7684DEV_REQUIRES) |\n| make isort | \u6267\u884cisort\uff0c\u89c4\u8303\u5316import\u987a\u5e8f(**\u64cd\u4f5c\u66f4\u6539\u4ee3\u7801!**) |\n| make isort_check | \u6267\u884cimport\u987a\u5e8f\u89c4\u8303\u6027\u68c0\u67e5 |\n| make lint | \u6267\u884cflake8\uff0c\u68c0\u67e5\u4f60\u7684\u4ee3\u7801\u89c4\u8303\u6027 |\n| make test | \u6267\u884ctox\uff0c\u68c0\u6d4b\u5355\u5143\u6d4b\u8bd5\u7684\u6b63\u786e\u6027 |\n| make clean | \u6e05\u9664\u6d4b\u8bd5\u548c\u68c0\u67e5\u4ea7\u7269 |\n\n\u5efa\u8bae\u6bcf\u6b21\u51c6\u5907\u53d1\u5e03\u4ee3\u7801\u524d\uff0c\u6267\u884c\u4e00\u6b21make\u6216\u8005make check\u6765\u4fdd\u8bc1\u4ee3\u7801\u7684\u89c4\u8303\u6027\u548c\u5065\u58ee\u6027\u3002\n\n### Python2/3 \u517c\u5bb9\n\n**\u6bcf\u4e2a** Python \u6587\u4ef6\u5934\u90e8\u90fd\u589e\u52a0\u5982\u4e0b\u4ee3\u7801(\u5c3d\u91cf\u4fdd\u8bc1\u6b64import\u4f4d\u4e8e\u4efb\u4f55\u5176\u4ed6import\u4e4b\u524d)\uff1a\n\n```python\n# coding: utf-8\n\nfrom __future__ import absolute_import, division, print_function, unicode_literals\n```\n\n\u6765\u4fdd\u8bc1\u4ee3\u7801\u5728 Python2 \u548c Python3 \u4e0b\u5c3d\u53ef\u80fd\u4fdd\u6301\u4e00\u81f4\u3002\n\nPython2 \u4e0e Python3 \u4e0d\u517c\u5bb9\u7684\u4ee3\u7801\uff0c\u5c3d\u91cf\u4f7f\u7528 [six](https://pythonhosted.org/six/) \u6a21\u5757\u505a\u517c\u5bb9\u3002\u6bd4\u5982 Python2 \u548c Python3 \u4e0b `range` \u51fd\u6570\u884c\u4e3a\u4e0d\u4e00\u81f4\uff0c\u7edf\u4e00\u4f7f\u7528 `six.moves.range` \u53ef\u4ee5\u4fdd\u8bc1\u517c\u5bb9\u6027\u3002\n\n### \u7c7b\u578b\u6807\u6ce8\n\nPython [PEP484](https://www.python.org/dev/peps/pep-0484/) \u4e2d\u65b0\u589e\u4e86\u7c7b\u578b\u6807\u6ce8\u529f\u80fd\uff0c\u53ef\u4ee5\u7ed9\u4ee3\u7801\u589e\u52a0\u53ef\u9009\u7684\u7c7b\u578b\u6807\u6ce8\uff0c\u914d\u5408 [mypy](http://mypy-lang.org/) \u53ef\u4ee5\u9759\u6001\u7684\u7ed9\u4ee3\u7801\u505a\u7c7b\u578b\u68c0\u67e5\u3002\n\n\u5f00\u53d1\u4e2d\u7ed9\u6bcf\u4e2a `.py` \u6587\u4ef6\u7f16\u5199\u4e00\u4e2a\u5bf9\u5e94\u7684 `.pyi`\uff0c\u7f16\u5199\u597d\u5bfc\u51fa\u7c7b\u578b\u7684\u51fd\u6570\u7b7e\u540d\u3002\u6b64\u9879\u76ee\u5df2\u7ecf\u914d\u7f6e\u597d\u76f8\u5173\u89c4\u5219\uff0c\u5305\u53d1\u5e03\u540e\uff0c\u4f7f\u7528\u8005\u5c31\u53ef\u4ee5\u4f7f\u7528\u7f16\u5199\u597d\u7684\u7c7b\u578b\u4fe1\u606f\u505a\u9759\u6001\u7c7b\u578b\u68c0\u67e5\u3001\u4ee3\u7801\u8865\u5168\u3002\n\n\u5982\u679c\u5bf9\u5bfc\u51fa\u51fd\u6570\u5199 docstring\uff0c\u9664\u4e86\u6309\u7167 PEP8 \u7684\u8981\u6c42\u8fdb\u884c\u7f16\u5199\u4e4b\u5916\uff0c\u8fd8\u53ef\u4ee5\u5bf9\u4f20\u5165\u4f20\u51fa\u6570\u636e\u7c7b\u578b\u505a\u6807\u6ce8\u4e0e\u6ce8\u91ca\u3002\u6ce8\u91ca\u683c\u5f0f\u53c2\u8003 PyCharm \u7684[\u8fd9\u7bc7\u6587\u6863](https://www.jetbrains.com/help/pycharm/using-docstrings-to-specify-types.html)\u7684\u683c\u5f0f\u8fdb\u884c\u7f16\u5199\u3002PyCharm \u4ee5\u53ca Jedi\uff08vim / emacs / vscode \u90fd\u662f\u57fa\u4e8e jedi \u8fdb\u884c\u81ea\u52a8\u8865\u5168\uff09\u7b49\u7b49\u81ea\u52a8\u8865\u5168/\u9759\u6001\u68c0\u67e5\u5de5\u5177\u90fd\u53ef\u4ee5\u57fa\u4e8e\u6b64\u683c\u5f0f\u7684\u4fe1\u606f\u8fdb\u884c\u68c0\u67e5\uff0cSphinx \u751f\u6210\u7684 API doc \u4e5f\u53ef\u4ee5\u8fdb\u884c\u8bc6\u522b\u3002\n\n### editorconfig\n\n\u53ef\u4ee5\u5b89\u88c5 [editorconfig](https://editorconfig.org/) \u7f16\u8f91\u5668\u63d2\u4ef6\uff0c\u4fdd\u6301\u4ee3\u7801\u4e00\u81f4\u6027\u3002\u6b64\u9879\u76ee\u5df2\u7ecf\u9ed8\u8ba4\u914d\u7f6e\u3002\n\n\n",
"bugtrack_url": null,
"license": "",
"summary": "\u6d4b\u8bd5pip\u53d1\u5305",
"version": "0.0.3",
"project_urls": {
"Homepage": "https://code.byted.org/liuzhe.inf/test_pip"
},
"split_keywords": [
"boilerplate"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5fdf35c82b4832fc8e6f7db3bb3004b7726c7e12489d9fe1a0469d065a7cf101",
"md5": "e914df93c2591e2e88a69c5ace3a62b7",
"sha256": "b03720db42034670718cdac0939c487b5f7430837cc36fd2f56f4390a01b97e9"
},
"downloads": -1,
"filename": "zxy_Test-0.3-py2-none-any.whl",
"has_sig": false,
"md5_digest": "e914df93c2591e2e88a69c5ace3a62b7",
"packagetype": "bdist_wheel",
"python_version": "py2",
"requires_python": ">=2.7,!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*",
"size": 5236,
"upload_time": "2023-05-06T07:45:02",
"upload_time_iso_8601": "2023-05-06T07:45:02.568465Z",
"url": "https://files.pythonhosted.org/packages/5f/df/35c82b4832fc8e6f7db3bb3004b7726c7e12489d9fe1a0469d065a7cf101/zxy_Test-0.3-py2-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "84f4cedd40608c6444c15d5707564e058655f399f4b492d8d888c2df10e3f851",
"md5": "76982fbaea2411bc5897e64ec9e6241e",
"sha256": "53327b89602eb8eadfa3148b8093d0333eed2440bc791ea4232be7bf766d081a"
},
"downloads": -1,
"filename": "zxy_Test-0.3.tar.gz",
"has_sig": false,
"md5_digest": "76982fbaea2411bc5897e64ec9e6241e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=2.7,!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*",
"size": 4813,
"upload_time": "2023-05-06T07:45:04",
"upload_time_iso_8601": "2023-05-06T07:45:04.601884Z",
"url": "https://files.pythonhosted.org/packages/84/f4/cedd40608c6444c15d5707564e058655f399f4b492d8d888c2df10e3f851/zxy_Test-0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-06 07:45:04",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "zxy-test"
}
JSON