# 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:

# python-doc bot, 2025

#

#, fuzzy

msgid ""

msgstr ""

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

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

"POT-Creation-Date: 2025-01-03 16:35+0000\n"

"PO-Revision-Date: 2025-09-22 17:54+0000\n"

"Last-Translator: python-doc bot, 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.rst:7

msgid "Defining Extension Types: Assorted Topics"

msgstr "定义扩展类型：已分类主题"

#: ../../extending/newtypes.rst:11

msgid ""

"This section aims to give a quick fly-by on the various type methods you can"

" implement and what they do."

msgstr "本章节目标是提供一个各种你可以实现的类型方法及其功能的简短介绍。"

#: ../../extending/newtypes.rst:14

msgid ""

"Here is the definition of :c:type:`PyTypeObject`, with some fields only used"

" in debug builds omitted:"

msgstr "这是C类型 :c:type:`PyTypeObject` 的定义，省略了只用于调试构建的字段:"

#: ../../extending/newtypes.rst:20

msgid ""

"Now that's a *lot* of methods. Don't worry too much though -- if you have a"

" type you want to define, the chances are very good that you will only "

"implement a handful of these."

msgstr "这里有 *很多* 方法。但是不要太担心，如果你要定义一个类型，通常只需要实现少量的方法。"

#: ../../extending/newtypes.rst:24

msgid ""

"As you probably expect by now, we're going to go over this and give more "

"information about the various handlers. We won't go in the order they are "

"defined in the structure, because there is a lot of historical baggage that "

"impacts the ordering of the fields. It's often easiest to find an example "

"that includes the fields you need and then change the values to suit your "

"new type. ::"

msgstr ""

"正如你猜到的一样，我们正要一步一步详细介绍各种处理程序。因为有大量的历史包袱影响字段的排序，所以我们不会根据它们在结构体里定义的顺序讲解。通常非常容易找到一个包含你需要的字段的例子，然后改变值去适应你新的类型。"

#: ../../extending/newtypes.rst:33

msgid ""

"The name of the type -- as mentioned in the previous chapter, this will "

"appear in various places, almost entirely for diagnostic purposes. Try to "

"choose something that will be helpful in such a situation! ::"

msgstr "类型的名字 - 上一章提到过的，会出现在很多地方，几乎全部都是为了诊断目的。尝试选择一个好名字，对于诊断很有帮助。"

#: ../../extending/newtypes.rst:39

msgid ""

"These fields tell the runtime how much memory to allocate when new objects "

"of this type are created. Python has some built-in support for variable "

"length structures (think: strings, tuples) which is where the "

":c:member:`~PyTypeObject.tp_itemsize` field comes in. This will be dealt "

"with later. ::"

msgstr ""

"这些字段告诉运行时在创造这个类型的新对象时需要分配多少内存。Python为了可变长度的结构（想下：字符串，元组）有些内置支持，这是 "

":c:member:`~PyTypeObject.tp_itemsize` 字段存在的原由。这部分稍后解释。"

#: ../../extending/newtypes.rst:46

msgid ""

"Here you can put a string (or its address) that you want returned when the "

"Python script references ``obj.__doc__`` to retrieve the doc string."

msgstr "这里你可以放置一段字符串（或者它的地址），当你想在Python脚本引用 ``obj.__doc__`` 时返回这段文档字符串。"

#: ../../extending/newtypes.rst:49

msgid ""

"Now we come to the basic type methods -- the ones most extension types will "

"implement."

msgstr "现在我们来看一下基本类型方法 - 大多数扩展类型将实现的方法。"

#: ../../extending/newtypes.rst:54

msgid "Finalization and De-allocation"

msgstr "终结和内存释放"

#: ../../extending/newtypes.rst:66

msgid ""

"This function is called when the reference count of the instance of your "

"type is reduced to zero and the Python interpreter wants to reclaim it. If "

"your type has memory to free or other clean-up to perform, you can put it "

"here. The object itself needs to be freed here as well. Here is an example"

" of this function::"

msgstr ""

"当您的类型实例的引用计数减少为零并且Python解释器想要回收它时，将调用此函数。如果你的类型有内存可供释放或执行其他清理，你可以把它放在这里。 "

"对象本身也需要在这里释放。 以下是此函数的示例："

#: ../../extending/newtypes.rst:79

msgid ""

"If your type supports garbage collection, the destructor should call "

":c:func:`PyObject_GC_UnTrack` before clearing any member fields::"

msgstr "如果你的类型支持垃圾回收，则析构器应当在清理任何成员字段之前调用 :c:func:`PyObject_GC_UnTrack`::"

#: ../../extending/newtypes.rst:95

msgid ""

"One important requirement of the deallocator function is that it leaves any "

"pending exceptions alone. This is important since deallocators are "

"frequently called as the interpreter unwinds the Python stack; when the "

"stack is unwound due to an exception (rather than normal returns), nothing "

"is done to protect the deallocators from seeing that an exception has "

"already been set. Any actions which a deallocator performs which may cause "

"additional Python code to be executed may detect that an exception has been "

"set. This can lead to misleading errors from the interpreter. The proper "

