公用对象结构体
**************

大量的结构体被用于定义 Python 的对象类型。这一节描述了这些的结构体和它
们的使用方法。


基本的对象类型和宏
==================

所有的 Python 对象最终都会在对象的内存表示的开始部分共享少量的字段。这
些字段由 "PyObject" 和 "PyVarObject" 类型来表示，相应地，这些类型又是
由一些宏扩展来定义的，它们也直接或间接地被用于所有其他 Python 对象的定
义。附加的宏可以在 引用计数 下找到。

type PyObject
    * 属于 稳定 ABI (see below).*

   所有对象类型都是此类型的扩展。这是一个包含 Python 需要将对象指针视
   为对象所需信息的类型。在正常的“发布”构建版本中，它仅包含对象的引用
   计数和指向相应类型对象的指针。虽然没有任何内容被显式声明为
   "PyObject" 类型，但所有指向 Python 对象的指针都可以被强制转换为
   PyObject* 类型。

   成员不得直接访问；而应使用诸如 "Py_REFCNT" 和 "Py_TYPE" 之类的宏。

   In the Stable ABI for Free-Threaded Builds ("abi3t"), this struct
   is opaque; its size and layout may change between Python versions.
   In Stable ABI for non-free-threaded builds ("abi3"), the
   "ob_refcnt" and "ob_type" fields are available, but using them
   directly is discouraged.

   Py_ssize_t ob_refcnt
       * 属于 稳定 ABI.*

      对象的引用计数，由 "Py_REFCNT" 返回。不要直接使用此字段；而应使
      用函数和宏，如 "Py_REFCNT"，"Py_INCREF()" 和 "Py_DecRef()"。

      字段类型可能不同于 "Py_ssize_t"，具体取决于构建配置和平台。

   PyTypeObject *ob_type
       * 属于 稳定 ABI.*

      对象的类型。不要直接使用此字段；而应使用 "Py_TYPE" 和
      "Py_SET_TYPE()"。

   PyMutex ob_mutex

      A per-object lock, present only in the *free-threaded* build
      (when "Py_GIL_DISABLED" is defined).

      This field is **reserved for use by the critical section API**
      ("Py_BEGIN_CRITICAL_SECTION" / "Py_END_CRITICAL_SECTION"). Do
      **not** lock it directly with "PyMutex_Lock"; doing so can cause
      deadlocks.  If you need your own lock, add a separate "PyMutex"
      field to your object struct.

      Added in version 3.13.

type PyVarObject
    * 属于 稳定 ABI (see below).*

   "PyObject" 的扩展，添加了 "ob_size" 字段。这适用于具有某种 *长度*
   概念的对象。

   与 "PyObject" 一样，成员不得直接访问；而应使用诸如 "Py_SIZE"，
   "Py_REFCNT" 和 "Py_TYPE" 之类的宏。

   In the Stable ABI for Free-Threaded Builds ("abi3t"), this struct
   is opaque; its size and layout may change between Python versions.
   In Stable ABI for non-free-threaded builds ("abi3"), the "ob_base"
   and "ob_size" fields are available, but using them directly is
   discouraged.

   PyObject ob_base
       * 属于 稳定 ABI.*

      Common object header. Typically, this field is not accessed
      directly; instead "PyVarObject" can be cast to "PyObject".

   Py_ssize_t ob_size
       * 属于 稳定 ABI.*

      一个大小字段，其内容应被视为对象的内部实现细节。

      不要直接使用此字段；而应使用 "Py_SIZE"。

      对象创建函数，如 "PyObject_NewVar()"，通常会将此字段设置为请求的
      大小（条目数）。创建后，可以使用 "Py_SET_SIZE" 在 "ob_size" 中存
      储任意值。

      若需获取对象公开暴露的长度（即 Python 内置函数 "len()" 所返回的
      值），应使用 "PyObject_Length()" 接口。

PyObject_HEAD

   这是一个在声明新类型时使用的宏，用于表示不包含可变长度成员的对象。
   PyObject_HEAD 宏展开后为：

      PyObject ob_base;

   参见上面 "PyObject" 的文档。

