扩展不透明类型

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

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

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

这在受限 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 在受限 API 中未公开，因此支持受限 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结构）的方法。

一种方法是在使用新 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;
}

此函数最初将不会添加到受限 API 中。

使用负spec->basicsize扩展具有正base->itemsize的类将失败，除非在基类或spec->flags中设置了Py_TPFLAGS_ITEMS_AT_END。（有关完整说明，请参阅扩展可变大小对象。）

使用负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 提出的所有机制都可以调整以支持它。也可以添加其他布局。但是，这似乎几乎没有实际好处，因此这只是一个理论上的可能性。