建立開發環境#

若要測試程式碼變更，您需要從原始碼建置 pandas，這需要 C/C++ 編譯器和 Python 環境。如果您正在進行文件變更，您可以跳到 貢獻文件，但如果您略過建立開發環境，您將無法在提交變更前在本地建置文件。建議同時安裝 提交前掛鉤。

步驟 1：安裝 C 編譯器#

執行此操作的方式會取決於您的平台。如果您選擇在下一步中使用 Docker 或 GitPod，則可以跳過此步驟。

Windows

您將需要 Visual Studio 2022 的建置工具。

注意

您不需要安裝 Visual Studio 2022。您只需要向下捲動至「所有下載」->「Visual Studio 工具」就能找到「Visual Studio 2022 的建置工具」。在安裝程式中，選取「使用 C++ 的桌面開發」工作負載。

或者，您可以使用 vs_BuildTools.exe 在命令列上安裝必要的元件。

或者，您可以使用 WSL 並參閱以下 Linux 指示說明。

macOS

若要使用基於 mamba 的編譯器，您需要使用 xcode-select --install 安裝開發人員工具。

如果您偏好使用不同的編譯器，可以在此處找到一般資訊： https://devguide.python.org/setup/#macos

Linux

對於基於 Linux 的 mamba 安裝，您不必在 mamba 環境之外安裝任何其他元件。只有在您的設定不是基於 mamba 環境時，才需要以下指示說明。

某些 Linux 發行版會附帶預先安裝的 C 編譯器。若要找出您的系統上安裝了哪些編譯器（和版本）

# for Debian/Ubuntu:
dpkg --list | grep compiler
# for Red Hat/RHEL/CentOS/Fedora:
yum list installed | grep -i --color compiler

GCC (GNU 編譯器集合) 是一個廣泛使用的編譯器，支援 C 和許多其他語言。如果 GCC 已列為已安裝的編譯器，則不需要執行任何其他操作。

如果未安裝 C 編譯器，或您希望升級，或您使用的是不同的 Linux 發行版，請諮詢您最喜愛的搜尋引擎以取得編譯器安裝/更新說明。

如果您遇到任何困難，請透過開啟問題或透過我們的貢獻者社群 Slack 與我們聯繫。

步驟 2：建立隔離環境#

在我們開始之前，請

  • 確認您已 複製儲存庫

  • cd 到您剛使用複製指令建立的 pandas 原始碼目錄

選項 2：使用 pip#

您至少需要 pandas 支援的 最低 Python 版本。您還需要 setuptools 51.0.0 或更新版本才能建置 pandas。

Unix/macOS 搭配 virtualenv

# Create a virtual environment
# Use an ENV_DIR of your choice. We'll use ~/virtualenvs/pandas-dev
# Any parent directories should already exist
python3 -m venv ~/virtualenvs/pandas-dev

# Activate the virtualenv
. ~/virtualenvs/pandas-dev/bin/activate

# Install the build dependencies
python -m pip install -r requirements-dev.txt

Unix/macOS 搭配 pyenv

在此處查看設定 pyenv 的文件 here。

# Create a virtual environment
# Use an ENV_DIR of your choice. We'll use ~/Users/<yourname>/.pyenv/versions/pandas-dev
pyenv virtualenv <version> <name-to-give-it>

# For instance:
pyenv virtualenv 3.9.10 pandas-dev

# Activate the virtualenv
pyenv activate pandas-dev

# Now install the build dependencies in the cloned pandas repo
python -m pip install -r requirements-dev.txt

Windows

以下是 Windows 下使用 Powershell 設定虛擬環境的簡要說明。如需詳細資訊，請參閱 官方 virtualenv 使用者指南。

使用您選擇的 ENV_DIR。我們將使用 ~\\virtualenvs\\pandas-dev，其中 ~ 是 $env:USERPROFILE (Powershell) 或 %USERPROFILE% (cmd.exe) 環境變數所指的資料夾。任何父目錄都應已存在。

# Create a virtual environment
python -m venv $env:USERPROFILE\virtualenvs\pandas-dev

# Activate the virtualenv. Use activate.bat for cmd.exe
~\virtualenvs\pandas-dev\Scripts\Activate.ps1

# Install the build dependencies
python -m pip install -r requirements-dev.txt

選項 3：使用 Docker#

pandas 在根目錄中提供 DockerFile，以建置包含完整 pandas 開發環境的 Docker 映像。

Docker 指令

建置 Docker 映像

# Build the image
docker build -t pandas-dev .

執行容器

# Run a container and bind your local repo to the container
# This command assumes you are running from your local repo
# but if not alter ${PWD} to match your local repo path
docker run -it --rm -v ${PWD}:/home/pandas pandas-dev

更簡單的方法是，您可以將 Docker 與下列 IDE 整合

Visual Studio Code

您可以使用 DockerFile 啟動與 Visual Studio Code（一種熱門的免費 IDE）的遠端工作階段，方法是使用 .devcontainer.json 檔案。請參閱 https://vscode.dev.org.tw/docs/remote/containers 以取得詳細資訊。