PyObject_VAR_HEAD

   这是一个在声明代表每个实例具有可变长度的对象时所使用的宏。
   PyObject_VAR_HEAD 宏被扩展为:

      PyVarObject ob_base;

   参见上面 "PyVarObject" 的文档。

PyTypeObject PyBaseObject_Type
    * 属于 稳定 ABI.*

   所有其他对象的基类，与 Python 中的 "object" 相同。

int Py_Is(PyObject *x, PyObject *y)
    * 属于 稳定 ABI 自 3.10 版起.*

   测试 *x* 是否为 *y* 对象，与 Python 中的 "x is y" 相同。

   Added in version 3.10.

int Py_IsNone(PyObject *x)
    * 属于 稳定 ABI 自 3.10 版起.*

   测试一个对象是否为 "None" 单例，与 Python 中的 "x is None" 相同。

   Added in version 3.10.

int Py_IsTrue(PyObject *x)
    * 属于 稳定 ABI 自 3.10 版起.*

   测试一个对象是否为 "True" 单例，与 Python 中的 "x is True" 相同。

   Added in version 3.10.

int Py_IsFalse(PyObject *x)
    * 属于 稳定 ABI 自 3.10 版起.*

   测试一个对象是否为 "False" 单例，与 Python 中的 "x is False" 相同。

   Added in version 3.10.

PyTypeObject *Py_TYPE(PyObject *o)
    *返回值：借入的引用。** 属于 稳定 ABI 自 3.14 版起.*

   获取 Python 对象 *o* 的类型。

   返回的引用是从 *o* *借用的*。不要使用 "Py_DECREF()" 或类似方法释放
   它。

   在 3.11 版本发生变更: "Py_TYPE()" 被改为一个内联的静态函数。形参类
   型不再是 const PyObject*。

int Py_IS_TYPE(PyObject *o, PyTypeObject *type)
    * 属于 稳定 ABI 自 3.15 版起.*

   如果对象 *o* 的类型为 *type* 则返回非零值。 否则返回零。 等价于:
   "Py_TYPE(o) == type"。

   Added in version 3.9.

void Py_SET_TYPE(PyObject *o, PyTypeObject *type)

   将对象 *o* 的类型设置为 *type*，不进行任何检查或引用计数。

   这是一个非常低级的操作。建议改为使用 "PyObject_SetAttrString()" 或
   类似方法设置 Python 属性 "__class__".

   请注意，分配不兼容的类型可能会导致未定义行为。

   如果 *type* 是一个 堆类型，调用者必须为其创建一个新的引用。同样地，
   如果 *o* 的旧类型是堆类型，调用者必须释放对该类型的引用。

   Added in version 3.9.

Py_ssize_t Py_SIZE(PyVarObject *o)
    * 属于 稳定 ABI 自 3.15 版起.*

   获取 *o* 的 "ob_size" 字段。

   在 3.11 版本发生变更: "Py_SIZE()" 被改为一个内联静态函数。形参类型
   不再是 const PyVarObject*。

void Py_SET_SIZE(PyVarObject *o, Py_ssize_t size)
    * 属于 稳定 ABI 自 3.15 版起.*

   将 *o* 的 "ob_size" 字段设置为 *size*。

   Added in version 3.9.

PyObject_HEAD_INIT(type)

   这是一个为新的 "PyObject" 类型扩展初始化值的宏。该宏扩展为:

      _PyObject_EXTRA_INIT
      1, type,

PyVarObject_HEAD_INIT(type, size)

   这是一个为新的 "PyVarObject" 类型扩展初始化值的宏，包括 "ob_size"
   字段。该宏会扩展为:

      _PyObject_EXTRA_INIT
      1, type, size,


实现函数和方法
==============

type PyCFunction
    * 属于 稳定 ABI.*

   用于在 C 中实现大多数 Python 可调用对象的函数类型。该类型的函数接受
   两个 PyObject* 形参并返回一个这样的值。 如果返回值为 "NULL"，则将设
   置一个异常。如果不为 "NULL"，则返回值将被解读为 Python 中暴露的函数
   的返回值。 此函数必须返回一个新的引用。

   函数的签名为:

      PyObject *PyCFunction(PyObject *self,
                            PyObject *args);

