高级调试工具#

如果你来到了这里，你想要深入了解或使用更高级的工具。对于首次贡献者和大多数日常开发而言，这通常是不必要的。这些工具在更罕见的情况下使用，例如在 NumPy 新版本发布之前，或当进行了大型或特别复杂的更改时。

由于并非所有这些工具都在常规基础上使用，而且只在某些系统上可用，因此请预期存在差异、问题或怪癖；如果您遇到困难，我们会很乐意提供帮助，并感谢您对这些工作流程的任何改进或建议。

使用其他工具查找 C 错误#

大多数开发不需要超过 调试 中所示的典型调试工具链。但例如内存泄漏可能特别难以察觉或难以缩小范围。

我们不希望大多数贡献者运行这些工具中的任何一个。但是，你可以确保我们能够更容易地追踪到这些问题。

  • 测试应该涵盖所有代码路径，包括错误路径。

  • 尝试编写简短且简单的测试。如果你的测试非常复杂，请考虑再创建一个更简单的测试。这可能会有所帮助，因为通常只容易找到哪个测试触发了问题，而不是测试中的哪一行。

  • 如果要读取/使用数据，切勿使用 np.empty。 valgrind 会注意到这一点并报告错误。如果你不关心值，你可以生成随机值来代替。

这将帮助我们在发布你的更改之前捕获任何疏忽，这意味着你不必担心出现引用计数错误，这可能会让人望而生畏。

Python 调试构建#

Python 调试构建很容易获得，例如通过 Linux 系统上的系统包管理器，但也可以在其他平台上获得，可能格式不太方便。如果不能从系统包管理器轻松安装 Python 调试构建，你可以使用 pyenv 自己构建一个。例如，要安装并全局激活 Python 3.10.8 的调试构建，你可以执行以下操作：

pyenv install -g 3.10.8
pyenv global 3.10.8

请注意，pyenv install 会从源代码构建 Python，因此你必须确保在构建之前安装 Python 的依赖项，请参阅 pyenv 文档以获取特定于平台的安装说明。你可以使用 pip 安装调试会话所需的 Python 依赖项。如果 pypi 上没有可用的调试轮子，你需要从源代码构建依赖项并确保你的依赖项也作为调试构建进行编译。

通常，Python 调试构建会将 Python 可执行文件命名为 pythond 而不是 python。要检查是否已安装 Python 调试构建，可以运行例如 pythond -m sysconfig 以获取 Python 可执行文件的构建配置。调试构建将在 CFLAGS 中使用调试编译器选项（例如 -g -Og）进行构建。

运行 Numpy 测试或交互式终端通常与以下操作一样简单：

python3.8d runtests.py
# or
python3.8d runtests.py --ipython

并且已经在 调试 中提及过。

Python 调试构建将有助于

  • 查找可能导致随机行为的错误。一个例子是在对象被删除后仍然使用它。

  • Python 调试构建允许检查正确的引用计数。这使用以下附加命令工作：

    sys.gettotalrefcount()
sys.getallocatedblocks()

  • Python 调试构建允许使用 gdb 和其他 C 调试器更容易地进行调试。

与 pytest 结合使用#

仅使用调试版本的 Python 运行测试套件本身不会找到太多错误。Python 调试构建的另一个优点是它允许检测内存泄漏。

一个简化此过程的工具是 pytest-leaks，它可以使用 pip 安装。不幸的是，pytest 本身可能会泄漏内存，但通常（目前）可以通过删除以下内容来获得良好的结果：

@pytest.fixture(autouse=True)
def add_np(doctest_namespace):
    doctest_namespace['np'] = numpy

@pytest.fixture(autouse=True)
def env_setup(monkeypatch):
    monkeypatch.setenv('PYTHONHASHSEED', '0')

来自 numpy/conftest.py （这可能会随着新版本的 pytest-leaks 或 pytest 更新而发生变化）。

这允许你方便地运行测试套件或其一部分：

python3.8d runtests.py -t numpy/_core/tests/test_multiarray.py -- -R2:3 -s

其中 -R2:3 是 pytest-leaks 命令（请参阅其文档），-s 会导致输出打印，并且可能是必要的（在某些版本中，捕获的输出被检测为泄漏）。

请注意，已知某些测试会泄漏引用（甚至被设计为泄漏引用），我们试图标记它们，但预期会有一些误报。

valgrind#

Valgrind 是一个功能强大的工具，用于查找某些内存访问问题，应该在复杂的 C 代码上运行。 valgrind 的基本用法通常不需要超过以下操作：

PYTHONMALLOC=malloc valgrind python runtests.py

其中 PYTHONMALLOC=malloc 是必要的，以避免来自 python 本身的误报。根据系统和 valgrind 版本，你可能会看到更多误报。 valgrind 支持“抑制”，以忽略其中的一些，Python 确实有一个抑制文件（甚至有一个编译时选项），如果发现有必要，它可能会有所帮助。

Valgrind 有助于

  • 查找未初始化的变量/内存的使用。

  • 检测内存访问冲突（在已分配内存之外读取或写入）。

  • 查找许多内存泄漏。请注意，对于大多数泄漏，python 调试构建方法（以及 pytest-leaks）要敏感得多。原因是 valgrind 只能检测内存是否确实丢失。如果

    dtype = np.dtype(np.int64)
arr.astype(dtype=dtype)

    dtype 的引用计数不正确，这是一个错误，但 valgrind 无法看到它，因为 np.dtype(np.int64) 始终返回同一个对象。但是，并非所有 dtype 都是单例，因此这可能会在不同的输入中导致内存泄漏。在极少数情况下，NumPy 会使用 malloc 而不是 Python 内存分配器，这些分配器对 Python 调试构建不可见。通常应避免使用 malloc，但有一些例外（例如，PyArray_Dims 结构是公共 API，不能使用 Python 分配器）。

即使使用 valgrind 进行内存泄漏检测速度很慢且灵敏度较低，它仍然很方便：你可以在没有任何修改的情况下使用 valgrind 运行大多数程序。

需要注意的事项

  • Valgrind 不支持 numpy longdouble，这意味着测试将失败或被标记为完全正常的错误。

  • 预期在运行 NumPy 代码之前和之后会出现一些错误。

  • 缓存可能意味着错误（尤其是内存泄漏）可能无法检测到，或者仅在以后的无关时间检测到。

Valgrind 的一大优势是它除了 valgrind 本身之外没有其他要求（尽管你可能希望使用调试构建以获得更好的跟踪信息）。

与 pytest 结合使用#

你可以使用 valgrind 运行测试套件，当你只对少数测试感兴趣时，这可能就足够了

PYTHOMMALLOC=malloc valgrind python runtests.py \
 -t numpy/_core/tests/test_multiarray.py -- --continue-on-collection-errors

请注意 --continue-on-collection-errors，这在当前情况下是必要的，因为缺少 longdouble 支持会导致失败（如果你不运行完整的测试套件，这通常是不必要的）。

如果你希望检测内存泄漏，你还需要 --show-leak-kinds=definite 以及可能更多的 valgrind 选项。就像 pytest-leaks 一样，某些测试已知会泄漏导致 valgrind 中出现错误，并且可能被标记为这样，也可能没有标记为这样。

我们开发了 pytest-valgrind，它可以

  • 分别报告每个测试的错误

  • 将内存泄漏缩小到单个测试（默认情况下，valgrind 只在程序停止后检查内存泄漏，这非常麻烦）。

请参阅其 README 以获取更多信息（它包含 NumPy 的示例命令）。

本页内容