Python套件版本更新與持續整合

– 10 分鐘閱讀

隨著專案的發展，Python 套件的版本更新與維護變得至關重要。妥善處理版本更新，尤其是涉及破壞性變更的部分，能有效降低對使用者的影響。同時，匯入持續整合流程能自動化測試、程式碼覆寫率追蹤及檔案建置，確保套件的品質與穩定性。本文將探討如何使用棄用警告、Poetry 套件管理工具以及 GitHub Actions，有效管理套件版本更新並建立 CI/CD 流程。透過逐步的說明與程式碼範例，開發者能輕鬆掌握這些技巧，提升套件開發效率與品質。

7.5 重大變更與套件功能的棄用

在軟體開發過程中，重大版本更新可能會伴隨不向後相容的變更，我們稱之為「重大變更」或「破壞性變更」。這些變更會影響套件的使用者，影響程度與使用者的數量成正比。然而，這並不意味著應該完全避免重大變更，因為有時進行重大變更是必要的，例如改善軟體設計、增強功能或簡化程式碼。

使用棄用警告

如果需要進行重大變更，最佳做法是逐步實施，並透過「棄用警告」向使用者提供適當的警告和建議。Python 的標準函式庫中的 warnings 模組可以用於新增棄用警告。例如，假設我們計畫在即將發布的 pycounts 套件的 v1.0.0 版本中移除 get_flatland() 函式，我們可以在 datasets.py 模組中新增 FutureWarning。

from importlib import resources
import warnings

def get_flatland():
    """取得範例 "Flatland" [1]_ 文字檔案的路徑。"""
    warnings.warn("此函式將在 v1.0.0 版本中棄用。", FutureWarning)
    with resources.path("pycounts.data", "flatland.txt") as f:
        data_file_path = f
    return data_file_path

內容解密：

  1. warnings.warn(): 用於發出警告的函式。在這裡，我們使用它來發出 FutureWarning，告知使用者 get_flatland() 函式將在未來的版本中棄用。
  2. FutureWarning: 一種警告型別，用於指示即將發生的變更。
  3. resources.path(): 用於取得指定資源檔案路徑的方法。

當我們嘗試使用這個函式時，會在輸出中看到 FutureWarning。

重大變更的最佳實踐

進行重大變更時，還有幾點需要考慮：

  • 逐步棄用: 如果對函式進行了重大變更，考慮在幾個版本中同時保留舊版（帶有棄用警告）和新版函式，以幫助使用者平滑過渡到新函式。
  • 小步伐棄用: 如果需要棄用大量程式碼，考慮在多個版本中逐步進行。
  • 相依性變更: 如果重大變更是由於套件的相依性變更引起的，通常最好先警告使用者需要更新相依性版本，而不是立即將其設為套件的必要相依性。
  • 檔案記錄: 詳細記錄重大變更至關重要，不要吝於在套件的檔案和變更日誌中詳細描述這些變更。

7.6 更新相依性版本

隨著時間的推移，當套件的相依性有新版本發布時，您需要更新相依性的版本限制。幸運的是，poetry 使得這個過程相對簡單。使用 poetry update 命令可以更新虛擬環境中已安裝的相依性版本，但這不會更新 pyproject.toml 檔案中的版本限制。要更新這些限制，您可以手動修改 pyproject.toml 或使用 poetry add 命令更新相依性到特定版本。

使用 Poetry 更新相依性

例如，要更新 matplotlib 的最低版本到 3.5.0，可以手動修改 pyproject.toml：

[tool.poetry.dependencies]
python = ">=3.9"
matplotlib = ">=3.5.0"

或者執行以下命令：

$ poetry add "matplotlib>=3.5.0"

內容解密：

  1. poetry update: 用於更新虛擬環境中已安裝相依性的命令。
  2. poetry add: 用於新增或更新相依性到特定版本的命令。
  3. 版本限制: 在 pyproject.toml 中指定的相依性版本範圍，用於確保套件的相容性。

第8章：持續整合與佈署

本章將介紹持續整合（CI）和持續佈署（CD），並展示如何使用 GitHub Actions 設定 CI/CD，以自動化測試、構建和佈署流程，從而讓開發者能夠專注於編寫程式碼。