type PyCFunctionWithKeywords
    * 属于 稳定 ABI.*

   用于在 C 中实现具有 METH_VARARGS | METH_KEYWORDS 签名的 Python 可调
   用对象的函数类型。函数的签名为:

      PyObject *PyCFunctionWithKeywords(PyObject *self,
                                        PyObject *args,
                                        PyObject *kwargs);

type PyCFunctionFast
    * 属于 稳定 ABI 自 3.13 版起.*

   用于在 C 中实现具有 "METH_FASTCALL" 签名的 Python 可调用对象的函数
   类型。函数的签名为:

      PyObject *PyCFunctionFast(PyObject *self,
                                PyObject *const *args,
                                Py_ssize_t nargs);

type PyCFunctionFastWithKeywords
    * 属于 稳定 ABI 自 3.13 版起.*

   用于在 C 中实现具有 METH_FASTCALL | METH_KEYWORDS 签名的 Python 可
   调用对象的函数类型。函数的签名为:

      PyObject *PyCFunctionFastWithKeywords(PyObject *self,
                                            PyObject *const *args,
                                            Py_ssize_t nargs,
                                            PyObject *kwnames);

type PyCMethod

   用于在 C 中实现具有 METH_METHOD | METH_FASTCALL | METH_KEYWORDS 签
   名的 Python 可调用对象的函数类型。函数的签名为:

      PyObject *PyCMethod(PyObject *self,
                          PyTypeObject *defining_class,
                          PyObject *const *args,
                          Py_ssize_t nargs,
                          PyObject *kwnames)

   Added in version 3.9.

type PyMethodDef
    * 属于 稳定 ABI （包括所有成员）.*

   用于描述一个扩展类型的方法的结构体。该结构体有四个字段：

   const char *ml_name

      方法的名称。

      A "NULL" *ml_name* marks the end of a "PyMethodDef" array.

   PyCFunction ml_meth

      指向 C 语言实现的指针。

   int ml_flags

      指明调用应当如何构建的旗标位。

   const char *ml_doc

      指向文档字符串的内容。

"ml_meth" 是一个 C 函数指针。该函数可以为不同类型，但它们将总是返回
PyObject*。如果该函数不属于 "PyCFunction"，则编译器将要求在方法表中进
行转换。尽管 "PyCFunction" 将第一个参数定义为 PyObject*，但该方法的实
现使用 *self* 对象的特定 C 类型也很常见。

"ml_flags" 字段是可以包含以下旗标的位字段。每个旗标表示一个调用惯例或
绑定惯例。

调用惯例有如下这些：

METH_VARARGS
    * 属于 稳定 ABI.*

   这是典型的调用惯例，其中方法的类型为 "PyCFunction"。该函数接受两个
   PyObject* 值。 第一个是用于方法的 *self* 对象；对于模块函数，它将为
   模块对象。第二个形参 (常被命名为 *args*) 是一个代表所有参数的元组对
   象。 该形参通常是使用 "PyArg_ParseTuple()" 或 "PyArg_UnpackTuple()"
   来处理的。

METH_KEYWORDS

   只能用于同其他旗标形成特定的组合： METH_VARARGS | METH_KEYWORDS,
   METH_FASTCALL | METH_KEYWORDS 和 METH_METHOD | METH_FASTCALL |
   METH_KEYWORDS.

METH_VARARGS | METH_KEYWORDS
   带有这些旗标的方法必须为 "PyCFunctionWithKeywords" 类型。该函数接受
   三个形参：*self*, *args*, *kwargs* 其中 *kwargs* 是一个包含所有关键
   字参数的字典或者如果没有关键字参数则可以为 "NULL"。 这些形参通常是
   使用 "PyArg_ParseTupleAndKeywords()" 来处理的。

