python里面Dataset干嘛的_Python 库从开发到维护

每个法师都有一颗近战的心，每个 CS 学生都有开发一个算法库的小目标～

前言

在学习和开发过程中，笔者发现项目开发和库开发有很大不同的，下面从 __init__.py 、单元测试、README、测试、文档和 Pypi/Conda 几方面分别介绍一个 Python 库应当具备的内容。最开始项目目录是这样的：

|- .
|- torchcluster 库名称
  |- __init__.py
  |- dataset 用来放数据集
    |- __init__.py
  |- zoo 用来放算法
    |- __init__.py
  |- helper 用来放辅助函数
    |- __init__.py

这套代码是在做实验的过程编写的，传统算法在 GPU 上的库比较少，因此自己用 PyTorch 写了谱聚类和 K-Means，正好可以拿来做成 Python 库共享给要用的童鞋们～

__init__.py

大家都知道 __init__.py 会将文件夹转化为 package 从而使文件夹下的所有 py 文件都可以被外界 import。现在我们要写一个库啦，要更严谨一点，所以这里要注意对用户可以 import 的内容进行限制：

# ./torchcluster/zoo/__init__.py

此外，我们在使用库的时候常常会用 .__version__ 查看版本，也要记得填上～

# ./torchcluster/__init__.py

单元测试

单元测试是用来对模块、函数或者类来进行检查的测试。一个没有单元测试的库是没人敢用的～ 自动化的单元测试可以帮助我们在修改部分代码之后，高效的检测整个库是否有出错的地方。这里我们选择 pytest 完成单元测试～

第一步是建立一个 tests 文件夹：

|- .
|- tests 单元测试
  |- test_method_name.py 这里要以 test_ 开头～
|- torchcluster 库名称
  |- ...

这里要注意 pytest 的三个要求：

• 测试文件名必须以 test_ 开头
• 测试类以 Test 开头，并且不能带有 init 方法
• 测试方法必须以 test_ 开头

pytest 会自动运行负荷要求的模块、函数或者类，捕捉到抛出的异常：

# ./tests/test_k_means.py 文件名称

在写单元测试的时候，我们会引用到 ../torchcluster 内的模块，而 pytest 的运行目录是 tests，直接运行 pytest 会造成向上级文件夹引用的错误，因此我们需要将库中的 python 模块用作脚本运行：

# 添加了 -m
python -m pytest tests/test_k_means.py

README

在写 README 之前先说一下 LICENSE，自己写的库要声明自己的版权，不然别人拿走改个名字说是他写的怎么办～ 我一般都是选用比较宽松的 MIT 许可证的，毕竟有人抄算是看得起我～ 在根目录下建立一个名为 LICENSE 的文件就好了：

# ./LICENSE
The MIT License (MIT)
​
Copyright (c) 2019-present, Zhang Zhi
​
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
​
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
​
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.

README.md 文件主要是在 github 首页上显示的，所以尽可能简洁一点突出自己的库的特点咯，我一般是分为四个部分：

• System requirement
• Installaction
• How torchcluster looks like / How to use
• License

# torchcluster

[Documentation](...) |

...

## System requirements

torchcluster should work on

- all Linux distributions no earlier than Ubuntu 16.04
- macOS X
- Windows 10

torchcluster also requires Python 3.5 or later. Python 2 support is coming.