"way to protect against this is to save a pending exception before performing"

" the unsafe action, and restoring it when done. This can be done using the "

":c:func:`PyErr_Fetch` and :c:func:`PyErr_Restore` functions::"

msgstr ""

"一个重要的释放器函数实现要求是把所有未决异常放着不动。这很重要是因为释放器会被解释器频繁的调用，当栈异常退出时(而非正常返回)，不会有任何办法保护释放器看到一个异常尚未被设置。此事释放器的任何行为都会导致额外增加的Python代码来检查异常是否被设置。这可能导致解释器的误导性错误。正确的保护方法是，在任何不安全的操作前，保存未决异常，然后在其完成后恢复。者可以通过"

" :c:func:`PyErr_Fetch` 和 :c:func:`PyErr_Restore` 函数来实现::"

#: ../../extending/newtypes.rst:134

msgid ""

"There are limitations to what you can safely do in a deallocator function. "

"First, if your type supports garbage collection (using "

":c:member:`~PyTypeObject.tp_traverse` and/or "

":c:member:`~PyTypeObject.tp_clear`), some of the object's members can have "

"been cleared or finalized by the time :c:member:`~PyTypeObject.tp_dealloc` "

"is called. Second, in :c:member:`~PyTypeObject.tp_dealloc`, your object is "

"in an unstable state: its reference count is equal to zero. Any call to a "

"non-trivial object or API (as in the example above) might end up calling "

":c:member:`~PyTypeObject.tp_dealloc` again, causing a double free and a "

"crash."

msgstr ""

"你能在释放器函数中安全执行的操作是有限的。 首先，如果你的类型支持垃圾回收 (使用 "

":c:member:`~PyTypeObject.tp_traverse` 和/或 "

":c:member:`~PyTypeObject.tp_clear`)，对象的部分成员可以在调用 "

":c:member:`~PyTypeObject.tp_dealloc` 时被清空或终结。 其次，在 "

":c:member:`~PyTypeObject.tp_dealloc` 中，你的对象将处于不稳定状态：它的引用计数等于零。 任何对非琐碎对象或 API"

" 的调用 (如上面的示例所做的) 最终都可能会再次调用 "

":c:member:`~PyTypeObject.tp_dealloc`，导致双重释放并发生崩溃。"

#: ../../extending/newtypes.rst:143

msgid ""

"Starting with Python 3.4, it is recommended not to put any complex "

"finalization code in :c:member:`~PyTypeObject.tp_dealloc`, and instead use "

"the new :c:member:`~PyTypeObject.tp_finalize` type method."

msgstr ""

"从 Python 3.4 开始，推荐不要在 :c:member:`~PyTypeObject.tp_dealloc` 放复杂的终结代码，而是使用新的 "

":c:member:`~PyTypeObject.tp_finalize` 类型方法。"

#: ../../extending/newtypes.rst:148

msgid ":pep:`442` explains the new finalization scheme."

msgstr ":pep:`442` 解释了新的终结方案。"

#: ../../extending/newtypes.rst:155

msgid "Object Presentation"

msgstr "对象展示"

#: ../../extending/newtypes.rst:157

msgid ""

"In Python, there are two ways to generate a textual representation of an "

"object: the :func:`repr` function, and the :func:`str` function. (The "

":func:`print` function just calls :func:`str`.) These handlers are both "

"optional."

msgstr ""

"在 Python 中，有两种方式可以生成对象的文本表示: :func:`repr` 函数和 :func:`str` 函数。 (:func:`print`"

" 函数会直接调用 :func:`str`。) 这些处理程序都是可选的。"

#: ../../extending/newtypes.rst:166

msgid ""

"The :c:member:`~PyTypeObject.tp_repr` handler should return a string object "

"containing a representation of the instance for which it is called. Here is"

" a simple example::"

msgstr ""

":c:member:`~PyTypeObject.tp_repr` 处理程序应该返回一个字符串对象，其中包含调用它的实例的表示形式。 "

"下面是一个简单的例子::"

#: ../../extending/newtypes.rst:177

msgid ""

"If no :c:member:`~PyTypeObject.tp_repr` handler is specified, the "

"interpreter will supply a representation that uses the type's "

":c:member:`~PyTypeObject.tp_name` and a uniquely-identifying value for the "

"object."

msgstr ""

"如果没有指定 :c:member:`~PyTypeObject.tp_repr` 处理程序，解释器将提供一个使用 "

":c:member:`~PyTypeObject.tp_name` 的表示形式以及对象的惟一标识值。"

#: ../../extending/newtypes.rst:181

msgid ""

"The :c:member:`~PyTypeObject.tp_str` handler is to :func:`str` what the "

":c:member:`~PyTypeObject.tp_repr` handler described above is to "

":func:`repr`; that is, it is called when Python code calls :func:`str` on an"

" instance of your object. Its implementation is very similar to the "

":c:member:`~PyTypeObject.tp_repr` function, but the resulting string is "

"intended for human consumption. If :c:member:`~PyTypeObject.tp_str` is not "

"specified, the :c:member:`~PyTypeObject.tp_repr` handler is used instead."

msgstr ""

