Python套件開發

– 11 分鐘閱讀

Python 套件已成為程式碼分享和重用的重要機制，有效提升開發效率。本文從套件的基礎概念出發，逐步引導讀者建立自己的 Python 套件。過程中，我們將會探討如何設計套件結構、管理依賴關係、撰寫單元測試和整合測試，並利用程式碼覆寫率工具確保測試的完整性。最後，我們將會介紹如何使用 PyPI 釋出套件，以及如何透過版本控制和持續整合流程提升套件的維護性和可靠度。

開發Python套件的全面

在當今的軟體開發領域中，Python已成為最受歡迎的程式語言之一。隨著Python在資料科學、人工智慧和機器學習等領域的廣泛應用，建立和管理Python套件的需求也日益增長。本篇文章將探討如何建立、測試和發布Python套件，幫助開發者掌握相關技能。

為什麼要建立Python套件

建立Python套件的主要原因包括程式碼重用、模組化開發和與他人分享程式碼。透過建立套件，開發者可以將常用的功能模組化，方便在不同專案中重用，同時也便於與其他開發者分享和協作。

設定開發環境

在開始建立Python套件之前，需要設定適當的開發環境。這包括安裝Python、必要的封裝軟體，以及註冊PyPI帳戶。此外，使用版本控制系統（如Git和GitHub）對於管理套件的開發過程至關重要。

安裝Python和必要的工具

  1. 安裝Python：從官方網站下載並安裝最新版本的Python。
  2. 安裝封裝軟體：使用pip安裝必要的封裝工具，如setuptools和wheel。
  3. 註冊PyPI帳戶：在Python套件索引（PyPI）上註冊帳戶，以便發布您的套件。

設定版本控制

  1. 安裝Git：下載並安裝Git，用於本地版本控制。
  2. 建立GitHub帳戶：在GitHub上建立帳戶，用於遠端版本控制和協作。

建立Python套件

建立Python套件涉及多個步驟，包括設計套件結構、編寫程式碼、新增依賴項和測試。

設計套件結構

一個典型的Python套件結構包括：

my_package/
    my_package/
        __init__.py
        module1.py
        module2.py
    tests/
        test_module1.py
        test_module2.py
    setup.py
    README.md
    LICENSE

編寫程式碼和測試

  1. 編寫模組：在my_package目錄下編寫您的Python模組。
  2. 編寫測試：在tests目錄下編寫單元測試，使用unittest或其他測試框架。

新增依賴項

在setup.py檔案中指定您的套件依賴項：

from setuptools import setup, find_packages

setup(
    name='my_package',
    version='0.1',
    packages=find_packages(),
    install_requires=[
        'requests>=2.25',
        'numpy>=1.20'
    ],
)

測試和發布套件

  1. 執行測試：使用測試框架執行您的單元測試，確保程式碼的正確性。
  2. 建立檔案：編寫詳細的檔案，包括使用範例和API參考。
  3. 發布到PyPI：使用twine將您的套件發布到PyPI，使其可供他人安裝和使用。

軟體開發流程中的測試與持續整合

在軟體開發過程中，測試是確保程式碼品質的重要環節。良好的測試策略不僅能提高程式碼的可靠性，還能減少除錯時間，加速開發流程。本篇文章將探討軟體測試的不同型別、測試方法，以及如何透過持續整合（CI）和持續佈署（CD）來最佳化開發流程。

測試型別與方法

軟體測試可以根據不同的目的和範圍分為多種型別，主要包括單元測試（Unit Tests）、整合測試（Integration Tests）和迴歸測試（Regression Tests）。

單元測試

單元測試是針對程式碼中最小的可測試單元進行驗證，通常是一個函式或方法。單元測試的目的是確保每個單元都能按照預期工作。撰寫單元測試時，應關注以下幾點：

  1. 獨立性：每個測試應獨立執行，不依賴於其他測試的結果。
  2. 全面性：測試應覆寫所有可能的執行路徑，包括邊界條件和錯誤處理。
  3. 自動化：單元測試應能自動執行，以便於持續整合。
import unittest
from pycounts.pycounts import count_words

