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:

    以 开发模式 安装:

    pipenv install --dev

  • conda:

    从配置文件 environment.yml 新建一个专用于这个项目的、名为ks33requests-dev的环境，然后激活它，将本项目以 开发模式 安装到这个环境：

    conda env create -f environment.yml
conda activate ks33requests-dev
python setup.py develop

编码条例

  1. 代码风格遵照 PEP 8

  2. 版本命名遵照 PEP 440

  3. 使用 git 进行版本控制：

    1. 按照 git-flow 流程进行工作

    2. 使用 setuptools 的扩展 setuptools_scm 与 setuptools_scm_git_archive 配合上述工作流程进行打包

  4. 对外的 API 须提供 Sphinx-Docs 样式的 doc comments

  5. 对外 API 须提供 type hints

  6. 做静态检查，不提交带有错误或许多警告的代码

  7. 提供有足够覆盖面的测试用例

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 setup.py test

如果需要在运行测试时进行代码覆盖性检查，可运行:

python -m coverage run setup.py test

静态检查

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