":c:member:`~PyTypeObject.tp_str` 处理器对于 :func:`str` 就如上述的 "

":c:member:`~PyTypeObject.tp_repr` 处理器对于 :func:`repr` 一样；也就是说，它会在当 Python "

"代码在你的对象的某个实例上调用 :func:`str` 时被调用。 它的实现与 :c:member:`~PyTypeObject.tp_repr` "

"函数非常相似，但其结果字符串是供人类查看的。 如果未指定 :c:member:`~PyTypeObject.tp_str`，则会使用 "

":c:member:`~PyTypeObject.tp_repr` 处理器来代替。"

#: ../../extending/newtypes.rst:188

msgid "Here is a simple example::"

msgstr "下面是一个简单的例子::"

#: ../../extending/newtypes.rst:200

msgid "Attribute Management"

msgstr "属性管理"

#: ../../extending/newtypes.rst:202

msgid ""

"For every object which can support attributes, the corresponding type must "

"provide the functions that control how the attributes are resolved. There "

"needs to be a function which can retrieve attributes (if any are defined), "

"and another to set attributes (if setting attributes is allowed). Removing "

"an attribute is a special case, for which the new value passed to the "

"handler is ``NULL``."

msgstr ""

"对于每个可支持属性操作的对象，相应的类型必须提供用于控制属性获取方式的函数。 "

"需要有一个能够检索属性的函数（如果定义了任何属性）还要有另一个函数负责设置属性（如果允许设置属性）。 "

"移除属性是一种特殊情况，在此情况下要传给处理器的新值为 ``NULL``。"

#: ../../extending/newtypes.rst:208

msgid ""

"Python supports two pairs of attribute handlers; a type that supports "

"attributes only needs to implement the functions for one pair. The "

"difference is that one pair takes the name of the attribute as a "

":c:type:`char\\*`, while the other accepts a :c:type:`PyObject\\*`. Each "

"type can use whichever pair makes more sense for the implementation's "

"convenience. ::"

msgstr ""

"Python 支持两对属性处理器；一个支持属性操作的类型只需要实现其中一对的函数。 两者的差别在于一对接受 :c:type:`char\\*` "

"作为属性名称，而另一对则接受 :c:type:`PyObject\\*`。 每种类型都可以选择使用对于实现的便利性来说更有意义的那一对。 ::"

#: ../../extending/newtypes.rst:220

msgid ""

"If accessing attributes of an object is always a simple operation (this will"

" be explained shortly), there are generic implementations which can be used "

"to provide the :c:type:`PyObject\\*` version of the attribute management "

"functions. The actual need for type-specific attribute handlers almost "

"completely disappeared starting with Python 2.2, though there are many "

"examples which have not been updated to use some of the new generic "

"mechanism that is available."

msgstr ""

"如果访问一个对象的属性总是属于简单操作（这将在下文进行解释），则有一些泛用实现可被用来提供 :c:type:`PyObject\\*` "

"版本的属性管理函数。 从 Python 2.2 "

"开始对于类型专属的属性处理器的实际需要几乎已完全消失，尽管还存在着许多尚未更新为使用某种新的可选泛用机制的例子。"

#: ../../extending/newtypes.rst:231

msgid "Generic Attribute Management"

msgstr "泛型属性管理"

#: ../../extending/newtypes.rst:233

msgid ""

"Most extension types only use *simple* attributes. So, what makes the "

"attributes simple? There are only a couple of conditions that must be met:"

msgstr "大多数扩展类型只使用 **简单** 属性，那么，是什么让属性变得“简单”呢？只需要满足下面几个条件："

#: ../../extending/newtypes.rst:236

msgid ""

"The name of the attributes must be known when :c:func:`PyType_Ready` is "

"called."

msgstr "当调用 :c:func:`PyType_Ready` 时，必须知道属性的名称。"

#: ../../extending/newtypes.rst:239

msgid ""

"No special processing is needed to record that an attribute was looked up or"

" set, nor do actions need to be taken based on the value."

msgstr "不需要特殊的处理来记录属性是否被查找或设置，也不需要根据值采取操作。"

#: ../../extending/newtypes.rst:242

msgid ""

"Note that this list does not place any restrictions on the values of the "

"attributes, when the values are computed, or how relevant data is stored."

msgstr "请注意，此列表不对属性的值、值的计算时间或相关数据的存储方式施加任何限制。"

#: ../../extending/newtypes.rst:245

msgid ""

"When :c:func:`PyType_Ready` is called, it uses three tables referenced by "

"the type object to create :term:`descriptor`\\s which are placed in the "

"dictionary of the type object. Each descriptor controls access to one "

"attribute of the instance object. Each of the tables is optional; if all "

"three are ``NULL``, instances of the type will only have attributes that are"

" inherited from their base type, and should leave the "

":c:member:`~PyTypeObject.tp_getattro` and "

":c:member:`~PyTypeObject.tp_setattro` fields ``NULL`` as well, allowing the "

"base type to handle attributes."

msgstr ""

"当 :c:func:`PyType_Ready` 被调用时，它会使用由类型对象所引用的三个表来创建要放置到类型对象的字典中的 "