class TestCountWords(unittest.TestCase):
    def test_count_words(self):
        # 測試 count_words 函式
        result = count_words("test.txt")
        self.assertEqual(result, expected_result)

整合測試

整合測試旨在驗證不同模組或元件之間的互動是否正確。它們通常比單元測試更複雜，需要更多的設定和準備。

import pytest
from pycounts.pycounts import count_words, plot_words

def test_integration():
    # 整合測試範例
    counts = count_words("test.txt")
    plot_words(counts)
    # 驗證結果是否符合預期

迴歸測試

迴歸測試用於確保新的程式碼變更沒有引入新的錯誤或破壞現有的功能。它們通常與單元測試和整合測試重疊，但更側重於檢查變更後的結果。

先進測試方法

除了基本的測試型別，還有一些先進的測試方法可以提高測試的有效性和效率。

Fixtures

Fixtures 是 pytest 中的一個強大功能，用於在測試前設定必要的環境或資料，並在測試後清理。

import pytest

@pytest.fixture
def example_fixture():
    # 設定 fixture
    data = prepare_data()
    yield data
    # 清理 fixture
    cleanup_data(data)

def test_with_fixture(example_fixture):
    # 使用 fixture 進行測試
    result = process_data(example_fixture)
    assert result == expected_result

Parameterizations

Parameterizations 允許使用不同的輸入引數多次執行同一個測試，從而提高測試的覆寫率。

import pytest

@pytest.mark.parametrize("input, expected", [
    ("input1", "expected1"),
    ("input2", "expected2"),
])
def test_parameterized(input, expected):
    # 引數化測試範例
    result = process_input(input)
    assert result == expected

程式碼覆寫率

程式碼覆寫率（Code Coverage）是衡量測試完整性的重要指標。它表示程式碼中有多少部分被測試執行過。常見的覆寫率指標包括行覆寫率（Line Coverage）和分支覆寫率（Branch Coverage）。

計算覆寫率

可以使用工具如 coverage.py 來計算 Python 程式碼的覆寫率。

coverage run -m pytest tests/
coverage report -m

版本控制與持續整合

版本控制系統（如 Git）是軟體開發的基礎。它們幫助團隊管理程式碼變更，協作開發。持續整合（CI）則是在版本控制的基礎上，自動化地執行測試、建置和佈署流程。

GitHub Actions

GitHub Actions 是 GitHub 提供的 CI/CD 工具，可以根據倉函式庫中的事件自動觸發工作流程。

name: CI

on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v2
      - name: Set up Python
        uses: actions/setup-python@v2
        with:
          python-version: '3.x'
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -r requirements.txt
      - name: Run tests
        run: |
          pytest tests/

前言

Python 套件是 Python 中可分享程式碼的基本單元。套件使組織、重用和維護程式碼變得容易，並能在專案之間、與同事以及更廣泛的 Python 社群分享程式碼。《Python 套件》是一本開源書籍，描述了建立 Python 套件的現代和高效工作流程。本文重點極為實用，將展示可用於快速、可重複地開發和維護套件的方法和工具，並盡可能實作自動化，以便專注於撰寫和分享程式碼！

為何閱讀本文？

儘管套件很重要，但對於初學者和經驗豐富的開發人員來說，理解和建立套件可能會很困難。本文旨在以易於理解和實用的方式描述封裝過程，適合資料科學家、開發人員和程式設計師。在過程中，我們將開發一個真實的 Python 套件，並探索 Python 封裝的所有關鍵元素，包括建立套件檔案和目錄結構、何時以及為何撰寫測試和檔案，以及如何藉助自動化的持續整合和持續佈署（CI/CD）管道來維護和更新套件。

閱讀本文後，您將：

  • 瞭解 Python 套件是什麼，以及何時以及為何使用它們。
  • 能夠從零開始建立自己的 Python 套件。
  • 學習如何為 Python 程式碼和套件撰寫檔案。
  • 為程式碼撰寫軟體測試並自動化它們。
  • 學習如何在 Python 套件索引（PyPI）上發布套件，並發現更新和版本控制程式碼的最佳實踐。
  • 實施 CI/CD 工作流程以自動建立、測試和佈署套件。
  • 獲得有關 Python 程式碼風格、最佳實踐封裝工作流程和其他有用的開發工具的提示。

