# SOME DESCRIPTIVE TITLE.

# Copyright (C) 2001-2025, Python Software Foundation

# This file is distributed under the same license as the Python package.

# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.

#

# Translators:

# Rafael Fontenelle <[email protected]>, 2025

#

#, fuzzy

msgid ""

msgstr ""

"Project-Id-Version: Python 3.12\n"

"Report-Msgid-Bugs-To: \n"

"POT-Creation-Date: 2025-07-25 16:03+0000\n"

"PO-Revision-Date: 2025-07-18 19:57+0000\n"

"Last-Translator: Rafael Fontenelle <[email protected]>, 2025\n"

"Language-Team: Chinese (China) (https://app.transifex.com/python-doc/teams/5390/zh_CN/)\n"

"MIME-Version: 1.0\n"

"Content-Type: text/plain; charset=UTF-8\n"

"Content-Transfer-Encoding: 8bit\n"

"Language: zh_CN\n"

"Plural-Forms: nplurals=1; plural=0;\n"

#: ../../extending/newtypes_tutorial.rst:7

msgid "Defining Extension Types: Tutorial"

msgstr "自定义扩展类型：教程"

#: ../../extending/newtypes_tutorial.rst:14

msgid ""

"Python allows the writer of a C extension module to define new types that "

"can be manipulated from Python code, much like the built-in :class:`str` and"

" :class:`list` types. The code for all extension types follows a pattern, "

"but there are some details that you need to understand before you can get "

"started. This document is a gentle introduction to the topic."

msgstr ""

"Python 允许编写 C 扩展模块定义可以从 Python 代码中操纵的新类型，这很像内置的 :class:`str` 和 :class:`list`"

" 类型。所有扩展类型的代码都遵循一个模式，但是在您开始之前，您需要了解一些细节。这份文件是对这个主题介绍。"

#: ../../extending/newtypes_tutorial.rst:24

msgid "The Basics"

msgstr "基础"

#: ../../extending/newtypes_tutorial.rst:26

msgid ""

"The :term:`CPython` runtime sees all Python objects as variables of type "

":c:expr:`PyObject*`, which serves as a \"base type\" for all Python objects."

" The :c:type:`PyObject` structure itself only contains the object's "

":term:`reference count` and a pointer to the object's \"type object\". This "

"is where the action is; the type object determines which (C) functions get "

"called by the interpreter when, for instance, an attribute gets looked up on"

" an object, a method called, or it is multiplied by another object. These C"

" functions are called \"type methods\"."

msgstr ""

":term:`CPython` 运行时会将所有 Python 对象都视为 :c:expr:`PyObject*` 类型的变量，这是所有 Python "

"对象的“基础类型”。 :c:type:`PyObject` 结构体本身只包含对象的 :term:`reference count` "

"和指向对象的“类型对象”的指针。 这是动作所针对的目标。 类型对象决定解释器要调用哪些 (C) "

"函数，例如，在对象上查找一个属性，调用一个方法，或者与另一个对象相乘等。 这些 C 函数被称为“类型方法”。"

#: ../../extending/newtypes_tutorial.rst:35

msgid ""

"So, if you want to define a new extension type, you need to create a new "

"type object."

msgstr "所以，如果你想要定义新的扩展类型，需要创建新的类型对象。"

#: ../../extending/newtypes_tutorial.rst:38

msgid ""

"This sort of thing can only be explained by example, so here's a minimal, "

"but complete, module that defines a new type named :class:`!Custom` inside a"

" C extension module :mod:`!custom`:"

msgstr ""

"这种事情只能通过例子来解释，下面是一个最小但完整的模块，它在 C 扩展模块 :mod:`!custom` 中定义了一个名为 "

":class:`!Custom` 的新类型："

#: ../../extending/newtypes_tutorial.rst:43

msgid ""

"What we're showing here is the traditional way of defining *static* "

"extension types. It should be adequate for most uses. The C API also "

"allows defining heap-allocated extension types using the "

":c:func:`PyType_FromSpec` function, which isn't covered in this tutorial."

msgstr ""

"这里展示的方法是定义 *static* 扩展类型的传统方法。可以适合大部分用途。C API也可以定义在堆上分配的扩展类型，使用 "

":c:func:`PyType_FromSpec` 函数，但不在本入门里讨论。"

#: ../../extending/newtypes_tutorial.rst:48

msgid ""

"#define PY_SSIZE_T_CLEAN\n"

"#include <Python.h>\n"

"\n"

"typedef struct {\n"

" PyObject_HEAD\n"

" /* Type-specific fields go here. */\n"

"} CustomObject;\n"

"\n"

"static PyTypeObject CustomType = {\n"

" .ob_base = PyVarObject_HEAD_INIT(NULL, 0)\n"

" .tp_name = \"custom.Custom\",\n"

" .tp_doc = PyDoc_STR(\"Custom objects\"),\n"

" .tp_basicsize = sizeof(CustomObject),\n"

" .tp_itemsize = 0,\n"

" .tp_flags = Py_TPFLAGS_DEFAULT,\n"

" .tp_new = PyType_GenericNew,\n"

"};\n"

"\n"

"static PyModuleDef custommodule = {\n"

" .m_base = PyModuleDef_HEAD_INIT,\n"

" .m_name = \"custom\",\n"

" .m_doc = \"Example module that creates an extension type.\",\n"

" .m_size = -1,\n"

"};\n"

"\n"

"PyMODINIT_FUNC\n"

"PyInit_custom(void)\n"

"{\n"

" PyObject *m;\n"

" if (PyType_Ready(&CustomType) < 0)\n"

" return NULL;\n"

"\n"

" m = PyModule_Create(&custommodule);\n"

" if (m == NULL)\n"

" return NULL;\n"

"\n"

" Py_INCREF(&CustomType);\n"

