Python套件開發環境設定指引

– 13 分鐘閱讀

在 Python 生態圈中，開發和分享套件是常見的需求。本文將引導您完成設定 Python 套件開發環境的必要步驟，從帳號註冊到工具安裝，讓您得以順利踏上套件開發之旅。首先，您需要在 PyPI 和 TestPyPI 上註冊帳號，以便日後釋出和測試您的套件。接著，建議您建立 Git 和 GitHub 帳號，並學習使用版本控制系統來管理您的程式碼。版本控制不僅能追蹤程式碼變更，還能方便團隊協作和程式碼備份。選擇一個合適的 IDE 也至關重要，Visual Studio Code、Atom、Sublime Text 等都是常用的選擇，它們提供程式碼自動完成、偵錯等功能，能提升開發效率。最後，為了確保開發環境的一致性，建議您使用 Docker 建立開發容器，避免跨平台相容性問題。

2.3 註冊 PyPI 帳號

Python Package Index（PyPI）是官方的 Python 軟體儲存函式庫。軟體儲存函式庫是用來存放可下載軟體的地方，例如 Python 套件。在本文中，我們將釋出一個套件到 PyPI。在釋出套件到 PyPI 之前，通常會先在 TestPyPI（PyPI 的測試版本）上進行測試。要跟隨本文的步驟，您應該在 TestPyPI 網站上註冊一個 TestPyPI 帳號，並在 PyPI 網站上註冊一個 PyPI 帳號。

2.4 設定 Git 和 GitHub

如果您尚未使用版本控制系統，強烈建議您養成這個習慣。版本控制系統能夠追蹤專案檔案的變更，讓您的專案歷程清晰有序。版本控制系統包含了專案的所有變更歷史，您可以隨時檢視和檢索這些變更。閱讀本文不需要具備使用或熟悉版本控制的經驗，但如果您認真想要建立 Python 套件，版本控制將成為您工作流程中不可或缺的一部分，因此現在是學習的好時機。

有多種版本控制系統可供選擇，但最常見的是 Git，我們將在本文中使用它。您可以按照 Git 檔案中的指示下載 Git。Git 有助於在本地電腦上追蹤專案的變更，但如果我們想要與他人協作，或者電腦損壞導致工作丟失，該怎麼辦？這就是 GitHub 的作用。GitHub 是多個線上服務之一，用於託管由 Git 管理的專案。GitHub 有助於建立本地 Git 儲存函式庫的線上副本，作為本地工作的備份，並允許他人輕鬆透明地協作於您的專案。您可以在 GitHub 網站上註冊免費的 GitHub 帳號。註冊後，您還應該按照官方 GitHub 檔案中的步驟設定 SSH 認證，以協助從 GitHub 推播和提取檔案。

2.5 Python 整合開發環境

Python 整合開發環境（IDE）將使建立 Python 套件的過程變得更加容易。IDE 是一種軟體，提供先進的功能來進行程式碼開發，例如目錄和檔案的建立和導航、自動完成、偵錯和語法突顯等功能。IDE 將為您節省時間並幫助您寫出更好的程式碼。常用的免費 Python IDE 包括 Visual Studio Code、Atom、Sublime Text、Spyder 和 PyCharm Community Edition。對於更熟悉 Jupyter 生態系統的人來說，JupyterLab 是一個合適的根據瀏覽器的 IDE。最後，對於 R 社群來說，RStudio IDE 也支援 Python。

2.5.1 Visual Studio Code

您可以從 Visual Studio Code 網站下載 Visual Studio Code（VS Code）。安裝 VS Code 後，您應該從 VS Code 市集安裝「Python」擴充套件。要做到這一點，請按照下面列出的步驟，並參考圖 2.1：

  1. 透過點選 VS Code 活動列上的擴充套件標籤開啟市集。
  2. 在搜尋列中搜尋「Python」。
  3. 選擇名為「Python」的擴充套件，然後點選安裝。

