扩展不透明类型

在 Limited API 中，大多数 struct 都是不透明的：它们的尺寸和内存布局不暴露，因此可以在 CPython 的新版本（或 C API 的替代实现）中更改。

这意味着通常的子类化模式——将用于基类型实例的 struct 作为用于派生类型实例的 struct 的第一个元素——不起作用。为了用代码说明，教程中的示例 使用以下 struct 扩展了 PyListObject （list）

typedef struct {
    PyListObject list;
    int state;
} SubListObject;

这在 Limited API 中将无法编译，因为 PyListObject 是不透明的（以允许在实现功能和优化时进行更改）。

相反，本 PEP 建议使用一个只包含子类所需状态的 struct，即

typedef struct {
    int state;
} SubListState;

// (or just `typedef int SubListState;` in this case)

子类现在可以与超类的内存布局（和大小）完全解耦。

这在今天已经可能。要使用这样的结构，请执行以下操作：

• 创建类时，使用 PyListObject->tp_basicsize + sizeof(SubListState) 作为 PyType_Spec.basicsize；
• 访问数据时，使用 PyListObject->tp_basicsize 作为实例（PyObject*）的偏移量。

然而，这有缺点

• 基类的 basicsize 可能没有正确对齐，如果未缓解，可能导致某些架构上出现问题。（如果对齐在新版本中发生变化，这些问题可能特别棘手。）
• PyTypeObject.tp_basicsize 未在 Limited API 中公开，因此支持 Limited API 的扩展需要使用 PyObject_GetAttrString(obj, "__basicsize__")。这很麻烦，并且在极端情况下不安全（Python 属性可能被覆盖）。
• 可变大小对象未处理（参见下面的扩展可变大小对象）。

为了使其易于使用（甚至对于选择松散耦合而非最大性能的项目而言成为最佳实践），本 PEP 提出了一个 API 来

1. 在类创建期间，指定 SubListState 应该“附加”到 PyListObject，而无需传递有关 list 的任何其他详细信息。（解释器本身从基类获取所有必要信息，例如 tp_basicsize。）

   这将通过负的 PyType_Spec.basicsize 指定：-sizeof(SubListState)。

2. 给定一个实例和子类 PyTypeObject*，获取指向 SubListState 的指针。为此将添加一个新函数 PyObject_GetTypeData。

基类当然不限于 PyListObject：它可以用于扩展任何基类，其实例 struct 是不透明的、在不同版本之间不稳定或根本未公开的——包括 type (PyHeapTypeObject) 或第三方扩展（例如 NumPy 数组 [1]）。

对于不需要额外状态的情况，允许零 basicsize：在这种情况下，将继承基类的 tp_basicsize。（这目前有效，但缺乏明确的文档和测试。）

新类的 tp_basicsize 将设置为计算出的总大小，因此检查类的代码将继续像以前一样工作。

扩展可变大小对象

子类化 可变大小对象 时需要额外的考虑，同时保持松散耦合：可变大小数据可能与子类数据（上例中的 SubListState）冲突。

目前，CPython 没有提供防止此类冲突的方法。因此，扩展不透明类的建议机制（负 base->tp_itemsize）默认将失败。

我们可以止步于此，但是由于激励类型——PyHeapTypeObject——是可变大小的，我们需要一种安全的方法来允许对其进行子类化。首先介绍一些背景知识：

PyTupleObject:
┌───────────────────┬───┬───┬╌╌╌╌┐
│ PyObject_VAR_HEAD │var. data   │
└───────────────────┴───┴───┴╌╌╌╌┘

tuple subclass:
┌───────────────────┬───┬───┬╌╌╌╌┬─────────────┐
│ PyObject_VAR_HEAD │var. data   │subclass data│
└───────────────────┴───┴───┴╌╌╌╌┴─────────────┘

heap type:
┌───────────────────┬──────────────┬───┬───┬╌╌╌╌┐
│ PyObject_VAR_HEAD │Heap type data│var. data   │
└───────────────────┴──────────────┴───┴───┴╌╌╌╌┘

type subclass:
┌───────────────────┬──────────────┬─────────────┬───┬───┬╌╌╌╌┐
│ PyObject_VAR_HEAD │Heap type data│subclass data│var. data   │
└───────────────────┴──────────────┴─────────────┴───┴───┴╌╌╌╌┘

相对成员偏移

难题的另一部分是 PyMemberDef.offset。使用特定于子类的 struct（上面的 SubListState）的扩展将能够指定“相对”偏移量（基于此 struct 的偏移量），而不是“绝对”偏移量（基于 PyObject struct）。

一种方法是在使用新 API 创建类时自动假定“相对”偏移量。然而，这种隐式假设会过于令人惊讶。

为了更明确，本 PEP 提出了一个用于“相对”偏移量的新标志。至少在最初，此标志将仅用于检查误用（并为审阅者提供提示）。如果与新 API 一起使用，则必须存在此标志，否则不得使用此标志。