PyCharm（專業版）

啟用 Docker 支援並使用服務工具視窗來建置和管理映像，以及執行和與容器互動。請參閱 https://www.jetbrains.com/help/pycharm/docker.html 以取得詳細資料。

選項 4：使用 Gitpod#

Gitpod 是一個開源平台，可自動在您的瀏覽器中建立正確的開發環境，減少安裝本機開發環境和處理不相容相依性的需求。

如果您是 Windows 使用者，不熟悉使用命令列或第一次建置 pandas，通常使用 Gitpod 建置會比較快。以下是 使用 GitPod 建置 pandas 的深入說明。

步驟 3：建置和安裝 pandas#

目前有兩種支援的建置 pandas 方式，pip/meson 和 setuptools(setup.py)。過去，pandas 僅支援使用 setuptools 建置 pandas。但是，此方法需要在 setup.py 中撰寫許多複雜的程式碼，而且由於 setuptools 的限制，在並行編譯 pandas 時也會產生許多問題。

較新的建置系統，透過 pip (透過 PEP 517 建置) 來呼叫 meson 後端。它會自動使用 CPU 上所有可用的核心，而且透過在每次匯入 pandas 時自動重新建置 (使用可編輯安裝)，避免需要手動重新建置。

基於這些原因，您應該使用 meson 編譯 pandas。由於 meson 建置系統較新，您可能會在它成熟時發現錯誤/小問題。您可以 在此 回報這些錯誤。

若要使用 meson 編譯 pandas，請執行

# Build and install pandas
# By default, this will print verbose output
# showing the "rebuild" taking place on import (see section below for explanation)
# If you do not want to see this, omit everything after --no-build-isolation
python -m pip install -ve . --no-build-isolation --config-settings editable-verbose=true

注意

版本號碼從最新的儲存庫標籤中提取。在建置之前，務必從上游取得最新的標籤

# set the upstream repository, if not done already, and fetch the latest tags
git remote add upstream https://github.com/pandas-dev/pandas.git
git fetch upstream --tags

建置選項

如果您想要設定您的安裝，可以從 pip 前端傳遞選項到 meson 後端。偶爾，您會想要使用此選項來調整建置目錄，和/或切換除錯/最佳化層級。

您可以透過附加 --config-settings builddir="your builddir here" 到您的 pip 指令，將建置目錄傳遞給 pandas。此選項讓您可以設定 meson 儲存您的已建置 C 擴充套件的位置，並允許快速重新建置。

有時，在除錯 C 擴充套件時，使用除錯符號編譯 pandas 可能會很有用。附加 --config-settings setup-args="-Ddebug=true" 將可以解決問題。

使用 pip，可以串連多個設定值（例如同時指定建置目錄和使用除錯符號建置會看起來像 --config-settings builddir="your builddir here" --config-settings=setup-args="-Dbuildtype=debug"。

使用 setup.py 編譯 pandas

注意

隨著 meson 後端逐漸成熟，這種編譯 pandas 的方法將很快被棄用並移除。

若要使用 setuptools 編譯 pandas，請執行

python setup.py develop

注意

如果已安裝 pandas（透過 meson），您必須先將其解除安裝

python -m pip uninstall pandas

這是因為 python setup.py develop 不會解除安裝載入程式碼，而 meson-python 會使用該程式碼從建置資料夾匯入擴充功能，這可能會導致錯誤，例如引發 FileNotFoundError。

注意

每次 C 擴充功能變更時，您都需要重複這個步驟，例如，如果您修改了 pandas/_libs 中的任何檔案，或者您從 upstream/main 擷取並合併。

檢查建置

此時，您應該可以從您本機建置的版本匯入 pandas

$ python
>>> import pandas
>>> print(pandas.__version__)  # note: the exact output may differ
2.0.0.dev0+880.g2b9e661fbb.dirty

此時，您可能想嘗試 執行測試套件。

與最新建置保持同步

使用 meson 建置 pandas 時，匯入 pandas 會自動觸發重新建置，即使修改了 C/Cython 檔案。預設情況下，此重新建置不會產生任何輸出（匯入只會花費較長的時間）。如果您想在匯入 pandas 時看到 meson 的輸出，您可以設定環境變數 MESONPY_EDTIABLE_VERBOSE。例如，這將是

# On Linux/macOS
MESONPY_EDITABLE_VERBOSE=1 python

# Windows
set MESONPY_EDITABLE_VERBOSE=1 # Only need to set this once per session
python

如果您想每次都看到此詳細輸出，您可以將 editable-verbose 設定設定為 true，如下所示

python -m pip install -ve . --config-settings editable-verbose=true

提示

如果你曾經想知道你的 pandas 是使用 setuptools 還是 meson 建置的，你可以檢查 pandas._built_with_meson 的值，如果 pandas 是使用 meson 編譯的，這個值會是 True。