开发 PyArrow#

编码风格#

我们遵循与 pandas 项目 类似的 PEP8 编码风格。要修复样式问题，请使用 pre-commit 命令

$ pre-commit run --show-diff-on-failure --color=always --all-files python

单元测试#

我们使用 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

并查找“自定义选项”部分。

注意

有一些直接用 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 来检查文档字符串示例是否最新且正确。您也可以通过运行以下命令在本地执行此操作

$ 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 插件。

调试#

调试构建#

由于 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 扩展。

同样，在 macOS 上调试时使用 lldb。

基准测试#

有关运行基准测试的信息，请参阅 基准测试。