工具和概念

項目布局

當準備一個項目時，正確合理的布局（目錄結構）是十分重要的。一個合理的布局意味著想?yún)⑴c開發(fā)者不必花時間來尋找某些代碼的位置; 憑直覺就可以找到文件的位置。因為我們在處理一個項目，就意味著可能需要到處移動一些東西。

如你所看到那樣，這里有一些頂層文件，一個docs目錄（建立一個空目錄，因為sphinx會將生成的文檔放到這里），一個sandman目錄，以及一個在sandman目錄下的test目錄。

setuptools 和 setup.py文件

setup.py文件，你可能已經(jīng)在其它包中看到過，被distuils包用來安裝Python包的。對于任何一個項目，它都是一個很重要的文件，因為它包含了版本，包依賴信息，PyPi需要的項目描述，你的名字和聯(lián)系信息，以及其它一些信息。它允許以編程的方式搜索安裝包，提供元數(shù)據(jù)和指令說明讓工具如何做。

其他的setup.py參數(shù)

有一些sandman 用不到的啟動參數(shù)，在你的包里可能會用到。舉個例子，你可能正在分派一些腳本并希望你的用戶能夠從命令行執(zhí)行。在這個例子中，腳本會和你其他的代碼一起安裝在正常的site-packages位置。用戶安裝完后，沒有其他的簡單方法運行它。基于這一點，setup可以帶有一個的腳本參數(shù)來指明Python腳本應該如何安裝。在包中安裝一個調(diào)用go_foo.py的腳本，這個用來啟動的調(diào)用包括下面這行：

scripts = ['go_foo.py'],

確保在腳本中填入相對路徑，并不僅僅是一個名稱 (如scripts = [‘scripts/foo_scripts/go_foo.py’]).同樣，你的腳本應該以”shebang”行和”python”開始，如下：

它(README)讀起來很傻的感覺，但是確是一個很重要的文件。它可能是你未來的用戶或者貢獻者首先從它了解你的項目的?；ㄐr間來寫一個清楚明白的說明和使用GFM（GitHubFlavoredMarkdown）來使它更好看。實際上，如果使用原生的Markdown來寫文檔不爽，那么可以在Github上使用立即預覽來創(chuàng)建或者修改這個文件

我們還沒觸及列表中的第二和第三項（ReadTheDocs和TravisCI），你會在接下來看到。

安裝

按照你系統(tǒng)平臺的git-flow安裝指導操作，在這里。

安裝完后，你可以使用下附命令遷移你的已有項目

$ git flow init

Branch細節(jié)

腳本將詢問你一些配置問題，git-flow的默認建議值可以很好的工作。你可能會注意到你的默認分支被設置成develop?，F(xiàn)在，讓我們后頭描述一下git-flow…嗯，flow，更詳細一點。這樣做的最簡單的方法是討論一下不同的分支及模型中的分支類型。

git flow feature finish

這會把代碼合并進develop分支，并且刪除 feature/分支

Release

一個release分支是當你準備好進行產(chǎn)品發(fā)布的時候從develop分支創(chuàng)建出來的。使用以下的命令來創(chuàng)建：

$ git flow release start

注意，這是發(fā)布版本號第一次創(chuàng)建。所有完成的，準備好發(fā)布的分支必須已經(jīng)合并到develop分支上。在release分支創(chuàng)建后，發(fā)布你的代碼。任何小的bug修改需要提交到 release/ 分支上。當所有的bug被修復之后，運行以下的命令：

$ git flow release finish

這個命令會把你的release/ 分支合并到master和develop分支，這意味著你永遠不需要擔心這幾個分支會缺少一些必要的產(chǎn)品變更（可能是因為一個快速的bug修復導致的）。

Hotfix

然而hotfix分支可能會很有用，在現(xiàn)實世界中很少使用，至少我是這樣認為的。hotfix就像master分支下創(chuàng)建的feature分支： 如果你已經(jīng)關閉了release分支，但是之后又認識到還有一些很重要的東西需要一起發(fā)布，那么就在master分支（由$git flow release finish 創(chuàng)建的標簽）下創(chuàng)建一個hotfix分支，就像這樣：

$ git flow hotfix start

當你完成改變和增加你的版本號使之獨一無二(bump your version number)，然后完成hotfix分支：

$ git flow hotfix finish

這好像一個release分支（因為它本質(zhì)上就是一種release分支），會在master和develop分支上提交修改。

我猜想它們很少使用的原因是因為已經(jīng)存在一種可以給已發(fā)布的代碼做出修改的機制：提交到一個未完成的release分支。當然，可能一開始，團隊使用git flow release finish .. 太早了，然后第二天又發(fā)現(xiàn)需要快速修改。隨著時間的推移，他們就會為一個release 分支多留一些時間，所以，不會再需要hotfix分支。另一種需要hotfix分支情況就是如果你立即需要在產(chǎn)品中加入新的特性，等不及在develop分支中加入改變。不過（期望）這些都是小概率事件。