METH_FASTCALL
    * 属于 稳定 ABI 自 3.7 版起.*

   快速调用惯例仅支持位置参数。这些方法的类型为 "PyCFunctionFast"。第
   一个形参为 *self*，第二个形参是由表示位置参数的由 PyObject* 值组成
   的 C 数组而第三个形参是位置参数的数量（数组的长度）。

   Added in version 3.7.

   在 3.10 版本发生变更: "METH_FASTCALL" 现在是 稳定 ABI 的一部分。

METH_FASTCALL | METH_KEYWORDS
   "METH_FASTCALL" 的扩展也支持关键字参数，它使用类型为
   "PyCFunctionFastWithKeywords" 的方法。关键字参数的传递方式与
   vectorcall 协议 中的相同：还存在额外的第四个 PyObject* 形参，它是一
   个代表关键字参数名称（它会保证是字符串）的元组，或者如果没有关键字
   则可以是 "NULL"。关键字参数的值存放在 *args* 数组中，在位置参数之后
   。

   Added in version 3.7.

METH_METHOD
    * 属于 稳定 ABI 自 3.7 版起.*

   只能与其他旗标组合使用： METH_METHOD | METH_FASTCALL |
   METH_KEYWORDS.

METH_METHOD | METH_FASTCALL | METH_KEYWORDS
   METH_FASTCALL | METH_KEYWORDS 的扩展支持 *定义式类*，也就是包含相应
   方法的类。定义式类可以是 "Py_TYPE(self)" 的超类。

   该方法必须为 "PyCMethod" 类型，与在 "self" 之后添加了
   "defining_class" 参数的 "METH_FASTCALL | METH_KEYWORDS" 一样。

   Added in version 3.9.

METH_NOARGS
    * 属于 稳定 ABI.*

   没有形参的方法如果使用 "METH_NOARGS" 旗标列出，则无需检查是否给出了
   参数。它们必须为 "PyCFunction" 类型。第一个形参通常被命名为 *self*
   并将持有对模块或对象实例的引用。在所有情况下第二个形参都将为
   "NULL".

   该函数必须有 2 个形参。由于第二个形参不会被使用，"Py_UNUSED" 可以被
   用来防止编译器警告。

METH_O
    * 属于 稳定 ABI.*

   具有一个单独对象参数的方法可使用 "METH_O" 旗标列出，而不必调用
   "PyArg_ParseTuple()" 并附带 ""O"" 参数。它们的类型为 "PyCFunction"
   ，带有 *self* 形参，以及代表该单独参数的 PyObject* 形参。

这两个常量不是被用来指明调用惯例而是在配合类方法使用时指明绑定。 它们
不会被用于在模块上定义的函数。 对于任何给定方法这些旗标最多只会设置其
中一个。

METH_CLASS
    * 属于 稳定 ABI.*

   该方法将接受类型对象而不是类型的实例作为第一个形参。它会被用于创建
   *类方法*，类似于使用 "classmethod()" 内置函数所创建的结果。

METH_STATIC
    * 属于 稳定 ABI.*

   该方法将接受 "NULL" 而不是类型的实例作为第一个形参。它会被用于创建
   *静态方法*，类似于使用 "staticmethod()" 内置函数所创建的结果。

另一个常量控制方法是否将被载入来替代具有相同方法名的另一个定义。

METH_COEXIST
    * 属于 稳定 ABI.*

   该方法将被加载以替代现有的定义。如果没有 *METH_COEXIST*，默认将跳过
   重复的定义。由于槽位包装器会在方法表之前被加载，例如 当存在
   *sq_contains* 槽位时，将会生成一个名为 "__contains__()" 的已包装方
   法并阻止加载同名的相应 PyCFunction。如果定义了此旗标，PyCFunction
   将被加载以替代此包装器对象并与槽位共存。因为对 PyCFunction 的调用相
   比对包装器对象调用更为优化所以这是很有帮助的。

PyTypeObject PyCMethod_Type

   对应 Python C 方法对象的类型对象。它在 Python 层面上为
   "types.BuiltinMethodType"。

int PyCMethod_Check(PyObject *op)

   如果 *op* 是 "PyCMethod_Type" 类型或其子类型的实例则返回真值。此函
   数总是会成功执行。

