python项目了解_神级程序员都是这样来开源 Python 项目！今天算是涨知识了！

工具和概念

项目布局

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

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

setuptools 和 setup.py文件

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

其他的setup.py参数

有一些sandman 用不到的启动参数，在你的包里可能会用到。举个例子，你可能正在分派一些脚本并希望你的用户能够从命令行执行。在这个例子中，脚本会和你其他的代码一起安装在正常的site-packages位置。用户安装完后，没有其他的简单方法运行它。基于这一点，setup可以带有一个的脚本参数来指明Python脚本应该如何安装。在包中安装一个调用go_foo.py的脚本，这个用来启动的调用包括下面这行：scripts = ['go_foo.py'],

确保在脚本中填入相对路径，并不仅仅是一个名称 (如scripts = [‘scripts/foo_scripts/go_foo.py’]).同样，你的脚本应该以”shebang”行和”python”开始，如下：

它(README)读起来很傻的感觉，但是确是一个很重要的文件。它可能是你未来的用户或者贡献者首先从它了解你的项目的。花些时间来写一个清楚明白的说明和使用GFM(GitHubFlavoredMarkdown)来使它更好看。实际上，如果使用原生的Markdown来写文档不爽，那么可以在Github上使用立即预览来创建或者修改这个文件

我们还没触及列表中的第二和第三项(ReadTheDocs和TravisCI)，你会在接下来看到。

安装

按照你系统平台的git-flow安装指导操作，在这里。

安装完后，你可以使用下附命令迁移你的已有项目$ git flow init

Branch细节

脚本将询问你一些配置问题，git-flow的默认建议值可以很好的工作。你可能会注意到你的默认分支被设置成develop。现在，让我们后头描述一下git-flow…嗯，flow，更详细一点。这样做的最简单的方法是讨论一下不同的分支及模型中的分支类型。

git flow feature finish

这会把代码合并进develop分支，并且删除 feature/分支

Release

一个release分支是当你准备好进行产品发布的时候从develop分支创建出来的。使用以下的命令来创建：$ git flow release start

注意，这是发布版本号第一次创建。所有完成的，准备好发布的分支必须已经合并到develop分支上。在release分支创建后，发布你的代码。任何小的bug修改需要提交到 release/分支上。当所有的bug被修复之后，运行以下的命令：

$ git flow release finish

这个命令会把你的release/分支合并到master和develop分支，这意味着你永远不需要担心这几个分支会缺少一些必要的产品变更(可能是因为一个快速的bug修复导致的)。

Hotfix

然而hotfix分支可能会很有用，在现实世界中很少使用，至少我是这样认为的。hotfix就像master分支下创建的feature分支： 如果你已经关闭了release分支，但是之后又认识到还有一些很重要的东西需要一起发布，那么就在master分支(由$git flow release finish 创建的标签)下创建一个hotfix分支，就像这样：

$ git flow hotfix start

当你完成改变和增加你的版本号使之独一无二(bump your version number)，然后完成hotfix分支：$ git flow hotfix finish

这好像一个release分支(因为它本质上就是一种release分支)，会在master和develop分支上提交修改。

我猜想它们很少使用的原因是因为已经存在一种可以给已发布的代码做出修改的机制：提交到一个未完成的release分支。当然，可能一开始，团队使用git flow release finish .. 太早了，然后第二天又发现需要快速修改。随着时间的推移，他们就会为一个release 分支多留一些时间，所以，不会再需要hotfix分支。另一种需要hotfix分支情况就是如果你立即需要在产品中加入新的特性，等不及在develop分支中加入改变。不过(期望)这些都是小概率事件。

virtualenv和virtualenvwrapper

一旦你安装了virtualenvwrapper，你需要添加一行内容到你的.zhsrc文件(对bash用户来说是.bashrc文件)：$ echo 'source /usr/local/bin/virtualenvwrapper.sh' >> ~/.zshrc

这样在你的shell中增加了一些有用的命令(记得第一次使用时source一下你的.zshrc文件以使它生效)。虽然你可以使用mkvirtualenv命令直接创建一个virtualenv，但使用mkproject [OPTIONS] DEST_DIR创建一个“项目”将更有用。因为我们已经有一个现有的项目了，所有我们只需为我们的项目创建一个新的virtualenv，下附命令可以达到这效果：