":term:`descriptor`。 每个描述器控制对实例对象的一个属性的访问。 每个表都是可选的；如果三个表全都为 "

"``NULL``，则该类型的实例将只有从它们的基础类型继承来的属性，并且还应当让 "

":c:member:`~PyTypeObject.tp_getattro` 和 "

":c:member:`~PyTypeObject.tp_setattro` 字段保持为 ``NULL``，以允许由基础类型处理这些属性。"

#: ../../extending/newtypes.rst:253

msgid "The tables are declared as three fields of the type object::"

msgstr "表被声明为object::类型的三个字段::"

#: ../../extending/newtypes.rst:259

msgid ""

"If :c:member:`~PyTypeObject.tp_methods` is not ``NULL``, it must refer to an"

" array of :c:type:`PyMethodDef` structures. Each entry in the table is an "

"instance of this structure::"

msgstr ""

"如果 :c:member:`~PyTypeObject.tp_methods` 不为 ``NULL``，则它必须指向一个由 "

":c:type:`PyMethodDef` 结构体组成的数组。 表中的每个条目都是该结构体的一个实例::"

#: ../../extending/newtypes.rst:270

msgid ""

"One entry should be defined for each method provided by the type; no entries"

" are needed for methods inherited from a base type. One additional entry is"

" needed at the end; it is a sentinel that marks the end of the array. The "

":attr:`ml_name` field of the sentinel must be ``NULL``."

msgstr ""

"应当为该类型所提供的每个方法都定义一个条目；从基础类型继承来的方法不需要条目。 还需要在末尾加一个额外的条目；它是一个标记数组结束的哨兵条目。 "

"该哨兵条目的 :attr:`ml_name` 字段必须为 ``NULL``。"

#: ../../extending/newtypes.rst:275

msgid ""

"The second table is used to define attributes which map directly to data "

"stored in the instance. A variety of primitive C types are supported, and "

"access may be read-only or read-write. The structures in the table are "

"defined as::"

msgstr "第二个表被用来定义要直接映射到实例中的数据的属性。 各种原始 C 类型均受到支持，并且访问方式可以为只读或读写。 表中的结构体被定义为::"

#: ../../extending/newtypes.rst:287

msgid ""

"For each entry in the table, a :term:`descriptor` will be constructed and "

"added to the type which will be able to extract a value from the instance "

"structure. The :attr:`type` field should contain one of the type codes "

"defined in the :file:`structmember.h` header; the value will be used to "

"determine how to convert Python values to and from C values. The "

":attr:`flags` field is used to store flags which control how the attribute "

"can be accessed."

msgstr ""

"对于表中的每个条目，将构建一个 :term:`descriptor` 并添加到类型中使其能够从实例结构体中提取值。 :attr:`type` "

"字段应当包含在 :file:`structmember.h` 头文件中定义的某个类型的代码；该值将被用来确定如何将 Python 值转换为 C "

"值或者反之。 :attr:`flags` 字段将被用来储存控制属性可以如何被访问的旗标。"

#: ../../extending/newtypes.rst:294

msgid ""

"The following flag constants are defined in :file:`structmember.h`; they may"

" be combined using bitwise-OR."

msgstr "以下标志常量定义在:file: ' structmember.h ';它们可以使用bitwise-OR组合。"

#: ../../extending/newtypes.rst:298

msgid "Constant"

msgstr "常量"

#: ../../extending/newtypes.rst:298

msgid "Meaning"

msgstr "含意"

#: ../../extending/newtypes.rst:300

msgid ":const:`READONLY`"

msgstr ":const:`READONLY`"

#: ../../extending/newtypes.rst:300

msgid "Never writable."

msgstr "没有可写的"

#: ../../extending/newtypes.rst:302

msgid ":const:`READ_RESTRICTED`"

msgstr ":const:`READ_RESTRICTED`"

#: ../../extending/newtypes.rst:302

msgid "Not readable in restricted mode."

msgstr "限制模式下不可写"

#: ../../extending/newtypes.rst:304

msgid ":const:`WRITE_RESTRICTED`"

msgstr ":const:`WRITE_RESTRICTED`"

#: ../../extending/newtypes.rst:304

msgid "Not writable in restricted mode."

msgstr "限制模式不可写"

#: ../../extending/newtypes.rst:306

msgid ":const:`RESTRICTED`"

msgstr ":const:`RESTRICTED`"

#: ../../extending/newtypes.rst:306

msgid "Not readable or writable in restricted mode."

msgstr "在受限模式下不可读，也不可写。"

#: ../../extending/newtypes.rst:315

msgid ""

"An interesting advantage of using the :c:member:`~PyTypeObject.tp_members` "

"table to build descriptors that are used at runtime is that any attribute "

"defined this way can have an associated doc string simply by providing the "

"text in the table. An application can use the introspection API to retrieve"

" the descriptor from the class object, and get the doc string using its "

":attr:`__doc__` attribute."

msgstr ""

"使用 :c:member:`~PyTypeObject.tp_members` "

"表来构建用于运行时的描述器还有一个有趣的优点是任何以这种方式定义的属性都可以简单地通过在表中提供文本来设置一个相关联的文档字符串。 "

