Apache Arrow 的 Python 接口 PyArrow从安装、源码构建到测试与类型检查的完整工程指南【免费下载链接】arrowApache Arrow is the universal columnar format and multi-language toolbox for fast data interchange and in-memory analytics项目地址: https://gitcode.com/GitHub_Trending/arrow3/arrowPyArrow 是 Apache Arrow 项目提供的官方 Python 库它将 Arrow C 库的全部能力列式内存、IPC、Parquet、Dataset、Flight 等暴露给 Python并提供与 pandas、NumPy 等生态组件的互操作工具。本文以仓库中 PyArrow 官方 README 为骨架结合 构建文档、开发文档 以及 pyproject.toml 等仓库内实际文件完整讲解 PyArrow 的安装方式、从源码构建的两条路径Conda / pip、关键构建环境变量与可选组件开关以及单元测试、doctest 与类型桩type stubs体系的运作方式。读完本文你将能够独立安装 PyArrow 官方发行版并从源码完成一个可编辑editable的 PyArrow 构建与测试闭环。1. PyArrow 的定位Arrow C 之上的 Python APIpython/README.md 对 PyArrow 的定义非常明确This library provides a Python API for functionality provided by the Arrow C libraries, along with tools for Arrow integration and interoperability with pandas, NumPy, and other software in the Python ecosystem.也就是说PyArrow 本身不是独立的列式实现而是 Arrow C 的 Python 封装层。从仓库目录结构可以印证这一点python/pyarrow/ 下几乎每个功能域都由「Cython 模块.pyx/.pxd Python 模块.py C 绑定src/」三件套组成文件/目录职责python/pyarrow/lib.pyx、lib.pxd核心 Cython 层数组、表、IPC、Scalar 等基础对象python/pyarrow/_parquet.pyx、parquet/Parquet 读写封装python/pyarrow/_dataset.pyxDataset 组件封装python/pyarrow/_flight.pyx、flight.pyArrow Flight RPC 客户端/服务端python/pyarrow/_s3fs.pyx、_gcsfs.pyx、_azurefs.pyx、_hdfs.pyx各文件系统后端封装python/pyarrow/_compute.pyx、compute.py计算内核接口python/pyarrow/src/与 Arrow C 直接对接的 C 绑定源码python/pyarrow-stubs/供 mypy/pyright 使用的 PEP 561 类型桩这个结构决定了 PyArrow 的构建必然分为两步先构建并安装 Arrow C 库再在其之上编译 Cython/C 扩展——下面的源码构建章节会围绕这条主线展开。2. 安装conda 与 pip 两条官方路径python/README.md 给出了两个平台覆盖的安装命令。跨平台condaconda install pyarrow -c conda-forgeLinux / macOS / Windowspip 二进制 wheelpip install pyarrowREADME 中还特别提示了一个 Windows 上的常见坑如果在 Windows 上导入 pip 安装的 wheel 时遇到问题可能需要安装最新的 Visual C Redistributable for Visual Studio——这是因为 wheel 中的 C 扩展依赖该运行时库。2.1 Nightly 预发布包除正式发行版外构建文档 还说明 PyArrow 提供 nightly 轮子托管于 scientific-python-nightly-wheels供下游库在 CI 中提前验证即将发布的新特性、弃用与移除项。安装方式为pip install \ -i https://pypi.anaconda.org/scientific-python-nightly-wheels/simple \ pyarrow文档同时明确警告nightly 包不是官方发行版使用需自行承担风险。3. 版本要求与构建系统3.1 当前构建基线从 pyproject.toml 可以确认 PyArrow 当前的构建基线Python 版本requires-python 3.11classifiers 覆盖 Python 3.11 ~ 3.15并标注了 Free-Threading实验性无 GIL 构建支持构建后端scikit-build-core 1.0 CMake Cython 3.1即 PyArrow 已经是一套CMake 驱动的 PEP 517 构建依赖构建期需要numpy2.0、setuptools_scm[toml]8版本从 git tagapache-arrow-*推导见 pyproject.toml。构建文档 中有一个重要的历史事实自PyArrow 24.0.0起构建后端从 setuptools 迁移到了 scikit-build-core。旧版本使用的PYARROW_BUILD_TYPE和PYARROW_CMAKE_OPTIONS环境变量不再受支持取而代之的是pip install/python -m build的-C参数语法# 设置构建类型 pip install --no-build-isolation -vv -C cmake.build-typeDebug . # 追加任意 CMake 定义 pip install --no-build-isolation -vv -C cmake.args-DARROW_SIMD_LEVELNONE . # 打开构建工具的详细输出 pip install --no-build-isolation -C build.verbosetrue .3.2 关键构建环境变量pyproject.toml 中的[tool.scikit-build.cmake.define]与构建文档的表格共同列出了可用环境变量环境变量作用默认值CMAKE_BUILD_PARALLEL_LEVEL编译 PyArrow C/Cython 组件的并行进程数空CMAKE_GENERATORCMake 生成器如Visual Studio 17 2022 Win64空PYARROW_CXXFLAGS附加 C 编译标志空PYARROW_GENERATE_COVERAGE为 Cython 编译器设置linetrace用于覆盖率falsePYARROW_BUNDLE_ARROW_CPP是否将 Arrow C 库打包进 pyarrowOFFPYARROW_BUNDLE_CYTHON_CPP是否打包 Cython 生成的 C 文件OFF其中PYARROW_BUNDLE_ARROW_CPP决定了构建形态默认开发模式下 wheel 不内置 Arrow C 库要求系统/conda 环境中已存在而制作要分发到 PyPI 的自包含 wheel 时必须置为ON文档给出的分发场景命令为export PYARROW_BUNDLE_ARROW_CPPON pip install build wheel # 若未安装 python -m build --sdist --wheel . --no-isolation文档同时提醒bundled 的 Arrow C 库在后续单独重建 C 库时不会自动更新。另外pyproject.toml 中有一条值得注意的构建细节由于类型桩尚未完全覆盖所有 API关联 issue 为 GH-49831wheel 会主动排除pyarrow/py.typed即 PEP 561 标记暂时不下发到安装产物中以免静态检查器依赖不完整桩而导致下游报错仓库内的 pyarrow/py.typed 仍保留用于 CI 类型检查。4. 从源码构建 PyArrow 的完整流程以下是 构建文档 中完整流程的继承与整理适用于 Linux 与 macOSWindows 仅 conda 路径有文档覆盖。4.1 系统要求Linux至少 gcc/clang 9可用gcc --version检查旧系统可用CC/CXX环境变量切换到新版编译器如export CCgcc-9。macOS任一现代 Xcode 或 Command Line Toolsxcode-select --install即可。WindowsBuild Tools for Visual Studio 2022 或 Visual Studio 2022安装时确保至少选中一个 Windows SDK。4.2 准备测试数据与环境无论走 conda 还是 pip 路径都需要先拉取子模块中的测试数据git submodule update --init export PARQUET_TEST_DATA${PWD}/cpp/submodules/parquet-testing/data export ARROW_TEST_DATA${PWD}/testing/data4.3 路径一Conda 管理依赖推荐利用 ci/conda_env_*.txt 环境清单一次性装齐 C 构建与 Python 依赖以 Python 3.13 为例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 \ python3.13 \ pandas conda activate pyarrow-dev export ARROW_HOME$CONDA_PREFIXWindows 上对应set ARROW_HOME%CONDA_PREFIX%\Library。conda 的优势在于 Arrow C 的构建期依赖均以预编译二进制提供能显著缩短首次构建时间。4.4 路径二pip 系统/venv 管理依赖注意文档中的警告如果 Python 来自 Anaconda/Miniconda 发行版则无法使用 pip 虚拟环境路径必须走 conda 方案。pip 路径的关键步骤# macOS用 Homebrew 装齐 C 依赖 brew update brew bundle --filearrow/cpp/Brewfile # Debian/Ubuntu最小依赖集 sudo apt-get install build-essential ninja-build cmake python3-dev # 创建 venv 并安装构建依赖 python3 -m venv pyarrow-dev source ./pyarrow-dev/bin/activate pip install -r arrow/python/requirements-build.txt mkdir dist # 告知构建系统工具链位置 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 的构建链仍可尝试在线下载并即时编译但耗时更长Linux 上 CMake 太旧时可用pip install cmake补齐。4.5 第一步构建并安装 Arrow CPyArrow 依赖 Arrow C 先就位。Linux/macOS 下文档推荐使用 CMake presetpreset 定义见 cpp/CMakePresets.jsoncmake -S arrow/cpp -B arrow/cpp/build \ -DCMAKE_INSTALL_PREFIX$ARROW_HOME \ --preset ninja-release-python cmake --build arrow/cpp/build --target install关于 preset 的选择逻辑ninja-release-python是面向 Python 开发的默认预设需要 CUDA、Flight、Gandiva 等更多特性时可用ninja-release-python-maximal想裁剪 ORC、Dataset 等组件时用ninja-release-python-minimal将release换成debug即得到调试构建。仓库 preset 文件中确实定义了features-python-minimal、features-python、features-python-maximal等特性集与文档描述一一对应。也可以不用 preset手动指定组件文档给出的完整示例cmake -S arrow/cpp -B arrow/cpp/build \ -DCMAKE_INSTALL_PREFIX$ARROW_HOME \ -DCMAKE_BUILD_TYPEDebug \ -DARROW_BUILD_TESTSON \ -DARROW_COMPUTEON \ -DARROW_CSVON \ -DARROW_DATASETON \ -DARROW_FILESYSTEMON \ -DARROW_HDFSON \ -DARROW_JSONON \ -DARROW_PARQUETON \ -DARROW_WITH_BROTLION \ -DARROW_WITH_BZ2ON \ -DARROW_WITH_LZ4ON \ -DARROW_WITH_SNAPPYON \ -DARROW_WITH_ZLIBON \ -DARROW_WITH_ZSTDON \ -DPARQUET_REQUIRE_ENCRYPTIONON cmake --build arrow/cpp/build --target install -j4文档附带了两条 Linux 上的实用建议多架构 Linux 上make可能默认装到lib64建议追加-DCMAKE_INSTALL_LIBDIRlib因为 Python 构建脚本假定库目录是lib环境里装了 conda 但不打算用它管理依赖时可能需要显式传-DARROW_DEPENDENCY_SOURCEAUTO以免 CMake 误走 conda 路径多 Python 版本共存时可用-DPython3_EXECUTABLEpath/to/bin/python指定正确的解释器。4.6 第二步构建 PyArroweditable 安装pushd arrow/python pip install --no-build-isolation --editable . -vv popd这里有三个要点值得展开editable 安装修改 Python 源码后无需重装即可生效适合日常开发--no-build-isolation强制使用当前环境的依赖scikit-build-core、Cython、CMake 等而非 pip 临时隔离环境否则 conda 环境里的 C 依赖无法被构建链看到默认 Release即便 Arrow C 是 debug 构建PyArrow 默认仍是 release 构建要 debug 版 PyArrow 需追加-C cmake.build-typeDebugRelWithDebInfo同理。Windows 补充事项若用 Conda 且 Python ≤ 3.9需设置CONDA_DLL_SEARCH_MODIFICATION_ENABLE1非 conda 用户要么每次import pyarrow前把 C DLL 目录加入PATH要么用PYARROW_BUNDLE_ARROW_CPPON打包。4.7 可选组件开关PYARROW_WITH_*构建文档 给出了完整的组件映射表PyArrow 组件默认跟随 Arrow C 的ARROW_$COMPONENT开关但可用PYARROW_WITH_$COMPONENT环境变量取 0/1覆盖Arrow C 开关对应 PyArrow 环境变量ARROW_GCSPYARROW_WITH_GCSARROW_S3PYARROW_WITH_S3ARROW_AZUREPYARROW_WITH_AZUREARROW_HDFSPYARROW_WITH_HDFSARROW_CUDAPYARROW_WITH_CUDAARROW_SUBSTRAITPYARROW_WITH_SUBSTRAITARROW_FLIGHTPYARROW_WITH_FLIGHTARROW_ACEROPYARROW_WITH_ACEROARROW_DATASETPYARROW_WITH_DATASETARROW_PARQUETPYARROW_WITH_PARQUETPARQUET_REQUIRE_ENCRYPTIONPYARROW_WITH_PARQUET_ENCRYPTIONARROW_ORCPYARROW_WITH_ORCARROW_GANDIVAPYARROW_WITH_GANDIVA自 24.0.0 起弃用这与 python/pyarrow/ 下按组件拆分的 Cython 模块_s3fs.pyx、_flight.pyx、_acero.pyx等互相印证组件在 C 层未启用时对应的 Python 子模块也就不可用。4.8 清理陈旧构建产物C 库结构或 PyArrow 结构变化后陈旧产物是构建报错的首要嫌疑典型症状如Unknown CMake command arrow_keep_backward_compatibility。文档给出的清理命令rm -rf arrow/cpp/build # 清理 Arrow C 构建目录 git clean -Xfd python # 清理 PyArrow 构建产物使用 Conda 时$ARROW_HOME即$CONDA_PREFIX下也会有$ARROW_HOME/lib/cmake/Arrow*、$ARROW_HOME/include/arrow、libarrow*等产物可手动删除不确定删哪些时最稳妥的做法是删掉重建环境conda remove -n pyarrow-dev或新建一个同名环境。4.9 构建困难时的 Docker 参考文档建议遇到构建困难时参考 python/examples/minimal_build 目录——该目录在仓库中真实存在包含 Dockerfile.ubuntu、Dockerfile.fedora、build_conda.sh、build_venv.sh 与 compose.yaml分别演示了 conda 与 pip 两条完整「从源码构建 测试」的路径。5. 测试体系pytest、测试组与 doctest开发文档 是 PyArrow 测试规范的权威来源构建完成后按如下方式运行测试pushd arrow/python python -m pytest pyarrow popd测试依赖定义在 python/requirements-test.txtpytest、hypothesis、cffi、pytz、pandas 等需要时pip install -r requirements-test.txt安装。若出现pyarrow._lib等模块的 import 错误说明 editable 安装没有正确生效可改用python -m pytest arrow/python/pyarrow定位。全局 pytest 配置见 python/setup.cfgaddopts --ignorescripts并对个别 DeprecationWarning 做了忽略/升级为错误的处理faulthandler_timeout 300用于在单个测试卡死 300 秒时输出调试堆栈。5.1 测试组Test Groups大量测试通过 pytest marks 分组部分组默认禁用。控制语法统一为--$GROUP_NAME启用如--parquet--disable-$GROUP_NAME禁用如--disable-parquet--only-$GROUP_NAME仅运行该组如--only-parquet全部选项可用python -m pytest pyarrow --help的 custom options 一节查看。当前定义的测试组包括dataset、flight、gandivaLLVM 表达式编译器自 24.0.0 起弃用、hdfs、hypothesis注意由于 pytest 的一个怪癖需写成--enable-hypothesis、large_memory、orc、parquet、s3、tensorflow。5.2 C 底层测试的 pytest 桥接开发文档特别说明存在少量直接用 C 编写的底层测试其 C 实现位于pyarrow/src/的 python_test.cc同时被包装进一个 pytest 测试模块 python/pyarrow/tests/test_cpp_internals.py自动纳入 PyArrow 测试套件运行。这解释了为什么 python/pyarrow/ 下会有_pyarrow_cpp_tests.pyx这样的绑定模块——C 单元测试通过 Cython 桥接到 Python 测试框架。5.3 doctest让文档字符串保持可运行PyArrow 用 doctest 校验 docstring 示例的时效性三类入口# .py 文件 python -m pytest --doctest-modules python -m pytest --doctest-modules path/to/module.py # .pyx / .pxi 文件需安装 pytest-cython 插件 python -m pytest --doctest-cython python -m pytest --doctest-cython path/to/lib.pyx # 文档中的 .rst 示例 pytest --doctest-glob*.rst docs/source/python/file.rst pytest --doctest-glob*.rst docs/source/python两个实现细节值得注意Cython 的.pxi文件在编译期被包含进.pyx所以--doctest-cython无法直接跑.pxi文件在 PyArrow 中所有.pxi最终包含进 lib.pyx跑lib.pyx即可覆盖错误会挂在lib.pyx名下而非原.pxi文件名。文档示例则使用标准 doctest 语法提示符、...续行python/pyarrow/conftest.py 提供的 fixture 会自动处理示例中创建文件所需的临时目录。5.4 调试跨 Python/C 断点由于 PyArrow 依赖 Arrow C调试经常跨越 Python 与 C 共享库。文档建议两边都用 Debug 构建C 用-DCMAKE_BUILD_TYPEDebugPyArrow 用pip install --no-build-isolation -C cmake.build-typeDebug .然后在 Linux 上gdb --args python -m pytest pyarrow/tests/test_to_run.py -k $TEST_TO_MATCH (gdb) b src/arrow/python/arrow_to_pandas.cc:1874macOS 上同理使用 lldb并可参考仓库内的 GDB 扩展见 cpp/gdb_arrow.py。6. 类型桩Type Stubs与静态类型检查开发文档 的 Type Checking 章节描述了 PyArrow 的类型支持体系类型桩*.pyi维护在 python/pyarrow-stubs/ 目录镜像主包 pyarrow/ 的结构对 Cython 模块或动态生成的 API如 compute 内核需在对应桩文件中补齐签名构建流程会把桩文件自动拷贝进 wheelpyproject.toml 的sdist.include中列有pyarrow-stubs/使下游项目和 IDE 可做类型检查但如前文 3.2 节所述py.typed标记在桩完整前被有意从 wheel 中排除支持三类检查器配置均在 pyproject.tomlcd arrow/python mypy # 配置见 [tool.mypy]files [pyarrow-stubs] pyright # 配置见 [tool.pyright]typeCheckingMode basic ty check # 配置见 [tool.ty.*]目前仅部分配置完成从配置看三类检查器的 include 范围都被限定在pyarrow-stubs并统一排除pyarrow、benchmarks、examples、scripts——可以推断当前阶段类型检查主要针对桩文件本身的正确性与完整性而非整个运行时包。7. 编码规范与快速参考编码风格遵循类似 pandas 项目的 PEP8 风格setup.cfg 中 max_line_length 为 88用pre-commit run --show-diff-on-failure --coloralways --all-files python自动修复文档构建见 docs/source/developers/documentation.rst基准测试development.rst 指向 benchmarks 章节基准脚本位于 python/benchmarks/。8. 关键路径速查用途路径PyArrow 官方 README安装入口python/README.md构建系统配置scikit-build-corepython/pyproject.tomlpytest 全局配置python/setup.cfg测试依赖清单python/requirements-test.txt构建文档源码构建全流程docs/source/developers/python/building.rst开发文档测试/类型检查/doctestdocs/source/developers/python/development.rstPython 包源码Cython C 绑定python/pyarrow/类型桩python/pyarrow-stubs/最小化构建 Docker 示例python/examples/minimal_build/CMake preset 定义cpp/CMakePresets.jsonconda 环境清单ci/conda_env_cpp.txt、ci/conda_env_python.txt总结PyArrow 工程上由「Arrow C 构建 → scikit-build-core 驱动的 pip editable 构建 → pytest 测试组 doctest 验证」三段式闭环构成。理解PYARROW_BUNDLE_ARROW_CPP、PYARROW_WITH_*组件开关与-C cmake.*参数这三组控制点就掌握了从源码定制构建 PyArrow 的全部关键自由度而 python/examples/minimal_build 与两套开发者文档则提供了可随时对照的权威参考。【免费下载链接】arrowApache Arrow is the universal columnar format and multi-language toolbox for fast data interchange and in-memory analytics项目地址: https://gitcode.com/GitHub_Trending/arrow3/arrow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Apache Arrow 的 Python 接口 PyArrow：从安装、源码构建到测试与类型检查的完整工程指南
Apache Arrow 的 Python 接口 PyArrow从安装、源码构建到测试与类型检查的完整工程指南【免费下载链接】arrowApache Arrow is the universal columnar format and multi-language toolbox for fast data interchange and in-memory analytics项目地址: https://gitcode.com/GitHub_Trending/arrow3/arrowPyArrow 是 Apache Arrow 项目提供的官方 Python 库它将 Arrow C 库的全部能力列式内存、IPC、Parquet、Dataset、Flight 等暴露给 Python并提供与 pandas、NumPy 等生态组件的互操作工具。本文以仓库中 PyArrow 官方 README 为骨架结合 构建文档、开发文档 以及 pyproject.toml 等仓库内实际文件完整讲解 PyArrow 的安装方式、从源码构建的两条路径Conda / pip、关键构建环境变量与可选组件开关以及单元测试、doctest 与类型桩type stubs体系的运作方式。读完本文你将能够独立安装 PyArrow 官方发行版并从源码完成一个可编辑editable的 PyArrow 构建与测试闭环。1. PyArrow 的定位Arrow C 之上的 Python APIpython/README.md 对 PyArrow 的定义非常明确This library provides a Python API for functionality provided by the Arrow C libraries, along with tools for Arrow integration and interoperability with pandas, NumPy, and other software in the Python ecosystem.也就是说PyArrow 本身不是独立的列式实现而是 Arrow C 的 Python 封装层。从仓库目录结构可以印证这一点python/pyarrow/ 下几乎每个功能域都由「Cython 模块.pyx/.pxd Python 模块.py C 绑定src/」三件套组成文件/目录职责python/pyarrow/lib.pyx、lib.pxd核心 Cython 层数组、表、IPC、Scalar 等基础对象python/pyarrow/_parquet.pyx、parquet/Parquet 读写封装python/pyarrow/_dataset.pyxDataset 组件封装python/pyarrow/_flight.pyx、flight.pyArrow Flight RPC 客户端/服务端python/pyarrow/_s3fs.pyx、_gcsfs.pyx、_azurefs.pyx、_hdfs.pyx各文件系统后端封装python/pyarrow/_compute.pyx、compute.py计算内核接口python/pyarrow/src/与 Arrow C 直接对接的 C 绑定源码python/pyarrow-stubs/供 mypy/pyright 使用的 PEP 561 类型桩这个结构决定了 PyArrow 的构建必然分为两步先构建并安装 Arrow C 库再在其之上编译 Cython/C 扩展——下面的源码构建章节会围绕这条主线展开。2. 安装conda 与 pip 两条官方路径python/README.md 给出了两个平台覆盖的安装命令。跨平台condaconda install pyarrow -c conda-forgeLinux / macOS / Windowspip 二进制 wheelpip install pyarrowREADME 中还特别提示了一个 Windows 上的常见坑如果在 Windows 上导入 pip 安装的 wheel 时遇到问题可能需要安装最新的 Visual C Redistributable for Visual Studio——这是因为 wheel 中的 C 扩展依赖该运行时库。2.1 Nightly 预发布包除正式发行版外构建文档 还说明 PyArrow 提供 nightly 轮子托管于 scientific-python-nightly-wheels供下游库在 CI 中提前验证即将发布的新特性、弃用与移除项。安装方式为pip install \ -i https://pypi.anaconda.org/scientific-python-nightly-wheels/simple \ pyarrow文档同时明确警告nightly 包不是官方发行版使用需自行承担风险。3. 版本要求与构建系统3.1 当前构建基线从 pyproject.toml 可以确认 PyArrow 当前的构建基线Python 版本requires-python 3.11classifiers 覆盖 Python 3.11 ~ 3.15并标注了 Free-Threading实验性无 GIL 构建支持构建后端scikit-build-core 1.0 CMake Cython 3.1即 PyArrow 已经是一套CMake 驱动的 PEP 517 构建依赖构建期需要numpy2.0、setuptools_scm[toml]8版本从 git tagapache-arrow-*推导见 pyproject.toml。构建文档 中有一个重要的历史事实自PyArrow 24.0.0起构建后端从 setuptools 迁移到了 scikit-build-core。旧版本使用的PYARROW_BUILD_TYPE和PYARROW_CMAKE_OPTIONS环境变量不再受支持取而代之的是pip install/python -m build的-C参数语法# 设置构建类型 pip install --no-build-isolation -vv -C cmake.build-typeDebug . # 追加任意 CMake 定义 pip install --no-build-isolation -vv -C cmake.args-DARROW_SIMD_LEVELNONE . # 打开构建工具的详细输出 pip install --no-build-isolation -C build.verbosetrue .3.2 关键构建环境变量pyproject.toml 中的[tool.scikit-build.cmake.define]与构建文档的表格共同列出了可用环境变量环境变量作用默认值CMAKE_BUILD_PARALLEL_LEVEL编译 PyArrow C/Cython 组件的并行进程数空CMAKE_GENERATORCMake 生成器如Visual Studio 17 2022 Win64空PYARROW_CXXFLAGS附加 C 编译标志空PYARROW_GENERATE_COVERAGE为 Cython 编译器设置linetrace用于覆盖率falsePYARROW_BUNDLE_ARROW_CPP是否将 Arrow C 库打包进 pyarrowOFFPYARROW_BUNDLE_CYTHON_CPP是否打包 Cython 生成的 C 文件OFF其中PYARROW_BUNDLE_ARROW_CPP决定了构建形态默认开发模式下 wheel 不内置 Arrow C 库要求系统/conda 环境中已存在而制作要分发到 PyPI 的自包含 wheel 时必须置为ON文档给出的分发场景命令为export PYARROW_BUNDLE_ARROW_CPPON pip install build wheel # 若未安装 python -m build --sdist --wheel . --no-isolation文档同时提醒bundled 的 Arrow C 库在后续单独重建 C 库时不会自动更新。另外pyproject.toml 中有一条值得注意的构建细节由于类型桩尚未完全覆盖所有 API关联 issue 为 GH-49831wheel 会主动排除pyarrow/py.typed即 PEP 561 标记暂时不下发到安装产物中以免静态检查器依赖不完整桩而导致下游报错仓库内的 pyarrow/py.typed 仍保留用于 CI 类型检查。4. 从源码构建 PyArrow 的完整流程以下是 构建文档 中完整流程的继承与整理适用于 Linux 与 macOSWindows 仅 conda 路径有文档覆盖。4.1 系统要求Linux至少 gcc/clang 9可用gcc --version检查旧系统可用CC/CXX环境变量切换到新版编译器如export CCgcc-9。macOS任一现代 Xcode 或 Command Line Toolsxcode-select --install即可。WindowsBuild Tools for Visual Studio 2022 或 Visual Studio 2022安装时确保至少选中一个 Windows SDK。4.2 准备测试数据与环境无论走 conda 还是 pip 路径都需要先拉取子模块中的测试数据git submodule update --init export PARQUET_TEST_DATA${PWD}/cpp/submodules/parquet-testing/data export ARROW_TEST_DATA${PWD}/testing/data4.3 路径一Conda 管理依赖推荐利用 ci/conda_env_*.txt 环境清单一次性装齐 C 构建与 Python 依赖以 Python 3.13 为例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 \ python3.13 \ pandas conda activate pyarrow-dev export ARROW_HOME$CONDA_PREFIXWindows 上对应set ARROW_HOME%CONDA_PREFIX%\Library。conda 的优势在于 Arrow C 的构建期依赖均以预编译二进制提供能显著缩短首次构建时间。4.4 路径二pip 系统/venv 管理依赖注意文档中的警告如果 Python 来自 Anaconda/Miniconda 发行版则无法使用 pip 虚拟环境路径必须走 conda 方案。pip 路径的关键步骤# macOS用 Homebrew 装齐 C 依赖 brew update brew bundle --filearrow/cpp/Brewfile # Debian/Ubuntu最小依赖集 sudo apt-get install build-essential ninja-build cmake python3-dev # 创建 venv 并安装构建依赖 python3 -m venv pyarrow-dev source ./pyarrow-dev/bin/activate pip install -r arrow/python/requirements-build.txt mkdir dist # 告知构建系统工具链位置 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 的构建链仍可尝试在线下载并即时编译但耗时更长Linux 上 CMake 太旧时可用pip install cmake补齐。4.5 第一步构建并安装 Arrow CPyArrow 依赖 Arrow C 先就位。Linux/macOS 下文档推荐使用 CMake presetpreset 定义见 cpp/CMakePresets.jsoncmake -S arrow/cpp -B arrow/cpp/build \ -DCMAKE_INSTALL_PREFIX$ARROW_HOME \ --preset ninja-release-python cmake --build arrow/cpp/build --target install关于 preset 的选择逻辑ninja-release-python是面向 Python 开发的默认预设需要 CUDA、Flight、Gandiva 等更多特性时可用ninja-release-python-maximal想裁剪 ORC、Dataset 等组件时用ninja-release-python-minimal将release换成debug即得到调试构建。仓库 preset 文件中确实定义了features-python-minimal、features-python、features-python-maximal等特性集与文档描述一一对应。也可以不用 preset手动指定组件文档给出的完整示例cmake -S arrow/cpp -B arrow/cpp/build \ -DCMAKE_INSTALL_PREFIX$ARROW_HOME \ -DCMAKE_BUILD_TYPEDebug \ -DARROW_BUILD_TESTSON \ -DARROW_COMPUTEON \ -DARROW_CSVON \ -DARROW_DATASETON \ -DARROW_FILESYSTEMON \ -DARROW_HDFSON \ -DARROW_JSONON \ -DARROW_PARQUETON \ -DARROW_WITH_BROTLION \ -DARROW_WITH_BZ2ON \ -DARROW_WITH_LZ4ON \ -DARROW_WITH_SNAPPYON \ -DARROW_WITH_ZLIBON \ -DARROW_WITH_ZSTDON \ -DPARQUET_REQUIRE_ENCRYPTIONON cmake --build arrow/cpp/build --target install -j4文档附带了两条 Linux 上的实用建议多架构 Linux 上make可能默认装到lib64建议追加-DCMAKE_INSTALL_LIBDIRlib因为 Python 构建脚本假定库目录是lib环境里装了 conda 但不打算用它管理依赖时可能需要显式传-DARROW_DEPENDENCY_SOURCEAUTO以免 CMake 误走 conda 路径多 Python 版本共存时可用-DPython3_EXECUTABLEpath/to/bin/python指定正确的解释器。4.6 第二步构建 PyArroweditable 安装pushd arrow/python pip install --no-build-isolation --editable . -vv popd这里有三个要点值得展开editable 安装修改 Python 源码后无需重装即可生效适合日常开发--no-build-isolation强制使用当前环境的依赖scikit-build-core、Cython、CMake 等而非 pip 临时隔离环境否则 conda 环境里的 C 依赖无法被构建链看到默认 Release即便 Arrow C 是 debug 构建PyArrow 默认仍是 release 构建要 debug 版 PyArrow 需追加-C cmake.build-typeDebugRelWithDebInfo同理。Windows 补充事项若用 Conda 且 Python ≤ 3.9需设置CONDA_DLL_SEARCH_MODIFICATION_ENABLE1非 conda 用户要么每次import pyarrow前把 C DLL 目录加入PATH要么用PYARROW_BUNDLE_ARROW_CPPON打包。4.7 可选组件开关PYARROW_WITH_*构建文档 给出了完整的组件映射表PyArrow 组件默认跟随 Arrow C 的ARROW_$COMPONENT开关但可用PYARROW_WITH_$COMPONENT环境变量取 0/1覆盖Arrow C 开关对应 PyArrow 环境变量ARROW_GCSPYARROW_WITH_GCSARROW_S3PYARROW_WITH_S3ARROW_AZUREPYARROW_WITH_AZUREARROW_HDFSPYARROW_WITH_HDFSARROW_CUDAPYARROW_WITH_CUDAARROW_SUBSTRAITPYARROW_WITH_SUBSTRAITARROW_FLIGHTPYARROW_WITH_FLIGHTARROW_ACEROPYARROW_WITH_ACEROARROW_DATASETPYARROW_WITH_DATASETARROW_PARQUETPYARROW_WITH_PARQUETPARQUET_REQUIRE_ENCRYPTIONPYARROW_WITH_PARQUET_ENCRYPTIONARROW_ORCPYARROW_WITH_ORCARROW_GANDIVAPYARROW_WITH_GANDIVA自 24.0.0 起弃用这与 python/pyarrow/ 下按组件拆分的 Cython 模块_s3fs.pyx、_flight.pyx、_acero.pyx等互相印证组件在 C 层未启用时对应的 Python 子模块也就不可用。4.8 清理陈旧构建产物C 库结构或 PyArrow 结构变化后陈旧产物是构建报错的首要嫌疑典型症状如Unknown CMake command arrow_keep_backward_compatibility。文档给出的清理命令rm -rf arrow/cpp/build # 清理 Arrow C 构建目录 git clean -Xfd python # 清理 PyArrow 构建产物使用 Conda 时$ARROW_HOME即$CONDA_PREFIX下也会有$ARROW_HOME/lib/cmake/Arrow*、$ARROW_HOME/include/arrow、libarrow*等产物可手动删除不确定删哪些时最稳妥的做法是删掉重建环境conda remove -n pyarrow-dev或新建一个同名环境。4.9 构建困难时的 Docker 参考文档建议遇到构建困难时参考 python/examples/minimal_build 目录——该目录在仓库中真实存在包含 Dockerfile.ubuntu、Dockerfile.fedora、build_conda.sh、build_venv.sh 与 compose.yaml分别演示了 conda 与 pip 两条完整「从源码构建 测试」的路径。5. 测试体系pytest、测试组与 doctest开发文档 是 PyArrow 测试规范的权威来源构建完成后按如下方式运行测试pushd arrow/python python -m pytest pyarrow popd测试依赖定义在 python/requirements-test.txtpytest、hypothesis、cffi、pytz、pandas 等需要时pip install -r requirements-test.txt安装。若出现pyarrow._lib等模块的 import 错误说明 editable 安装没有正确生效可改用python -m pytest arrow/python/pyarrow定位。全局 pytest 配置见 python/setup.cfgaddopts --ignorescripts并对个别 DeprecationWarning 做了忽略/升级为错误的处理faulthandler_timeout 300用于在单个测试卡死 300 秒时输出调试堆栈。5.1 测试组Test Groups大量测试通过 pytest marks 分组部分组默认禁用。控制语法统一为--$GROUP_NAME启用如--parquet--disable-$GROUP_NAME禁用如--disable-parquet--only-$GROUP_NAME仅运行该组如--only-parquet全部选项可用python -m pytest pyarrow --help的 custom options 一节查看。当前定义的测试组包括dataset、flight、gandivaLLVM 表达式编译器自 24.0.0 起弃用、hdfs、hypothesis注意由于 pytest 的一个怪癖需写成--enable-hypothesis、large_memory、orc、parquet、s3、tensorflow。5.2 C 底层测试的 pytest 桥接开发文档特别说明存在少量直接用 C 编写的底层测试其 C 实现位于pyarrow/src/的 python_test.cc同时被包装进一个 pytest 测试模块 python/pyarrow/tests/test_cpp_internals.py自动纳入 PyArrow 测试套件运行。这解释了为什么 python/pyarrow/ 下会有_pyarrow_cpp_tests.pyx这样的绑定模块——C 单元测试通过 Cython 桥接到 Python 测试框架。5.3 doctest让文档字符串保持可运行PyArrow 用 doctest 校验 docstring 示例的时效性三类入口# .py 文件 python -m pytest --doctest-modules python -m pytest --doctest-modules path/to/module.py # .pyx / .pxi 文件需安装 pytest-cython 插件 python -m pytest --doctest-cython python -m pytest --doctest-cython path/to/lib.pyx # 文档中的 .rst 示例 pytest --doctest-glob*.rst docs/source/python/file.rst pytest --doctest-glob*.rst docs/source/python两个实现细节值得注意Cython 的.pxi文件在编译期被包含进.pyx所以--doctest-cython无法直接跑.pxi文件在 PyArrow 中所有.pxi最终包含进 lib.pyx跑lib.pyx即可覆盖错误会挂在lib.pyx名下而非原.pxi文件名。文档示例则使用标准 doctest 语法提示符、...续行python/pyarrow/conftest.py 提供的 fixture 会自动处理示例中创建文件所需的临时目录。5.4 调试跨 Python/C 断点由于 PyArrow 依赖 Arrow C调试经常跨越 Python 与 C 共享库。文档建议两边都用 Debug 构建C 用-DCMAKE_BUILD_TYPEDebugPyArrow 用pip install --no-build-isolation -C cmake.build-typeDebug .然后在 Linux 上gdb --args python -m pytest pyarrow/tests/test_to_run.py -k $TEST_TO_MATCH (gdb) b src/arrow/python/arrow_to_pandas.cc:1874macOS 上同理使用 lldb并可参考仓库内的 GDB 扩展见 cpp/gdb_arrow.py。6. 类型桩Type Stubs与静态类型检查开发文档 的 Type Checking 章节描述了 PyArrow 的类型支持体系类型桩*.pyi维护在 python/pyarrow-stubs/ 目录镜像主包 pyarrow/ 的结构对 Cython 模块或动态生成的 API如 compute 内核需在对应桩文件中补齐签名构建流程会把桩文件自动拷贝进 wheelpyproject.toml 的sdist.include中列有pyarrow-stubs/使下游项目和 IDE 可做类型检查但如前文 3.2 节所述py.typed标记在桩完整前被有意从 wheel 中排除支持三类检查器配置均在 pyproject.tomlcd arrow/python mypy # 配置见 [tool.mypy]files [pyarrow-stubs] pyright # 配置见 [tool.pyright]typeCheckingMode basic ty check # 配置见 [tool.ty.*]目前仅部分配置完成从配置看三类检查器的 include 范围都被限定在pyarrow-stubs并统一排除pyarrow、benchmarks、examples、scripts——可以推断当前阶段类型检查主要针对桩文件本身的正确性与完整性而非整个运行时包。7. 编码规范与快速参考编码风格遵循类似 pandas 项目的 PEP8 风格setup.cfg 中 max_line_length 为 88用pre-commit run --show-diff-on-failure --coloralways --all-files python自动修复文档构建见 docs/source/developers/documentation.rst基准测试development.rst 指向 benchmarks 章节基准脚本位于 python/benchmarks/。8. 关键路径速查用途路径PyArrow 官方 README安装入口python/README.md构建系统配置scikit-build-corepython/pyproject.tomlpytest 全局配置python/setup.cfg测试依赖清单python/requirements-test.txt构建文档源码构建全流程docs/source/developers/python/building.rst开发文档测试/类型检查/doctestdocs/source/developers/python/development.rstPython 包源码Cython C 绑定python/pyarrow/类型桩python/pyarrow-stubs/最小化构建 Docker 示例python/examples/minimal_build/CMake preset 定义cpp/CMakePresets.jsonconda 环境清单ci/conda_env_cpp.txt、ci/conda_env_python.txt总结PyArrow 工程上由「Arrow C 构建 → scikit-build-core 驱动的 pip editable 构建 → pytest 测试组 doctest 验证」三段式闭环构成。理解PYARROW_BUNDLE_ARROW_CPP、PYARROW_WITH_*组件开关与-C cmake.*参数这三组控制点就掌握了从源码定制构建 PyArrow 的全部关键自由度而 python/examples/minimal_build 与两套开发者文档则提供了可随时对照的权威参考。【免费下载链接】arrowApache Arrow is the universal columnar format and multi-language toolbox for fast data interchange and in-memory analytics项目地址: https://gitcode.com/GitHub_Trending/arrow3/arrow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考