既然Python tuple设计为不可变，为何CPython暴露PyTuple_SetItem作为C API？

问题背景 #

Python中的tuple在设计上是不可变的，尝试在Python层修改tuple会抛出TypeError，符合预期：

>>> a = (1, 2, 3)
>>> a[0] = 12
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: 'tuple' object does not support item assignment

但CPython却暴露了一个名为PyTuple_SetItem的C API，根据文档描述：

int PyTuple_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)

该函数会将对象o的引用插入到p指向的tuple的pos位置。成功返回0；若pos越界，返回-1并设置IndexError异常。

这看起来和Python层的tuple[index] = value操作完全等价，如果是要创建tuple，使用PyTuple_Pack也能实现。那么为什么要暴露这个API？

补充验证 #

通过ctypes调用该API，甚至可以直接修改已创建的tuple：

import ctypes
from ctypes import py_object

my_tuple = (1, 2, 3)
newObj = py_object(my_tuple)

m = "hello"

# 不清楚为何需要在此处调用Py_DecRef。
# 重现时所需的调用次数取决于newObj的引用计数。
ctypes.pythonapi.Py_DecRef(newObj)
ctypes.pythonapi.Py_DecRef(newObj)
ctypes.pythonapi.Py_DecRef(newObj)

ctypes.pythonapi.Py_IncRef(m)

PyTuple_SetItem = ctypes.pythonapi.PyTuple_SetItem
PyTuple_SetItem.argtypes = ctypes.py_object, ctypes.c_size_t, ctypes.py_object

PyTuple_SetItem(newObj, 0, m)
print(my_tuple) # 输出 ('hello', 2, 3)

解答 #

核心原因：tuple的不可变性是Python层约束，底层需保留初始化灵活性 #

PyTuple_SetItem的设计目的是在tuple创建阶段高效初始化元素，而非允许修改已完成创建的tuple。

在CPython内部，创建tuple的流程通常是：

1. 先分配一个指定大小的空tuple结构；
2. 通过PyTuple_SetItem逐个填充元素；
3. 完成填充后，该tuple在Python层就被标记为不可变，上层代码无法再修改。

如果仅依赖PyTuple_Pack，虽然能直接打包多个元素，但对于需要动态构建tuple的场景（比如循环中逐步添加元素），PyTuple_SetItem的灵活性更高，无需预先收集所有元素再打包，能提升底层创建效率。

为什么能用ctypes修改已创建的tuple？ #

这属于绕过Python层约束的底层操作，本质上是因为C API没有对PyTuple_SetItem的调用时机做严格的runtime检查——底层假设这个API只会在tuple初始化阶段被调用。但这种操作非常不安全：

• 违反了Python对tuple不可变性的约定，会破坏依赖该特性的代码逻辑（比如用tuple作为字典键、集合元素时，修改tuple会导致哈希值不一致，引发异常或数据错乱）；
• 代码中多次调用Py_DecRef是因为py_object(my_tuple)会增加tuple的引用计数，而PyTuple_SetItem会接管原位置元素的引用，必须调整引用计数来避免内存泄漏或对象被提前释放。

简言之，PyTuple_SetItem是给CPython内部和扩展模块用来构建tuple的工具，并非用于修改已存在的tuple。Python层的不可变性是为了保证语言的安全性和一致性，而底层C API保留必要的灵活性以实现高效的tuple创建。

内容的提问来源于stack exchange，提问作者user459872