virtualenv和virtualenvwrapper

一旦你安裝了virtualenvwrapper，你需要添加一行內(nèi)容到你的.zhsrc文件(對bash用戶來說是.bashrc文件)：

$ echo 'source /usr/local/bin/virtualenvwrapper.sh' >> ~/.zshrc

這樣在你的shell中增加了一些有用的命令（記得第一次使用時source一下你的.zshrc文件以使它生效）。雖然你可以使用mkvirtualenv命令直接創(chuàng)建一個virtualenv，但使用mkproject [OPTIONS] DEST_DIR創(chuàng)建一個“項目”將更有用。因為我們已經(jīng)有一個現(xiàn)有的項目了，所有我們只需為我們的項目創(chuàng)建一個新的virtualenv，下附命令可以達到這效果：

將requirements.txt提交到你的git代碼庫中。此外，你現(xiàn)在可以添加這里的列出的包列表作為install_requirement參數(shù)的值到setup.py文件中的distutils.setup。這樣做我們可以確保當上傳包到PyPI后，它可以被pip安裝并自動解決依賴關系。

使用py.test測試

在Python的自動測試系統(tǒng)里有兩個主要的Python標準單元測試包（很有用）的替代品：nose和py.test。兩個方案都將單元測試拓展的易于使用且增加額外的功能。說真的，哪個都是很好的選擇。我更喜歡py.test因為下述幾個原因：

• 支持setuptools/distutils項目

• Python的setup.py測試技能始終其作用

• 支持常見的斷言（assert）語法 (而不是需要記住所有jUnit風格的斷言函數(shù))

• 更少的樣板

• 支持多種測試風格

• 單元測試

• 文檔測試

• nose測試

使用py.test，我們可以使用Ned Batchelder的覆蓋測試工具。使用pip安裝pytest-cov。如果你之前這樣運行你的測試：

$ py.test

你可以通過傳遞一些新的標識生成覆蓋率報告，下面是運行sandman的一個例子：

當然不是所有項目都有100%的測試覆蓋率（事實上，正如你讀到的，sandman沒有100%覆蓋），但獲得100%的覆蓋率是一個有用的練習。它能夠揭示我之前沒有留意的缺陷與重構機會。

因為，作為測試本身，自動生成的測試覆蓋報可以作為你持續(xù)集成的一部分。如果你選擇這樣做，部署一個標記來顯示當前的測試覆蓋率會為你的項目增加透明度（大多數(shù)時候會極大的鼓勵他人貢獻）。

使用Tox進行標準化測試

一個所有Python項目維護者都需要面對的問題是兼容性。如果你的目標是同時支持Python 2.x和Python 3.x（如果你目前只支持Python 2.x，應該這樣做），實際中你如何確保你的項目支持你所說的所有版本呢？畢竟，當你運行測試時，你只使用特定的版本環(huán)境來運行測試，它很可能在Python2.7.5中運行良好但在Python 2.6和3.3出現(xiàn)問題。

幸運的是有一個工具致力于解決這個問題。tox提供了“Python的標準化測試”，它不僅僅是在多個版本環(huán)境中運行你的測試。它創(chuàng)造了一個完整的沙箱環(huán)境，在這個環(huán)境中你的包和需求被安裝和測試。如果你做了更改在測試時沒有異常，但意外地影響了安裝，使用Tox你會發(fā)現(xiàn)這類問題。

通過一個.ini文件配置tox：tox.ini。它是一個很容易配置的文件，下面是從tox文檔中摘出來的一個最小化配置的tox.ini：

這個配置文件依舊比較簡單。而結果呢？

我從輸出列表里截取了一部分）。如果想看我的測試對一個環(huán)境的覆蓋率，只需運行：

結果很可怕啊。

setuptools整合

tox可以和setuptools整合，這樣python的setup.py測試可以運行你的tox測試。將下面的代碼段放到你的setup.py文件里，這段代碼是直接從tox的文檔里拿來的：

文檔需要花費一點功夫，但是為了你的使用者，這個付出是值得的。好吧，好的文檔使一個可用的項目去其糟粕。

Sphinx的autodoc擴展讓我們可以使用很多指令，而這些指令可以自動的從你文檔中生成文檔。

安裝

確認將Sphinx安裝在你的virtualenv內(nèi)，因為文檔在項目里也是按版本來的。Sphinx不同的版本可能會產(chǎn)生不同的HTML輸出。通過將其安裝在你的virtualenv內(nèi)，你可以以受控的方式升級你的文檔。