"一个应用程序可以使用自省 API 从类对象获取描述器，并使用其 :attr:`__doc__` 属性来获取文档字符串。"

#: ../../extending/newtypes.rst:321

msgid ""

"As with the :c:member:`~PyTypeObject.tp_methods` table, a sentinel entry "

"with a :attr:`name` value of ``NULL`` is required."

msgstr ""

"与 :c:member:`~PyTypeObject.tp_methods` 表一样，需要有一个值为 ``NULL`` 的哨兵条目 "

":attr:`name`。"

#: ../../extending/newtypes.rst:335

msgid "Type-specific Attribute Management"

msgstr "类型专属的属性管理"

#: ../../extending/newtypes.rst:337

msgid ""

"For simplicity, only the :c:type:`char\\*` version will be demonstrated "

"here; the type of the name parameter is the only difference between the "

":c:type:`char\\*` and :c:type:`PyObject\\*` flavors of the interface. This "

"example effectively does the same thing as the generic example above, but "

"does not use the generic support added in Python 2.2. It explains how the "

"handler functions are called, so that if you do need to extend their "

"functionality, you'll understand what needs to be done."

msgstr ""

"为了简单起见，这里只演示 :c:type:`char\\*` 版本；name 形参的类型是 :c:type:`char\\*` 和 "

":c:type:`PyObject\\*` 风格接口之间的唯一区别。 这个示例实际上做了与上面的泛用示例相同的事情，但没有使用在 Python 2.2 "

"中增加的泛用支持。 它解释了处理器函数是如何被调用的，因此如果你确实需要扩展它们的功能，你就会明白有什么是需要做的。"

#: ../../extending/newtypes.rst:345

msgid ""

"The :c:member:`~PyTypeObject.tp_getattr` handler is called when the object "

"requires an attribute look-up. It is called in the same situations where "

"the :meth:`__getattr__` method of a class would be called."

msgstr ""

":c:member:`~PyTypeObject.tp_getattr` 处理器会在对象需要查找属性时被调用。 它被调用的情况与一个类的 "

":meth:`__getattr__` 方法要被调用的情况相同。"

#: ../../extending/newtypes.rst:349

msgid "Here is an example::"

msgstr "例如："

#: ../../extending/newtypes.rst:365

msgid ""

"The :c:member:`~PyTypeObject.tp_setattr` handler is called when the "

":meth:`__setattr__` or :meth:`__delattr__` method of a class instance would "

"be called. When an attribute should be deleted, the third parameter will be"

" ``NULL``. Here is an example that simply raises an exception; if this were"

" really all you wanted, the :c:member:`~PyTypeObject.tp_setattr` handler "

"should be set to ``NULL``. ::"

msgstr ""

":c:member:`~PyTypeObject.tp_setattr` 处理器会在要调用一个类实例的 :meth:`__setattr__` 或 "

":meth:`__delattr__` 方法时被调用。 当一个属性应当被删除时，第三个形参将为 ``NULL``。 "

"下面是一个简单地引发异常的例子；如果这确实是你想要的，则 :c:member:`~PyTypeObject.tp_setattr` 处理器应当被设为 "

"``NULL``。 ::"

#: ../../extending/newtypes.rst:379

msgid "Object Comparison"

msgstr "对象比较"

#: ../../extending/newtypes.rst:385

msgid ""

"The :c:member:`~PyTypeObject.tp_richcompare` handler is called when "

"comparisons are needed. It is analogous to the :ref:`rich comparison "

"methods <richcmpfuncs>`, like :meth:`__lt__`, and also called by "

":c:func:`PyObject_RichCompare` and :c:func:`PyObject_RichCompareBool`."

msgstr ""

":c:member:`~PyTypeObject.tp_richcompare` 处理器会在需要进行比较时被调用。 它类似于 :ref:`富比较方法 "

"<richcmpfuncs>`，例如 :meth:`__lt__`，并会被 :c:func:`PyObject_RichCompare` 和 "

":c:func:`PyObject_RichCompareBool` 所调用。"

#: ../../extending/newtypes.rst:390

msgid ""

"This function is called with two Python objects and the operator as "

"arguments, where the operator is one of ``Py_EQ``, ``Py_NE``, ``Py_LE``, "

"``Py_GE``, ``Py_LT`` or ``Py_GT``. It should compare the two objects with "

"respect to the specified operator and return ``Py_True`` or ``Py_False`` if "

"the comparison is successful, ``Py_NotImplemented`` to indicate that "

"comparison is not implemented and the other object's comparison method "

"should be tried, or ``NULL`` if an exception was set."

msgstr ""

"此函数被调用时将传入两个 Python 对象和运算符作为参数，其中运算符为 ``Py_EQ``, ``Py_NE``, ``Py_LE``, "

"``Py_GE``, ``Py_LT`` 或 ``Py_GT`` 之一。 它应当使用指定的运算符来比较两个对象并在比较操作成功时返回 "

"``Py_True`` 或 ``Py_False``，如果比较操作未被实现并应尝试其他对象比较方法时则返回 "

"``Py_NotImplemented``，或者如果设置了异常则返回 ``NULL``。"