" if (PyModule_AddObject(m, \"Custom\", (PyObject *) &CustomType) < 0) {\n"

" Py_DECREF(&CustomType);\n"

" Py_DECREF(m);\n"

" return NULL;\n"

" }\n"

"\n"

" return m;\n"

"}\n"

msgstr ""

#: ../../extending/newtypes_tutorial.rst:50

msgid ""

"Now that's quite a bit to take in at once, but hopefully bits will seem "

"familiar from the previous chapter. This file defines three things:"

msgstr "这部分很容易理解，这是为了跟上一章能对接上。这个文件定义了三件事："

#: ../../extending/newtypes_tutorial.rst:53

msgid ""

"What a :class:`!Custom` **object** contains: this is the ``CustomObject`` "

"struct, which is allocated once for each :class:`!Custom` instance."

msgstr ""

"一个 :class:`!Custom` **对象** 包含的东西：这是 ``CustomObject`` 结构体，它会为每个 "

":class:`!Custom` 实例分配一次。"

#: ../../extending/newtypes_tutorial.rst:55

msgid ""

"How the :class:`!Custom` **type** behaves: this is the ``CustomType`` "

"struct, which defines a set of flags and function pointers that the "

"interpreter inspects when specific operations are requested."

msgstr ""

":class:`!Custom` **类型** 的行为：这是 ``CustomType`` "

"结构体，它定义了一组旗标和函数指针供解释器在收到特定操作请求时进行检查。"

#: ../../extending/newtypes_tutorial.rst:58

msgid ""

"How to initialize the :mod:`!custom` module: this is the ``PyInit_custom`` "

"function and the associated ``custommodule`` struct."

msgstr ""

"如何初始化 :mod:`!custom` 模块：这是 ``PyInit_custom`` 函数及其对应的 ``custommodule`` 结构体。"

#: ../../extending/newtypes_tutorial.rst:61

msgid "The first bit is::"

msgstr "结构的第一块是 ::"

#: ../../extending/newtypes_tutorial.rst:63

msgid ""

"typedef struct {\n"

" PyObject_HEAD\n"

"} CustomObject;"

msgstr ""

"typedef struct {\n"

" PyObject_HEAD\n"

"} CustomObject;"

#: ../../extending/newtypes_tutorial.rst:67

msgid ""

"This is what a Custom object will contain. ``PyObject_HEAD`` is mandatory "

"at the start of each object struct and defines a field called ``ob_base`` of"

" type :c:type:`PyObject`, containing a pointer to a type object and a "

"reference count (these can be accessed using the macros :c:macro:`Py_TYPE` "

"and :c:macro:`Py_REFCNT` respectively). The reason for the macro is to "

"abstract away the layout and to enable additional fields in :ref:`debug "

"builds <debug-build>`."

msgstr ""

"这就是一个自定义对象将会包含的内容。 ``PyObject_HEAD`` 是强制要求放在每个对象结构体之前并定义一个名为 ``ob_base`` 的 "

":c:type:`PyObject` 类型的字段，其中包含一个指向类型对象和引用计数的指针（这两者可以分别使用宏 :c:macro:`Py_TYPE` "

"和 :c:macro:`Py_REFCNT` 来区分）。 使用宏的理由是将布局抽象出来并在 :ref:`调试编译版中 <debug-build>` "

"中启用附加字段。"

#: ../../extending/newtypes_tutorial.rst:76

msgid ""

"There is no semicolon above after the :c:macro:`PyObject_HEAD` macro. Be "

"wary of adding one by accident: some compilers will complain."

msgstr "注意在宏 :c:macro:`PyObject_HEAD` 后没有分号。意外添加分号会导致编译器提示出错。"

#: ../../extending/newtypes_tutorial.rst:79

msgid ""

"Of course, objects generally store additional data besides the standard "

"``PyObject_HEAD`` boilerplate; for example, here is the definition for "

"standard Python floats::"

msgstr "当然，对象除了在 ``PyObject_HEAD`` 存储数据外，还有额外数据；例如，如下定义了标准的Python浮点数::"

#: ../../extending/newtypes_tutorial.rst:83

msgid ""

"typedef struct {\n"

" PyObject_HEAD\n"

" double ob_fval;\n"

"} PyFloatObject;"

msgstr ""

"typedef struct {\n"

" PyObject_HEAD\n"

" double ob_fval;\n"

"} PyFloatObject;"

#: ../../extending/newtypes_tutorial.rst:88

msgid "The second bit is the definition of the type object. ::"

msgstr "第二个位是类型对象的定义::"

#: ../../extending/newtypes_tutorial.rst:90

msgid ""

"static PyTypeObject CustomType = {\n"

" .ob_base = PyVarObject_HEAD_INIT(NULL, 0)\n"

" .tp_name = \"custom.Custom\",\n"

" .tp_doc = PyDoc_STR(\"Custom objects\"),\n"

" .tp_basicsize = sizeof(CustomObject),\n"

" .tp_itemsize = 0,\n"

" .tp_flags = Py_TPFLAGS_DEFAULT,\n"

" .tp_new = PyType_GenericNew,\n"

"};"

msgstr ""

"static PyTypeObject CustomType = {\n"

" .ob_base = PyVarObject_HEAD_INIT(NULL, 0)\n"

" .tp_name = \"custom.Custom\",\n"

" .tp_doc = PyDoc_STR(\"Custom objects\"),\n"

" .tp_basicsize = sizeof(CustomObject),\n"

" .tp_itemsize = 0,\n"

" .tp_flags = Py_TPFLAGS_DEFAULT,\n"

" .tp_new = PyType_GenericNew,\n"

"};"

#: ../../extending/newtypes_tutorial.rst:101

msgid ""

"We recommend using C99-style designated initializers as above, to avoid "