此圖示說明：

圖 2.1：安裝 Visual Studio Code 中的 Python 擴充套件。

完成後，您就擁有了開始建立套件所需的一切！例如，您可以從 VS Code 活動列上的檔案總管標籤建立檔案和目錄，並透過選擇檢視功能表中的終端機開啟整合式命令列介面。圖 2.2 顯示了在 VS Code 中從命令列執行 Python .py 檔案的範例。

我們建議您檢視 VS Code 入門，以瞭解更多關於使用 VS Code 的資訊。雖然您不需要安裝任何額外的擴充套件來開始在 VS Code 中建立套件，但有許多其他擴充套件可用來增強您的開發體驗。

# 在終端機中執行 Python 程式碼
python hello.py

程式碼解析：

上述程式碼是在終端機中執行一個名為 hello.py 的 Python 程式碼檔。這種方式可以直接執行 Python 指令碼，是開發和測試 Python 程式碼的常見做法。

使用 Plantuml 圖表呈現 IDE 的基本架構

@startuml
skinparam backgroundColor #FEFEFE
skinparam componentStyle rectangle

title Python套件開發環境設定指引

package "Docker 架構" {
    actor "開發者" as dev

    package "Docker Engine" {
        component [Docker Daemon] as daemon
        component [Docker CLI] as cli
        component [REST API] as api
    }

    package "容器運行時" {
        component [containerd] as containerd
        component [runc] as runc
    }

    package "儲存" {
        database [Images] as images
        database [Volumes] as volumes
        database [Networks] as networks
    }

    cloud "Registry" as registry
}

dev --> cli : 命令操作
cli --> api : API 呼叫
api --> daemon : 處理請求
daemon --> containerd : 容器管理
containerd --> runc : 執行容器
daemon --> images : 映像檔管理
daemon --> registry : 拉取/推送
daemon --> volumes : 資料持久化
daemon --> networks : 網路配置

@enduml

此圖示說明：

此圖示呈現了使用 VS Code 進行 Python 開發的基本流程，從安裝 VS Code 和 Python 擴充套件開始，到建立專案、撰寫和執行程式碼為止。

2.5 整合開發環境（IDE）安裝與設定

在開發Python專案時，選擇適當的整合開發環境（IDE）至關重要。本章節將介紹幾種常見的Python IDE，包括Visual Studio Code、JupyterLab和RStudio，並提供詳細的安裝和設定步驟。

2.5.1 Visual Studio Code

Visual Studio Code（VS Code）是一款功能強大且廣受歡迎的開源程式碼編輯器。它支援多種程式語言，包括Python。VS Code具有豐富的外掛程式生態系統，可以根據需求安裝不同外掛來提升開發效率。

安裝與設定VS Code

  1. 安裝VS Code：前往VS Code官方網站下載並安裝最新版本。
  2. 安裝Python相關外掛：開啟VS Code後，進入擴充功能市場，搜尋並安裝以下外掛：
    • Python Docstring Generator：快速為Python函式生成檔案字串（docstrings）。
    • Markdown All in One：提供Markdown檔案的鍵盤快捷鍵、自動目錄和預覽功能。

使用VS Code執行Python程式

  1. 開啟VS Code，建立或開啟一個Python檔案（例如hello-world.py）。
  2. 開啟整合終端，輸入python hello-world.py以執行程式。

圖示 2.2：在VS Code中執行Python檔案

此圖示展示了在VS Code整合終端中執行hello-world.py的過程。

2.5.2 JupyterLab

JupyterLab是一款根據瀏覽器的IDE，特別適合資料科學和機器學習領域的工作。它支援建立和編輯Jupyter筆記本，以及執行Python指令碼。

安裝JupyterLab

使用以下命令安裝JupyterLab：

$ conda install -c conda-forge jupyterlab

安裝完成後，可以透過以下命令啟動JupyterLab：

$ jupyter lab

