CONTRIBUTING¶
ℹ 注意:
这个项目需要 Python
3.5
及以上版本。
复刻项目¶
复刻项目源码到工作目录,然后切换到项目的目录:
cd path/to/your/workspace/directory/
git clone https://github.com/tanbro/ks33requests.git
cd ks33requests
开发环境¶
强烈建议在 virtual environment 中进行开发工作。建议的方法有:
标准库:
使用 venv 与 pip 在目录
env
(此处仅为举例,可根据实际需要使用其它目录) 创建虚拟环境,将本项目以 开发模式 安装到这个环境,并安装开发工作所要使用的包:Linux:
path/of/your/python -m venv env env/bin/python setup.py develop env/bin/python -m pip install -r requires/dev.txt
Windows:
path\of\python.exe -m venv env env\Scripts\python.exe setup.py develop env\Scripts\python.exe -m pip install -r requires\dev.txt
-
以 开发模式 安装:
pipenv install --dev
-
从配置文件
environment.yml
新建一个专用于这个项目的、名为ks33requests-dev
的环境,然后激活它,将本项目以 开发模式 安装到这个环境:conda env create -f environment.yml conda activate ks33requests-dev python setup.py develop
编码条例¶
代码风格遵照 PEP 8
版本命名遵照 PEP 440
使用 git 进行版本控制:
按照 git-flow 流程进行工作
使用 setuptools 的扩展 setuptools_scm 与 setuptools_scm_git_archive 配合上述工作流程进行打包
对外的 API 须提供 Sphinx-Docs 样式的 doc comments
对外 API 须提供 type hints
做静态检查,不提交带有错误或许多警告的代码
提供有足够覆盖面的测试用例
XML Schema¶
金山云 KS3 的 WebAPI 数据结构有许多与 S3 兼容。 所以,这个项目直接使用来自 http://s3.amazonaws.com/doc/2006-03-01/AmazonS3.xsd 的 Schema 转换部分数据的结构。
我们使用 generateDS 工具,从xsd
文件生成 Python 类型定义:
mkdir -p schemas
wget http://s3.amazonaws.com/doc/2006-03-01/AmazonS3.xsd -P schemas
generateDS.py -f -o s3_api.py -s s3_sub.py --super=s3_api schemas/AmazonS3.xsd
生成的源代码文件复制到名称空间 ks33requests.schemas
中,小幅修改 s3_sub.py
的源码即可使用。
静态检查¶
python -m flake8
文档生成¶
执行下面的命令构建文档,输出到目录 build/sphinx
:
python setup.py build_sphinx
ℹ 说明:
如果模块有增减,需要删除原来的 Sphinx-Docs 自动API文档并重新生成:
rm -rf docs/ks3requests.rst docs/api mkdir -p docs/api sphinx-apidoc -e -f -o docs/api src/ks33requests src/ks33requests/schemas/s3_*.py