"listing all the :c:type:`PyTypeObject` fields that you don't care about and "

"also to avoid caring about the fields' declaration order."

msgstr ""

"推荐使用如上C99风格的初始化，以避免列出所有的 :c:type:`PyTypeObject` "

"字段，其中很多是你不需要关心的，这样也可以避免关注字段的定义顺序。"

#: ../../extending/newtypes_tutorial.rst:105

msgid ""

"The actual definition of :c:type:`PyTypeObject` in :file:`object.h` has many"

" more :ref:`fields <type-structs>` than the definition above. The remaining"

" fields will be filled with zeros by the C compiler, and it's common "

"practice to not specify them explicitly unless you need them."

msgstr ""

"在 :file:`object.h` 中实际定义的 :c:type:`PyTypeObject` 具有比如上定义更多的 :ref:`字段 <type-"

"structs>`。 剩余的字段会由 C 编译器用零来填充，通常的做法是不显式地指定它们，除非你确实需要它们。"

#: ../../extending/newtypes_tutorial.rst:110

msgid "We're going to pick it apart, one field at a time::"

msgstr "我们先挑选一部分，每次一个字段::"

#: ../../extending/newtypes_tutorial.rst:112

msgid ".ob_base = PyVarObject_HEAD_INIT(NULL, 0)"

msgstr ".ob_base = PyVarObject_HEAD_INIT(NULL, 0)"

#: ../../extending/newtypes_tutorial.rst:114

msgid ""

"This line is mandatory boilerplate to initialize the ``ob_base`` field "

"mentioned above. ::"

msgstr "这一行是强制的样板，用以初始化如上提到的 ``ob_base`` 字段::"

#: ../../extending/newtypes_tutorial.rst:117

msgid ".tp_name = \"custom.Custom\","

msgstr ".tp_name = \"custom.Custom\","

#: ../../extending/newtypes_tutorial.rst:119

msgid ""

"The name of our type. This will appear in the default textual "

"representation of our objects and in some error messages, for example:"

msgstr "我们的类型的名称。 这将出现在我们的对象的默认文本表示形式和某些错误消息中，例如:"

#: ../../extending/newtypes_tutorial.rst:122

msgid ""

">>> \"\" + custom.Custom()\n"

"Traceback (most recent call last):\n"

" File \"<stdin>\", line 1, in <module>\n"

"TypeError: can only concatenate str (not \"custom.Custom\") to str"

msgstr ""

">>> \"\" + custom.Custom()\n"

"Traceback (most recent call last):\n"

" File \"<stdin>\", line 1, in <module>\n"

"TypeError: can only concatenate str (not \"custom.Custom\") to str"

#: ../../extending/newtypes_tutorial.rst:129

msgid ""

"Note that the name is a dotted name that includes both the module name and "

"the name of the type within the module. The module in this case is "

":mod:`!custom` and the type is :class:`!Custom`, so we set the type name to "

":class:`!custom.Custom`. Using the real dotted import path is important to "

"make your type compatible with the :mod:`pydoc` and :mod:`pickle` modules. "

"::"

msgstr ""

"请注意此名称是一个带点号名称，它同时包括模块名称和模块中的类型名称。 本例中的模块是 :mod:`!custom` 而类型是 "

":class:`!Custom`，因此我们将类型名称设为 :class:`!custom.Custom`。 使用真正的带点号的导入路径对于使你的类型与 "

":mod:`pydoc` 和 :mod:`pickle` 模块保持兼容是很重要的。 ::"

#: ../../extending/newtypes_tutorial.rst:135

msgid ""

".tp_basicsize = sizeof(CustomObject),\n"

".tp_itemsize = 0,"

msgstr ""

".tp_basicsize = sizeof(CustomObject),\n"

".tp_itemsize = 0,"

#: ../../extending/newtypes_tutorial.rst:138

msgid ""

"This is so that Python knows how much memory to allocate when creating new "

":class:`!Custom` instances. :c:member:`~PyTypeObject.tp_itemsize` is only "

"used for variable-sized objects and should otherwise be zero."

msgstr ""

"这样能让 Python 知道当创建新的 :class:`!Custom` 实例时需要分配多少内存。 "

":c:member:`~PyTypeObject.tp_itemsize` 仅用于可变大小的对象而在其他情况下都应为零。"

#: ../../extending/newtypes_tutorial.rst:144

msgid ""

"If you want your type to be subclassable from Python, and your type has the "

"same :c:member:`~PyTypeObject.tp_basicsize` as its base type, you may have "

"problems with multiple inheritance. A Python subclass of your type will "

"have to list your type first in its :attr:`~type.__bases__`, or else it will"

" not be able to call your type's :meth:`~object.__new__` method without "

"getting an error. You can avoid this problem by ensuring that your type has"

" a larger value for :c:member:`~PyTypeObject.tp_basicsize` than its base "

"type does. Most of the time, this will be true anyway, because either your "

"base type will be :class:`object`, or else you will be adding data members "

"to your base type, and therefore increasing its size."

msgstr ""

"如果你希望你的类型可在 Python 中被子类化，并且你的类型和它的基类型具有相同的 "

":c:member:`~PyTypeObject.tp_basicsize`，那么你可能会遇到多重继承问题。 你的类型的 Python 子类必须在其 "

":attr:`~type.__bases__` 中将你的类型列在最前面，否则在调用你的类型的 :meth:`~object.__new__` "

"方法时将会出错。 你可以通过确保你的类型具有比它的基类型更大的 :c:member:`~PyTypeObject.tp_basicsize` "

"值来避免这个问题。 在大多数时候，这都是可以的，因为要么你的类型是 :class:`object`，要么你将为你的基类型添加数据成员，从而增加其大小。"

#: ../../extending/newtypes_tutorial.rst:154

