[Python Dev] 在poetry環境下使用github actions和coveralls來進行CI 之一

Published in

SWF Lab

6 min readSep 9, 2022

前言：

前幾天想試著把 poetry、github actions 和 coveralls.py 這三個東西一起結合使用，建立一個可以自動更新 code coverage 的 CI 流程，最後得到還不錯的結果，所以想說寫一篇文做個紀錄同時推廣一下這些好用的開發工具。

這系列文會牽扯到幾個工具和他們的用法，我預計用三篇文章來完成。

三篇文章內容：

簡述 Poetry、poethepoet 與開始使用
簡述 github actions 與 coveralls.py
建立開發流程

那就開始吧！

Poetry and Poethepoet:

Poetry:

What is it:

Poetry 如同其他 pip, pipenv 等套件一樣，簡單來說就是 python 套件管理系統，但 Poetry 比其他套件更強的地方是他同時包含

virtual environment
package dependency
packaging

三個完善的管理功能。

而每一個套件管理系統都會有一套自己的 package 管理清單，有點像在寫 node 的時候會有的 package.json ，在 poetry 裡就是 pyproject.toml。而其實 pyproject.toml 這個檔案形式也有在 pep 621 被提到，定義為正式的設定檔標準，已經有不少套件支持。接下來就大致介紹一下如何開始使用 poetry 吧！

Usage:

首先附上官方文件 — Poetry。

再來不免俗的一定要先使用 pip 安裝：

pip install poetry

安裝好之後可以直接新增一個 poetry 專案：

是不是覺得跟React似曾相似阿

poetry new --src my-package

這時就會得到一個基本的 poetry project 架構：

正常來講得到這個架構就可以開始開發了，但這裡我習慣再安裝 poethepoet 這個插件來進行之後的 task 管理，安裝同時我也會順便介紹一些 poetry 常用的操作指令。

安裝：poetry add --dev <poethepoet>

這時可以看到 pyproject.toml：

已經把我們用到的 dependencies 都更新好了。在這裡可以注意到 poetry add 有加上 dev 這個 flag 時，表示只供開發使用，所以一般人安裝的版本是不會有這些 dev 裡的 dependencies 的。如果安裝一般套件直接用 poetry add blablabla 就可以了。

刪除： poetry remove <blablabla>

更新Lock： poetry lock

這裡就要提到一下這個 lock 檔的作用了，在使用 poetry 時有可能會遇到要手動在 toml 檔裡解決衝突的狀況，當 toml 檔案受到變動時 lock 檔就有更新的必要，因為在 env setup 階段時主要是透過 lock 檔，這時就會需要上面提到的這個指令。

很酷的樹狀功能： poetry show --tree

可以把 dependencies 用樹狀結構顯示出來：

那前面安裝的這個 poethepoet 又是怎麼個用法呢？我們接著介紹。

Poethepoet:

What is it:

要介紹 Poethepoet 我們可以直接看官方簡短的說明：

A task runner that works well with poetry.

就這麼簡單！但如果沒有接觸過類似概念應該會覺得有點模糊，不會沒關係，我相信透過接下來一些舉例可以讓各位很快了解他的概念以及好用之處。

Usage:

這裡先附上官方文件 — Poethepoet

再來我們接續剛剛的 pyproject.toml 檔，在裡面新增幾行字。

以下只是大概展示他的結構，會用到一些前面沒有提到的套件。

[tool.poe.env]
SRC = "my-package"
DIFF.default = ""
INPLACE.default = "--in-place"[tool.poe.tasks]
_black = 'black $SRC $DIFF --color'
_mypy-install-type = 'mypy $SRC --ignore-missing-imports --install-types --non-interactive'
_mypy = 'mypy $SRC --ignore-missing-imports'

這些由 tool 開頭的就是 poethepoet 定義的 env 或是 task，env 的部分主要可以設置一些 Global variables；而 task 主要有四種形態，分別是 simple commands (cmd), python scripts (script), shell scripts (shell), 和sequence tasks (sequence)，像這邊我可以結合 pytest, pytest-cov 來建立一個之後跑 unit test 的 task:

[tool.poe.tasks.test]
help = "Testing tasks."
shell = """
echo run unit tests
pytest --cov=$SRC --cov-report term-missing
"""

如此一來我只要在 terminal 跑 poe test 就可以進行 unit test ，這樣的功能在只有少數指令時可能會顯得有點雞肋或是混亂，但通常一個專案除了 test 外可能至少還會有 lint 跟 format 等需求，當有很多 task 要跑時，有這樣一個管理全部的工具就可以大大減少混亂程度並提高開發效率。

小結：

這篇文章主要先介紹 poetry 和 poethepoet 的基本用法，這些都和之後會一起使用的 github actions 息息相關。

下一篇會介紹 github actions 的基本用法跟如何和其他 CI 工具一起使用，讓專案在建 pr 或是 push 到任意 branch 時可以自動跑我們設定好的指令。（同時好好利用微軟爸爸給的資源）

謝謝大家！

References:

pep-518:https://peps.python.org/pep-0518/
pep-621:https://peps.python.org/pep-0621/
poetry:https://python-poetry.org/docs/
poethepoet:https://github.com/nat-n/poethepoet