Python 開發

本頁提供所有平台的通用 Python 開發指南和原始碼建置說明。

程式碼風格

我們遵循類似 PEP8 的程式碼風格，如同 pandas 專案。要檢查風格問題，請使用 Archery 子命令 lint

$ pip install -e "arrow/dev/archery[lint]"

$ archery lint --python

某些問題可以透過傳遞 --fix 選項自動修正

$ archery lint --python --fix

Python 程式碼庫也包含一些 C++ 檔案。要修正這些檔案中的格式，請新增 --clang-format 選項

$ archery lint --python --clang-format --fix

單元測試

我們使用 pytest 來開發我們的單元測試套件。在建置專案（見下方）之後，您可以像這樣執行其單元測試

$ pushd arrow/python
$ python -m pytest pyarrow
$ popd

執行單元測試的套件需求可以在 requirements-test.txt 中找到，如果需要，可以使用 pip install -r requirements-test.txt 安裝。

如果您在嘗試執行測試時遇到 pyarrow._lib 或其他 PyArrow 模組的匯入錯誤，請執行 python -m pytest arrow/python/pyarrow 並檢查是否正確安裝了 pyarrow 的可編輯版本。

該專案的測試套件有許多自訂命令列選項。例如，某些測試預設為停用。要查看所有選項，請執行

$ python -m pytest pyarrow --help

並尋找「custom options」區段。

注意

有一些底層測試直接以 C++ 撰寫。這些測試實作於 pyarrow/src/arrow/python/python_test.cc，但它們也包裝在基於 pytest 的 測試模組 中，作為 PyArrow 測試套件的一部分自動執行。

測試群組

我們有許多使用 pytest 標記分組在一起的測試。其中一些預設為停用。要啟用測試群組，請傳遞 --$GROUP_NAME，例如 --parquet。要停用測試群組，請在前面加上 disable，因此例如 --disable-parquet。要僅執行特定群組的單元測試，請在前面加上 only-，例如 --only-parquet。

目前的測試群組包括

• dataset：Apache Arrow Dataset 測試

• flight：Flight RPC 測試

• gandiva：Gandiva 運算式編譯器測試（使用 LLVM）

• hdfs：使用 libhdfs 存取 Hadoop 檔案系統的測試

• hypothesis：使用 hypothesis 模組產生隨機測試案例的測試。請注意，由於 pytest 的怪癖，--hypothesis 無效，因此您必須傳遞 --enable-hypothesis

• large_memory：需要大量系統 RAM 的測試

• orc：Apache ORC 測試

• parquet：Apache Parquet 測試

• s3：Amazon S3 測試

• tensorflow：涉及 TensorFlow 的測試

Doctest

我們使用 doctest 來檢查 docstring 範例是否為最新且正確。您也可以透過執行以下命令在本機執行此操作

$ pushd arrow/python
$ python -m pytest --doctest-modules
$ python -m pytest --doctest-modules path/to/module.py # checking single file
$ popd

適用於 .py 檔案，或

$ pushd arrow/python
$ python -m pytest --doctest-cython
$ python -m pytest --doctest-cython path/to/module.pyx # checking single file
$ popd

適用於 .pyx 和 .pxi 檔案。在這種情況下，您還需要安裝 pytest-cython 外掛程式。

基準評測

如需執行基準評測，請參閱 基準測試。

在 Linux 和 macOS 上建置

系統需求

在 macOS 上，任何現代 XCode（6.4 或更高版本；目前版本為 13）或 Xcode Command Line Tools（xcode-select --install）都已足夠。

在 Linux 上，對於本指南，我們最低要求 gcc 4.8 或 clang 3.7。您可以透過執行以下命令檢查您的版本

$ gcc --version

如果系統編譯器早於 gcc 4.8，則可以使用 $CC 和 $CXX 環境變數將其設定為較新版本

$ export CC=gcc-4.8
$ export CXX=g++-4.8

環境設定與建置

首先，讓我們複製 Arrow git 儲存庫

$ git clone https://github.com/apache/arrow.git

拉取測試資料並設定環境變數

$ pushd arrow
$ git submodule update --init
$ export PARQUET_TEST_DATA="${PWD}/cpp/submodules/parquet-testing/data"
$ export ARROW_TEST_DATA="${PWD}/testing/data"
$ popd

使用 Conda