msgid "We set the class flags to :c:macro:`Py_TPFLAGS_DEFAULT`. ::"

msgstr "我们将类旗标设为 :c:macro:`Py_TPFLAGS_DEFAULT`。 ::"

#: ../../extending/newtypes_tutorial.rst:156

msgid ".tp_flags = Py_TPFLAGS_DEFAULT,"

msgstr ".tp_flags = Py_TPFLAGS_DEFAULT,"

#: ../../extending/newtypes_tutorial.rst:158

msgid ""

"All types should include this constant in their flags. It enables all of "

"the members defined until at least Python 3.3. If you need further members,"

" you will need to OR the corresponding flags."

msgstr ""

"所有类型都应当在它们的旗标中包括此常量。 该常量将启用至少在 Python 3.3 之前定义的全部成员。 如果你需要更多的成员，你将需要对相应的旗标进行"

" OR 运算。"

#: ../../extending/newtypes_tutorial.rst:162

msgid ""

"We provide a doc string for the type in :c:member:`~PyTypeObject.tp_doc`. ::"

msgstr "我们为 :c:member:`~PyTypeObject.tp_doc` 类型提供一个文档字符串. ::"

#: ../../extending/newtypes_tutorial.rst:164

msgid ".tp_doc = PyDoc_STR(\"Custom objects\"),"

msgstr ".tp_doc = PyDoc_STR(\"Custom objects\"),"

#: ../../extending/newtypes_tutorial.rst:166

msgid ""

"To enable object creation, we have to provide a "

":c:member:`~PyTypeObject.tp_new` handler. This is the equivalent of the "

"Python method :meth:`~object.__new__`, but has to be specified explicitly. "

"In this case, we can just use the default implementation provided by the API"

" function :c:func:`PyType_GenericNew`. ::"

msgstr ""

"要启用对象创建，我们必须提供一个 :c:member:`~PyTypeObject.tp_new` 处理器。 这等价于 Python 方法 "

":meth:`~object.__new__`，但必须显式地指定。 在这种情况下，我们可以使用 API 函数 "

":c:func:`PyType_GenericNew` 所提供的默认实现。 ::"

#: ../../extending/newtypes_tutorial.rst:171

msgid ".tp_new = PyType_GenericNew,"

msgstr ".tp_new = PyType_GenericNew,"

#: ../../extending/newtypes_tutorial.rst:173

msgid ""

"Everything else in the file should be familiar, except for some code in "

":c:func:`!PyInit_custom`::"

msgstr "除了 :c:func:`!PyInit_custom` 中的某些代码以外，文件中的其他内容应该都很容易理解::"

#: ../../extending/newtypes_tutorial.rst:176

msgid ""

"if (PyType_Ready(&CustomType) < 0)\n"

" return;"

msgstr ""

"if (PyType_Ready(&CustomType) < 0)\n"

" return;"

#: ../../extending/newtypes_tutorial.rst:179

msgid ""

"This initializes the :class:`!Custom` type, filling in a number of members "

"to the appropriate default values, including :c:member:`~PyObject.ob_type` "

"that we initially set to ``NULL``. ::"

msgstr ""

"这将初始化 :class:`!Custom` 类型，为一些成员填充适当的默认值，包括我们在初始时设为 ``NULL`` 的 "

":c:member:`~PyObject.ob_type`。 ::"

#: ../../extending/newtypes_tutorial.rst:183

msgid ""

"Py_INCREF(&CustomType);\n"

"if (PyModule_AddObject(m, \"Custom\", (PyObject *) &CustomType) < 0) {\n"

" Py_DECREF(&CustomType);\n"

" Py_DECREF(m);\n"

" return NULL;\n"

"}"

msgstr ""

#: ../../extending/newtypes_tutorial.rst:190

msgid ""

"This adds the type to the module dictionary. This allows us to create "

":class:`!Custom` instances by calling the :class:`!Custom` class:"

msgstr "这将把类型添加到模块字典中。 这样我们就能通过调用 :class:`!Custom` 类来创建 :class:`!Custom` 实例："

#: ../../extending/newtypes_tutorial.rst:193

msgid ""

">>> import custom\n"

">>> mycustom = custom.Custom()"

msgstr ""

">>> import custom\n"

">>> mycustom = custom.Custom()"

#: ../../extending/newtypes_tutorial.rst:198

msgid ""

"That's it! All that remains is to build it; put the above code in a file "

"called :file:`custom.c`,"

msgstr "就是这样！ 剩下的工作就是编译它；将上述代码放入名为 :file:`custom.c` 的文件中，"

#: ../../extending/newtypes_tutorial.rst:201

msgid ""

"[build-system]\n"

"requires = [\"setuptools\"]\n"

"build-backend = \"setuptools.build_meta\"\n"

"\n"

"[project]\n"

"name = \"custom\"\n"

"version = \"1\"\n"

msgstr ""

"[build-system]\n"

"requires = [\"setuptools\"]\n"

"build-backend = \"setuptools.build_meta\"\n"

"\n"

"[project]\n"

"name = \"custom\"\n"

"version = \"1\"\n"

#: ../../extending/newtypes_tutorial.rst:203

msgid "in a file called :file:`pyproject.toml`, and"

msgstr "名为 :file:`pyproject.toml` 的文件中，并且"

#: ../../extending/newtypes_tutorial.rst:205

msgid ""

"from setuptools import Extension, setup\n"

"setup(ext_modules=[Extension(\"custom\", [\"custom.c\"])])"

msgstr ""

"from setuptools import Extension, setup\n"

"setup(ext_modules=[Extension(\"custom\", [\"custom.c\"])])"

#: ../../extending/newtypes_tutorial.rst:210

msgid "in a file called :file:`setup.py`; then typing"

msgstr "在名为 :file:`setup.py` 的文件中；然后输入"