使用JupyterLab執行Python程式

  1. 在JupyterLab中，建立一個新的終端。
  2. 輸入python hello-world.py以執行Python程式。

圖示 2.3：在JupyterLab中執行Python檔案

此圖示展示了在JupyterLab終端中執行hello-world.py的過程。

2.5.3 RStudio

對於具有R背景的使用者，可以在RStudio中使用Python。RStudio是一款流行的R語言IDE，支援多種功能，包括版本控制和專案管理。

安裝與設定RStudio

  1. 安裝RStudio：前往RStudio官方網站下載並安裝最新版本（至少版本1.4）。
  2. 安裝R：從CRAN下載並安裝最新版本的R。
  3. 安裝reticulate套件：在RStudio中執行以下命令安裝reticulate套件：
    install.packages("reticulate")
  4. 組態reticulate：根據作業系統，按照以下步驟組態reticulate：
    • Mac和Linux：
      1. 在終端中輸入which python以查詢Python直譯器的路徑。
      2. 在HOME目錄中建立或編輯.Rprofile檔案，新增Sys.setenv(RETICULATE_PYTHON = "path_to_python")。
      3. 在HOME目錄中建立或編輯.bash_profile檔案，新增export PATH="/opt/miniconda3/bin:$PATH"。
      4. 重啟R。
      5. 在R控制檯中執行以下命令以測試Python：
      library(reticulate)
repl_python()
    • Windows：
      1. 開啟Anaconda Prompt，輸入where python以查詢Python直譯器的路徑。
      2. 在HOME目錄中建立或編輯.Rprofile檔案，新增Sys.setenv(RETICULATE_PYTHON = "path_to_python")，注意路徑分隔符號使用\\。
      3. 重複Mac和Linux的步驟3-5。

圖示 2.4：在RStudio中執行Python程式碼

此圖示展示了在RStudio控制檯中互動式執行Python程式碼的過程。

#### 內容解密：

上述章節介紹了三種常見的Python IDE：VS Code、JupyterLab和RStudio。每一種IDE都有其特點和優勢，開發者可以根據自己的需求選擇合適的工具。每個部分的安裝和設定步驟都提供了詳細的指導，以幫助讀者順利完成設定。

對於VS Code，外掛程式的安裝極大地提升了開發效率，例如自動生成docstrings和Markdown支援。對於JupyterLab，使用者可以在瀏覽器中方便地進行資料科學相關的工作。對於RStudio，使用者可以透過reticulate套件在R環境中使用Python，大大提高了靈活性。

每種工具的使用範例和圖示都有助於讀者更好地理解如何在實際工作中應用這些IDE。接下來的章節將進一步探討如何使用Docker進行開發，以解決環境相容性問題。

2.6 使用Docker進行開發

在開發過程中，環境相容性問題常常會導致各種困擾。Docker提供了一個乾淨、隔離的開發環境，能夠有效地解決這些問題。本文將介紹如何使用Docker進行開發。

為何使用Docker？

Docker可以將應用程式及其依賴環境封裝成一個容器，確保在不同系統上的一致性。這樣可以避免“在我的機器上可以執行”的問題，並且簡化了佈署流程。

安裝Docker

前往Docker官方網站下載並安裝Docker Desktop。根據作業系統的不同，安裝步驟可能會有所不同。

使用Docker進行開發

  1. 建立Dockerfile：在專案根目錄下建立一個名為Dockerfile的檔案，用於定義Docker映象的構建過程。

    FROM python:3.9-slim

# 設定工作目錄
WORKDIR /app

# 複製需求檔案
COPY requirements.txt .

# 安裝依賴
RUN pip install --no-cache-dir -r requirements.txt

# 複製專案檔案
COPY . .

# 暴露埠
EXPOSE 8000

# 執行命令
CMD ["python", "app.py"]

  2. 構建Docker映象：在終端中導航到包含Dockerfile的目錄，並執行以下命令：

    docker build -t my-python-app .

  3. 執行Docker容器：使用以下命令啟動一個新的容器：

    docker run -p 8000:8000 my-python-app