int PyCMethod_CheckExact(PyObject *op)

   此函数与 "PyCMethod_Check()" 类似，但不会考虑子类型。

PyObject *PyCMethod_New(PyMethodDef *ml, PyObject *self, PyObject *module, PyTypeObject *cls)
    *返回值：新的引用。** 属于 稳定 ABI 自 3.9 版起.*

   将 *ml* 转为一个 Python *callable* 对象。调用方必须确保 *ml* 的生命
   期长于 *callable*。通常，*ml* 会被定义为一个静态变量。

   *self* 形参将在调用时作为 "ml->ml_meth" 中 C 函数的 *self* 参数传入
   。 *self* 可以为 "NULL"。

   *callable* 对象的 "__module__" 属性可以根据给定的 *module* 参数来设
   置。 *module* 应为一个 Python 字符串，它将被用作函数定义所在的模块
   名称。如果不可用，它将被设为 "None" 或 "NULL"。

   参见: "function.__module__"

   *cls* 形参将被作为 C 函数的 *defining_class* 参数传入。如果在
   "ml->ml_flags" 上设置了 "METH_METHOD" 则必须设置该形参。

   Added in version 3.9.

PyTypeObject PyCFunction_Type
    * 属于 稳定 ABI.*

   对应 Python C 函数对象的类型对象。它在 Python 层面上为
   "types.BuiltinFunctionType"。

int PyCFunction_Check(PyObject *op)

   如果 *op* 是 "PyCFunction_Type" 类型或其子类型的实例则返回真值。此
   函数总是会成功执行。

int PyCFunction_CheckExact(PyObject *op)

   此函数与 "PyCFunction_Check()" 类似，但不会考虑子类型。

PyObject *PyCFunction_NewEx(PyMethodDef *ml, PyObject *self, PyObject *module)
    *返回值：新的引用。** 属于 稳定 ABI.*

   等价于 "PyCMethod_New(ml, self, module, NULL)"。

PyObject *PyCFunction_New(PyMethodDef *ml, PyObject *self)
    *返回值：新的引用。** 属于 稳定 ABI 自 3.4 版起.*

   等价于 "PyCMethod_New(ml, self, NULL, NULL)"。

int PyCFunction_GetFlags(PyObject *func)
    * 属于 稳定 ABI.*

   获取 *func* 上的函数旗标，即传给 "ml_flags" 的值。

   如果 *func* 不是一个 C 函数对象，此函数执行将失败并引发异常。
   *func* 不可为 "NULL"。

   此函数成功时返回函数的旗标，失败时返回 "-1" 并设置一个异常。

int PyCFunction_GET_FLAGS(PyObject *func)

   此函数与 "PyCFunction_GetFlags()" 类似，但不带错误检测和类型检测。

PyCFunction PyCFunction_GetFunction(PyObject *func)
    * 属于 稳定 ABI.*

   获取 *func* 上的函数指针，即传给 "ml_meth" 的值。

   如果 *func* 不是一个 C 函数对象，此函数执行将失败并引发异常。
   *func* 不可为 "NULL"。

   此函数成功时返回函数指针，失败时返回 "NULL" 并设置一个异常。

int PyCFunction_GET_FUNCTION(PyObject *func)

   此函数与 "PyCFunction_GetFunction()" 类似，但不带错误检测和类型检测
   。

PyObject *PyCFunction_GetSelf(PyObject *func)
    * 属于 稳定 ABI.*

   获取 *func* 上的 "self" 对象。即将被传给 "PyCFunction" 的第一个参数
   的对象。对于通过 "PyModuleDef" 上的 "PyMethodDef" 创建的 C 函数对象
   ，这将是结果模块对象。

   如果 *func* 不是一个 C 函数对象，此函数执行将失败并引发异常。
   *func* 不可为 "NULL"。

   此函数成功时返回一个指向 "self" 对象的 *borrowed reference*，失败时
   返回 "NULL" 并设置一个异常。