#: ../../extending/newtypes_tutorial.rst:212

#: ../../extending/newtypes_tutorial.rst:527

msgid "$ python -m pip install ."

msgstr "$ python -m pip install ."

#: ../../extending/newtypes_tutorial.rst:216

msgid ""

"in a shell should produce a file :file:`custom.so` in a subdirectory and "

"install it; now fire up Python --- you should be able to ``import custom`` "

"and play around with ``Custom`` objects."

msgstr ""

"在 shell 中应该会在子目录下产生一个文件 :file:`custom.so` 并安装它；现在启动 Python --- 你应当能够执行 "

"``import custom`` 并尝试使用 ``Custom`` 对象。"

#: ../../extending/newtypes_tutorial.rst:220

msgid "That wasn't so hard, was it?"

msgstr "这并不难，对吗？"

#: ../../extending/newtypes_tutorial.rst:222

msgid ""

"Of course, the current Custom type is pretty uninteresting. It has no data "

"and doesn't do anything. It can't even be subclassed."

msgstr "当然，当前的自定义类型非常无趣。它没有数据，也不做任何事情。它甚至不能被子类化。"

#: ../../extending/newtypes_tutorial.rst:227

msgid "Adding data and methods to the Basic example"

msgstr "向基本示例添加数据和方法"

#: ../../extending/newtypes_tutorial.rst:229

msgid ""

"Let's extend the basic example to add some data and methods. Let's also "

"make the type usable as a base class. We'll create a new module, "

":mod:`!custom2` that adds these capabilities:"

msgstr ""

"让我们通过添加一些数据和方法来扩展这个基本示例。 让我们再使该类型可以作为基类使用。 我们将创建一个新模块 :mod:`!custom2` "

"来添加这些功能："

#: ../../extending/newtypes_tutorial.rst:233

msgid ""

"#define PY_SSIZE_T_CLEAN\n"

"#include <Python.h>\n"

"#include <stddef.h> /* for offsetof() */\n"

"\n"

"typedef struct {\n"

" PyObject_HEAD\n"

" PyObject *first; /* first name */\n"

" PyObject *last; /* last name */\n"

" int number;\n"

"} CustomObject;\n"

"\n"

"static void\n"

"Custom_dealloc(CustomObject *self)\n"

"{\n"

" Py_XDECREF(self->first);\n"

" Py_XDECREF(self->last);\n"

" Py_TYPE(self)->tp_free((PyObject *) self);\n"

"}\n"

"\n"

"static PyObject *\n"

"Custom_new(PyTypeObject *type, PyObject *args, PyObject *kwds)\n"

"{\n"

" CustomObject *self;\n"

" self = (CustomObject *) type->tp_alloc(type, 0);\n"

" if (self != NULL) {\n"

" self->first = PyUnicode_FromString(\"\");\n"

" if (self->first == NULL) {\n"

" Py_DECREF(self);\n"

" return NULL;\n"

" }\n"

" self->last = PyUnicode_FromString(\"\");\n"

" if (self->last == NULL) {\n"

" Py_DECREF(self);\n"

" return NULL;\n"

" }\n"

" self->number = 0;\n"

" }\n"

" return (PyObject *) self;\n"

"}\n"

"\n"

"static int\n"

"Custom_init(CustomObject *self, PyObject *args, PyObject *kwds)\n"

"{\n"

" static char *kwlist[] = {\"first\", \"last\", \"number\", NULL};\n"

" PyObject *first = NULL, *last = NULL;\n"

"\n"

" if (!PyArg_ParseTupleAndKeywords(args, kwds, \"|OOi\", kwlist,\n"

" &first, &last,\n"

" &self->number))\n"

" return -1;\n"

"\n"

" if (first) {\n"

" Py_XSETREF(self->first, Py_NewRef(first));\n"

" }\n"

" if (last) {\n"

" Py_XSETREF(self->last, Py_NewRef(last));\n"

" }\n"

" return 0;\n"

"}\n"

"\n"

"static PyMemberDef Custom_members[] = {\n"

" {\"first\", Py_T_OBJECT_EX, offsetof(CustomObject, first), 0,\n"

" \"first name\"},\n"

" {\"last\", Py_T_OBJECT_EX, offsetof(CustomObject, last), 0,\n"

" \"last name\"},\n"

" {\"number\", Py_T_INT, offsetof(CustomObject, number), 0,\n"

" \"custom number\"},\n"

" {NULL} /* Sentinel */\n"

"};\n"

"\n"

"static PyObject *\n"

"Custom_name(CustomObject *self, PyObject *Py_UNUSED(ignored))\n"

"{\n"

" if (self->first == NULL) {\n"

" PyErr_SetString(PyExc_AttributeError, \"first\");\n"

" return NULL;\n"

" }\n"

" if (self->last == NULL) {\n"

" PyErr_SetString(PyExc_AttributeError, \"last\");\n"

" return NULL;\n"

" }\n"

" return PyUnicode_FromFormat(\"%S %S\", self->first, self->last);\n"

"}\n"

"\n"

"static PyMethodDef Custom_methods[] = {\n"

" {\"name\", (PyCFunction) Custom_name, METH_NOARGS,\n"

" \"Return the name, combining the first and last name\"\n"

" },\n"

" {NULL} /* Sentinel */\n"

"};\n"

"\n"

"static PyTypeObject CustomType = {\n"

" .ob_base = PyVarObject_HEAD_INIT(NULL, 0)\n"

" .tp_name = \"custom2.Custom\",\n"

" .tp_doc = PyDoc_STR(\"Custom objects\"),\n"

" .tp_basicsize = sizeof(CustomObject),\n"

" .tp_itemsize = 0,\n"

" .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE,\n"

" .tp_new = Custom_new,\n"

" .tp_init = (initproc) Custom_init,\n"