conda 套件管理器允許安裝 Arrow C++ 和 PyArrow 的建置時依賴項作為預先建置的二進位檔，這可以使 Arrow 開發更輕鬆、更快速。

讓我們建立一個 conda 環境，其中包含來自 conda-forge 的所有 C++ 建置和 Python 依賴項，目標是 Python 3.10 的開發

在 Linux 和 macOS 上

$ conda create -y -n pyarrow-dev -c conda-forge \
       --file arrow/ci/conda_env_unix.txt \
       --file arrow/ci/conda_env_cpp.txt \
       --file arrow/ci/conda_env_python.txt \
       --file arrow/ci/conda_env_gandiva.txt \
       compilers \
       python=3.10 \
       pandas

截至 2019 年 1 月，在許多 Linux 發行版上，需要 compilers 套件才能使用來自 conda-forge 的套件。

完成此步驟後，您現在可以啟用 conda 環境

$ conda activate pyarrow-dev

對於 Windows，請參閱下方的 在 Windows 上建置 章節。

我們需要設定一些環境變數，以讓 Arrow 的建置系統知道我們的建置工具鏈

$ export ARROW_HOME=$CONDA_PREFIX

使用系統和捆綁依賴

警告

如果您使用 Anaconda 發行版或 Miniconda 安裝 Python，您目前無法使用基於 pip 的虛擬環境。請改為遵循基於 conda 的開發說明。

如果不使用 conda，您必須安排您的系統提供所需的建置工具和依賴項。請注意，如果缺少某些依賴項，Arrow C++ 建置鏈可能仍然能夠即時下載並編譯它們，但這將比使用預先安裝的二進位檔花費更長的時間。

在 macOS 上，使用 Homebrew 安裝建置 Arrow C++ 所需的所有依賴項

$ brew update && brew bundle --file=arrow/cpp/Brewfile

請參閱 此處 以取得您可能需要的依賴項清單。

在 Debian/Ubuntu 上，您需要以下最少的依賴項集合

$ sudo apt-get install build-essential ninja-build cmake python3-dev

現在，讓我們在與儲存庫相同的資料夾中建立一個包含所有 Python 依賴項的 Python 虛擬環境，以及目標安裝資料夾

$ python3 -m venv pyarrow-dev
$ source ./pyarrow-dev/bin/activate
$ pip install -r arrow/python/requirements-build.txt

$ # This is the folder where we will install the Arrow libraries during
$ # development
$ mkdir dist

如果您的 CMake 版本在 Linux 上太舊，您可以透過 pip install cmake 取得較新的版本。

我們需要設定一些環境變數，以讓 Arrow 的建置系統知道我們的建置工具鏈

$ export ARROW_HOME=$(pwd)/dist
$ export LD_LIBRARY_PATH=$(pwd)/dist/lib:$LD_LIBRARY_PATH
$ export CMAKE_PREFIX_PATH=$ARROW_HOME:$CMAKE_PREFIX_PATH

建置與測試

現在建置 Arrow C++ 函式庫並將其安裝到我們上面建立的目錄中（儲存在 $ARROW_HOME 中）

$ cmake -S arrow/cpp -B arrow/cpp/build \
        -DCMAKE_INSTALL_PREFIX=$ARROW_HOME \
        --preset ninja-release-python
$ cmake --build arrow/cpp/build --target install

ninja-release-python 不是唯一可用的預設設定 - 如果您想要具有更多功能的建置，例如 CUDA、Flight 和 Gandiva 支援，您可以選擇 ninja-release-python-maximal 預設設定。如果您想要較少的功能（即移除 ORC 和 dataset 支援），您可以選擇 ninja-release-python-minimal。將任何上述預設設定中的單字 release 變更為 debug 將產生 Arrow 的偵錯版本。

預設設定是為了方便起見而提供的，但您可以選擇指定個別組件

有許多可選組件可以透過新增帶有 ON 的旗標來開啟

• ARROW_CUDA：支援啟用 CUDA 的 GPU

• ARROW_DATASET：支援 Apache Arrow Dataset

• ARROW_FLIGHT：Flight RPC 框架

• ARROW_GANDIVA：基於 LLVM 的運算式編譯器

• ARROW_ORC：支援 Apache ORC 檔案格式

• ARROW_PARQUET：支援 Apache Parquet 檔案格式