CI/CD 簡介

持續整合是指自動評估程式碼更新的過程，以捕捉潛在問題。CI 工作流程通常包括自動化測試、構建和佈署軟體。使用 GitHub Actions，可以輕鬆地為 Python 套件設定 CI/CD。

8. 持續整合與佈署

持續整合（CI）與持續佈署（CD）是現代軟體開發中的關鍵實踐，能夠自動執行許多重要步驟，例如執行測試、計算程式碼覆寫率、建立檔案等。持續佈署則進一步自動化新版本的佈署，例如將軟體釋出到 PyPI 等平台。透過 CI/CD，開發者可以節省時間、加快版本釋出，並簡化他人參與貢獻的流程。

8.2 CI/CD 工具

雖然可以手動撰寫指令碼來執行 CI/CD 工作流程，但使用專門的 CI/CD 服務更為高效且具可擴充套件性。這些服務允許開發者定義工作流程，並在特定事件觸發時自動執行。常見的 CI/CD 服務包括 GitHub Actions、Travis CI 和 CircleCI。本章將重點介紹 GitHub Actions。

8.3 GitHub Actions 簡介

8.3.1 關鍵概念

GitHub Actions 是一項用於執行 CI/CD 工作流程的服務。開發者需在 .yml 檔案中定義工作流程，其中包含一系列「動作」（actions），例如使用 pytest 執行測試或使用 sphinx 建立檔案。這些動作被組織成「步驟」（steps），進一步組成「任務」（jobs），並在特定的「事件」（event）觸發時於「執行器」（runner）上執行。

關鍵字描述
Actions需要執行的個別任務
Workflow一組動作的集合，在單一檔案中定義
Event觸發工作流程執行的事件
Runner執行 GitHub Actions 的機器
Job在同一執行器上執行的一組步驟
Step任務中執行的命令或動作序列

8.3.2 簡易範例

本文將示範如何使用 GitHub Actions 建立並執行一個簡單的工作流程。

  1. 建立新儲存函式庫：在 GitHub 上建立一個名為 actions-example 的儲存函式庫（名稱可自訂）。點選「Actions」標籤，然後點選「Set up this workflow」按鈕。

  2. 提交 .yml 檔案：系統會自動建立一個 .yml 檔案。點選「Start commit」並選擇「Commit new file」提交。開啟該檔案，可以看到以下內容：

    name: CI

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Check-out repository
        uses: actions/checkout@v2
      - name: Print Hello world
        run: echo "Hello, world!"
      - name: Print two lines
        run: |
          echo "Line 1"
          echo "Line 2"

    內容解密：

    • name: 定義工作流程的名稱為 “CI”。
    • on: 指定觸發工作流程的事件，包括推播到 main 分支、對 main 分支的提取請求以及手動觸發。
    • jobs: 定義了一個名為 build 的任務，該任務在最新的 Ubuntu 執行器上執行。
    • steps: 包含三個步驟：簽出儲存函式庫、印出 “Hello, world!” 以及印出兩行文字。

  3. 檢視執行結果：提交後，GitHub Actions 將根據定義的工作流程自動執行。你可以在 GitHub 的「Actions」標籤下檢視執行結果和日誌。

圖示說明

@startuml
skinparam backgroundColor #FEFEFE

title Python套件版本更新與持續整合

|開發者|
start
:提交程式碼;
:推送到 Git;

|CI 系統|
:觸發建置;
:執行單元測試;
:程式碼品質檢查;

if (測試通過?) then (是)
    :建置容器映像;
    :推送到 Registry;
else (否)
    :通知開發者;
    stop
endif

|CD 系統|
:部署到測試環境;
:執行整合測試;

if (驗證通過?) then (是)
    :部署到生產環境;
    :健康檢查;
    :完成部署;
else (否)
    :回滾變更;
endif

stop

@enduml

此圖示展示了 GitHub Actions 的基本工作流程，從觸發事件到執行具體的動作。

持續整合與佈署的基礎：GitHub Actions 入門

GitHub Actions 的基本概念