" .tp_dealloc = (destructor) Custom_dealloc,\n"

" .tp_members = Custom_members,\n"

" .tp_methods = Custom_methods,\n"

"};\n"

"\n"

"static PyModuleDef custommodule = {\n"

" .m_base =PyModuleDef_HEAD_INIT,\n"

" .m_name = \"custom2\",\n"

" .m_doc = \"Example module that creates an extension type.\",\n"

" .m_size = -1,\n"

"};\n"

"\n"

"PyMODINIT_FUNC\n"

"PyInit_custom2(void)\n"

"{\n"

" PyObject *m;\n"

" if (PyType_Ready(&CustomType) < 0)\n"

" return NULL;\n"

"\n"

" m = PyModule_Create(&custommodule);\n"

" if (m == NULL)\n"

" return NULL;\n"

"\n"

" if (PyModule_AddObjectRef(m, \"Custom\", (PyObject *) &CustomType) < 0) {\n"

" Py_DECREF(m);\n"

" return NULL;\n"

" }\n"

"\n"

" return m;\n"

"}\n"

msgstr ""

"#define PY_SSIZE_T_CLEAN\n"

"#include <Python.h>\n"

"#include <stddef.h> /* for offsetof() */\n"

"\n"

"typedef struct {\n"

" PyObject_HEAD\n"

" PyObject *first; /* first name */\n"

" PyObject *last; /* last name */\n"

" int number;\n"

"} CustomObject;\n"

"\n"

"static void\n"

"Custom_dealloc(CustomObject *self)\n"

"{\n"

" Py_XDECREF(self->first);\n"

" Py_XDECREF(self->last);\n"

" Py_TYPE(self)->tp_free((PyObject *) self);\n"

"}\n"

"\n"

"static PyObject *\n"

"Custom_new(PyTypeObject *type, PyObject *args, PyObject *kwds)\n"

"{\n"

" CustomObject *self;\n"

" self = (CustomObject *) type->tp_alloc(type, 0);\n"

" if (self != NULL) {\n"

" self->first = PyUnicode_FromString(\"\");\n"

" if (self->first == NULL) {\n"

" Py_DECREF(self);\n"

" return NULL;\n"

" }\n"

" self->last = PyUnicode_FromString(\"\");\n"

" if (self->last == NULL) {\n"

" Py_DECREF(self);\n"

" return NULL;\n"

" }\n"

" self->number = 0;\n"

" }\n"

" return (PyObject *) self;\n"

"}\n"

"\n"

"static int\n"

"Custom_init(CustomObject *self, PyObject *args, PyObject *kwds)\n"

"{\n"

" static char *kwlist[] = {\"first\", \"last\", \"number\", NULL};\n"

" PyObject *first = NULL, *last = NULL;\n"

"\n"

" if (!PyArg_ParseTupleAndKeywords(args, kwds, \"|OOi\", kwlist,\n"

" &first, &last,\n"

" &self->number))\n"

" return -1;\n"

"\n"

" if (first) {\n"

" Py_XSETREF(self->first, Py_NewRef(first));\n"

" }\n"

" if (last) {\n"

" Py_XSETREF(self->last, Py_NewRef(last));\n"

" }\n"

" return 0;\n"

"}\n"

"\n"

"static PyMemberDef Custom_members[] = {\n"

" {\"first\", Py_T_OBJECT_EX, offsetof(CustomObject, first), 0,\n"

" \"first name\"},\n"

" {\"last\", Py_T_OBJECT_EX, offsetof(CustomObject, last), 0,\n"

" \"last name\"},\n"

" {\"number\", Py_T_INT, offsetof(CustomObject, number), 0,\n"

" \"custom number\"},\n"

" {NULL} /* Sentinel */\n"

"};\n"

"\n"

"static PyObject *\n"

"Custom_name(CustomObject *self, PyObject *Py_UNUSED(ignored))\n"

"{\n"

" if (self->first == NULL) {\n"

" PyErr_SetString(PyExc_AttributeError, \"first\");\n"

" return NULL;\n"

" }\n"

" if (self->last == NULL) {\n"

" PyErr_SetString(PyExc_AttributeError, \"last\");\n"

" return NULL;\n"

" }\n"

" return PyUnicode_FromFormat(\"%S %S\", self->first, self->last);\n"

"}\n"

"\n"

"static PyMethodDef Custom_methods[] = {\n"

" {\"name\", (PyCFunction) Custom_name, METH_NOARGS,\n"

" \"Return the name, combining the first and last name\"\n"

" },\n"

" {NULL} /* Sentinel */\n"

"};\n"

"\n"

"static PyTypeObject CustomType = {\n"

" .ob_base = PyVarObject_HEAD_INIT(NULL, 0)\n"

" .tp_name = \"custom2.Custom\",\n"

" .tp_doc = PyDoc_STR(\"Custom objects\"),\n"

" .tp_basicsize = sizeof(CustomObject),\n"

" .tp_itemsize = 0,\n"

" .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE,\n"

" .tp_new = Custom_new,\n"

" .tp_init = (initproc) Custom_init,\n"

" .tp_dealloc = (destructor) Custom_dealloc,\n"

" .tp_members = Custom_members,\n"

" .tp_methods = Custom_methods,\n"

"};\n"

"\n"

"static PyModuleDef custommodule = {\n"

" .m_base =PyModuleDef_HEAD_INIT,\n"

" .m_name = \"custom2\",\n"

" .m_doc = \"Example module that creates an extension type.\",\n"

" .m_size = -1,\n"

"};\n"

"\n"

"PyMODINIT_FUNC\n"

"PyInit_custom2(void)\n"

"{\n"

" PyObject *m;\n"

" if (PyType_Ready(&CustomType) < 0)\n"

" return NULL;\n"

"\n"