• PARQUET_REQUIRE_ENCRYPTION：支援 Parquet 模組化加密

上面設定為 ON 的任何項目也可以關閉。請注意，建議使用一些壓縮函式庫以獲得完整的 Parquet 支援。

您可以選擇不同種類的 C++ 建置類型

• -DCMAKE_BUILD_TYPE=Release（預設）產生啟用最佳化和停用偵錯資訊的建置；

• -DCMAKE_BUILD_TYPE=Debug 產生停用最佳化和啟用偵錯資訊的建置；

• -DCMAKE_BUILD_TYPE=RelWithDebInfo 產生同時啟用最佳化和偵錯資訊的建置。

另請參閱

建置 Arrow C++.

如果您的環境中安裝了多個 Python 版本，您可能必須將其他參數傳遞給 CMake，以便它可以找到正確的可執行檔、標頭和函式庫。例如，指定 -DPython3_EXECUTABLE=<path/to/bin/python> 讓 CMake 選擇您正在使用的 Python 可執行檔。

注意

在支援在多個架構上建置的 Linux 系統上，make 預設可能會將函式庫安裝在 lib64 目錄中。因此，我們建議傳遞 -DCMAKE_INSTALL_LIBDIR=lib，因為 Python 建置腳本假設函式庫目錄為 lib

注意

如果您安裝了 conda 但未使用它來管理依賴項，並且您在建置 C++ 函式庫時遇到問題，您可能需要設定 -DARROW_DEPENDENCY_SOURCE=AUTO 或其他一些值（此處 有描述）以明確告知 CMake 不要使用 conda。

對於任何其他 C++ 建置挑戰，請參閱 C++ 開發。

如果您可能需要由於程序中的錯誤而重建 C++ 部分，建議使用命令 rm -rf arrow/cpp/build 刪除建置資料夾。如果建置已成功通過，並且您需要由於從 git main 最新拉取而重建，則不需要此步驟。

現在，建置 pyarrow

$ pushd arrow/python
$ export PYARROW_PARALLEL=4
$ python setup.py build_ext --inplace
$ popd

如果您建置了其中一個 C++ 中的可選組件，則預設情況下將啟用等效組件以建置 pyarrow。此預設值可以透過將相應的 PYARROW_WITH_$COMPONENT 環境變數設定為 0 或 1 來覆寫，請參閱下方的 相關組件和環境變數。

要設定用於編譯 PyArrow 的 C++/Cython 組件的執行緒數量，請設定 PYARROW_PARALLEL 環境變數。

如果您希望在重建之前刪除過時的 PyArrow 建置產物，請導航到 arrow/python 資料夾並執行 git clean -Xfd .。

預設情況下，即使 Arrow C++ 已在偵錯模式下建置，PyArrow 也將在發布模式下建置。要建立 PyArrow 的偵錯版本，請在執行上面的 python setup.py build_ext --inplace 之前執行 export PYARROW_BUILD_TYPE=debug。可以使用類似的方式建立 relwithdebinfo 建置。

現在您已準備好安裝測試依賴項並執行 單元測試，如上所述。

要建置獨立的 wheel（包括 Arrow 和 Parquet C++ 函式庫），可以設定 --bundle-arrow-cpp

$ pip install wheel  # if not installed
$ python setup.py build_ext --build-type=$ARROW_BUILD_TYPE \
         --bundle-arrow-cpp bdist_wheel

注意

要在可編輯的 PyArrow 建置中安裝，請在 arrow/python 目錄中執行 pip install -e . --no-build-isolation。

Docker 範例

如果您在從原始碼建置 Python 函式庫時遇到困難，請查看 python/examples/minimal_build 目錄，其中說明了使用 conda 和 pip 建置方法從原始碼完成建置和測試的完整過程。

除錯

由於 pyarrow 依賴於 Arrow C++ 函式庫，除錯經常涉及跨越 Python 和 C++ 共享函式庫。為了獲得最佳體驗，請確保您已在偵錯模式下建置 Arrow C++（-DCMAKE_BUILD_TYPE=Debug）和 PyArrow（export PYARROW_BUILD_TYPE=debug）。

在 Linux 上使用 gdb

要在執行 Python 單元測試時使用 gdb 偵錯 C++ 函式庫，請先使用 gdb 啟動 pytest

$ gdb --args python -m pytest pyarrow/tests/test_to_run.py -k $TEST_TO_MATCH