PyObject *PyCFunction_GET_SELF(PyObject *func)

   此函数与 "PyCFunction_GetSelf()" 类似，但不带错误检测和类型检测。


访问扩展类型的属性
==================

type PyMemberDef
    * 属于 稳定 ABI （包括所有成员）.*

   描述某个 C 结构成员对应类型的属性的结构体。在定义类时，要把由这些结
   构组成的以 NULL 结尾的数组 放在 "tp_members" 槽位中。

   其中的字段及顺序如下：

   const char *name

      成员名称。NULL 值表示 "PyMemberDef[]" 数组的结束。

      字符串应当是静态的，它不会被复制。

   int type

      C 结构体中成员的类型。请参阅 成员类型 了解可能的取值。

   Py_ssize_t offset

      成员在类型的对象结构体中所在位置的以字节为单位的偏移量。

   int flags

      零个或多个 成员旗标，使用按位或运算进行组合。

   const char *doc

      文档字符串，或者为空。该字符串应当是静态的，它不会被拷贝。通常，
      它是使用 "PyDoc_STR" 来定义的。

   默认情况下 (当 "flags" 为 "0" 时)，成员同时允许读取和写入访问。使用
   "Py_READONLY" 旗标表示只读访问。某些类型，如 "Py_T_STRING"，隐含要
   求 "Py_READONLY"。只有 "Py_T_OBJECT_EX" (以及旧式的 "T_OBJECT") 成
   员可以删除。

   对于堆分配类型（使用 "PyType_FromSpec()" 或类似函数创建），
   "PyMemberDef" 可能包含特殊成员 ""__vectorcalloffset__"" 的定义，与
   类型对象中的 "tp_vectorcall_offset" 相对应。此成员必须用
   "Py_T_PYSSIZET" 和 "Py_READONLY" 或 "Py_READONLY |
   Py_RELATIVE_OFFSET" 来定义，例如:

      static PyMemberDef spam_type_members[] = {
          {"__vectorcalloffset__", Py_T_PYSSIZET,
           offsetof(Spam_object, vectorcall), Py_READONLY},
          {NULL}  /* 哨兵 */
      };

   （您可能需要为 "offsetof()" 添加 "#include <stddef.h>"。）

   旧式的偏移量 "tp_dictoffset" 和 "tp_weaklistoffset" 可使用
   ""__dictoffset__"" 和 ""__weaklistoffset__"" 成员进行类似的定义，但
   强烈建议扩展程序改用 "Py_TPFLAGS_MANAGED_DICT" 和
   "Py_TPFLAGS_MANAGED_WEAKREF"。

   在 3.12 版本发生变更: "PyMemberDef" 将始终可用。在之前版本中，它需
   要包括 ""structmember.h""。

   在 3.14 版本发生变更: 宏 "Py_RELATIVE_OFFSET" 现在允许用于
   ""__vectorcalloffset__""、""__dictoffset__"" 和
   ""__weaklistoffset__""。

PyObject *PyMember_GetOne(const char *obj_addr, struct PyMemberDef *m)
    * 属于 稳定 ABI.*

   获取属于位于地址 *obj_addr* 上的对象的某个属性。该属性是以
   "PyMemberDef" *m* 来描述的。出错时返回 "NULL".

   在 3.12 版本发生变更: "PyMember_GetOne" 将总是可用。在之前版本中，
   它需要包括 ""structmember.h""。

int PyMember_SetOne(char *obj_addr, struct PyMemberDef *m, PyObject *o)
    * 属于 稳定 ABI.*

   将属于位于地址 *obj_addr* 的对象的属性设置到对象 *o*。要设置的属性
   由 "PyMemberDef" *m* 描述。成功时返回 "0" 而失败时返回负值。

   在 3.12 版本发生变更: "PyMember_SetOne" 将总是可用。在之前版本中，
   它需要包括 ""structmember.h""。


成员旗标
--------

以下旗标可被用于 "PyMemberDef.flags":

Py_READONLY
    * 属于 稳定 ABI 自 3.12 版起.*

   不可写入。

Py_AUDIT_READ
    * 属于 稳定 ABI 自 3.12 版起.*

   在读取之前发出一个 "object.__getattr__" 审计事件。