" m = PyModule_Create(&custommodule);\n"

" if (m == NULL)\n"

" return NULL;\n"

"\n"

" if (PyModule_AddObjectRef(m, \"Custom\", (PyObject *) &CustomType) < 0) {\n"

" Py_DECREF(m);\n"

" return NULL;\n"

" }\n"

"\n"

" return m;\n"

"}\n"

#: ../../extending/newtypes_tutorial.rst:236

msgid "This version of the module has a number of changes."

msgstr "该模块的新版本包含多处修改。"

#: ../../extending/newtypes_tutorial.rst:238

msgid ""

"The :class:`!Custom` type now has three data attributes in its C struct, "

"*first*, *last*, and *number*. The *first* and *last* variables are Python "

"strings containing first and last names. The *number* attribute is a C "

"integer."

msgstr ""

"现在 :class:`!Custom` 类型的 C 结构体中有三个数据属性，*first*、*last* 和 *number*。 其中 *first* "

"和 *last* 变量是包含名字和姓氏的 Python 字符串。 *number* 属性是一个 C 整数。"

#: ../../extending/newtypes_tutorial.rst:242

msgid "The object structure is updated accordingly::"

msgstr "对象的结构将被相应地更新::"

#: ../../extending/newtypes_tutorial.rst:244

msgid ""

"typedef struct {\n"

" PyObject_HEAD\n"

" PyObject *first; /* first name */\n"

" PyObject *last; /* last name */\n"

" int number;\n"

"} CustomObject;"

msgstr ""

"typedef struct {\n"

" PyObject_HEAD\n"

" PyObject *first; /* first name */\n"

" PyObject *last; /* last name */\n"

" int number;\n"

"} CustomObject;"

#: ../../extending/newtypes_tutorial.rst:251

msgid ""

"Because we now have data to manage, we have to be more careful about object "

"allocation and deallocation. At a minimum, we need a deallocation method::"

msgstr "因为现在我们有数据需要管理，我们必须更加小心地处理对象的分配和释放。 至少，我们需要有一个释放方法::"

#: ../../extending/newtypes_tutorial.rst:254

msgid ""

"static void\n"

"Custom_dealloc(CustomObject *self)\n"

"{\n"

" Py_XDECREF(self->first);\n"

" Py_XDECREF(self->last);\n"

" Py_TYPE(self)->tp_free((PyObject *) self);\n"

"}"

msgstr ""

"static void\n"

"Custom_dealloc(CustomObject *self)\n"

"{\n"

" Py_XDECREF(self->first);\n"

" Py_XDECREF(self->last);\n"

" Py_TYPE(self)->tp_free((PyObject *) self);\n"

"}"

#: ../../extending/newtypes_tutorial.rst:262

msgid "which is assigned to the :c:member:`~PyTypeObject.tp_dealloc` member::"

msgstr "它会被赋值给 :c:member:`~PyTypeObject.tp_dealloc` 成员::"

#: ../../extending/newtypes_tutorial.rst:264

msgid ".tp_dealloc = (destructor) Custom_dealloc,"

msgstr ".tp_dealloc = (destructor) Custom_dealloc,"

#: ../../extending/newtypes_tutorial.rst:266

msgid ""

"This method first clears the reference counts of the two Python attributes. "

":c:func:`Py_XDECREF` correctly handles the case where its argument is "

"``NULL`` (which might happen here if ``tp_new`` failed midway). It then "

"calls the :c:member:`~PyTypeObject.tp_free` member of the object's type "

"(computed by ``Py_TYPE(self)``) to free the object's memory. Note that the "

"object's type might not be :class:`!CustomType`, because the object may be "

"an instance of a subclass."

msgstr ""

"此方法会先清空两个 Python 属性的引用计数。 :c:func:`Py_XDECREF` 可以正确处理参数为 ``NULL`` 的情况（这可能在 "

"``tp_new`` 中途失败时发生）。 随后它将调用对象类型的 :c:member:`~PyTypeObject.tp_free` 成员（通过 "

"``Py_TYPE(self)`` 计算得到）来释放对象的内存。 请注意对象类型可以不是 "

":class:`!CustomType`，因为对象可能是一个子类的实例。"

#: ../../extending/newtypes_tutorial.rst:275

msgid ""

"The explicit cast to ``destructor`` above is needed because we defined "

"``Custom_dealloc`` to take a ``CustomObject *`` argument, but the "

"``tp_dealloc`` function pointer expects to receive a ``PyObject *`` "

"argument. Otherwise, the compiler will emit a warning. This is object-"

"oriented polymorphism, in C!"

msgstr ""

"上面需要强制转换 ``destructor`` 是因为我们定义了 ``Custom_dealloc`` 接受一个 ``CustomObject *`` "

"参数，但 ``tp_dealloc`` 函数指针预期接受一个 ``PyObject *`` 参数。 如果不这样做，编译器将发出警告。 这是 C "

"语言中面向对象的多态性！"

#: ../../extending/newtypes_tutorial.rst:281

msgid ""

"We want to make sure that the first and last names are initialized to empty "

"strings, so we provide a ``tp_new`` implementation::"

msgstr "我们希望确保头一个和末一个名称被初始化为空字符串，因此我们提供了一个 ``tp_new`` 实现::"

#: ../../extending/newtypes_tutorial.rst:284

msgid ""

"static PyObject *\n"

"Custom_new(PyTypeObject *type, PyObject *args, PyObject *kwds)\n"

"{\n"

" CustomObject *self;\n"

" self = (CustomObject *) type->tp_alloc(type, 0);\n"

" if (self != NULL) {\n"

" self->first = PyUnicode_FromString(\"\");\n"

" if (self->first == NULL) {\n"

" Py_DECREF(self);\n"

" return NULL;\n"

" }\n"