#: ../../extending/newtypes.rst:398

msgid ""

"Here is a sample implementation, for a datatype that is considered equal if "

"the size of an internal pointer is equal::"

msgstr "下面是一个示例实现，该数据类型如果内部指针的大小相等就认为是相等的::"

#: ../../extending/newtypes.rst:428

msgid "Abstract Protocol Support"

msgstr "抽象协议支持"

#: ../../extending/newtypes.rst:430

msgid ""

"Python supports a variety of *abstract* 'protocols;' the specific interfaces"

" provided to use these interfaces are documented in :ref:`abstract`."

msgstr "Python 支持多种 *抽象* '协议'；被提供来使用这些接口的专门接口说明请在 :ref:`abstract` 中查看。"

#: ../../extending/newtypes.rst:434

msgid ""

"A number of these abstract interfaces were defined early in the development "

"of the Python implementation. In particular, the number, mapping, and "

"sequence protocols have been part of Python since the beginning. Other "

"protocols have been added over time. For protocols which depend on several "

"handler routines from the type implementation, the older protocols have been"

" defined as optional blocks of handlers referenced by the type object. For "

"newer protocols there are additional slots in the main type object, with a "

"flag bit being set to indicate that the slots are present and should be "

"checked by the interpreter. (The flag bit does not indicate that the slot "

"values are non-``NULL``. The flag may be set to indicate the presence of a "

"slot, but a slot may still be unfilled.) ::"

msgstr ""

"这些抽象接口很多都是在 Python 实现开发的早期被定义的。 特别地，数字、映射和序列协议从一开始就已经是 Python 的组成部分。 "

"其他协议则是后来添加的。 对于依赖某些来自类型实现的处理器例程的协议来说，较旧的协议被定义为类型对象所引用的处理器的可选块。 "

"对于较新的协议来说在主类型对象中还有额外的槽位，并带有一个预设旗标位来指明存在该槽位并应当由解释器来检查。 （此旗标位并不会指明槽位值非 "

"``NULL`` 的情况，可以设置该旗标来指明一个槽位的存在，但此本位仍可能保持未填充的状态。） ::"

#: ../../extending/newtypes.rst:449

msgid ""

"If you wish your object to be able to act like a number, a sequence, or a "

"mapping object, then you place the address of a structure that implements "

"the C type :c:type:`PyNumberMethods`, :c:type:`PySequenceMethods`, or "

":c:type:`PyMappingMethods`, respectively. It is up to you to fill in this "

"structure with appropriate values. You can find examples of the use of each "

"of these in the :file:`Objects` directory of the Python source distribution."

" ::"

msgstr ""

"如果你希望你的对象的行为类似一个数字、序列或映射对象，那么你就要分别放置一个实现了 C 类型 :c:type:`PyNumberMethods`, "

":c:type:`PySequenceMethods` 或 :c:type:`PyMappingMethods`, 的结构体的地址。 "

"你要负责将适当的值填入这些结构体。 你可以在 Python 源代码发布版的 :file:`Objects` 目录中找到这些对象各自的用法示例。 ::"

#: ../../extending/newtypes.rst:458

msgid ""

"This function, if you choose to provide it, should return a hash number for "

"an instance of your data type. Here is a simple example::"

msgstr "如果你选择提供此函数，则它应当为你的数据类型的实例返回一个哈希数值。 下面是一个简单的示例::"

#: ../../extending/newtypes.rst:471

msgid ""

":c:type:`Py_hash_t` is a signed integer type with a platform-varying width. "

"Returning ``-1`` from :c:member:`~PyTypeObject.tp_hash` indicates an error, "

"which is why you should be careful to avoid returning it when hash "

"computation is successful, as seen above."

msgstr ""

":c:type:`Py_hash_t` 是一个在宽度取决于具体平台的有符号整数类型。 从 "

":c:member:`~PyTypeObject.tp_hash` 返回 ``-1`` "

"表示发生了错误，这就是为什么你应当注意避免在哈希运算成功时返回它，如上面所演示的。"

#: ../../extending/newtypes.rst:480

msgid ""

"This function is called when an instance of your data type is \"called\", "

"for example, if ``obj1`` is an instance of your data type and the Python "

"script contains ``obj1('hello')``, the :c:member:`~PyTypeObject.tp_call` "

"handler is invoked."

msgstr ""

"此函数会在“调用”你的数据类型实例时被调用，举例来说，如果 ``obj1`` 是你的数据类型的实例而 Python 脚本包含了 "

"``obj1('hello')``，则将唤起 :c:member:`~PyTypeObject.tp_call` 处理器。"

#: ../../extending/newtypes.rst:484

msgid "This function takes three arguments:"

msgstr "此函数接受三个参数:"

#: ../../extending/newtypes.rst:486

msgid ""

"*self* is the instance of the data type which is the subject of the call. If"

" the call is ``obj1('hello')``, then *self* is ``obj1``."

msgstr "*self* 是作为调用目标的数据类型实例。 如果调用是 ``obj1('hello')``，则 *self* 为 ``obj1``。"

#: ../../extending/newtypes.rst:489

msgid ""

"*args* is a tuple containing the arguments to the call. You can use "