要設定中斷點，請使用與偵錯 C++ 程式時相同的 gdb 語法，例如

(gdb) b src/arrow/python/arrow_to_pandas.cc:1874
No source file named src/arrow/python/arrow_to_pandas.cc.
Make breakpoint pending on future shared library load? (y or [n]) y
Breakpoint 1 (src/arrow/python/arrow_to_pandas.cc:1874) pending.

另請參閱

Arrow C++ 的 GDB 擴充功能。

在 Windows 上建置

在 Windows 上建置需要安裝下列其中一個編譯器

• Visual Studio 2017 的建置工具

• Visual Studio 2017

在設定建置工具期間，請確保至少選取一個 Windows SDK。

我們引導啟動類似於上述的 conda 環境，但跳過一些僅限 Linux/macOS 的套件

首先，從 Apache Arrow 的全新複製開始

$ git clone https://github.com/apache/arrow.git

$ conda create -y -n pyarrow-dev -c conda-forge ^
      --file arrow\ci\conda_env_cpp.txt ^
      --file arrow\ci\conda_env_python.txt ^
      --file arrow\ci\conda_env_gandiva.txt ^
      python=3.10
$ conda activate pyarrow-dev

現在，我們建置並安裝 Arrow C++ 函式庫。

我們將 Arrow C++ 函式庫的安裝目錄路徑設定為 ARROW_HOME。當使用 conda 環境時，Arrow C++ 安裝在環境目錄中，其路徑儲存在 CONDA_PREFIX 環境變數中。

$ set ARROW_HOME=%CONDA_PREFIX%\Library

讓我們設定、建置和安裝 Arrow C++ 函式庫

$ mkdir arrow\cpp\build
$ pushd arrow\cpp\build
$ cmake -G "Ninja" ^
      -DCMAKE_INSTALL_PREFIX=%ARROW_HOME% ^
      -DCMAKE_UNITY_BUILD=ON ^
      -DARROW_COMPUTE=ON ^
      -DARROW_CSV=ON ^
      -DARROW_CXXFLAGS="/WX /MP" ^
      -DARROW_DATASET=ON ^
      -DARROW_FILESYSTEM=ON ^
      -DARROW_HDFS=ON ^
      -DARROW_JSON=ON ^
      -DARROW_PARQUET=ON ^
      -DARROW_WITH_LZ4=ON ^
      -DARROW_WITH_SNAPPY=ON ^
      -DARROW_WITH_ZLIB=ON ^
      -DARROW_WITH_ZSTD=ON ^
      ..
$ cmake --build . --target install --config Release
$ popd

現在，我們可以建置 pyarrow

$ pushd arrow\python
$ set CONDA_DLL_SEARCH_MODIFICATION_ENABLE=1
$ python setup.py build_ext --inplace
$ popd

注意

為了建置 pyarrow，還需要設定上面定義的環境變數。如果您想在初始建置後重新建置 pyarrow，請記住這一點。

注意

如果您將 Conda 與 Python 3.9 或更早版本搭配使用，則必須設定 CONDA_DLL_SEARCH_MODIFICATION_ENABLE=1。

然後使用以下命令執行單元測試

$ pushd arrow\python
$ python -m pytest pyarrow
$ popd

注意

透過上述說明，Arrow C++ 函式庫未與 Python 擴充功能捆綁在一起。建議用於開發，因為它允許單獨重新建置 C++ 函式庫。

如果您使用 conda 套件管理器，則 conda 將確保找到 Arrow C++ 函式庫。如果您不使用 conda，則必須

• 在每次匯入 pyarrow 之前，將已安裝 DLL 函式庫的路徑新增至 PATH，或

• 將 Arrow C++ 函式庫與 pyarrow 捆綁在一起。

如果您想將 Arrow C++ 函式庫與 pyarrow 捆綁在一起，請在建置 pyarrow 之前設定 PYARROW_BUNDLE_ARROW_CPP 環境變數

$ set PYARROW_BUNDLE_ARROW_CPP=1
$ python setup.py build_ext --inplace

請注意，當重建 Arrow C++ 時，捆綁的 Arrow C++ 函式庫將不會自動更新。

注意事項

相關組件和環境變數

可用於建置 PyArrow 的相關環境變數清單如下