" self->last = PyUnicode_FromString(\"\");\n"

" if (self->last == NULL) {\n"

" Py_DECREF(self);\n"

" return NULL;\n"

" }\n"

" self->number = 0;\n"

" }\n"

" return (PyObject *) self;\n"

"}"

msgstr ""

"static PyObject *\n"

"Custom_new(PyTypeObject *type, PyObject *args, PyObject *kwds)\n"

"{\n"

" CustomObject *self;\n"

" self = (CustomObject *) type->tp_alloc(type, 0);\n"

" if (self != NULL) {\n"

" self->first = PyUnicode_FromString(\"\");\n"

" if (self->first == NULL) {\n"

" Py_DECREF(self);\n"

" return NULL;\n"

" }\n"

" self->last = PyUnicode_FromString(\"\");\n"

" if (self->last == NULL) {\n"

" Py_DECREF(self);\n"

" return NULL;\n"

" }\n"

" self->number = 0;\n"

" }\n"

" return (PyObject *) self;\n"

"}"

#: ../../extending/newtypes_tutorial.rst:305

msgid "and install it in the :c:member:`~PyTypeObject.tp_new` member::"

msgstr "并在 :c:member:`~PyTypeObject.tp_new` 成员中安装它::"

#: ../../extending/newtypes_tutorial.rst:307

msgid ".tp_new = Custom_new,"

msgstr ".tp_new = Custom_new,"

#: ../../extending/newtypes_tutorial.rst:309

msgid ""

"The ``tp_new`` handler is responsible for creating (as opposed to "

"initializing) objects of the type. It is exposed in Python as the "

":meth:`~object.__new__` method. It is not required to define a ``tp_new`` "

"member, and indeed many extension types will simply reuse "

":c:func:`PyType_GenericNew` as done in the first version of the "

":class:`!Custom` type above. In this case, we use the ``tp_new`` handler to"

" initialize the ``first`` and ``last`` attributes to non-``NULL`` default "

"values."

msgstr ""

"``tp_new`` 处理器负责创建（而不是初始化）该类型的对象。 它在 Python 中被暴露为 :meth:`~object.__new__` "

"方法。 它不需要定义 ``tp_new`` 成员，实际上许多扩展类型会简单地重用 :c:func:`PyType_GenericNew`，就像上面 "

":class:`!Custom` 类型的第一个版本所做的那样。 在此情况下，我们使用 ``tp_new`` 处理器来将 ``first`` 和 "

"``last`` 属性初始化为非 ``NULL`` 的默认值。"

#: ../../extending/newtypes_tutorial.rst:317

msgid ""

"``tp_new`` is passed the type being instantiated (not necessarily "

"``CustomType``, if a subclass is instantiated) and any arguments passed when"

" the type was called, and is expected to return the instance created. "

"``tp_new`` handlers always accept positional and keyword arguments, but they"

" often ignore the arguments, leaving the argument handling to initializer "

"(a.k.a. ``tp_init`` in C or ``__init__`` in Python) methods."

msgstr ""

"``tp_new`` 将接受被实例化的类型（不要求为 "

"``CustomType``，如果被实例化的是一个子类）以及在该类型被调用时传入的任何参数，并预期返回所创建的实例。 ``tp_new`` "

"处理器总是接受位置和关键字参数，但它们总是会忽略这些参数，而将参数处理留给初始化（即 C 中的 ``tp_init`` 或 Python 中的 "

"``__init__`` 函数）方法来执行。"

#: ../../extending/newtypes_tutorial.rst:325

msgid ""

"``tp_new`` shouldn't call ``tp_init`` explicitly, as the interpreter will do"

" it itself."

msgstr "``tp_new`` 不应显式地调用 ``tp_init``，因为解释器会自行调用它。"

#: ../../extending/newtypes_tutorial.rst:328

msgid ""

"The ``tp_new`` implementation calls the :c:member:`~PyTypeObject.tp_alloc` "

"slot to allocate memory::"

msgstr "``tp_new`` 实现会调用 :c:member:`~PyTypeObject.tp_alloc` 槽位来分配内存::"

#: ../../extending/newtypes_tutorial.rst:331

msgid "self = (CustomObject *) type->tp_alloc(type, 0);"

msgstr "self = (CustomObject *) type->tp_alloc(type, 0);"

#: ../../extending/newtypes_tutorial.rst:333

msgid ""

"Since memory allocation may fail, we must check the "

":c:member:`~PyTypeObject.tp_alloc` result against ``NULL`` before "

"proceeding."

msgstr ""

"由于内存分配可能会失败，我们必须在继续执行之前检查 :c:member:`~PyTypeObject.tp_alloc` 结果确认其不为 "

"``NULL``。"

#: ../../extending/newtypes_tutorial.rst:337

msgid ""

"We didn't fill the :c:member:`~PyTypeObject.tp_alloc` slot ourselves. Rather"

" :c:func:`PyType_Ready` fills it for us by inheriting it from our base "

"class, which is :class:`object` by default. Most types use the default "

"allocation strategy."

msgstr ""

"我们没有自行填充 :c:member:`~PyTypeObject.tp_alloc` 槽位。 而是由 :c:func:`PyType_Ready` "

"通过从我们的基类继承来替我们填充它，其中默认为 :class:`object`。 大部分类型都是使用默认的分配策略。"

#: ../../extending/newtypes_tutorial.rst:343

msgid ""

"If you are creating a co-operative :c:member:`~PyTypeObject.tp_new` (one "

"that calls a base type's :c:member:`~PyTypeObject.tp_new` or "

":meth:`~object.__new__`), you must *not* try to determine what method to "

"call using method resolution order at runtime. Always statically determine "

"what type you are going to call, and call its "

":c:member:`~PyTypeObject.tp_new` directly, or via ``type->tp_base->tp_new``."