GitHub Actions 是 GitHub 提供的一個強大的自動化工具，允許開發者建立自動化工作流程（workflow），以簡化軟體開發、測試和佈署的流程。在本章中，我們將介紹 GitHub Actions 的基本概念，並逐步建立一個適用於 Python 套件的持續整合（CI）工作流程。

工作流程（Workflow）

工作流程是一系列由特定事件觸發執行的命令集合。在 GitHub Actions 中，這些事件可以是推播（push）、提取請求（pull request）等。工作流程執行在一台稱為執行器（runner）的機器上，這台機器使用特定的作業系統，並由 CI/CD 服務託管。

工作（Job）與步驟（Step）

一個工作流程包含一個或多個工作，每個工作又包含一個或多個步驟。在 GitHub Actions 中，步驟可以是「動作」（action）或「命令」（command）。動作是可重複使用的程式碼單元，用於執行特定任務，而無需編寫任何命令。命令則是直接在執行器的命令列上執行的指令。

建立第一個 GitHub Actions 工作流程

步驟 1：建立工作流程檔案

首先，在您的儲存函式庫根目錄下建立一個名為 .github/workflows 的目錄，並在該目錄下建立一個名為 ci-cd.yml 的檔案。可以使用以下命令完成此操作：

$ mkdir -p .github/workflows
$ touch .github/workflows/ci-cd.yml

步驟 2：定義工作流程

開啟 ci-cd.yml 檔案，並新增以下內容：

name: ci-cd
on: [push, pull_request]

這定義了一個名為 ci-cd 的工作流程，它將在推播或提取請求事件發生時觸發。

步驟 3：設定工作流程

接下來，我們需要設定工作流程的步驟。首先，指定要使用的作業系統：

runs-on: ubuntu-latest

然後，安裝 Python 和 Poetry：

- name: Set up Python
  uses: actions/setup-python@v2
  with:
    python-version: '3.9'

- name: Install Poetry
  run: |
    pip install poetry

步驟 4：執行測試和構建檔案

安裝完成後，我們可以執行測試和構建檔案：

- name: Install dependencies
  run: |
    poetry install
- name: Run tests
  run: |
    poetry run pytest
- name: Build documentation
  run: |
    poetry run sphinx-build docs docs/_build/html

檢視工作流程日誌

提交 ci-cd.yml 檔案後，GitHub Actions 將自動觸發工作流程。您可以透過檢視工作流程的日誌來檢查執行結果。

程式碼範例與解析

以下是一個完整的 ci-cd.yml 檔案範例：

name: ci-cd
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Check-out repository
        uses: actions/checkout@v2
      - name: Set up Python
        uses: actions/setup-python@v2
        with:
          python-version: '3.9'
      - name: Install Poetry
        run: |
          pip install poetry
      - name: Install dependencies
        run: |
          poetry install
      - name: Run tests
        run: |
          poetry run pytest
      - name: Build documentation
        run: |
          poetry run sphinx-build docs docs/_build/html

內容解密：

  1. name: ci-cd：定義了工作流程的名稱為 ci-cd。
  2. on: [push, pull_request]：指定了觸發工作流程的事件為推播和提取請求。
  3. jobs：定義了工作流程中的工作。
  4. runs-on: ubuntu-latest：指定了執行工作流程的作業系統為最新的 Ubuntu 版本。
  5. steps：定義了工作流程中的步驟，包括簽出儲存函式庫、設定 Python 環境、安裝 Poetry、安裝依賴項、執行測試和構建檔案等。

8.4 設定持續整合（Continuous Integration）

持續整合（CI）是軟體開發中的重要實踐，能夠在每次程式碼變更時自動執行測試、檢查程式碼覆寫率及建置檔案等任務，從而確保程式碼的品質和穩定性。

8.4.1 設定 CI 工作流程

要設定 CI，首先需要在 GitHub 倉函式庫中建立 .github/workflows/ci-cd.yml 檔案，定義工作流程的步驟。以下是一個基本的 CI 工作流程組態：