":c:func:`PyArg_ParseTuple` to extract the arguments."

msgstr "*args* 是包含调用参数的元组。 你可以使用 :c:func:`PyArg_ParseTuple` 来提取参数。"

#: ../../extending/newtypes.rst:492

msgid ""

"*kwds* is a dictionary of keyword arguments that were passed. If this is "

"non-``NULL`` and you support keyword arguments, use "

":c:func:`PyArg_ParseTupleAndKeywords` to extract the arguments. If you do "

"not want to support keyword arguments and this is non-``NULL``, raise a "

":exc:`TypeError` with a message saying that keyword arguments are not "

"supported."

msgstr ""

"*kwds* 是由传入的关键字参数组成的字典。 如果它不为 ``NULL`` 且你支持关键字参数，则可使用 "

":c:func:`PyArg_ParseTupleAndKeywords` 来提取参数。 如果你不想支持关键字参数而它为非 ``NULL`` "

"值，则会引发 :exc:`TypeError` 并附带一个提示不支持关键字参数的消息。"

#: ../../extending/newtypes.rst:498

msgid "Here is a toy ``tp_call`` implementation::"

msgstr "下面是一个演示性的 ``tp_call`` 实现::"

#: ../../extending/newtypes.rst:524

msgid ""

"These functions provide support for the iterator protocol. Both handlers "

"take exactly one parameter, the instance for which they are being called, "

"and return a new reference. In the case of an error, they should set an "

"exception and return ``NULL``. :c:member:`~PyTypeObject.tp_iter` "

"corresponds to the Python :meth:`__iter__` method, while "

":c:member:`~PyTypeObject.tp_iternext` corresponds to the Python "

":meth:`~iterator.__next__` method."

msgstr ""

"这些函数提供了对迭代器协议的支持。 两个处理器都只接受一个形参，即它们被调用时所使用的实例，并返回一个新的引用。 "

"当发生错误时，它们应当设置一个异常并返回 ``NULL``。 :c:member:`~PyTypeObject.tp_iter` 对应于 Python"

" :meth:`__iter__` 方法，而 :c:member:`~PyTypeObject.tp_iternext` 对应于 Python "

":meth:`~iterator.__next__` 方法。"

#: ../../extending/newtypes.rst:531

msgid ""

"Any :term:`iterable` object must implement the "

":c:member:`~PyTypeObject.tp_iter` handler, which must return an "

":term:`iterator` object. Here the same guidelines apply as for Python "

"classes:"

msgstr ""

"任何 :term:`iterable` 对象都必须实现 :c:member:`~PyTypeObject.tp_iter` 处理器，该处理器必须返回一个"

" :term:`iterator` 对象。 下面是与 Python 类所应用的同一个指导原则:"

#: ../../extending/newtypes.rst:535

msgid ""

"For collections (such as lists and tuples) which can support multiple "

"independent iterators, a new iterator should be created and returned by each"

" call to :c:member:`~PyTypeObject.tp_iter`."

msgstr ""

"对于可以支持多个独立迭代器的多项集（如列表和元组），则应当在每次调用 :c:member:`~PyTypeObject.tp_iter` "

"时创建并返回一个新的迭代器。"

#: ../../extending/newtypes.rst:538

msgid ""

"Objects which can only be iterated over once (usually due to side effects of"

" iteration, such as file objects) can implement "

":c:member:`~PyTypeObject.tp_iter` by returning a new reference to themselves"

" -- and should also therefore implement the "

":c:member:`~PyTypeObject.tp_iternext` handler."

msgstr ""

"只能被迭代一次的对象（通常是由于迭代操作的附带影响，例如文件对象）可以通过返回一个指向自身的新引用来实现 "

":c:member:`~PyTypeObject.tp_iter` -- 并且为此还应当实现 "

":c:member:`~PyTypeObject.tp_iternext` 处理器。"

#: ../../extending/newtypes.rst:543

msgid ""

"Any :term:`iterator` object should implement both "

":c:member:`~PyTypeObject.tp_iter` and :c:member:`~PyTypeObject.tp_iternext`."

" An iterator's :c:member:`~PyTypeObject.tp_iter` handler should return a "

"new reference to the iterator. Its :c:member:`~PyTypeObject.tp_iternext` "

"handler should return a new reference to the next object in the iteration, "

"if there is one. If the iteration has reached the end, "

":c:member:`~PyTypeObject.tp_iternext` may return ``NULL`` without setting an"

" exception, or it may set :exc:`StopIteration` *in addition* to returning "

"``NULL``; avoiding the exception can yield slightly better performance. If "

"an actual error occurs, :c:member:`~PyTypeObject.tp_iternext` should always "

"set an exception and return ``NULL``."

msgstr ""

"任何 :term:`iterator` 对象都应当同时实现 :c:member:`~PyTypeObject.tp_iter` 和 "

":c:member:`~PyTypeObject.tp_iternext`。 一个迭代器的 "

":c:member:`~PyTypeObject.tp_iter` 处理器应当返回一个指向该迭代器的新引用。 它的 "

":c:member:`~PyTypeObject.tp_iternext` 处理器应当返回一个指向迭代操作的下一个对象的新引用，如果还有下一个对象的话。"