相对 basicsize

PyType_Spec 的 basicsize 成员将允许为零或负数。在这种情况下，它的绝对值将指定新类的实例除了基类的 basicsize 之外所需的额外存储空间大小。也就是说，结果类的 basicsize 将是

type->tp_basicsize = _align(base->tp_basicsize) + _align(-spec->basicsize);

其中 _align 向上舍入到 alignof(max_align_t) 的倍数。

当 spec->basicsize 为零时，basicsize 将直接继承，即设置为 base->tp_basicsize 而不进行对齐。（这已经有效；将添加显式测试和文档。）

在实例上，特定于子类的内存区域——即子类除了其基类之外保留的“额外空间”——将通过一个新函数 PyObject_GetTypeData 获得。在 CPython 中，此函数将定义为

void *
PyObject_GetTypeData(PyObject *obj, PyTypeObject *cls) {
    return (char *)obj + _align(cls->tp_base->tp_basicsize);
}

将添加另一个函数以检索此内存区域的大小

Py_ssize_t
PyType_GetTypeDataSize(PyTypeObject *cls) {
    return cls->tp_basicsize - _align(cls->tp_base->tp_basicsize);
}

结果可能高于 -basicsize 请求的值。使用所有这些值是安全的（例如，使用 memset）。

新的 *Get* 函数带有一个重要的注意事项，这将在文档中指出：它们只能用于使用负 PyType_Spec.basicsize 创建的类。对于其他类，它们的行为是未定义的。（请注意，这允许上述代码假定 cls->tp_base 不为 NULL。）

继承 itemsize

当 spec->itemsize 为零时，tp_itemsize 将从基类继承。（这已经有效；将添加显式测试和文档。）

将添加一个新的类型标志 Py_TPFLAGS_ITEMS_AT_END。此标志只能在 tp_itemsize 非零的类型上设置。它表示实例的可变大小部分存储在实例内存的末尾。

默认元类型（PyType_Type）将设置此标志。

将添加一个新函数 PyObject_GetItemData，用于访问带有新标志的类型的可变大小内容所保留的内存。在 CPython 中，它将被定义为

void *
PyObject_GetItemData(PyObject *obj) {
    if (!PyType_HasFeature(Py_TYPE(obj), Py_TPFLAGS_ITEMS_AT_END) {
        <fail with TypeError>
    }
    return (char *)obj + Py_TYPE(obj)->tp_basicsize;
}

此函数最初不会添加到 Limited API 中。

使用负 spec->basicsize 扩展带有正 base->itemsize 的类将失败，除非设置了 Py_TPFLAGS_ITEMS_AT_END，无论是在基类上还是在 spec->flags 中。（有关完整解释，请参阅扩展可变大小对象。）

使用负 spec->basicsize 扩展带有正 spec->itemsize 的类将失败。

相对成员偏移

在使用负 PyType_Spec.basicsize 定义的类型中，通过 Py_tp_members 定义的成员的偏移量必须相对于额外的子类数据，而不是完整的 PyObject 结构体。这将在 PyMemberDef.flags 中由一个新标志表示：Py_RELATIVE_OFFSET。

在初始实现中，新标志将是冗余的。它仅用于使偏移量的更改含义清晰，并有助于避免错误。不使用带负 basicsize 的 Py_RELATIVE_OFFSET 将是一个错误，而在任何其他上下文（即对 PyDescr_NewMember、PyMember_GetOne、PyMember_SetOne 的直接或间接调用）中使用它也将是一个错误。

CPython 将在初始化类型时调整偏移量并清除 Py_RELATIVE_OFFSET 标志。这意味着

• 创建的类型的 tp_members 将与输入定义的 Py_tp_members 槽不匹配，并且
• 任何读取 tp_members 的代码都无需处理该标志。

对齐与性能

如果实例结构需要比 alignof(max_align_t) 更小的对齐方式，则拟议的实现可能会浪费一些空间。此外，处理对齐会使计算速度变慢，如果我们能够依赖 base->tp_basicsize 正确对齐子类型，那么计算速度会更快。

换句话说，提议的实现侧重于安全性和易用性，并为此牺牲了空间和时间。如果这被证明是一个问题，可以在不破坏 API 的情况下调整实现

• 类型特定缓冲区的偏移量可以存储起来，这样 PyObject_GetTypeData 实际上就变成了 (char *)obj + cls->ht_typedataoffset，这可能会以类中多一个指针为代价来加快速度。
• 然后，一个新的 PyType_Slot 可以指定所需的对齐方式，以减少实例的空间需求。

可变大小类型的其他布局

可以添加一个类似 Py_TPFLAGS_ITEMS_AT_END 的标志，以指示扩展可变大小对象中描述的“类元组”布局，并且本 PEP 提出的所有机制都可以适应以支持它。也可以添加其他布局。然而，似乎实际收益很小，因此这只是一个理论上的可能性。