Python 3.15 free-threaded Stable ABI 需要扩展做哪些准备

如果你维护的是 Python C/C++ 扩展，Python 3.15 的 abi3t 值得关注，但它不是把 wheel 文件名改一下就结束。它面向 free-threaded 构建，同时比原有 abi3 收紧了可用 C API；真正迁移前，要先处理线程安全、模块导出、对象布局和构建工具支持。

官方资料：

https://docs.python.org/3.15/howto/abi3t-migration.html

Python 3.15 的 abi3t 到底解决了哪一层兼容问题

abi3 解决的是普通 GIL 构建之间的 Stable ABI 兼容；cp315t 是针对某个 free-threaded CPython 版本的版本化 ABI；abi3t 则把 free-threaded 构建也纳入稳定 ABI 路线。按官方说明，设置 Python 3.15 的目标版本后，兼容双运行时的 wheel 可以使用 cp315-abi3.abi3t 这一类标签。

实际选择可以先看这张表：

先审计自由线程安全和模块初始化

迁移的第一步不是改宏，而是清点共享状态。free-threaded 版本下，直接读可能并发变化的结构体字段、使用不加锁的容器宏、长期持有借用引用，都不能再默认由 GIL 兜底。列表和字典的一些公开操作会执行内部锁，但这不等于扩展自己的复合操作天然是原子的。

模块还要明确声明自己是否支持关闭 GIL。多阶段初始化的模块可以在 slot 中加入 Py_mod_gil；旧式单阶段初始化则要按官方规则处理 PyUnstable_Module_SetGIL()，并保留构建条件。示意写法如下：

/* 只有确认模块内部不依赖 GIL 保护共享状态时才声明此项。 */
static PyModuleDef_Slot module_slots[] = {
    {Py_mod_gil, Py_MOD_GIL_NOT_USED}, /* 告诉 free-threaded 构建不要自动重启 GIL。 */
    {Py_mod_exec, module_exec},         /* 初始化状态应放在可重复执行的阶段。 */
    {0, NULL}                           /* slot 数组必须以结束项收尾。 */
};

如果模块还没有多阶段初始化或隔离状态，先把这项列为前置改造；否则导入成功也不能说明并发行为正确。

迁移时最容易卡住的两处源码改造

官方迁移指南把难点说得很具体。第一处是模块导出：面向 abi3t 时，传统的 PyInit_modname() 需要转到只返回静态 slot 数据的 PyModExport_modname()，模块定义中的状态、方法和清理函数改用新的 PySlot 描述。

第二处是自定义类型。PyObject 和 PyVarObject 在 abi3t 下是不透明的，不能把 PyObject_HEAD 当作自定义结构体的可见首字段。通常需要把自己的字段单独放进 data 结构，用负的 basicsize 表示额外存储，并通过 PyObject_GetTypeData() 取回数据。可把检查拆成下面三条线：

/* 迁移轮廓：真实项目还要按继承、token 和清理逻辑补齐字段。 */
typedef struct {
    int value; /* 这里只放扩展自己的字段，不复制 PyObject 基类布局。 */
} WidgetData;

static PyType_Spec Widget_spec = {
    .name = "demo.Widget",
    .basicsize = -sizeof(WidgetData), /* 负数表示为类型数据预留额外空间。 */
};

/* 读取时必须使用定义该存储的类型，不能盲目传 Py_TYPE(obj)。 */
WidgetData *data = PyObject_GetTypeData(obj, WidgetType);

同时检查 PyModule_GetDef()、PyType_GetModuleByDef()、ob_type、ob_refcnt、ob_size 等旧访问路径。若类型可被继承，取数据时还要用定义类型或 type token，避免把子类自己的额外存储误当成父类数据。

构建、打标签和测试要分成三个检查点

先让构建工具选择 abi3t；如果工具暂时没有该开关，官方迁移指南给出的手工方向是在包含 Python.h 前设置 Python 3.15 的目标宏。下面只是检查目标是否传入的最小示意，不能替代项目自己的构建配置：

# 先在构建系统中设置，版本号对应 Python 3.15。
CFLAGS="-DPy_LIMITED_API=0x030f0000 -DPy_TARGET_ABI3T=0x030f0000"
export CFLAGS

# 产物命名要与 ABI 一致：同时支持两类运行时时使用 abi3.abi3t。
python -m build

Linux 和 macOS 的扩展文件应呈现 .abi3t.so，wheel 的 ABI 标签使用压缩形式 abi3.abi3t；如果只能做版本化 free-threaded 构建，就使用与 Python 3.15t 对应的 cp315t，不要把它写成 abi3t。

最后做两套测试：在 GIL 与 free-threaded 的 Python 3.15 上分别安装并导入，覆盖并发调用、模块重复初始化、自定义类型继承、异常清理和 wheel 安装选择。Stable ABI 只解决二进制接口的一部分兼容，不保证行为完全相同；支持多个 Python 小版本时，仍应逐版本回归。

常见问题

现有 abi3 wheel 能直接在 Python 3.15t 使用吗？

不要把它当成稳定方案。free-threaded 构建要找 abi3t，旧的 abi3 可能无法满足目标；在未完成迁移前，准备对应的 cp315t 版本更稳妥。

使用 Cython 或 PyO3 的项目要马上改成 abi3t 吗？

先确认代码生成器或绑定工具是否已经支持。官方迁移指南建议这类项目等待工具支持；在此之前可以维持 abi3，并为 free-threaded 版本单独构建。

为什么只加 Py_TARGET_ABI3T 仍然编译不过？

这个宏只是让头文件暴露 abi3t 允许的 API。若源码依赖 PyObject 内部布局、旧模块导出或变量大小类型，仍需按迁移规则重构。