C扩展测试

相关源文件

• Doc/c-api/bytearray.rst
• Doc/c-api/bytes.rst
• Doc/c-api/concrete.rst
• Doc/c-api/utilities.rst
• Lib/test/test_capi/test_bytearray.py
• Lib/test/test_capi/test_bytes.py
• Lib/test/test_capi/test_misc.py
• Lib/test/test_capi/test_sys.py
• Modules/Setup.stdlib.in
• Modules/_testcapi/bytes.c
• Modules/_testcapi/codec.c
• Modules/_testcapi/numbers.c
• Modules/_testcapi/parts.h
• Modules/_testcapi/util.h
• Modules/_testcapimodule.c
• Modules/_testinternalcapi.c
• Modules/_testlimitedcapi/codec.c
• PCbuild/_testcapi.vcxproj
• PCbuild/_testcapi.vcxproj.filters

本文档介绍了 CPython 的 C 扩展测试系统，该系统用于验证 Python C API 的正确性和稳定性。有关 Python 的通用测试框架的信息，请参阅回归测试框架。

目的和概述

C 扩展测试系统通过用 C 编写的专用测试模块，对 Python 的 C API 进行全面测试。这些模块将 Python 的 C API 函数公开给 Python 测试套件，从而能够彻底验证 Python 与 C 代码之间的接口是否正常工作。

此测试基础设施对于以下方面至关重要：

• 验证 Python C API 的行为是否符合文档说明
• 防止在修改解释器内部时出现回归
• 测试 C API 中的边缘情况和错误处理
• 确保跨 Python 版本的 ABI 兼容性

来源：Modules/_testcapi/parts.h1-70 Modules/_testcapimodule.c1-30

测试模块层级结构

Python 的 C API 测试分为三个主要模块，分别测试不同的 API 层级：

• _testcapi：测试所有扩展模块可用的公共 C API（头文件位于 Include/ 和 Include/cpython/）
• _testlimitedcapi：测试 Limited API，它确保了跨 Python 版本的二进制兼容性
• _testinternalcapi：测试 CPython 实现本身使用的内部 C API

来源：Modules/_testcapi/parts.h9-23 Modules/_testinternalcapi.c1-45 Modules/Setup.stdlib.in165-167

模块架构

C API 测试模块以模块化方式进行组织，代码按功能领域划分。

每个 C 文件通过特定于模块的初始化函数（例如 _PyTestCapi_Init_Bytes()）注册测试函数，该函数在模块初始化期间被调用。

来源：Modules/_testcapi/parts.h31-67 PCbuild/_testcapi.vcxproj95-133 Modules/_testcapi/bytes.c1-68

测试注册和执行流程

来源：Modules/_testcapimodule.c127-169 Modules/_testcapi/bytes.c54-58 Lib/test/test_capi/test_misc.py48-83

测试覆盖区域

C API 测试系统提供了对 Python C API 的全面覆盖。主要领域包括：

功能领域	主要测试文件	测试的 API 示例
对象系统	heaptype.c, abstract.c	PyObject_, PyType_
字节串和字符串	bytes.c, unicode.c	PyBytes_, PyUnicode_
合集	dict.c, list.c, tuple.c, set.c	PyDict_, PyList_, PyTuple_, PySet_
内存	mem.c, buffer.c	PyMem_*, PyObject_Malloc, Buffer Protocol
类型	long.c, float.c, complex.c	PyLong_, PyFloat_, PyComplex_*
执行	code.c, frame.c, function.c	PyEval_, PyFrame_, PyFunction_*
系统	gc.c, import.c, time.c	PyGC_, PyImport_, PyCapsule_*

来源：PCbuild/_testcapi.vcxproj96-133 Modules/_testcapi/parts.h31-67

示例：字节对象测试

字节对象测试模块（bytes.c）展示了测试 Python C API 的方法。

C 测试函数通常会：

1. 接收 Python 对象作为参数
2. 将它们转换为 C 表示
3. 调用正在测试的 C API 函数
4. 将结果转换回 Python 对象
5. 返回给 Python 进行验证

来源：Modules/_testcapi/bytes.c5-37 Lib/test/test_capi/test_bytes.py1-70

测试实用函数

测试系统提供了有助于常见测试模式的实用工具。

这些实用工具有助于确保 C 和 Python 值之间一致的错误处理和转换。

来源：Modules/_testcapi/util.h1-26

测试示例

测试 PyBytes 函数

测试 C API 函数的典型模式

来源：Lib/test/test_capi/test_bytes.py49-67

测试扩展类型行为

来源：Lib/test/test_capi/test_misc.py517-531

运行 C API 测试

要运行 C API 测试：

1. 使用测试模块构建 Python

2. 使用 Python 测试框架运行测试

来源：Modules/Setup.stdlib.in165-167 PCbuild/_testcapi.vcxproj1-151

扩展测试系统

要添加新的 C API 测试：

1. 确定适合您测试的模块（例如，字节串函数使用 bytes.c）

2. 创建测试函数来执行 C API

3. 在模块的测试方法数组中注册您的函数

4. 创建 Python 测试来调用您的 C 函数并验证结果

来源：Modules/_testcapi/bytes.c54-58 Modules/_testcapi/numbers.c127-166

测试特殊情况和错误条件

C API 测试特别强调测试错误条件，例如：

• 无效参数
• NULL 指针
• 内存分配失败
• 类型不匹配
• 无效状态

例如，测试中通常包含关于什么会导致解释器崩溃的注释。

这些注释表明了未直接测试的条件，因为它们会导致段错误，但记录它们很重要。

来源： Lib/test/test_capi/test_bytes.py33 Lib/test/test_capi/test_bytes.py250-252

结论

C 扩展测试系统是 Python 质量保证流程的关键部分，它确保 C API 保持稳定、正确且文档完善。通过为 C API 提供全面的测试覆盖，它有助于防止回归，并确保扩展模块能够依赖跨 Python 版本的一致行为。