本文的結構

第 1 章：簡介

首先簡要介紹 Python 中的套件以及為什麼應該瞭解如何建立它們。

第 2 章：系統設定

描述如何設定開發環境以開發套件並遵循本文中的範例。

第 3 章：如何封裝 Python

我們將從頭到尾開發一個範例套件，作為封裝過程中關鍵步驟的實際演示。本章構成了本文的基礎，並將作為讀者未來建立套件的參考表。

其餘章節將更詳細地介紹此流程中的每個步驟，大致按照工作流程中的順序進行組織：

  • 第 4 章：套件結構和分發
  • 第 5 章：測試
  • 第 6 章：檔案
  • 第 7 章：發布和版本控制
  • 第 8 章：持續整合和佈署

假設

雖然本文旨在初學者級別介紹 Python 封裝，但我們假設讀者對表 0.1 中列出的概念有基本的瞭解：

表 0.1：本文假設讀者熟悉的概念

專案學習資源
如何使用 import 陳述式匯入 Python 套件Python 檔案
如何撰寫條件陳述式（if/elif/else）和迴圈（for）Python 檔案
如何使用和撰寫 Python 函式Plotting and Programming in Python: Writing Functions (The Carpentries, 2021)
（可選）基本熟悉版本控制和 Git 以及 GitHub（或類別似工具）Happy Git and GitHub for the useR (Bryan et al., 2021) 或 Research Software Engineering with Python (Irving et al., 2021)

內容解密：

本章節主要介紹了本文的主題、目標讀者以及預備知識。作者強調了Python套件的重要性和本文的實用性質，並概述了讀者在閱讀本文後將獲得的技能和知識。同時，也明確了本文的結構和內容安排，以及對讀者預備知識的要求。

Python 套件：可重複使用與分享的程式碼基礎

Python 套件是 Python 程式語言的核心元素，也是撰寫可重複使用和分享程式碼的主要方式。本文假設讀者已經熟悉如何使用套件安裝工具（如 pip 或 conda）安裝套件，並且知道如何使用 Python 的 import 陳述式匯入和使用套件。

安裝與使用套件

例如，下面的指令使用 pip 安裝 numpy（Harris et al., 2020），這是 Python 的核心科學計算套件：

$ pip install numpy

安裝完成後，可以在 Python 直譯器中使用該套件。例如，將圓周率四捨五入到小數點後三位：

$ python
>>> import numpy as np
>>> np.round(np.pi, decimals=3)
3.142

內容解密：

  1. pip install numpy：使用 pip 安裝 numpy 套件。
  2. import numpy as np：將 numpy 套件匯入 Python 環境中，並將其重新命名為 np 以方便使用。
  3. np.round(np.pi, decimals=3)：使用 numpy 中的 round 函式將圓周率 np.pi 四捨五入到小數點後三位。

套件的功能與重要性

一個套件至少會將程式碼（如函式、類別、變數或指令碼）封裝在一起，以便在不同專案中輕鬆重複使用。然而，套件通常還會包含額外的內容，如檔案和測試，這些在與他人分享套件時變得越來越重要。

截至 2022 年 1 月，Python 套件索引（PyPI）上有超過 35 萬個可用的套件。套件是 Python 成為強大且廣泛使用的程式語言的主要原因之一。很有可能已經有人解決了你正在處理的問題，你可以透過下載和安裝他們的套件來受益。簡單來說，套件是你讓自己的程式碼可被他人使用的方法。

為何需要 Python 套件？

Python 套件讓開發者能夠將自己的程式碼組織起來，並與他人分享。這不僅有助於促程式式碼的重複使用，也讓其他開發者能夠站在巨人的肩膀上，加速自己的開發程式。

Python 套件的未來發展

隨著 Python 軟體生態系統的不斷演進，本文中討論的套件工作流程和概念可能會有所變更。不過，只要這些工具的維護者做好檔案記錄、版本控制和適當的棄用處理，那麼調整過時的程式碼應該是相對直接的。

本文的目標與靈感來源