将requirements.txt提交到你的git代码库中。此外，你现在可以添加这里的列出的包列表作为install_requirement参数的值到setup.py文件中的distutils.setup。这样做我们可以确保当上传包到PyPI后，它可以被pip安装并自动解决依赖关系。

使用py.test测试

在Python的自动测试系统里有两个主要的Python标准单元测试包(很有用)的替代品：nose和py.test。两个方案都将单元测试拓展的易于使用且增加额外的功能。说真的，哪个都是很好的选择。我更喜欢py.test因为下述几个原因：支持setuptools/distutils项目Python的setup.py测试技能始终其作用支持常见的断言(assert)语法 (而不是需要记住所有jUnit风格的断言函数)

更少的样板

支持多种测试风格单元测试

文档测试

nose测试

使用py.test，我们可以使用Ned Batchelder的覆盖测试工具。使用pip安装pytest-cov。如果你之前这样运行你的测试：$ py.test

你可以通过传递一些新的标识生成覆盖率报告，下面是运行sandman的一个例子：

当然不是所有项目都有100%的测试覆盖率(事实上，正如你读到的，sandman没有100%覆盖)，但获得100%的覆盖率是一个有用的练习。它能够揭示我之前没有留意的缺陷与重构机会。

因为，作为测试本身，自动生成的测试覆盖报可以作为你持续集成的一部分。如果你选择这样做，部署一个标记来显示当前的测试覆盖率会为你的项目增加透明度(大多数时候会极大的鼓励他人贡献)。

使用Tox进行标准化测试

一个所有Python项目维护者都需要面对的问题是兼容性。如果你的目标是同时支持Python 2.x和Python 3.x(如果你目前只支持Python 2.x，应该这样做)，实际中你如何确保你的项目支持你所说的所有版本呢？毕竟，当你运行测试时，你只使用特定的版本环境来运行测试，它很可能在Python2.7.5中运行良好但在Python 2.6和3.3出现问题。

幸运的是有一个工具致力于解决这个问题。tox提供了“Python的标准化测试”，它不仅仅是在多个版本环境中运行你的测试。它创造了一个完整的沙箱环境，在这个环境中你的包和需求被安装和测试。如果你做了更改在测试时没有异常，但意外地影响了安装，使用Tox你会发现这类问题。

通过一个.ini文件配置tox：tox.ini。它是一个很容易配置的文件，下面是从tox文档中摘出来的一个最小化配置的tox.ini：

这个配置文件依旧比较简单。而结果呢？

我从输出列表里截取了一部分)。如果想看我的测试对一个环境的覆盖率，只需运行：

结果很可怕啊。

setuptools整合

tox可以和setuptools整合，这样python的setup.py测试可以运行你的tox测试。将下面的代码段放到你的setup.py文件里，这段代码是直接从tox的文档里拿来的：

文档需要花费一点功夫，但是为了你的使用者，这个付出是值得的。好吧，好的文档使一个可用的项目去其糟粕。

Sphinx的autodoc扩展让我们可以使用很多指令，而这些指令可以自动的从你文档中生成文档。

安装

确认将Sphinx安装在你的virtualenv内，因为文档在项目里也是按版本来的。Sphinx不同的版本可能会产生不同的HTML输出。通过将其安装在你的virtualenv内，你可以以受控的方式升级你的文档。

我们要保持我们的文档在docs文件夹，将文档生成到docs/generated文件夹。在项目的根目录运行以下命令将根据你的文档字符自动重构文本文档：$ sphinx-apidoc -F -o docs

这将产生一个包含多个文档文件的docs文件夹。此外，它创建了一个叫conf.py的文件，它将负责你的文档配置。你还会发现一个Makefile，方便使用一个命令(生成html)构建HTML文档。

在你最终生成文档之前，确保你已经在本地安装了相应的包(尽管可以使用pip，但python setup.py develop是最简单的保持更新的方法)，否则sphinx-apidoc无法找到你的包。

配置:conf.py