PyArrow 環境變數	描述	預設值
PYARROW_BUILD_TYPE	PyArrow 的建置類型（release、debug 或 relwithdebinfo），設定 CMAKE_BUILD_TYPE	release
PYARROW_CMAKE_GENERATOR	範例：'Visual Studio 15 2017 Win64'	''
PYARROW_CMAKE_OPTIONS	額外的 CMake 和 Arrow 選項（例如 "-DARROW_SIMD_LEVEL=NONE -DCMAKE_OSX_ARCHITECTURES=x86_64;arm64"）	''
PYARROW_CXXFLAGS	額外的 C++ 編譯器旗標	''
PYARROW_GENERATE_COVERAGE	為 Cython 編譯器將 Xlinetrace 旗標設定為 true	false
PYARROW_BUNDLE_ARROW_CPP	捆綁 Arrow C++ 函式庫	0 (OFF)
PYARROW_BUNDLE_CYTHON_CPP	捆綁 Cython 產生的 C++ 檔案	0 (OFF)
PYARROW_BUILD_VERBOSE	啟用 Makefile 建置的詳細輸出	0 (OFF)
PYARROW_PARALLEL	用於編譯 PyArrow 的 C++/Cython 組件的進程數	''

預設情況下，建置 PyArrrow 時停用或啟用的組件基於 Arrow C++ 的建置方式（即它遵循 ARROW_$COMPONENT 旗標）。但是，PYARROW_WITH_$COMPONENT 環境變數仍然可以用於在建置 PyArrow 時覆寫此設定（例如，停用組件，或強制建置某些組件）

Arrow 旗標/選項	PyArrow 的對應環境變數
ARROW_GCS	PYARROW_WITH_GCS
ARROW_S3	PYARROW_WITH_S3
ARROW_AZURE	PYARROW_WITH_AZURE
ARROW_HDFS	PYARROW_WITH_HDFS
ARROW_CUDA	PYARROW_WITH_CUDA
ARROW_SUBSTRAIT	PYARROW_WITH_SUBSTRAIT
ARROW_FLIGHT	PYARROW_WITH_FLIGHT
ARROW_ACERO	PYARROW_WITH_ACERO
ARROW_DATASET	PYARROW_WITH_DATASET
ARROW_PARQUET	PYARROW_WITH_PARQUET
PARQUET_REQUIRE_ENCRYPTION	PYARROW_WITH_PARQUET_ENCRYPTION
ARROW_ORC	PYARROW_WITH_ORC
ARROW_GANDIVA	PYARROW_WITH_GANDIVA

刪除過時的建置產物

當 Arrow C++ 函式庫或 PyArrow 的結構發生變更時，建議徹底清除作為修復建置錯誤的第一步嘗試。

注意

從錯誤本身不一定能直覺地判斷問題是由於過時的產物造成的。過時產物的建置錯誤範例是「Unknown CMake command “arrow_keep_backward_compatibility”」。

要刪除過時的 Arrow C++ 建置產物

$ rm -rf arrow/cpp/build

要刪除過時的 PyArrow 建置產物

$ git clean -Xfd python

如果使用 Conda 環境，則有一些建置產物會安裝在 $ARROW_HOME（又名 $CONDA_PREFIX）中。例如，$ARROW_HOME/lib/cmake/Arrow*、$ARROW_HOME/include/arrow、$ARROW_HOME/lib/libarrow* 等。

這些檔案可以手動刪除。如果不確定要刪除哪些檔案，一種方法是重新建立 Conda 環境。

可以刪除目前的環境，然後重新開始

$ conda deactivate
$ conda remove -n pyarrow-dev

或者，破壞性較小的方式是建立一個名稱不同的不同環境。

安裝每夜建置套件

警告

這些套件不是官方發布版本。使用風險自負。

PyArrow 具有用於測試目的的每夜建置 wheel 和 Conda 套件。

這些可能適用於其持續整合設定中的下游函式庫，以保持與即將推出的 PyArrow 功能、棄用和/或功能移除的相容性。

從 arrow-nightlies conda 頻道安裝 PyArrow 的開發版本

conda install -c arrow-nightlies pyarrow

請注意，這需要為所有其他套件使用 conda-forge 頻道（conda config --add channels conda-forge）。

從 替代 PyPI 索引安裝開發版本

pip install --extra-index-url https://pypi.fury.io/arrow-nightlies/ \
    --prefer-binary --pre pyarrow