本文的範疇和目標受到了 Hadley Wickham 和 Jenny Bryan 所著的《R Packages》（Wickham and Bryan, 2015）的啟發。這本文對 R 社群產生了深遠的影響，我們希望《Python Packages》也能在 Python 社群中扮演類別似的角色。

本文的寫作與編譯工具

本文使用 JupyterLab 編寫，並透過 Jupyter Book 編譯。原始碼託管在 GitHub 上，並透過 Netlify 佈署到 https://py-pkgs.org。

作者簡介

Tomas Beuzen 是一位駐紮在澳洲雪梨的資料科學家和教育工作者。Tiffany Timbers 是英屬哥倫比亞大學統計系的教學助理教授，同時也是該校資料科學碩士課程（溫哥華選項）的共同主任。他們兩位都致力於資料科學的教育和實踐，推動資料科學在現實世界中的應用。

為何建立Python套件以及環境設定

建立Python套件是現代軟體開發中非常重要的一環，不僅能有效提升程式碼的重用性和可維護性，也能讓開發者更方便地與他人分享自己的成果。本文將介紹建立Python套件的動機、優點以及如何設定開發環境。

為何應該建立Python套件

建立Python套件有許多好處，以下是幾個主要原因：

  • 能夠有效地與他人分享你的程式碼。
  • 即使你不打算與他人分享，套件也能幫助你在多個專案中重用和維護程式碼，從而節省時間。
  • 建立套件的過程會迫使你組織和記錄程式碼，使其更容易被理解和使用。
  • 套件能夠隔離程式碼的依賴關係，提高其可複製性。
  • 這是練習撰寫良好程式碼的好方法。
  • 套件可用於有效地捆綁可複製的資料分析和程式設計專案。
  • 最後，開發和分發套件支援了Python生態系統和其他可以從你的工作中受益的Python使用者。

系統設定

若你打算跟隨本文中的程式碼範例進行操作，建議遵循以下設定指示，以減少技術問題的發生。

命令列介面

命令列介面（CLI）是一種根據文字的介面，用於與你的電腦互動。在本文中，我們將使用CLI執行各種任務。我們假設Mac和Linux使用者使用「Terminal」，而Windows使用者使用「Anaconda Prompt」（我們將在下一節中安裝）作為CLI。

安裝軟體

以下將介紹如何安裝開發Python套件所需的軟體，以及如何跟隨本文中的範例進行操作。

安裝Python

我們建議透過Miniconda發行版安裝最新版本的Python。Miniconda是一個輕量級的Anaconda發行版。如果你已經安裝了Anaconda或Miniconda發行版，可以直接跳到下一節。

Miniconda和Anaconda都是Python的發行版，它們包含了conda套件和環境管理器，以及其他一些有用的套件。兩者的主要區別在於，Anaconda安裝了超過250個額外的套件（其中許多你可能永遠不會使用），而Miniconda則是一個更小的發行版，只包含了幾個關鍵的套件；你可以根據需要使用conda install命令安裝額外的套件。

# 更新conda及所有套件
$ conda update --all
安裝套件軟體

安裝Miniconda發行版後，請確保Python和conda是最新的。接下來，我們將安裝兩個主要的軟體工具，它們將幫助我們在本文中建立Python套件：

  1. poetry：一個幫助我們建立自己的Python套件的軟體。由於poetry正在積極開發中，我們建議參考官方的poetry檔案以取得詳細的安裝說明和支援。

    # 透過官方檔案安裝poetry
# https://python-poetry.org/docs/

使用Docker設定環境（可選）

對於那些在安裝或使用特定作業系統上的軟體時遇到問題的人，或是那些更喜歡使用Docker的人，我們也支援使用Docker進行設定。只需跳到第2.3節，我們將在第2.6節中描述Docker設定。

內容解密：

  1. 本文主要介紹如何設定開發Python套件所需的環境，包括安裝Python和必要的工具。
  2. 重點介紹了Miniconda作為Python的發行版，並說明瞭conda在環境管理和套件安裝方面的作用。
  3. 提到了使用Docker作為替代設定方案，以避免在特定作業系統上安裝軟體時可能遇到的問題。
玄貓 BlackCat

玄貓 BlackCat

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