python是谁维护的_Python 库从开发到维护
每個法師都有一顆近戰(zhàn)的心，每個 CS 學(xué)生都有開發(fā)一個算法庫的小目標(biāo)～
前言
在學(xué)習(xí)和開發(fā)過程中，筆者發(fā)現(xiàn)項目開發(fā)和庫開發(fā)有很大不同的，下面從 __init__.py 、單元測試、README、測試、文檔和 Pypi/Conda 幾方面分別介紹一個 Python 庫應(yīng)當(dāng)具備的內(nèi)容。最開始項目目錄是這樣的：
|- .
|- torchcluster 庫名稱
|- __init__.py
|- dataset 用來放數(shù)據(jù)集
|- __init__.py
|- zoo 用來放算法
|- __init__.py
|- helper 用來放輔助函數(shù)
|- __init__.py
這套代碼是在做實驗的過程編寫的，傳統(tǒng)算法在 GPU 上的庫比較少，因此自己用 PyTorch 寫了譜聚類和 K-Means，正好可以拿來做成 Python 庫共享給要用的童鞋們～
__init__.py
大家都知道 __init__.py 會將文件夾轉(zhuǎn)化為 package 從而使文件夾下的所有 py 文件都可以被外界 import。現(xiàn)在我們要寫一個庫啦，要更嚴(yán)謹(jǐn)一點，所以這里要注意對用戶可以 import 的內(nèi)容進(jìn)行限制：
# ./torchcluster/zoo/__init__.py
from .k_means import KMeans
from .spectrum import SpectrumClustering
?
__all__ = ('KMeans', 'SpectrumClustering')
此外，我們在使用庫的時候常常會用 .__version__ 查看版本，也要記得填上～
# ./torchcluster/__init__.py
?
from torchcluster import dataset
from torchcluster import zoo
?
__version__ = '0.1.3'
?
__all__ = ('dataset', 'zoo')
單元測試
單元測試是用來對模塊、函數(shù)或者類來進(jìn)行檢查的測試。一個沒有單元測試的庫是沒人敢用的～ 自動化的單元測試可以幫助我們在修改部分代碼之后，高效的檢測整個庫是否有出錯的地方。這里我們選擇 pytest 完成單元測試～
第一步是建立一個 tests 文件夾：
|- .
|- tests 單元測試
|- test_method_name.py 這里要以 test_ 開頭～
|- torchcluster 庫名稱
|- ...
這里要注意 pytest 的三個要求：測試文件名必須以 test_ 開頭
測試類以 Test 開頭，并且不能帶有 init 方法
測試方法必須以 test_ 開頭
pytest 會自動運行負(fù)荷要求的模塊、函數(shù)或者類，捕捉到拋出的異常：
# ./tests/test_k_means.py 文件名稱
def test_k_means(): # 測試方法名稱
...
assert(True) # 正常的使用異常檢測
在寫單元測試的時候，我們會引用到 ../torchcluster 內(nèi)的模塊，而 pytest 的運行目錄是 tests，直接運行 pytest 會造成向上級文件夾引用的錯誤，因此我們需要將庫中的 python 模塊用作腳本運行：
# 添加了 -m
python -m pytest tests/test_k_means.py
README
在寫 README 之前先說一下 LICENSE，自己寫的庫要聲明自己的版權(quán)，不然別人拿走改個名字說是他寫的怎么辦～ 我一般都是選用比較寬松的 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 文檔轉(zhuǎn)換成 rst 文檔，弄一個 README.rst 留給 pypi 首頁展示～ 推薦使用 convert。現(xiàn)在項目文件夾就會變成這個樣子啦：
|- tests
|- ...
|- torchcluster
|- ...
|- .gitignore
|- LICENSE
|- README.md
|- README.rst
文檔
手寫文檔比較麻煩，所以很少有手寫文檔的大佬，像 PyTorch 這種熱門庫也都是根據(jù)注釋自動生成，然后再手動添加和修改的。這里我們選擇 docstring + sphinx。docstring 用來生成標(biāo)準(zhǔn)的注釋格式，sphinx 用來根據(jù)注釋提取模塊、方法和類的信息，生成文檔 html。
我是用 vscode 里面的 docstring 生成注釋格式的，其實復(fù)制粘貼再改一改也不麻煩：
# ./torchcluster/zoo/k_means.py
class KMeans(Cluster):
"""K-Means algorithm"""
# 上面是對類的注釋，包含簡介
def __init__(self, n_clusters, tol=1e-4):
"""Spectrum clustering factory's config.?Args:n_clusters (int) - How many clusters in result.?Kwargs:tol (float) - stop to update when shift is smaller than tol?"""
# 上面是對方法的注釋，包含簡介、帶關(guān)鍵字的參數(shù)和不帶關(guān)鍵字的參數(shù)
super(KMeans, self).__init__()
self.n_clusters = n_clusters
self.tol = tol
?
def __call__(self, x):
"""Clustering.?Args:x (Tensor) - Data points of number n by feature dim m."""
然后再項目目錄下運行：
pip install sphinx
sphinx-quickstart docs
# 執(zhí)行期間 sphinx 會詢問你各項設(shè)置，如果不懂默認(rèn)也可以
# 記得下面的這一條一定要 yes，不然沒法自動生成文檔
# autodoc: automatically insert docstrings from modules (y/n) [n] y
sphinx 會在根目錄下創(chuàng)建 docs 目錄，用于存放構(gòu)建文件、配置文件、模板和內(nèi)容等等：
|- docs
|- _build
|- static
|- _templates
conf.py
make.bat
makefile
這里需要對 conf 添加一些附加配置：
# ./docs/conf.py
html_theme = 'sphinx_rtd_theme'
# -- Extension configuration -------------------------------------------------
autoclass_content = 'both'
?
import sys
from unittest.mock import MagicMock
?
class Mock(MagicMock):
@classmethod
def __getattr__(cls, name):
return MagicMock()
?
# 如果還有其他庫也要加在下面
MOCK_MODULES = [
'numpy',
'scipy',
'sklearn',
'matplotlib',
'matplotlib.pyplot',
'scipy.interpolate',
'scipy.special',
'math'
]
sys.modules.update((mod_name, Mock()) for mod_name in MOCK_MODULES)
其中 html_theme 是用來修改頁面樣式的，這個樣式算是文檔比較通用的了。
autoclass_content 是為了在自動生成文檔之后顯示 __init__.py 的內(nèi)容的(默認(rèn)省略)。
Mock 可以幫助我們在構(gòu)建文檔時不引入代碼內(nèi)的依賴庫，而是模擬一個依賴庫。你在本地或許有安裝依賴，但是使用遠(yuǎn)程自動構(gòu)建的時候就不一定有了，會造成各種 timeout～
現(xiàn)在可以運行：
make html
然后打開 ./docs/_build/index.html 頁面查看效果啦～文檔頁面
每次 build 完手動把 html 文件傳到自己服務(wù)器或者 github page 太麻煩了，因此我選擇使用 readthedoc。將項目傳到 github 上，然后再 readthedoc 點擊 import a Project 就可以了：導(dǎo)入項目
盡管我們已經(jīng) mock 了代碼中引用的庫，為了保險起見建議在管理-高級設(shè)置中進(jìn)行如下配置：管理-高級設(shè)置
然后點擊構(gòu)建版本進(jìn)行構(gòu)建，復(fù)制閱讀文檔的鏈接到 README.md 和 README.rst 就好了：構(gòu)建
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.
這里需要注意的是，由于我們的項目依賴支持所有平臺，而沒有引入其他基于系統(tǒng)的代碼，所以我們可以直接使用 noarch: generic 讓 mac、win 和 linux 都可以下載使用。之后運行：
conda build .
就可以自動構(gòu)建啦，構(gòu)建完成后 conda 會提示你上傳的命令，復(fù)制下來跑一下就行了。
針對 Pypi 我們需要定義 setup.py 和 http://MANIFEST.in，其中 http://MANIFEST.in 是定義保留文件的：
# MANIFEST.in
include LICENSE
include README.md
setup.py 是定義各種構(gòu)建配置的，這里 packages 一定要記得 find_packages 哦：
from setuptools import setup, find_packages
?
requirements = [
'numpy',
'torch',
]
?
readme = open('README.rst').read()
?
setup(
name='torchcluster',
version='0.1.3',
description='Torchcluster is a python package for cluster analysis.',
license='MIT',
author='Zhi Zhang',
author_email='850734033@qq.com',
keywords=['pytorch', 'cluster'],
url='https://github.com/tczhangzhi/cluster',
packages=find_packages(exclude=['tests']),
long_description=readme,
setup_requires=requirements
)
都定義好之后運行下面的命令就可以自動打包上傳了：
python setup.py register sdist upload
維護(hù)
Github 上的各路大佬可能會給你提 Issues，要及時回復(fù)和修復(fù)～ 修復(fù)完之后記得修改 __init__.py、setup.py 和 meta.yaml 中的版本號，重新打包上傳。回復(fù) issues
結(jié)尾
如果有什么不懂的可以直接翻看項目中的相關(guān)源代碼，項目地址是：tczhangzhi/cluster。
作為研究人員，開發(fā)出像 DGL 一樣優(yōu)秀的算法庫應(yīng)該也算是一種科研成就叭。革命尚未成功，同志仍需努力，高效、功能強(qiáng)大的算法庫少不了 C++ 和 CUDA 的支持，后面會補(bǔ)上相關(guān)內(nèi)容。
總結(jié)
以上是生活随笔為你收集整理的python是谁维护的_Python 库从开发到维护的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。
- 上一篇： python 装饰器分类_Python
- 下一篇： python函数递归年龄_Python学