#### 內容解密：

使用Docker可以確保開發環境的一致性，避免因環境差異導致的問題。透過建立Dockerfile並構建映象，可以輕鬆地在不同機器上佈署應用程式。上述步驟展示瞭如何為一個Python應用程式建立Docker映象並執行它。

這不僅簡化了佈署流程，還提高了應用的可移植性和可擴充套件性。在接下來的章節中，我們將進一步探討如何利用Docker進行更複雜的開發和佈署場景，例如多服務應用程式的容器化。

2.6 使用 Docker 進行開發

本文提供了一種使用 Docker 進行軟體開發的替代方案，該方案已經安裝了所需的所有工具。Docker 是一個允許你在隔離的環境（稱為容器）中執行和開發軟體的平台。映像檔包含了建立容器所需的指令。

我們已經開發了 Docker 映像檔，以支援在 Visual Studio Code 或 JupyterLab 中進行 Python 套件開發，並在下面的章節中描述了使用這些映像檔來跟隨本文學習的最小工作流程。您可以根據自己的特定使用案例自定義這些映像檔和/或工作流程。

我們將透過 GitHub 倉函式庫（py-pkgs/docker-vscode 和 py-pkgs/docker-jupyter）持續維護 Docker 映像檔，以支援本文的讀者。

2.6.1 在 Visual Studio Code 中使用 Docker

要在 Visual Studio Code 中使用 Docker 進行開發，您可以參考 Visual Studio Code 官方容器教程，或者嘗試按照以下步驟進行：

  1. 從官方網站安裝 Visual Studio Code。
  2. 按照官方網站上的說明安裝和組態適用於您作業系統的 Docker Desktop。
  3. 安裝 Docker 後，開啟命令列介面並執行以下命令以下載 pypkgs/vscode Docker 映像檔：
    $ docker pull pypkgs/vscode
  4. 在 Visual Studio Code 中，開啟/建立您想要開發的工作目錄（可以命名為任何名稱並位於您檔案系統中的任何位置）。
  5. 在 Visual Studio Code 中，開啟擴充套件標籤頁並在搜尋欄中搜尋 “Remote - Containers” 擴充套件。如果尚未安裝，請安裝它。
  6. 在當前工作目錄中建立一個名為 .devcontainer.json 的檔案（請務必在檔案名稱開頭包含句點）。此檔案將告訴 Visual Studio Code 如何在 Docker 容器中執行。您可以閱讀官方檔案以瞭解更多關於此組態的資訊，但目前，最小設定需要在該檔案中新增以下內容：
    {
  "name": "poetry",
  "image": "pypkgs/vscode",
  "extensions": ["ms-python.python"]
}
  7. 現在，開啟 Visual Studio Code 命令面板並搜尋並選擇 “Remote-Containers: Reopen in Container” 命令。此命令將在由 pypkgs/vscode Docker 映像檔建立的容器中開啟 Visual Studio Code。在 Visual Studio Code 在容器中完成開啟後，透過開啟整合終端並嘗試以下命令來測試您是否具有對我們需要的三個預安裝的軟體包軟體的存取許可權：
    $ poetry --version
$ conda --version
$ cookiecutter --version
  8. 現在，您的開發環境已經設定好了，您可以像在本地機器上一樣在 Visual Studio Code 中工作（除了現在您的開發環境存在於容器中）。如果您離開 Visual Studio Code，您的容器將停止，但會保留在您的機器上。它可以稍後使用我們在步驟 7 中使用的 “Remote-Containers: Reopen in Container” 命令重新開啟。
  9. 如果您想要完全刪除您的開發容器以釋放機器上的記憶體，請首先找到容器的 ID：
    $ docker ps -a