Right now, torchcluster works on [PyTorch](https://pytorch.org/) 0.4.1.

## Installation

...

## How torchcluster looks like

...

## License

[MIT](http://opensource.org/licenses/MIT)

Copyright (c) 2019-present, Zhang Zhi

因为 pypi 对 md 文件的支持比较差，所以我们需要手动将 md 文档转换成 rst 文档，弄一个 README.rst 留给 pypi 首页展示～ 推荐使用 convert。现在项目文件夹就会变成这个样子啦：

|- tests
  |- ...
|- torchcluster
  |- ...
|- .gitignore
|- LICENSE
|- README.md
|- README.rst

文档

手写文档比较麻烦，所以很少有手写文档的大佬，像 PyTorch 这种热门库也都是根据注释自动生成，然后再手动添加和修改的。这里我们选择 docstring + sphinx。docstring 用来生成标准的注释格式，sphinx 用来根据注释提取模块、方法和类的信息，生成文档 html。

我是用 vscode 里面的 docstring 生成注释格式的，其实复制粘贴再改一改也不麻烦：

# ./torchcluster/zoo/k_means.py

然后再项目目录下运行：

pip install sphinx
sphinx-quickstart docs
# 执行期间 sphinx 会询问你各项设置，如果不懂默认也可以
# 记得下面的这一条一定要 yes，不然没法自动生成文档
# autodoc: automatically insert docstrings from modules (y/n) [n] y

sphinx 会在根目录下创建 docs 目录，用于存放构建文件、配置文件、模板和内容等等：

|- docs
  |- _build
  |- static
  |- _templates
  conf.py
  make.bat
  makefile

这里需要对 conf 添加一些附加配置：

# ./docs/conf.py

其中 html_theme 是用来修改页面样式的，这个样式算是文档比较通用的了。

autoclass_content 是为了在自动生成文档之后显示 __init__.py 的内容的（默认省略）。

Mock 可以帮助我们在构建文档时不引入代码内的依赖库，而是模拟一个依赖库。你在本地或许有安装依赖，但是使用远程自动构建的时候就不一定有了，会造成各种 timeout～

现在可以运行：

make html

然后打开 ./docs/_build/index.html 页面查看效果啦～

文档页面

每次 build 完手动把 html 文件传到自己服务器或者 github page 太麻烦了，因此我选择使用 readthedoc。将项目传到 github 上，然后再 readthedoc 点击 import a Project 就可以了：

导入项目

尽管我们已经 mock 了代码中引用的库，为了保险起见建议在管理-高级设置中进行如下配置：

管理-高级设置

然后点击构建版本进行构建，复制阅读文档的链接到 README.md 和 README.rst 就好了：

构建

Pypi 和 Conda

接下来我们要把库上传到 pypi 和 conda 上，这样别人就能像使用 PyTorch 一样安装我们的库啦～

pip install torchcluster
conda install -c tczhangzhi torchcluster

针对 conda 我们需要定义 meta.yaml：

{% set version = "0.1.3" %}
​
package:
  name: torchcluster
  version: {{ version }}
​
build:
  noarch: generic
​
requirements:
  run:
    - python
    - pytorch
    - numpy
​
about:
  home: https://github.com/tczhangzhi/cluster
  license: MIT
  summary: 'Torchcluster is a python package for cluster analysis.'
  description: |
    Torchcluster is a python package for cluster analysis. The speed of the clustering algorithm has been effectively improved with the Pytorch backend. We are also working on test datasets and visualization tools. Related work is coming in the next release.

这里需要注意的是，由于我们的项目依赖支持所有平台，而没有引入其他基于系统的代码，所以我们可以直接使用 noarch: generic 让 mac、win 和 linux 都可以下载使用。之后运行：

conda build .

就可以自动构建啦，构建完成后 conda 会提示你上传的命令，复制下来跑一下就行了。

针对 Pypi 我们需要定义 setup.py 和 http://MANIFEST.in，其中 http://MANIFEST.in 是定义保留文件的：

# MANIFEST.in
include LICENSE
include README.md

setup.py 是定义各种构建配置的，这里 packages 一定要记得 find_packages 哦：

from 

都定义好之后运行下面的命令就可以自动打包上传了：

python setup.py register sdist upload

维护

Github 上的各路大佬可能会给你提 Issues，要及时回复和修复～ 修复完之后记得修改 __init__.py、setup.py 和 meta.yaml 中的版本号，重新打包上传。

回复 issues

结尾

如果有什么不懂的可以直接翻看项目中的相关源代码，项目地址是：tczhangzhi/cluster。

作为研究人员，开发出像 DGL 一样优秀的算法库应该也算是一种科研成就叭。革命尚未成功，同志仍需努力，高效、功能强大的算法库少不了 C++ 和 CUDA 的支持，后面会补上相关内容。