我們要保持我們的文檔在docs文件夾，將文檔生成到docs/generated文件夾。在項目的根目錄運行以下命令將根據(jù)你的文檔字符自動重構文本文檔：

$ sphinx-apidoc -F -o docs

這將產(chǎn)生一個包含多個文檔文件的docs文件夾。此外，它創(chuàng)建了一個叫conf.py的文件，它將負責你的文檔配置。你還會發(fā)現(xiàn)一個Makefile，方便使用一個命令（生成html）構建HTML文檔。

在你最終生成文檔之前，確保你已經(jīng)在本地安裝了相應的包（盡管可以使用pip，但python setup.py develop是最簡單的保持更新的方法），否則sphinx-apidoc無法找到你的包。

配置:conf.py

conf.py文件創(chuàng)建用來控制產(chǎn)生的文檔的各個方面。它自己會很好生成文檔，所以我只簡單地觸及兩點。

版本和發(fā)布

首先，確保你的版本和發(fā)布版本號保持最新。這些數(shù)字會作為生成的文檔的一部分顯示，所以你不希望它們遠離了實際值。

保持你的版本最新的最簡單方式就是在你的文檔和setup.py文件中都從你的包的__version__屬性讀取。我從Flask的conf.py借用過來配置sandman的conf.py：

PyPI

PyPI，Python包索引（以前被稱為“Cheeseshop”）是一個公開可用的Python包中央數(shù)據(jù)庫。PyPI是你的項目發(fā)布的地方。一旦你的包（及其相關的元數(shù)據(jù)）上傳到PyPI，別人通過pip或easy_instal可以下載并安裝它。這一點得強調(diào)一下：即使你的項目托管在GitHub，直到被上傳到PyPI后你的項目才是有用的。當然，有些人可以復制你的git庫任何直接手工安裝它，但更多的人想使用pip來安裝它。

最后的一步

如果你已經(jīng)完成了所有的前面部分中的步驟，你可能急著想把你的包上傳到PyPI，供其他人使用！

先別急著做上述事情，在分發(fā)你的包之前，有一個叫做cheesecake的有用的工具有助于運行最后一步。它分析你的包并指定一個分類的數(shù)字分數(shù)。它衡量你的包在打包、安裝、代碼質(zhì)量以及文檔的數(shù)量和質(zhì)量方面是否容易/正確。

除了作粗略衡量的“準備”，cheesecake在完整性檢查方面很優(yōu)秀。你會很快看到你的setup.py文件是否有錯或者有沒有忘記為一個文件制作文檔。我建議在上傳每個項目到PyPI之前運行一下它，而不僅只是第一個。

初始化上傳

現(xiàn)在，你已經(jīng)確定了你的代碼不是垃圾和當人們安裝它時不會崩潰，讓我們把你的包放到PyPI上吧！你將會通過setuptools和setup.py腳本交互。如果這是第一次上傳到PyPI，你將首先注冊它：

$ python setup.py register

注意：如果你還沒有一個免費的PyPI賬戶，你將需要現(xiàn)在去注冊一個，才能注冊這個包[@Lesus 注：注冊之后還需要到郵箱去驗證才行]。在你已使用了上面注冊之后，你就可以創(chuàng)建發(fā)布包和上傳到PyPI了:

$ python setup.py sdist upload

上面這個命令建立一個源碼發(fā)布版(sdist)，然后上傳到PyPI.如果你的包不是純粹的Python（也就是說，你有二進制需要編譯進去），你就需要發(fā)布一個二進制版，請看setuptools文檔，了解更多。

發(fā)布及版本號

PyPI使用發(fā)行版本模型來確定你軟件包的哪個版本是默認可用的。初次上傳后，為使你軟件包的每次更新后在PyPI可用，你需要指定一個新版本號創(chuàng)建一個發(fā)布。版本號管理是一個相當復雜的課題，PEP有專門的內(nèi)容：PEP 440——版本識別和依賴指定。我建議參照PEP 400指南（明顯地），但如果你選擇使用不同版本的方案，在setup.py中使用的版本比目前PyPI中的版本“高”，這樣PyPI才會認為這是一個新版本。

1. 我們項目使用的語言是什么

2. 它使用的是語言的哪個版本

3. 使用什么命令安裝它

4. 使用什么命令運行項目的測試

這些都是很直接的東西。下面是sandman.travis.yml的內(nèi)容：

你還會收到一封通知你編譯成功的電子郵件。當然你也可以設置只有在出錯或錯誤被修復時才有郵件通知，但編譯輸出結果相同時也不會發(fā)送。這是非常有用的，你在不必被無用的“編譯通過！”郵件淹沒的同時在發(fā)生改變?nèi)詴盏骄尽?/p>

用ReadTheDocs做持續(xù)文檔集成

盡管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