CONTAINER ID IMAGE
762bca6eb51e pypkgs/vscode
  10. 然後使用 docker rm 命令結合容器的 ID。這將刪除容器，包括其中安裝的任何套件或虛擬環境。但是，您建立的任何檔案和目錄將保留在您的機器上。
    $ docker rm 762bca6eb51e

內容解密：

此步驟詳細描述瞭如何在 Visual Studio Code 中設定和使用 Docker 容器進行開發。首先，需要安裝 Visual Studio Code 和 Docker Desktop。然後，下載特定的 Docker 映像檔並在 Visual Studio Code 中組態它以在容器中執行。透過建立 .devcontainer.json 檔案來指定容器的組態，包括使用的映像檔和需要安裝的擴充套件。最後，透過 “Remote-Containers: Reopen in Container” 命令在容器中啟動 Visual Studio Code，並驗證開發環境是否正確設定。

2.6.2 在 JupyterLab 中使用 Docker

要在 JupyterLab 中使用 Docker 進行開發，請按照以下說明進行。您也可以在 Jupyter Docker Stacks 檔案中找到有用的資訊和教程。

  1. 按照官方網站上的說明安裝和組態適用於您作業系統的 Docker Desktop。

  2. 安裝 Docker 後，開啟命令列介面並執行以下命令以下載 pypkgs/jupyter Docker 映像檔：

    $ docker pull pypkgs/jupyter

  3. 從命令列導航到您想要開發的目錄（可以命名為任何名稱並位於您檔案系統中的任何位置）。

  4. 從該目錄啟動一個新的容器，方法是從命令列執行以下命令：

    $ docker run -p 8888:8888 \
  -v "${PWD}":/home/jovyan/work \
  pypkgs/jupyter

    在上面的命令中，-p 將容器中的 8888 連線埠繫結到主機機器上的 8888 連線埠，-v 將當前目錄掛載到容器中的 /home/jovyan/work 位置。Windows 使用者可能會遇到上述命令的問題，可能需要嘗試在卷掛載路徑中使用雙斜線，例如：-v /$(pwd)://home//jovyan//work。您可以閱讀 Docker 命令列介面檔案以瞭解更多關於 docker run 命令及其引數的資訊。

  5. 將螢幕上列印的唯一 URL（看起來像這樣：http://127.0.0.1:8888/lab?token=45d53a348580b3acfafa）複製到您的瀏覽器中。這將開啟在 Docker 容器中執行的 JupyterLab 例項。

  6. 在 JupyterLab 中導航到工作目錄。這是您可以開發和建立新的檔案和目錄的地方，它們將儲存在您啟動容器的目錄中。

  7. 透過在 JupyterLab 中開啟終端並嘗試以下命令來測試您是否具有對我們需要的三個預安裝的軟體包軟體的存取許可權：

    $ poetry --version
$ conda --version
$ cookiecutter --version

  8. 當您完成工作時，您可以離開 JupyterLab，並殺死您的終端，您的容器將保留。您可以重新啟動容器並再次啟動 JupyterLab，首先找到其 ID：

    $ docker ps -a
CONTAINER ID IMAGE
653daa2cd48e pypkgs/jupyter

  9. 然後，使用 docker start -a 命令結合容器的 ID 來重新啟動容器並啟動 JupyterLab：

    $ docker start -a 653daa2cd48e

內容解密：

此部分介紹瞭如何在 JupyterLab 中使用 Docker。首先，需要安裝 Docker Desktop 並下載 pypkgs/jupyter Docker 映像檔。然後，透過執行特定的 docker run 命令來啟動一個新的容器，該命令指定了連線埠繫結和目錄掛載。之後，可以透過複製產生的 URL 在瀏覽器中存取 JupyterLab，並在指定的工作目錄中進行開發。與 Visual Studio Code 部分類別似，也需要驗證開發環境是否正確設定，包括檢查必要的軟體包是否可用。最後，還介紹瞭如何管理和重啟容器。

玄貓 BlackCat

玄貓 BlackCat

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