以正确的方式开源 Python 项目

468 查看

大多数Python开发者至少都写过一个像工具、脚本、库或框架等对其他人也有用的工具。我写这篇文章的目的是让现有Python代码的开源过程尽可能清晰和无痛。我不是简单的指——“创建一个GitHub库，提交，在Reddit上发布，每天调用它”。在本文的结尾，你可以把现有的代码转换成一个能够鼓励他人使用和贡献的开源项目。

然而每一个项目都是不同的，但其中将现有代码开源的流程对所有的Python项目都是类似的。在另一个受欢迎的文章系列里我写了“以正确方式开始一个Django项目”，我将概述在开源Python项目我发现的有必要的步骤。

更新 (8月17号): 感谢@pydann提醒我Cookiecutter的存在，@audreyr的一个不起的项目。我在文章结尾添加了其中的一段。看一下Audrey的项目吧！

更新 2 (8月18号)：感谢@ChristianHeimes（和其他人）关于ontox这一段。Christian也让我想起了PEP 440和其他一些都已实现很棒的改进建议。

工具和概念

特别是，我发现一些工具和概念十分有用或者说是必要的。下面我就会谈及这方面主题，包括需要运行的精确的命令和需要设置的配置值。其终极目标就是让整个流程简单明了。

项目布局（目录结构）
setuptools 和 setup.py文件
git版本控制
GitHub 项目管理
1. GitHub的”Issues” 如下作用:
  1. bug跟踪
  2. 请求新特性
  3. 计划好的新特性
  4. 发布或者版本管理
git-flow git工作流
py.test 单元测试
tox 标准化测试
Sphinx 自动生成HTML文档
TravisCI 持续测试集成
ReadTheDocs 持续文档集成
Cookiecutter 为开始下一个项目自动生成这些步骤

项目布局

当准备一个项目时，正确合理的布局（目录结构）是十分重要的。一个合理的布局意味着想参与开发者不必花时间来寻找某些代码的位置; 凭直觉就可以找到文件的位置。因为我们在处理一个项目，就意味着可能需要到处移动一些东西。

让我们从顶层开始。大多数项目都有很多顶层文件（如setup.py, README.md, requirements等等）。每个项目至少应该有下面三个目录：

doc目录，包括项目文档
项目目录，以项目命名，存储实际的Python包
test目录，包含下面两部分
1. 在这个目录下包括了测试代码和资源
2. 作为一个独立顶级包

为了更好理解文件该如何组织，这里是一个我的简单项目：sandman 布局快照。

$ pwd

~/code/sandman

$ tree

|- LICENSE

|- README.md

|- TODO.md

|- docs

| |-- conf.py

| |-- generated

| |-- index.rst

| |-- installation.rst

| |-- modules.rst

| |-- quickstart.rst

| |-- sandman.rst

|- requirements.txt

|- sandman

| |-- __init__.py

| |-- exception.py

| |-- model.py

| |-- sandman.py

| |-- test

| |-- models.py

| |-- test_sandman.py

|- setup.py

如你所看到那样，这里有一些顶层文件，一个docs目录（建立一个空目录，因为sphinx会将生成的文档放到这里），一个sandman目录，以及一个在sandman目录下的test目录。

setuptools 和 setup.py文件

setup.py文件，你可能已经在其它包中看到过，被distuils包用来安装Python包的。对于任何一个项目，它都是一个很重要的文件，因为它包含了版本，包依赖信息，PyPi需要的项目描述，你的名字和联系信息，以及其它一些信息。它允许以编程的方式搜索安装包，提供元数据和指令说明让工具如何做。

setuptools包（实际上就是对distutils的增强）简单化了建立发布python包。使用setuptools给python包打包，和distutils打包没什么区别。这实在是没有任何理由不使用它。

setup.py应该放在你的项目的根目录。setup.py中最重要的一部分就是调用setuptools.setup，这里面包含了此包所需的所有元信息。这里就是sandman的setup.py的所有内容

from __future__ import print_function

from setuptools import setup, find_packages

from setuptools.command.test import test as TestCommand

import io

import codecs

import os

import sys

import sandman

here = os.path.abspath(os.path.dirname(__file__))

def read(*filenames, **kwargs):

encoding = kwargs.get('encoding', 'utf-8')

sep = kwargs.get('sep', 'n')

buf = []

for filename in filenames:

with io.open(filename, encoding=encoding) as f:

buf.append(f.read())

return sep.join(buf)

long_description = read('README.txt', 'CHANGES.txt')

thon代码的开源过程尽可能清晰和无痛。我不是简单的指——“创建一个GitHub库，提交，在Reddit上发布，每天调用它”。在本文的结尾，你可以把现有的代码转换成一个能够鼓励他人使用和贡献的开源项目。