" 如果迭代已到达末尾，则 :c:member:`~PyTypeObject.tp_iternext` 可以返回 ``NULL`` "

"而不设置异常，或者也可以在返回 ``NULL`` 的基础上 *额外* 设置 :exc:`StopIteration`；避免异常可以产生更好的性能。 "

"如果发生了实际的错误，则 :c:member:`~PyTypeObject.tp_iternext` 应当总是设置一个异常并返回 ``NULL``。"

#: ../../extending/newtypes.rst:559

msgid "Weak Reference Support"

msgstr "弱引用支持"

#: ../../extending/newtypes.rst:561

msgid ""

"One of the goals of Python's weak reference implementation is to allow any "

"type to participate in the weak reference mechanism without incurring the "

"overhead on performance-critical objects (such as numbers)."

msgstr ""

"One of the goals of Python 弱引用实现的目标之一是允许任意类型参与弱引用机制而不会在重视性能的对象（例如数字）上产生额外开销。"

#: ../../extending/newtypes.rst:566

msgid "Documentation for the :mod:`weakref` module."

msgstr ":mod:`weakref` 模块的文档。"

#: ../../extending/newtypes.rst:568

msgid ""

"For an object to be weakly referencable, the extension type must do two "

"things:"

msgstr "对于可弱引用的对象，扩展类型必须做两件事:"

#: ../../extending/newtypes.rst:570

msgid ""

"Include a :c:type:`PyObject\\*` field in the C object structure dedicated to"

" the weak reference mechanism. The object's constructor should leave it "

"``NULL`` (which is automatic when using the default "

":c:member:`~PyTypeObject.tp_alloc`)."

msgstr ""

"在 C 对象结构体中包括一个专门用于弱引用机制的 :c:type:`PyObject\\*` 字段。 该对象的构造器应当让它保持为 ``NULL`` "

"(当使用默认的 :c:member:`~PyTypeObject.tp_alloc` 时这将会自动设置)。"

#: ../../extending/newtypes.rst:575

msgid ""

"Set the :c:member:`~PyTypeObject.tp_weaklistoffset` type member to the "

"offset of the aforementioned field in the C object structure, so that the "

"interpreter knows how to access and modify that field."

msgstr ""

"将 :c:member:`~PyTypeObject.tp_weaklistoffset` 类型成员设置为 C "

"对象结构体中上述字段的偏移量，这样解释器就能知道如何访问和修改该字段。"

#: ../../extending/newtypes.rst:579

msgid ""

"Concretely, here is how a trivial object structure would be augmented with "

"the required field::"

msgstr "具体来说，下面是一个微小的对象结构体如何被增强为具有所需的字段::"

#: ../../extending/newtypes.rst:587

msgid "And the corresponding member in the statically-declared type object::"

msgstr "以及在静态声明的类型对象中的相应成员::"

#: ../../extending/newtypes.rst:595

msgid ""

"The only further addition is that ``tp_dealloc`` needs to clear any weak "

"references (by calling :c:func:`PyObject_ClearWeakRefs`) if the field is "

"non-``NULL``::"

msgstr ""

"唯一的额外补充是如果字段不为 ``NULL`` 则 ``tp_dealloc`` 需要清除任何弱引用 (通过调用 "

":c:func:`PyObject_ClearWeakRefs`)。::"

#: ../../extending/newtypes.rst:611

msgid "More Suggestions"

msgstr "更多建议"

#: ../../extending/newtypes.rst:613

msgid ""

"In order to learn how to implement any specific method for your new data "

"type, get the :term:`CPython` source code. Go to the :file:`Objects` "

"directory, then search the C source files for ``tp_`` plus the function you "

"want (for example, ``tp_richcompare``). You will find examples of the "

"function you want to implement."

msgstr ""

"为了学习如何为你的新数据类型实现任何特定方法，请获取 :term:`CPython` 源代码。 进入 :file:`Objects` 目录，然后在 C "

"源文件中搜索 ``tp_`` 加上你想要的函数 (例如，``tp_richcompare``)。 你将找到你想要实现的函数的例子。"

#: ../../extending/newtypes.rst:619

msgid ""

"When you need to verify that an object is a concrete instance of the type "

"you are implementing, use the :c:func:`PyObject_TypeCheck` function. A "

"sample of its use might be something like the following::"

msgstr ""

"当你需要验证一个对象是否为你实现的类型的具体实例时，请使用 :c:func:`PyObject_TypeCheck` 函数。 它的一个用法示例如下::"

#: ../../extending/newtypes.rst:630

msgid "Download CPython source releases."

msgstr "下载CPython源代码版本。"

#: ../../extending/newtypes.rst:630

msgid "https://www.python.org/downloads/source/"

msgstr "https://www.python.org/downloads/source/"

#: ../../extending/newtypes.rst:632

msgid ""

"The CPython project on GitHub, where the CPython source code is developed."

msgstr "GitHub上开发CPython源代码的CPython项目。"

#: ../../extending/newtypes.rst:633

msgid "https://github.com/python/cpython"

msgstr "https://github.com/python/cpython"