conf.py文件创建用来控制产生的文档的各个方面。它自己会很好生成文档，所以我只简单地触及两点。

版本和发布

首先，确保你的版本和发布版本号保持最新。这些数字会作为生成的文档的一部分显示，所以你不希望它们远离了实际值。

保持你的版本最新的最简单方式就是在你的文档和setup.py文件中都从你的包的__version__属性读取。我从Flask的conf.py借用过来配置sandman的conf.py：

PyPI

PyPI，Python包索引(以前被称为“Cheeseshop”)是一个公开可用的Python包中央数据库。PyPI是你的项目发布的地方。一旦你的包(及其相关的元数据)上传到PyPI，别人通过pip或easy_instal可以下载并安装它。这一点得强调一下：即使你的项目托管在GitHub，直到被上传到PyPI后你的项目才是有用的。当然，有些人可以复制你的git库任何直接手工安装它，但更多的人想使用pip来安装它。

最后的一步

如果你已经完成了所有的前面部分中的步骤，你可能急着想把你的包上传到PyPI，供其他人使用！

先别急着做上述事情，在分发你的包之前，有一个叫做cheesecake的有用的工具有助于运行最后一步。它分析你的包并指定一个分类的数字分数。它衡量你的包在打包、安装、代码质量以及文档的数量和质量方面是否容易/正确。

除了作粗略衡量的“准备”，cheesecake在完整性检查方面很优秀。你会很快看到你的setup.py文件是否有错或者有没有忘记为一个文件制作文档。我建议在上传每个项目到PyPI之前运行一下它，而不仅只是第一个。

初始化上传

现在，你已经确定了你的代码不是垃圾和当人们安装它时不会崩溃，让我们把你的包放到PyPI上吧！你将会通过setuptools和setup.py脚本交互。如果这是第一次上传到PyPI，你将首先注册它：$ python setup.py register

注意：如果你还没有一个免费的PyPI账户，你将需要现在去注册一个，才能注册这个包[@Lesus 注：注册之后还需要到邮箱去验证才行]。在你已使用了上面注册之后，你就可以创建发布包和上传到PyPI了:$ python setup.py sdist upload

上面这个命令建立一个源码发布版(sdist)，然后上传到PyPI.如果你的包不是纯粹的Python(也就是说，你有二进制需要编译进去)，你就需要发布一个二进制版，请看setuptools文档，了解更多。

发布及版本号

PyPI使用发行版本模型来确定你软件包的哪个版本是默认可用的。初次上传后，为使你软件包的每次更新后在PyPI可用，你需要指定一个新版本号创建一个发布。版本号管理是一个相当复杂的课题，PEP有专门的内容：PEP 440——版本识别和依赖指定。我建议参照PEP 400指南(明显地)，但如果你选择使用不同版本的方案，在setup.py中使用的版本比目前PyPI中的版本“高”，这样PyPI才会认为这是一个新版本。

我们项目使用的语言是什么

它使用的是语言的哪个版本

使用什么命令安装它

使用什么命令运行项目的测试

这些都是很直接的东西。下面是sandman.travis.yml的内容：

你还会收到一封通知你编译成功的电子邮件。当然你也可以设置只有在出错或错误被修复时才有邮件通知，但编译输出结果相同时也不会发送。这是非常有用的，你在不必被无用的“编译通过！”邮件淹没的同时在发生改变仍会收到警示。

用ReadTheDocs做持续文档集成

尽管PyPI有一个官方文档站点(pythonhosted.org)，但是ReadTheDocs提供了一个更好的体验。为什么？ReadTheDocs有针对GitHub非常棒的集成。当你注册ReadTheDocs的时候，你就会看到你的所有GitHub 代码库。选择合适的代码库，做一些小幅的配置，那么你的文档就会在你每次提交到GitHub之后自动重新生成。

配置你的项目应该是一个很直观的事情。只有一些事需要记住，尽管，这里有一个配置字段的列表，对应的值可能不一定是你直接用得上的：Repo: https://github.com/github_username/project_name.git

Default Branch:develop

Default Version:latest

Python configuration file: (leave blank)

Usevirtualenv: (checked)

Requirements file:requirements.txt

Documentation Type: Sphinx HTML