Py_RELATIVE_OFFSET
    * 属于 稳定 ABI 自 3.12 版起.*

   表示该 "PyMemberDef" 条目的 "offset" 是指明来自子类专属数据的偏移量
   ，而不是来自 "PyObject" 的偏移量。

   只能在创建使用负的 "basicsize" 的类时被用作 "Py_tp_members" "槽位"
   的一部分。这在此场景下是必须的。当在类创建期间根据该槽位设置
   "tp_members" 时，Python 将清除旗标并将 "PyMemberDef.offset" 设为来
   自 "PyObject" 结构的偏移量。

在 3.10 版本发生变更: 通过 "#include "structmember.h"" 提供的
"RESTRICTED"、"READ_RESTRICTED" 和 "WRITE_RESTRICTED" 宏已被弃用。
"READ_RESTRICTED" 和 "RESTRICTED" 等同于 "Py_AUDIT_READ"；
"WRITE_RESTRICTED" 则没有任何作用。

在 3.12 版本发生变更: "READONLY" 宏被更名为 "Py_READONLY"。
"PY_AUDIT_READ" 宏被更名为 "Py_" 前缀。新名称现在将始终可用。在之前的
版本中，这些名称需要 "#include "structmember.h""。该头文件仍然可用并提
供了原有的名称。


成员类型
--------

"PyMemberDef.type" 可以是下列与各种 C 类型相对应的宏之一。在 Python 中
访问该成员时，它将被转换为对应的 Python 类型。当从 Python 设置成员时，
它将被转换回 C 类型。如果无法转换，则会引发一个异常如 "TypeError" 或
"ValueError"。

除非标记为 (D)，否则不能使用 "del" 或 "delattr()" 删除以这种方式定义的
属性。

+----------------------------------+-------------------------------+------------------------+
| 宏名称                           | C 类型                        | Python 类型            |
|==================================|===============================|========================|
| Py_T_BYTE  * 属于 稳定 ABI 自    | char                          | "int"                  |
| 3.12 版起.*                      |                               |                        |
+----------------------------------+-------------------------------+------------------------+
| Py_T_SHORT  * 属于 稳定 ABI 自   | short                         | "int"                  |
| 3.12 版起.*                      |                               |                        |
+----------------------------------+-------------------------------+------------------------+
| Py_T_INT  * 属于 稳定 ABI 自     | int                           | "int"                  |
| 3.12 版起.*                      |                               |                        |
+----------------------------------+-------------------------------+------------------------+
| Py_T_LONG  * 属于 稳定 ABI 自    | long                          | "int"                  |
| 3.12 版起.*                      |                               |                        |
+----------------------------------+-------------------------------+------------------------+
| Py_T_LONGLONG  * 属于 稳定 ABI   | long long                     | "int"                  |
| 自 3.12 版起.*                   |                               |                        |
+----------------------------------+-------------------------------+------------------------+
| Py_T_UBYTE  * 属于 稳定 ABI 自   | unsigned char                 | "int"                  |
| 3.12 版起.*                      |                               |                        |
+----------------------------------+-------------------------------+------------------------+
| Py_T_UINT  * 属于 稳定 ABI 自    | unsigned int                  | "int"                  |
| 3.12 版起.*                      |                               |                        |
+----------------------------------+-------------------------------+------------------------+
| Py_T_USHORT  * 属于 稳定 ABI 自  | unsigned short                | "int"                  |
| 3.12 版起.*                      |                               |                        |
+----------------------------------+-------------------------------+------------------------+
| Py_T_ULONG  * 属于 稳定 ABI 自   | unsigned long                 | "int"                  |
| 3.12 版起.*                      |                               |                        |
+----------------------------------+-------------------------------+------------------------+
| Py_T_ULONGLONG  * 属于 稳定 ABI  | unsigned long long            | "int"                  |
| 自 3.12 版起.*                   |                               |                        |
+----------------------------------+-------------------------------+------------------------+
| Py_T_PYSSIZET  * 属于 稳定 ABI   | Py_ssize_t                    | "int"                  |
| 自 3.12 版起.*                   |                               |                        |
+----------------------------------+-------------------------------+------------------------+
| Py_T_FLOAT  * 属于 稳定 ABI 自   | float                         | "float"                |
| 3.12 版起.*                      |                               |                        |
+----------------------------------+-------------------------------+------------------------+
| Py_T_DOUBLE  * 属于 稳定 ABI 自  | double                        | "float"                |
| 3.12 版起.*                      |                               |                        |
+----------------------------------+-------------------------------+------------------------+
| Py_T_BOOL  * 属于 稳定 ABI 自    | char (写为 0 或 1)            | "bool"                 |
| 3.12 版起.*                      |                               |                        |
+----------------------------------+-------------------------------+------------------------+
| Py_T_STRING  * 属于 稳定 ABI 自  | const char* (*)               | "str" (RO)             |
| 3.12 版起.*                      |                               |                        |
+----------------------------------+-------------------------------+------------------------+
| Py_T_STRING_INPLACE  * 属于 稳定 | const char[] (*)              | "str" (RO)             |
| ABI 自 3.12 版起.*               |                               |                        |
+----------------------------------+-------------------------------+------------------------+
| Py_T_CHAR  * 属于 稳定 ABI 自    | char (0-127)                  | "str" (**)             |
| 3.12 版起.*                      |                               |                        |
+----------------------------------+-------------------------------+------------------------+
| Py_T_OBJECT_EX  * 属于 稳定 ABI  | PyObject*                     | "object" (D)           |
| 自 3.12 版起.*                   |                               |                        |
+----------------------------------+-------------------------------+------------------------+

   (*): 以零结束的 UTF8 编码的 C 字符串。使用 "Py_T_STRING" 时的 C 表
   示形式是一个指针；使用 "Py_T_STRING_INPLACE" 时字符串将直接存储在结
   构体中。

   (**): 长度为 1 的字符串。只接受 ASCII 字符。

   (RO)：表示 "Py_READONLY"。

   (D)：可以删除，在这种情况下指针会被设为 "NULL"。读取 "NULL" 指针会
   引发 "AttributeError"。

