TravisCI & PyPI 筆記

TravisCI & PyPI 筆記

自從第一次跳進開源的坑-iTaiGi 後端開發以後就學到很多,然而每次要重新做一次 Travis CI 的設定又會再翻一次資料,所以乾脆用這一篇記錄文來把心得記下來 ♪( ´▽`)

內文所述的專案網址在此:aweimeow/PyPI_Travis_Example

Travis CI 設定

一開始你需要先去 TravisCI 官方網站 把你的專案調成 enable。

Travis CI Setting

如圖所示,有藍綠色勾勾就可以了。

而接下來是需要去 GitHub 的專案設定,到 Integrations & Services 找到 Travis CI

Travis CI @ Github

接下來就可以開始寫 最重要的 .travis.yml

Write .travis.yml

這是我的範例,因為我寫 Python,所以測試 Coding Style 使用 flake8 來測 PEP8、用 pytest 來測 Testing Code。

首先我們會在開頭定義能不能使用 sudo、還有使用的語言,而這邊我同時測 Python 2.7Python 3.4,並且設定環境變數(也就是我的測試):
* coverage run setup.py test
* flake8 –exclude=venv,setup.py

因為我使用 python setup.py test 來做測試,所以在這邊就讓 coverage 以呼叫 setup.py 的方式來執行我的 Testing Code。

且因為我有使用 Virtual Environment 的習慣,所以我也在這邊把 venv/ 資料夾排除掉,否則會跑去檢查相依套件的 Coding Style。

coverage report 單純就是在 Build Success 後把 Coverage 報表顯示出來,並且結合 coveralls 的服務讓他 comment Coverage 在你的 Pull Request 上面。

setup.py with PyPI

接下來要寫 setup.py 的資訊,並且寫下設定檔就可以直接把你的 Package 上傳到 PyPI 了!

PyPI Configure File

這個部分你可以參考 這一篇文章,當然我在此也會寫下我的作法,只是他的文章寫得不錯,也能看一看。

一開始你必須要先申請 PyPI 的帳號,PyPI 分為兩個網站:PyPI Live(上線版網站)PyPI Test(測試版網站),點擊連結即可連至網站申請帳號。

發布時可以先於 PyPI 發布測試,等確定沒有問題以後就能夠 publish 到 PyPI Live 了。

申請完之後我們要在家目錄下建立一個設定檔:~/.pypirc,如以下為範例,把剛剛申請的帳號密碼填入就可以了,為了方便記憶避免混淆,建議可以考慮使用相同一組帳號密碼

{% alert warning %}
如果您的密碼當中包含 % 且使用的版本是 Python3,請以 %% 來表示 %(一個跳脫符號的概念)。
{% endalert %}

並且使用以下指令來 Publish 到 PyPI:

setup.py

在此先寫出完整版本的 setup.py,至於 pytest 的部分稍後會在解釋。

基本上 setup 都很直觀,不過這邊還是條列一下以供參考:
* name: Package 的名字
* packages: Package 的路徑
* version: 這個 Package 的版本
* description: 關於這個 Package 的說明
* author: 作者名字
* author_email: 作者的 Email Address
* url: 專案網址
* download_url: 下載網址
* keywords: 關鍵字

至於後面沒解釋的是 Testing 用的東西,稍後再解釋。

這樣子寫完你的 setup.py 之後,就能夠發佈到 PyPI 上了,別人也能透過從 Github clone 專案並執行 python setup.py install 去安裝這個 Package。

setup.py with Testing

剛剛還沒解釋到的就是 setup.py 之中的:

加入這兩行以後,還需要再 setup.cfg 加入:

這邊的 metadata 之中是指定以哪一個檔案作為描述專案的文件,而 aliases 是讓你能透過下 python setup.py test 去呼叫 pytest。

至於最後的 tool:pytest 則是指定參數(addopts)與指定測試程式的資料夾。

到這邊設定就完成了,試試看執行:

Coveralls 設定

有 TravisCI 寫好設定檔來自動跑測試與檢查 Coding Style,當然不可或缺的還有 Testing Coverage!

這邊使用 coveralls 作為範例。

一開始碰到了 Coveralls 不會來 Commit 的問題,後來找到的解決方法是:
1. 從 Travis CI 網站中把 repository 撤掉
2. 從 Coveralls 網站中把 repository 撤掉
3. 加回 Travis CI 與 Coveralls

我認為我的問題出在於原本是我的 Repository 是在 Private,而後來轉成 Public,才導致 Coveralls 沒辦法找到我。(不過不確定,所以只是提出來讓大家參考)

而 Coveralls 設定超級容易的,只需要如下圖把他打開成 ON 就可以了:

只是你或許會納悶為什麼他沒來 Commit 呢?因為他要在 TravisCI build 成功後才會來根據 Travis CI config 檔:

所以在 build success 之後,Coveralls 的機器人就會來專案 Comment 了:

GitHub Service Hook

除此之外,我們還需要在 GitHub 上面設定一些保護措施,像是:
* 不能直接對 master 做 push,只能 commit 在別的 PR 進行 merge
* 在 merge 之前會做檢查,如果 Service Hook 沒有通過(如 Travis CI Test Failed)則不能 merge

首先連到 GitHub 的專案設定-branch:

Protected Branch

我們要把 Master 這個 Branch 設定為 protected

設定如下圖,我們需要勾選最上方的 Protect this branch 來啟用保護,並且可根據您的需要來勾選其他的選項:

  • Require pull request reviews before merging:如果勾選的話,每一個 commit 都要被 approve 才可以
  • Require status checks to pass before merging:在 merging 之前必須要通過 Status Check(如 Travis CI、Coveralls … 等),只要出現錯誤則不能 merge。

這樣設定之後,如果 Check 沒有問題的話則會像下方這樣可以進行 Merge 到 Master:

後話

大致上就是這樣子設定了,每一次建立新專案都必須再翻閱一堆資料,不如直接把它記錄下來,自己方便以外也能讓有需要的人能夠作為參考。

比較遺憾的是 Coveralls 一直設定不起來,搞不太清楚問題出在哪邊,如果後來有找到原因並弄出來再補上 Coveralls 的設定說明。

2017/3/30 update: 已經找到問題在哪邊了,如內文所述。

順帶一提,如果您也寫 Python 且覺得這個 Example 不錯的話,可以 Star 或 Fork 回去以它作為範本來修改,謝謝。

對於內容有疑問或內容有誤,也十分歡迎您來信與我討論。

Leave a Reply

Your email address will not be published. Required fields are marked *