name: ci-cd
on: [push, pull_request]
jobs:
  ci:
    runs-on: ubuntu-latest
    steps:
      - name: 設定 Python 3.9
        uses: actions/setup-python@v2
        with:
          python-version: 3.9
      - name: 簽出倉函式庫
        uses: actions/checkout@v2
      - name: 安裝 poetry
        uses: snok/install-poetry@v1
      - name: 安裝套件
        run: poetry install
      - name: 使用 pytest 進行測試
        run: poetry run pytest tests/ --cov=pycounts --cov-report=xml
      - name: 使用 Codecov 追蹤程式碼覆寫率
        uses: codecov/codecov-action@v2
        with:
          files: ./coverage.xml # 程式碼覆寫率報告
      - name: 建置檔案
        run: poetry run make html --directory docs/

內容解密：

  1. name: ci-cd：定義工作流程的名稱為 “ci-cd”。
  2. on: [push, pull_request]：設定工作流程在發生 push 或 pull_request 事件時觸發。
  3. jobs: ci:：定義一個名為 “ci” 的任務。
  4. runs-on: ubuntu-latest：指定任務執行在最新的 Ubuntu 環境中。
  5. steps:：定義任務中的步驟。
    • 設定 Python 3.9：使用 actions/setup-python@v2 設定 Python 環境為 3.9 版本。
    • 簽出倉函式庫：使用 actions/checkout@v2 簽出倉函式庫程式碼。
    • 安裝 poetry：使用 snok/install-poetry@v1 安裝 poetry 套件管理工具。
    • 安裝套件：執行 poetry install 安裝專案依賴套件。
    • 使用 pytest 進行測試：執行 poetry run pytest 進行單元測試，並透過 --cov 和 --cov-report 引數產生程式碼覆寫率報告。
    • 使用 Codecov 追蹤程式碼覆寫率：使用 codecov/codecov-action@v2 上傳程式碼覆寫率報告至 Codecov。
    • 建置檔案：執行 poetry run make html 建置專案檔案。

8.4.2 執行測試

在 CI 工作流程中，執行測試是至關重要的一步。透過執行單元測試，可以確保程式碼的正確性和穩定性。

- name: 使用 pytest 進行測試
  run: poetry run pytest tests/ --cov=pycounts --cov-report=xml

內容解密：

  1. poetry run pytest：在 poetry 虛擬環境中執行 pytest。
  2. tests/：指定測試檔案的目錄。
  3. --cov=pycounts：指定要測量的程式碼覆寫率的套件。
  4. --cov-report=xml：產生 XML 格式的程式碼覆寫率報告。

8.4.3 追蹤程式碼覆寫率

為了更好地追蹤程式碼覆寫率，可以使用 Codecov 這樣的服務。

- name: 使用 Codecov 追蹤程式碼覆寫率
  uses: codecov/codecov-action@v2
  with:
    files: ./coverage.xml # 程式碼覆寫率報告

內容解密：

  1. codecov/codecov-action@v2：使用 Codecov 的 GitHub Action 上傳程式碼覆寫率報告。
  2. files: ./coverage.xml：指定程式碼覆寫率報告的檔案路徑。

8.4.4 建置檔案

建置檔案是驗證檔案正確性的重要步驟。

- name: 建置檔案
  run: poetry run make html --directory docs/

內容解密：

  1. poetry run make html：在 poetry 虛擬環境中執行 make html 命令建置檔案。
  2. --directory docs/：指設定檔案的根目錄。

8.4.5 測試持續整合

完成 CI 工作流程的設定後，將 .github/workflows/ci-cd.yml 檔案提交到版本控制並推播到 GitHub，即可觸發 CI 工作流程。

$ git add .github/workflows/ci-cd.yml
$ git commit -m "build: add CI workflow"
$ git push

提交後，可以在 GitHub 倉函式庫的 “Actions” 標籤頁面檢視工作流程的執行結果。

此 CI 工作流程能夠在每次 push 或 pull_request 事件發生時自動執行測試、檢查程式碼覆寫率及建置檔案，從而確保程式碼的品質和穩定性。

玄貓 BlackCat

玄貓 BlackCat

技術愛好者，專注於分享程式開發、雲端技術與 AI 應用的心得體會。