Added in version 3.12: 在之前的版本中，这些宏仅通过 "#include
"structmember.h"" 提供并且其名称不带 "Py_" 前缀 (例如 "T_INT")。头文件
仍然可用并包含这些旧名称，以及下列已被弃用的类型：

T_OBJECT

   与 "Py_T_OBJECT_EX" 类似，但 "NULL" 会被转换为 "None"。这将在
   Python 中产生令人吃惊的行为：删除该属性实际上会将其设置为 "None"。

T_NONE

   总是为 "None"。必须与 "Py_READONLY" 一起使用。


定义读取器和设置器
------------------

type PyGetSetDef
    * 属于 稳定 ABI （包括所有成员）.*

   用于定义针对某个类型的特征属性式的访问的结构体。另请参阅
   "PyTypeObject.tp_getset" 槽位的描述。

   const char *name

      属性名称

   getter get

      用于获取属性的 C 函数。

   setter set

      可选的用于设置或删除属性的 C 函数。如为 "NULL"，则属性将是只读的
      。

   const char *doc

      可选的文档字符串

   void *closure

      可选的用户数据指针，为 getter 和 setter 提供附加数据。

typedef PyObject *(*getter)(PyObject*, void*)
    * 属于 稳定 ABI.*

   "get" 函数接受一个 PyObject* 形参 (相应的实例) 和一个用户数据指针 (
   关联的 "closure"):

   它应当在成功时返回一个新的引用或在失败时返回 "NULL" 并设置异常。

typedef int (*setter)(PyObject*, PyObject*, void*)
    * 属于 稳定 ABI.*

   "set" 函数接受两个 PyObject* 形参 (相应的实例和要设置的值) 和一个用
   户数据指针 (关联的 "closure"):

   对于属性要被删除的情况第二个形参应为 "NULL"。成功时应返回 "0" 或在
   失败时返回 "-1" 并设置异常。
