# 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/extending.rst:8

msgid "Extending Python with C or C++"

msgstr "使用 C 或 C++ 扩展 Python"

#: ../../extending/extending.rst:10

msgid ""

"It is quite easy to add new built-in modules to Python, if you know how to "

"program in C. Such :dfn:`extension modules` can do two things that can't be"

" done directly in Python: they can implement new built-in object types, and "

"they can call C library functions and system calls."

msgstr ""

"如果你会用 C，添加新的 Python 内置模块会很简单。以下两件不能用 Python 直接做的事，可以通过 :dfn:`extension "

"modules` 来实现：实现新的内置对象类型；调用 C 的库函数和系统调用。"

#: ../../extending/extending.rst:15

msgid ""

"To support extensions, the Python API (Application Programmers Interface) "

"defines a set of functions, macros and variables that provide access to most"

" aspects of the Python run-time system. The Python API is incorporated in a"

" C source file by including the header ``\"Python.h\"``."

msgstr ""

"为了支持扩展，Python API（应用程序编程接口）定义了一系列函数、宏和变量，可以访问 Python 运行时系统的大部分内容。Python 的 "

"API 可以通过在一个 C 源文件中引用 ``\"Python.h\"`` 头文件来使用。"

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

msgid ""

"The compilation of an extension module depends on its intended use as well "

"as on your system setup; details are given in later chapters."

msgstr "扩展模块的编写方式取决与你的目的以及系统设置；下面章节会详细介绍。"

#: ../../extending/extending.rst:25

msgid ""

"The C extension interface is specific to CPython, and extension modules do "

"not work on other Python implementations. In many cases, it is possible to "

"avoid writing C extensions and preserve portability to other "

"implementations. For example, if your use case is calling C library "

"functions or system calls, you should consider using the :mod:`ctypes` "

"module or the `cffi <https://cffi.readthedocs.io/>`_ library rather than "

"writing custom C code. These modules let you write Python code to interface "

"with C code and are more portable between implementations of Python than "

"writing and compiling a C extension module."

msgstr ""

"C扩展接口特指CPython，扩展模块无法在其他Python实现上工作。在大多数情况下，应该避免写C扩展，来保持可移植性。举个例子，如果你的用例调用了C库或系统调用，你应该考虑使用"

" :mod:`ctypes` 模块或 `cffi <https://cffi.readthedocs.io/>`_ "

"库，而不是自己写C代码。这些模块允许你写Python代码来接口C代码，并且相较于编写和编译C扩展模块，该方法在不同Python实现之间具有更高的可移植性。"

#: ../../extending/extending.rst:40

msgid "A Simple Example"

msgstr "一个简单的例子"

#: ../../extending/extending.rst:42

msgid ""

"Let's create an extension module called ``spam`` (the favorite food of Monty"

" Python fans...) and let's say we want to create a Python interface to the C"

" library function :c:func:`system` [#]_. This function takes a null-"

"terminated character string as argument and returns an integer. We want "

"this function to be callable from Python as follows:"

msgstr ""

"让我们创建一个扩展模块 ``spam`` (Monty Python 粉丝最喜欢的食物...) 并且想要创建对应 C 库函数 "

":c:func:`system` [#]_ 的 Python 接口。 这个函数接受一个以 null 结尾的字符串参数并返回一个整数。 我们希望可以在 "

"Python 中以如下方式调用此函数:"

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

msgid ""

"Begin by creating a file :file:`spammodule.c`. (Historically, if a module "

"is called ``spam``, the C file containing its implementation is called "

":file:`spammodule.c`; if the module name is very long, like ``spammify``, "

"the module name can be just :file:`spammify.c`.)"

msgstr ""

"首先创建一个 :file:`spammodule.c` 文件。（传统上，如果一个模块叫 ``spam``，则对应实现它的 C 文件叫 "

":file:`spammodule.c`；如果这个模块名字非常长，比如 ``spammify``，则这个模块的文件可以直接叫 "

":file:`spammify.c`。）"

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

msgid "The first two lines of our file can be::"

msgstr "文件中开始的两行是："

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

msgid ""

"which pulls in the Python API (you can add a comment describing the purpose "

"of the module and a copyright notice if you like)."

msgstr "这会导入 Python API（如果你喜欢，你可以在这里添加描述模块目标和版权信息的注释)。"

#: ../../extending/extending.rst:68

msgid ""

"Since Python may define some pre-processor definitions which affect the "

"standard headers on some systems, you *must* include :file:`Python.h` before"

" any standard headers are included."

msgstr ""

"由于 Python 可能会定义一些能在某些系统上影响标准头文件的预处理器定义，因此在包含任何标准头文件之前，你 *必须* 先包含 "

":file:`Python.h`。"

#: ../../extending/extending.rst:72

msgid ""

"It is recommended to always define ``PY_SSIZE_T_CLEAN`` before including "

"``Python.h``. See :ref:`parsetuple` for a description of this macro."

msgstr ""

"推荐总是在 ``Python.h`` 前定义 ``PY_SSIZE_T_CLEAN`` 。查看 :ref:`parsetuple` "

"来了解这个宏的更多内容。"

#: ../../extending/extending.rst:75

msgid ""

"All user-visible symbols defined by :file:`Python.h` have a prefix of ``Py``"

" or ``PY``, except those defined in standard header files. For convenience, "

"and since they are used extensively by the Python interpreter, "

"``\"Python.h\"`` includes a few standard header files: ``<stdio.h>``, "

"``<string.h>``, ``<errno.h>``, and ``<stdlib.h>``. If the latter header "

"file does not exist on your system, it declares the functions "

":c:func:`malloc`, :c:func:`free` and :c:func:`realloc` directly."

msgstr ""

"所有在 :file:`Python.h` 中定义的用户可见的符号都具有 ``Py`` 或 ``PY`` 前缀，已在标准头文件中定义的那些除外。 "

"考虑到便利性，也由于其在 Python 解释器中被广泛使用，``\"Python.h\"`` 还包含了一些标准头文件: "

"``<stdio.h>``，``<string.h>``，``<errno.h>`` 和 ``<stdlib.h>``。 "

"如果后面的头文件在你的系统上不存在，它还会直接声明函数 :c:func:`malloc`，:c:func:`free` 和 "

":c:func:`realloc`。"

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

msgid ""

"The next thing we add to our module file is the C function that will be "

"called when the Python expression ``spam.system(string)`` is evaluated "

"(we'll see shortly how it ends up being called)::"

msgstr "下面添加C函数到扩展模块，当调用 ``spam.system(string)`` 时会做出响应，(我们稍后会看到调用)："

#: ../../extending/extending.rst:99

msgid ""

"There is a straightforward translation from the argument list in Python (for"

" example, the single expression ``\"ls -l\"``) to the arguments passed to "

"the C function. The C function always has two arguments, conventionally "

"named *self* and *args*."

msgstr ""

"有个直接翻译参数列表的方法(举个例子，单独的 ``\"ls -l\"`` )到要传递给C函数的参数。C函数总是有两个参数，通常名字是 *self* 和 "

"*args* 。"

#: ../../extending/extending.rst:104

msgid ""

"The *self* argument points to the module object for module-level functions; "

"for a method it would point to the object instance."

msgstr "对模块级函数， *self* 参数指向模块对象；对于方法则指向对象实例。"

#: ../../extending/extending.rst:107

msgid ""

"The *args* argument will be a pointer to a Python tuple object containing "

"the arguments. Each item of the tuple corresponds to an argument in the "

"call's argument list. The arguments are Python objects --- in order to do "

"anything with them in our C function we have to convert them to C values. "

"The function :c:func:`PyArg_ParseTuple` in the Python API checks the "

"argument types and converts them to C values. It uses a template string to "

"determine the required types of the arguments as well as the types of the C "

"variables into which to store the converted values. More about this later."

msgstr ""

"*args* 参数是指向一个 Python 的 tuple 对象的指针，其中包含参数。 每个 tuple 项对应一个调用参数。 这些参数也全都是 "

"Python 对象 --- 要在我们的 C 函数中使用它们就需要先将其转换为 C 值。 Python API 中的函数 "

":c:func:`PyArg_ParseTuple` 会检查参数类型并将其转换为 C 值。 它使用模板字符串确定需要的参数类型以及存储被转换的值的 C "

"变量类型。 细节将稍后说明。"

#: ../../extending/extending.rst:116

msgid ""

":c:func:`PyArg_ParseTuple` returns true (nonzero) if all arguments have the "

"right type and its components have been stored in the variables whose "

"addresses are passed. It returns false (zero) if an invalid argument list "

"was passed. In the latter case it also raises an appropriate exception so "

"the calling function can return ``NULL`` immediately (as we saw in the "

"example)."

msgstr ""

":c:func:`PyArg_ParseTuple` "

"在所有参数都有正确类型且组成部分按顺序放在传递进来的地址里时，返回真(非零)。其在传入无效参数时返回假(零)。在后续例子里，还会抛出特定异常，使得调用的函数可以理解返回"

" ``NULL`` (也就是例子里所见)。"

#: ../../extending/extending.rst:126

msgid "Intermezzo: Errors and Exceptions"

msgstr "关于错误和异常"

#: ../../extending/extending.rst:128

msgid ""

"An important convention throughout the Python interpreter is the following: "

"when a function fails, it should set an exception condition and return an "

"error value (usually ``-1`` or a ``NULL`` pointer). Exception information "

"is stored in three members of the interpreter's thread state. These are "

"``NULL`` if there is no exception. Otherwise they are the C equivalents of "

"the members of the Python tuple returned by :meth:`sys.exc_info`. These are"

" the exception type, exception instance, and a traceback object. It is "

"important to know about them to understand how errors are passed around."

msgstr ""

"整个 Python 解释器系统有一个如下所述的重要惯例：当一个函数运行失败时，它应当设置一个异常条件并返回一个错误值（通常为 ``-1`` 或 "

"``NULL`` 指针）。 异常信息保存在解释器线程状态的三个成员中。 如果没有异常则它们的值为 ``NULL``。 在其他情况下它们是 "

":meth:`sys.exc_info` 所返回的 Python 元组的成员的 C 对应物。 它们分别是异常类型、异常实例和回溯对象。 "

"理解它们对于理解错误是如何被传递的非常重要。"

#: ../../extending/extending.rst:137

msgid ""

"The Python API defines a number of functions to set various types of "

"exceptions."

msgstr "Python API中定义了一些函数来设置这些变量。"

#: ../../extending/extending.rst:139

msgid ""

"The most common one is :c:func:`PyErr_SetString`. Its arguments are an "

"exception object and a C string. The exception object is usually a "

"predefined object like :c:data:`PyExc_ZeroDivisionError`. The C string "

"indicates the cause of the error and is converted to a Python string object "

"and stored as the \"associated value\" of the exception."

msgstr ""

"最常用的就是 :c:func:`PyErr_SetString`。 其参数是异常对象和 C 字符串。 异常对象一般是像 "

":c:data:`PyExc_ZeroDivisionError` 这样的预定义对象。 C 字符串指明异常原因，并被转换为一个 Python "

"字符串对象存储为异常的“关联值”。"

#: ../../extending/extending.rst:145

msgid ""

"Another useful function is :c:func:`PyErr_SetFromErrno`, which only takes an"

" exception argument and constructs the associated value by inspection of the"

" global variable :c:data:`errno`. The most general function is "

":c:func:`PyErr_SetObject`, which takes two object arguments, the exception "

"and its associated value. You don't need to :c:func:`Py_INCREF` the objects"

" passed to any of these functions."

msgstr ""

"另一个有用的函数是 :c:func:`PyErr_SetFromErrno` ，仅接受一个异常对象，异常描述包含在全局变量 "

":c:data:`errno` 中。最通用的函数还是 :c:func:`PyErr_SetObject` "

"，包含两个参数，分别为异常对象和异常描述。你不需要使用 :c:func:`Py_INCREF` 来增加传递到其他函数的参数对象的引用计数。"

#: ../../extending/extending.rst:152

msgid ""

"You can test non-destructively whether an exception has been set with "

":c:func:`PyErr_Occurred`. This returns the current exception object, or "

"``NULL`` if no exception has occurred. You normally don't need to call "

":c:func:`PyErr_Occurred` to see whether an error occurred in a function "

"call, since you should be able to tell from the return value."

msgstr ""

"你可以通过 :c:func:`PyErr_Occurred` 在不造成破坏的情况下检测是否设置了异常。 这将返回当前异常对象，或者如果未发生异常则返回 "

"``NULL``。 你通常不需要调用 :c:func:`PyErr_Occurred` 来查看函数调用中是否发生了错误，因为你应该能从返回值中看出来。"

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

msgid ""

"When a function *f* that calls another function *g* detects that the latter "

"fails, *f* should itself return an error value (usually ``NULL`` or ``-1``)."

" It should *not* call one of the :c:func:`PyErr_\\*` functions --- one has "

"already been called by *g*. *f*'s caller is then supposed to also return an "

"error indication to *its* caller, again *without* calling "

":c:func:`PyErr_\\*`, and so on --- the most detailed cause of the error was "

"already reported by the function that first detected it. Once the error "

"reaches the Python interpreter's main loop, this aborts the currently "

"executing Python code and tries to find an exception handler specified by "

"the Python programmer."

msgstr ""

"当一个函数 *f* 调用另一个函数 *g* 时检测到后者出错了，*f* 应当自己返回一个错误值 (通常为 ``NULL`` 或 ``-1``)。 它 "

"*不应该* 调用某个 :c:func:`PyErr_\\*` 函数 --- 这类函数已经被 *g* 调用过了。 *f* "

"的调用者随后也应当返回一个错误来提示 *它的* 调用者，同样 *不应该* 调用 :c:func:`PyErr_\\*`，依此类推 --- "

"错误的最详细原因已经由首先检测到它的函数报告了。 一旦这个错误到达 Python 解释器的主循环，它会中止当前执行的 Python 代码并尝试找出由 "

"Python 程序员所指定的异常处理程序。"

#: ../../extending/extending.rst:168

msgid ""

"(There are situations where a module can actually give a more detailed error"

" message by calling another :c:func:`PyErr_\\*` function, and in such cases "

"it is fine to do so. As a general rule, however, this is not necessary, and"

" can cause information about the cause of the error to be lost: most "

"operations can fail for a variety of reasons.)"

msgstr ""

"（在某些情况下，当模块确实能够通过调用其它 :c:func:`PyErr_\\*` 函数给出更加详细的错误消息，并且在这些情况是可以这样做的。 "

"但是按照一般规则，这是不必要的，并可能导致有关错误原因的信息丢失：大多数操作会由于种种原因而失败。）"

#: ../../extending/extending.rst:174

msgid ""

"To ignore an exception set by a function call that failed, the exception "

"condition must be cleared explicitly by calling :c:func:`PyErr_Clear`. The "

"only time C code should call :c:func:`PyErr_Clear` is if it doesn't want to "

"pass the error on to the interpreter but wants to handle it completely by "

"itself (possibly by trying something else, or pretending nothing went "

"wrong)."

msgstr ""

"想要忽略由一个失败的函数调用所设置的异常，异常条件必须通过调用 :c:func:`PyErr_Clear` 显式地被清除。 C 代码应当调用 "

":c:func:`PyErr_Clear` 的唯一情况是如果它不想将错误传给解释器而是想完全由自己来处理它（可能是尝试其他方法，或是假装没有出错）。"

#: ../../extending/extending.rst:180

msgid ""

"Every failing :c:func:`malloc` call must be turned into an exception --- the"

" direct caller of :c:func:`malloc` (or :c:func:`realloc`) must call "

":c:func:`PyErr_NoMemory` and return a failure indicator itself. All the "

"object-creating functions (for example, :c:func:`PyLong_FromLong`) already "

"do this, so this note is only relevant to those who call :c:func:`malloc` "

"directly."

msgstr ""

"每次失败的 :c:func:`malloc` 调用必须转换为一个异常。 :c:func:`malloc` (或 :c:func:`realloc` "

")的直接调用者必须调用 :c:func:`PyErr_NoMemory` 来返回错误来提示。所有对象创建函数(例如 "

":c:func:`PyLong_FromLong` )已经这么做了，所以这个提示仅用于直接调用 :c:func:`malloc` 的情况。"

#: ../../extending/extending.rst:186

msgid ""

"Also note that, with the important exception of :c:func:`PyArg_ParseTuple` "

"and friends, functions that return an integer status usually return a "

"positive value or zero for success and ``-1`` for failure, like Unix system "

"calls."

msgstr ""

"还要注意的是，除了 :c:func:`PyArg_ParseTuple` 等重要的例外，返回整数状态码的函数通常都是返回正值或零来表示成功，而以 "

"``-1`` 表示失败，如同 Unix 系统调用一样。"

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

msgid ""

"Finally, be careful to clean up garbage (by making :c:func:`Py_XDECREF` or "

":c:func:`Py_DECREF` calls for objects you have already created) when you "

"return an error indicator!"

msgstr ""

"最后，当你返回一个错误指示器时要注意清理垃圾（通过为你已经创建的对象执行 :c:func:`Py_XDECREF` 或 "

":c:func:`Py_DECREF` 调用）！"

#: ../../extending/extending.rst:194

msgid ""

"The choice of which exception to raise is entirely yours. There are "

"predeclared C objects corresponding to all built-in Python exceptions, such "

"as :c:data:`PyExc_ZeroDivisionError`, which you can use directly. Of course,"

" you should choose exceptions wisely --- don't use :c:data:`PyExc_TypeError`"

" to mean that a file couldn't be opened (that should probably be "

":c:data:`PyExc_IOError`). If something's wrong with the argument list, the "

":c:func:`PyArg_ParseTuple` function usually raises "

":c:data:`PyExc_TypeError`. If you have an argument whose value must be in a"

" particular range or must satisfy other conditions, "

":c:data:`PyExc_ValueError` is appropriate."

msgstr ""

"选择引发哪个异常完全取决于你的喜好。 所有内置的 Python 异常都有对应的预声明 C 对象，例如 "

":c:data:`PyExc_ZeroDivisionError`，你可以直接使用它们。 当然，你应当明智地选择异常 --- 不要使用 "

":c:data:`PyExc_TypeError` 来表示一个文件无法被打开 (那大概应该用 :c:data:`PyExc_IOError`)。 "

"如果参数列表有问题，:c:func:`PyArg_ParseTuple` 函数通常会引发 :c:data:`PyExc_TypeError`。 "

"如果你想要一个参数的值必须处于特定范围之内或必须满足其他条件，则适宜使用 :c:data:`PyExc_ValueError`。"

#: ../../extending/extending.rst:204

msgid ""

"You can also define a new exception that is unique to your module. For this,"

" you usually declare a static object variable at the beginning of your "

"file::"

msgstr "你也可以为你的模块定义一个唯一的新异常。需要在文件前部声明一个静态对象变量，如:"

#: ../../extending/extending.rst:209

msgid ""

"and initialize it in your module's initialization function "

"(:c:func:`PyInit_spam`) with an exception object::"

msgstr "并且在你的模块的初始化函数 (:c:func:`PyInit_spam`) 中使用一个异常对象来初始化::"

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

msgid ""

"Note that the Python name for the exception object is :exc:`spam.error`. "

"The :c:func:`PyErr_NewException` function may create a class with the base "

"class being :exc:`Exception` (unless another class is passed in instead of "

"``NULL``), described in :ref:`bltin-exceptions`."

msgstr ""

"注意异常对象的Python名字是 :exc:`spam.error` 。而 :c:func:`PyErr_NewException` "

"函数可以创建一个类，其基类为 :exc:`Exception` (除非是另一个类传入以替换 ``NULL`` )， 细节参见 :ref:`bltin-"

"exceptions` 。"

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

msgid ""

"Note also that the :c:data:`SpamError` variable retains a reference to the "

"newly created exception class; this is intentional! Since the exception "

"could be removed from the module by external code, an owned reference to the"

" class is needed to ensure that it will not be discarded, causing "

":c:data:`SpamError` to become a dangling pointer. Should it become a "

"dangling pointer, C code which raises the exception could cause a core dump "

"or other unintended side effects."

msgstr ""

"同样注意的是创建类保存了 :c:data:`SpamError` 的一个引用，这是有意的。为了防止被垃圾回收掉，否则 "

":c:data:`SpamError` 随时会成为野指针。"

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

msgid ""

"We discuss the use of ``PyMODINIT_FUNC`` as a function return type later in "

"this sample."

msgstr "一会讨论 ``PyMODINIT_FUNC`` 作为函数返回类型的用法。"

#: ../../extending/extending.rst:248

msgid ""

"The :exc:`spam.error` exception can be raised in your extension module using"

" a call to :c:func:`PyErr_SetString` as shown below::"

msgstr ":exc:`spam.error` 异常可以在扩展模块中抛出，通过 :c:func:`PyErr_SetString` 函数调用，如下："

#: ../../extending/extending.rst:271

msgid "Back to the Example"

msgstr "回到例子"

#: ../../extending/extending.rst:273

msgid ""

"Going back to our example function, you should now be able to understand "

"this statement::"

msgstr "回到前面的例子，你应该明白下面的代码:"

#: ../../extending/extending.rst:279

msgid ""

"It returns ``NULL`` (the error indicator for functions returning object "

"pointers) if an error is detected in the argument list, relying on the "

"exception set by :c:func:`PyArg_ParseTuple`. Otherwise the string value of "

"the argument has been copied to the local variable :c:data:`command`. This "

"is a pointer assignment and you are not supposed to modify the string to "

"which it points (so in Standard C, the variable :c:data:`command` should "

"properly be declared as ``const char *command``)."

msgstr ""

"如果在参数列表中检测到错误，它将返回 ``NULL`` (该值是返回对象指针的函数所使用的错误提示)，这取决于 "

":c:func:`PyArg_ParseTuple` 设置的异常。 在其他情况下参数的字符串值会被拷贝到局部变量 :c:data:`command`。 "

"这是一个指针赋值并且你不应该修改它所指向的字符串 (因此在标准 C 中，变量 :c:data:`command` 应当被正确地声明为 ``const "

"char *command``)。"

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

msgid ""

"The next statement is a call to the Unix function :c:func:`system`, passing "

"it the string we just got from :c:func:`PyArg_ParseTuple`::"

msgstr ""

"下一个语句使用UNIX系统函数 :c:func:`system` ，传递给他的参数是刚才从 :c:func:`PyArg_ParseTuple` "

"取出的:"

#: ../../extending/extending.rst:292

msgid ""

"Our :func:`spam.system` function must return the value of :c:data:`sts` as a"

" Python object. This is done using the function :c:func:`PyLong_FromLong`. "

"::"

msgstr ""

"我们的 :func:`spam.system` 函数必须返回 :c:data:`sts` 的值作为Python对象。这通过使用函数 "

":c:func:`PyLong_FromLong` 来实现。"

#: ../../extending/extending.rst:297

msgid ""

"In this case, it will return an integer object. (Yes, even integers are "

"objects on the heap in Python!)"

msgstr "在这种情况下，会返回一个整数对象，(这个对象会在Python堆里面管理)。"

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

msgid ""

"If you have a C function that returns no useful argument (a function "

"returning :c:type:`void`), the corresponding Python function must return "

"``None``. You need this idiom to do so (which is implemented by the "

":c:macro:`Py_RETURN_NONE` macro)::"

msgstr ""

"如果你的 C 函数没有有用的返回值 (返回 :c:type:`void` 的函数)，则对应的 Python 函数必须返回 ``None``。 "

"你必须使用这种写法（可以通过 :c:macro:`Py_RETURN_NONE` 宏来实现）:"

#: ../../extending/extending.rst:308

msgid ""

":c:data:`Py_None` is the C name for the special Python object ``None``. It "

"is a genuine Python object rather than a ``NULL`` pointer, which means "

"\"error\" in most contexts, as we have seen."

msgstr ""

":c:data:`Py_None` 是特殊 Python 对象 ``None`` 所对应的 C 名称。 它是一个真正的 Python 对象而不是 "

"``NULL`` 指针，如我们所见，后者在大多数上下文中都意味着“错误”。"

#: ../../extending/extending.rst:316

msgid "The Module's Method Table and Initialization Function"

msgstr "模块方法表和初始化函数"

#: ../../extending/extending.rst:318

msgid ""

"I promised to show how :c:func:`spam_system` is called from Python programs."

" First, we need to list its name and address in a \"method table\"::"

msgstr ""

"为了展示 :c:func:`spam_system` 如何被Python程序调用。把函数声明为可以被Python调用，需要先定义一个方法表 "

"\"method table\" 。"

#: ../../extending/extending.rst:329

msgid ""

"Note the third entry (``METH_VARARGS``). This is a flag telling the "

"interpreter the calling convention to be used for the C function. It should"

" normally always be ``METH_VARARGS`` or ``METH_VARARGS | METH_KEYWORDS``; a "

"value of ``0`` means that an obsolete variant of :c:func:`PyArg_ParseTuple` "

"is used."

msgstr ""

"注意第三个参数 ( ``METH_VARARGS`` ) ，这个标志指定会使用C的调用惯例。可选值有 ``METH_VARARGS`` 、 "

"``METH_VARARGS | METH_KEYWORDS`` 。值 ``0`` 代表使用 :c:func:`PyArg_ParseTuple` "

"的陈旧变量。"

#: ../../extending/extending.rst:334

msgid ""

"When using only ``METH_VARARGS``, the function should expect the Python-"

"level parameters to be passed in as a tuple acceptable for parsing via "

":c:func:`PyArg_ParseTuple`; more information on this function is provided "

"below."

msgstr ""

"如果单独使用 ``METH_VARARGS`` ，函数会等待Python传来tuple格式的参数，并最终使用 "

":c:func:`PyArg_ParseTuple` 进行解析。"

#: ../../extending/extending.rst:338

msgid ""

"The :const:`METH_KEYWORDS` bit may be set in the third field if keyword "

"arguments should be passed to the function. In this case, the C function "

"should accept a third ``PyObject *`` parameter which will be a dictionary of"

" keywords. Use :c:func:`PyArg_ParseTupleAndKeywords` to parse the arguments "

"to such a function."

msgstr ""

":const:`METH_KEYWORDS` 值表示接受关键字参数。这种情况下C函数需要接受第三个 ``PyObject *`` "

"对象，表示字典参数，使用 :c:func:`PyArg_ParseTupleAndKeywords` 来解析出参数。"

#: ../../extending/extending.rst:344

msgid ""

"The method table must be referenced in the module definition structure::"

msgstr "这个方法表必须被模块定义结构所引用。"

#: ../../extending/extending.rst:355

msgid ""

"This structure, in turn, must be passed to the interpreter in the module's "

"initialization function. The initialization function must be named "

":c:func:`PyInit_name`, where *name* is the name of the module, and should be"

" the only non-\\ ``static`` item defined in the module file::"

msgstr ""

"这个结构体必须传递给解释器的模块初始化函数。初始化函数必须命名为 :c:func:`PyInit_name` ，其中 *name* "

"是模块的名字，并应该定义为非 ``static`` ，且在模块文件里："

#: ../../extending/extending.rst:366

msgid ""

"Note that PyMODINIT_FUNC declares the function as ``PyObject *`` return "

"type, declares any special linkage declarations required by the platform, "

"and for C++ declares the function as ``extern \"C\"``."

msgstr ""

"注意 PyMODINIT_FUNC 将函数声明为 ``PyObject *`` 返回类型，声明了任何平台所要求的特殊链接声明，并针对 C++ "

"将函数声明为 ``extern \"C\"``。"

#: ../../extending/extending.rst:370

msgid ""

"When the Python program imports module :mod:`spam` for the first time, "

":c:func:`PyInit_spam` is called. (See below for comments about embedding "

"Python.) It calls :c:func:`PyModule_Create`, which returns a module object, "

"and inserts built-in function objects into the newly created module based "

"upon the table (an array of :c:type:`PyMethodDef` structures) found in the "

"module definition. :c:func:`PyModule_Create` returns a pointer to the module"

" object that it creates. It may abort with a fatal error for certain "

"errors, or return ``NULL`` if the module could not be initialized "

"satisfactorily. The init function must return the module object to its "

"caller, so that it then gets inserted into ``sys.modules``."

msgstr ""

"当 Python 程序首次导入 :mod:`spam` 模块时， :c:func:`PyInit_spam` 会被调用。 （有关嵌入 Python "

"的注释参见下文。） 它将调用 "

":c:func:`PyModule_Create`，该函数会返回一个模块对象，并基于在模块定义中找到的表将内置函数对象插入到新创建的模块中（该表是一个 "

":c:type:`PyMethodDef` 结构体的数组）。 :c:func:`PyModule_Create` 返回一个指向它所创建的模块对象的指针。"

" 它可能会因程度严重的特定错误而中止，或者在模块无法成功初始化时返回 ``NULL``。 初始化函数必须返回模块对象给其调用者，这样它就可以被插入到 "

"``sys.modules`` 中。"

#: ../../extending/extending.rst:381

msgid ""

"When embedding Python, the :c:func:`PyInit_spam` function is not called "

"automatically unless there's an entry in the :c:data:`PyImport_Inittab` "

"table. To add the module to the initialization table, use "

":c:func:`PyImport_AppendInittab`, optionally followed by an import of the "

"module::"

msgstr ""

"当嵌入Python时， :c:func:`PyInit_spam` 函数不会被自动调用，除非放在 :c:data:`PyImport_Inittab` "

"表里。要添加模块到初始化表，使用 :c:func:`PyImport_AppendInittab` ，可选的跟着一个模块的导入。"

#: ../../extending/extending.rst:425

msgid ""

"Removing entries from ``sys.modules`` or importing compiled modules into "

"multiple interpreters within a process (or following a :c:func:`fork` "

"without an intervening :c:func:`exec`) can create problems for some "

"extension modules. Extension module authors should exercise caution when "

"initializing internal data structures."

msgstr ""

"要从 ``sys.modules`` 删除实体或导入已编译模块到一个进程里的多个解释器(或使用 :c:func:`fork` 而没用 "

":c:func:`exec` )会在一些扩展模块上产生错误。扩展模块作者可以在初始化内部数据结构时给出警告。"

#: ../../extending/extending.rst:431

msgid ""

"A more substantial example module is included in the Python source "

"distribution as :file:`Modules/xxmodule.c`. This file may be used as a "

"template or simply read as an example."

msgstr ""

"更多关于模块的现实的例子包含在 Python 源码发布包的 :file:`Modules/xxmodule.c` 中。 "

"此文件可以被用作代码模板或是学习样例。"

#: ../../extending/extending.rst:437

msgid ""

"Unlike our ``spam`` example, ``xxmodule`` uses *multi-phase initialization* "

"(new in Python 3.5), where a PyModuleDef structure is returned from "

"``PyInit_spam``, and creation of the module is left to the import machinery."

" For details on multi-phase initialization, see :PEP:`489`."

msgstr ""

"不像我们的 ``spam`` 例子， ``xxmodule`` 使用了 *多阶段初始化* (Python3.5开始引入)， "

"``PyInit_spam`` 会返回一个 PyModuleDef 结构体，然后创建的模块放到导入机制。细节参考 :PEP:`489` 的多阶段初始化。"

#: ../../extending/extending.rst:446

msgid "Compilation and Linkage"

msgstr "编译和链接"

#: ../../extending/extending.rst:448

msgid ""

"There are two more things to do before you can use your new extension: "

"compiling and linking it with the Python system. If you use dynamic "

"loading, the details may depend on the style of dynamic loading your system "

"uses; see the chapters about building extension modules (chapter "

":ref:`building`) and additional information that pertains only to building "

"on Windows (chapter :ref:`building-on-windows`) for more information about "

"this."

msgstr ""

"在你能使用你的新写的扩展之前，你还需要做两件事情：使用 Python "

"系统来编译和链接。如果你使用动态加载，这取决于你使用的操作系统的动态加载机制；更多信息请参考编译扩展模块的章节（ :ref:`building` "

"章节），以及在 Windows 上编译需要的额外信息（ :ref:`building-on-windows` 章节）。"

#: ../../extending/extending.rst:455

msgid ""

"If you can't use dynamic loading, or if you want to make your module a "

"permanent part of the Python interpreter, you will have to change the "

"configuration setup and rebuild the interpreter. Luckily, this is very "

"simple on Unix: just place your file (:file:`spammodule.c` for example) in "

"the :file:`Modules/` directory of an unpacked source distribution, add a "

"line to the file :file:`Modules/Setup.local` describing your file:"

msgstr ""

"如果你不使用动态加载，或者想要让模块永久性的作为Python解释器的一部分，就必须修改配置设置，并重新构建解释器。幸运的是在Unix上很简单，只需要把你的文件"

" ( :file:`spammodule.c` 为例) 放在解压缩源码发行包的 :file:`Modules/` 目录下，添加一行到 "

":file:`Modules/Setup.local` 来描述你的文件："

#: ../../extending/extending.rst:466

msgid ""

"and rebuild the interpreter by running :program:`make` in the toplevel "

"directory. You can also run :program:`make` in the :file:`Modules/` "

"subdirectory, but then you must first rebuild :file:`Makefile` there by "

"running ':program:`make` Makefile'. (This is necessary each time you change"

" the :file:`Setup` file.)"

msgstr ""

"然后在顶层目录运行 :program:`make` 来重新构建解释器。你也可以在 :file:`Modules/` 子目录使用 "

":program:`make`，但是你必须先重建 :file:`Makefile` 文件，然后运行 ':program:`make` Makefile'"

" 命令。（你每次修改 :file:`Setup` 文件都需要这样操作。）"

#: ../../extending/extending.rst:472

msgid ""

"If your module requires additional libraries to link with, these can be "

"listed on the line in the configuration file as well, for instance:"

msgstr "如果你的模块需要额外的链接，这些内容可以列出在配置文件里，举个实例："

#: ../../extending/extending.rst:483

msgid "Calling Python Functions from C"

msgstr "在C中调用Python函数"

#: ../../extending/extending.rst:485

msgid ""

"So far we have concentrated on making C functions callable from Python. The"

" reverse is also useful: calling Python functions from C. This is especially"

" the case for libraries that support so-called \"callback\" functions. If a"

" C interface makes use of callbacks, the equivalent Python often needs to "

"provide a callback mechanism to the Python programmer; the implementation "

"will require calling the Python callback functions from a C callback. Other"

" uses are also imaginable."

msgstr ""

"迄今为止，我们一直把注意力集中于让Python调用C函数，其实反过来也很有用，就是用C调用Python函数。这在回调函数中尤其有用。如果一个C接口使用回调，那么就要实现这个回调机制。"

#: ../../extending/extending.rst:493

msgid ""

"Fortunately, the Python interpreter is easily called recursively, and there "

"is a standard interface to call a Python function. (I won't dwell on how to"

" call the Python parser with a particular string as input --- if you're "

"interested, have a look at the implementation of the :option:`-c` command "

"line option in :file:`Modules/main.c` from the Python source code.)"

msgstr ""

"幸运的是，Python解释器是比较方便回调的，并给标准Python函数提供了标准接口。(这里就不再详述解析Python字符串作为输入的方式，如果有兴趣可以参考"

" :file:`Python/pythonmain.c` 中的 :option:`-c` 命令行代码。)"

#: ../../extending/extending.rst:499

msgid ""

"Calling a Python function is easy. First, the Python program must somehow "

"pass you the Python function object. You should provide a function (or some"

" other interface) to do this. When this function is called, save a pointer "

"to the Python function object (be careful to :c:func:`Py_INCREF` it!) in a "

"global variable --- or wherever you see fit. For example, the following "

"function might be part of a module definition::"

msgstr ""

"调用Python函数很简单，首先Python程序要传递Python函数对象。应该提供个函数(或其他接口)来实现。当调用这个函数时，用全局变量保存Python函数对象的指针，还要调用"

" (:c:func:`Py_INCREF`) 来增加引用计数，当然不用全局变量也没什么关系。举个例子，如下函数可能是模块定义的一部分："

#: ../../extending/extending.rst:529

msgid ""

"This function must be registered with the interpreter using the "

":const:`METH_VARARGS` flag; this is described in section :ref:`methodtable`."

" The :c:func:`PyArg_ParseTuple` function and its arguments are documented "

"in section :ref:`parsetuple`."

msgstr ""

"这个函数必须使用 :const:`METH_VARARGS` 标志注册到解释器，这在 :ref:`methodtable` 章节会描述。 "

":c:func:`PyArg_ParseTuple` 函数及其参数的文档在 :ref:`parsetuple` 。"

#: ../../extending/extending.rst:534

msgid ""

"The macros :c:func:`Py_XINCREF` and :c:func:`Py_XDECREF` increment/decrement"

" the reference count of an object and are safe in the presence of ``NULL`` "

"pointers (but note that *temp* will not be ``NULL`` in this context). More"

" info on them in section :ref:`refcounts`."

msgstr ""

":c:func:`Py_XINCREF` 和 :c:func:`Py_XDECREF` 这两个宏可增加/减少一个对象的引用计数，并且当存在 "

"``NULL`` 指针时仍可保证安全 (但请注意在这个上下文中 *temp* 将不为 ``NULL``)。 更多相关信息请参考 "

":ref:`refcounts` 章节。"

#: ../../extending/extending.rst:541

msgid ""

"Later, when it is time to call the function, you call the C function "

":c:func:`PyObject_CallObject`. This function has two arguments, both "

"pointers to arbitrary Python objects: the Python function, and the argument "

"list. The argument list must always be a tuple object, whose length is the "

"number of arguments. To call the Python function with no arguments, pass in"

" ``NULL``, or an empty tuple; to call it with one argument, pass a singleton"

" tuple. :c:func:`Py_BuildValue` returns a tuple when its format string "

"consists of zero or more format codes between parentheses. For example::"

msgstr ""

"随后，当要调用此函数时，你将调用 C 函数 :c:func:`PyObject_CallObject`。 该函数有两个参数，它们都属于指针，指向任意 "

"Python 对象：即 Python 函数，及其参数列表。 参数列表必须总是一个元组对象，其长度即参数的个数量。 要不带参数地调用 Python "

"函数，则传入 ``NULL`` 或一个空元组；要带一个参数调用它，则传入一个单元组。 :c:func:`Py_BuildValue` "

"会在其格式字符串包含一对圆括号内的零个或多个格式代码时返回一个元组。 例如::"

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

msgid ""

":c:func:`PyObject_CallObject` returns a Python object pointer: this is the "

"return value of the Python function. :c:func:`PyObject_CallObject` is "

"\"reference-count-neutral\" with respect to its arguments. In the example a"

" new tuple was created to serve as the argument list, which is "

":c:func:`Py_DECREF`\\ -ed immediately after the "

":c:func:`PyObject_CallObject` call."

msgstr ""

":c:func:`PyObject_CallObject` 返回Python对象指针，这也是Python函数的返回值。 "

":c:func:`PyObject_CallObject` 是一个对其参数 \"引用计数无关\" 的函数。例子中新的元组创建用于参数列表，并且在 "

":c:func:`PyObject_CallObject` 之后立即使用了 :c:func:`Py_DECREF` 。"

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

msgid ""

"The return value of :c:func:`PyObject_CallObject` is \"new\": either it is a"

" brand new object, or it is an existing object whose reference count has "

"been incremented. So, unless you want to save it in a global variable, you "

"should somehow :c:func:`Py_DECREF` the result, even (especially!) if you are"

" not interested in its value."

msgstr ""

":c:func:`PyObject_CallObject` "

"的返回值总是“新”的：要么是一个新建的对象；要么是已有对象，但增加了引用计数。所以除非你想把结果保存在全局变量中，你需要对这个值使用 "

":c:func:`Py_DECREF`，即使你对里面的内容（特别！）不感兴趣。"

#: ../../extending/extending.rst:574

msgid ""

"Before you do this, however, it is important to check that the return value "

"isn't ``NULL``. If it is, the Python function terminated by raising an "

"exception. If the C code that called :c:func:`PyObject_CallObject` is called"

" from Python, it should now return an error indication to its Python caller,"

" so the interpreter can print a stack trace, or the calling Python code can "

"handle the exception. If this is not possible or desirable, the exception "

"should be cleared by calling :c:func:`PyErr_Clear`. For example::"

msgstr ""

"但是在你这么做之前，很重要的一点是检查返回值不是 ``NULL``。 如果是的话，Python 函数会终止并引发异常。 如果调用 "

":c:func:`PyObject_CallObject` 的 C 代码是在 Python 中唤起的，它应当立即返回一个错误来告知其 Python "

"调用者，以便解释器能打印栈回溯信息，或者让调用方 Python 代码能处理该异常。 如果这无法做到或不合本意，则应当通过调用 "

":c:func:`PyErr_Clear` 来清除异常。 例如::"

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

msgid ""

"Depending on the desired interface to the Python callback function, you may "

"also have to provide an argument list to :c:func:`PyObject_CallObject`. In "

"some cases the argument list is also provided by the Python program, through"

" the same interface that specified the callback function. It can then be "

"saved and used in the same manner as the function object. In other cases, "

"you may have to construct a new tuple to pass as the argument list. The "

"simplest way to do this is to call :c:func:`Py_BuildValue`. For example, if"

" you want to pass an integral event code, you might use the following code::"

msgstr ""

"依赖于具体的回调函数，你还要提供一个参数列表到 :c:func:`PyObject_CallObject` "

"。在某些情况下参数列表是由Python程序提供的，通过接口再传到回调函数对象。这样就可以不改变形式直接传递。另外一些时候你要构造一个新的元组来传递参数。最简单的方法就是"

" :c:func:`Py_BuildValue` 函数构造tuple。举个例子，你要传递一个事件代码时可以用如下代码:"

#: ../../extending/extending.rst:606

msgid ""

"Note the placement of ``Py_DECREF(arglist)`` immediately after the call, "

"before the error check! Also note that strictly speaking this code is not "

"complete: :c:func:`Py_BuildValue` may run out of memory, and this should be "

"checked."

msgstr ""

"注意 ``Py_DECREF(arglist)`` 所在处会立即调用，在错误检查之前。当然还要注意一些常规的错误，比如 "

":c:func:`Py_BuildValue` 可能会遭遇内存不足等等。"

#: ../../extending/extending.rst:610

msgid ""

"You may also call a function with keyword arguments by using "

":c:func:`PyObject_Call`, which supports arguments and keyword arguments. As"

" in the above example, we use :c:func:`Py_BuildValue` to construct the "

"dictionary. ::"

msgstr ""

"当你调用函数时还需要注意，用关键字参数调用 :c:func:`PyObject_Call` ，需要支持普通参数和关键字参数。有如如上例子中，我们使用 "

":c:func:`Py_BuildValue` 来构造字典。"

#: ../../extending/extending.rst:628

msgid "Extracting Parameters in Extension Functions"

msgstr "提取扩展函数的参数"

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

msgid "The :c:func:`PyArg_ParseTuple` function is declared as follows::"

msgstr "函数 :c:func:`PyArg_ParseTuple` 的声明如下："

#: ../../extending/extending.rst:636

msgid ""

"The *arg* argument must be a tuple object containing an argument list passed"

" from Python to a C function. The *format* argument must be a format "

"string, whose syntax is explained in :ref:`arg-parsing` in the Python/C API "

"Reference Manual. The remaining arguments must be addresses of variables "

"whose type is determined by the format string."

msgstr ""

"参数 *arg* 必须是一个元组对象，包含从 Python 传递给 C 函数的参数列表。*format* 参数必须是一个格式字符串，语法请参考 "

"Python C/API 手册中的 :ref:`arg-parsing`。剩余参数是各个变量的地址，类型要与格式字符串对应。"

#: ../../extending/extending.rst:642

msgid ""

"Note that while :c:func:`PyArg_ParseTuple` checks that the Python arguments "

"have the required types, it cannot check the validity of the addresses of C "

"variables passed to the call: if you make mistakes there, your code will "

"probably crash or at least overwrite random bits in memory. So be careful!"

msgstr ""

"注意 :c:func:`PyArg_ParseTuple` "

"会检测他需要的Python参数类型，却无法检测传递给他的C变量地址，如果这里出错了，可能会在内存中随机写入东西，小心。"

#: ../../extending/extending.rst:647

msgid ""

"Note that any Python object references which are provided to the caller are "

"*borrowed* references; do not decrement their reference count!"

msgstr "注意任何由调用者提供的 Python 对象引用是 *借来的* 引用；不要递减它们的引用计数！"

#: ../../extending/extending.rst:650

msgid "Some example calls::"

msgstr "一些调用的例子："

#: ../../extending/extending.rst:720

msgid "Keyword Parameters for Extension Functions"

msgstr "给扩展函数的关键字参数"

#: ../../extending/extending.rst:724

msgid ""

"The :c:func:`PyArg_ParseTupleAndKeywords` function is declared as follows::"

msgstr "函数 :c:func:`PyArg_ParseTupleAndKeywords` 声明如下："

#: ../../extending/extending.rst:729

msgid ""

"The *arg* and *format* parameters are identical to those of the "

":c:func:`PyArg_ParseTuple` function. The *kwdict* parameter is the "

"dictionary of keywords received as the third parameter from the Python "

"runtime. The *kwlist* parameter is a ``NULL``-terminated list of strings "

"which identify the parameters; the names are matched with the type "

"information from *format* from left to right. On success, "

":c:func:`PyArg_ParseTupleAndKeywords` returns true, otherwise it returns "

"false and raises an appropriate exception."

msgstr ""

"*arg* 与 *format* 形参与 :c:func:`PyArg_ParseTuple` 函数所定义的一致。 *kwdict* "

"形参是作为第三个参数从 Python 运行时接收的关键字字典。 *kwlist* 形参是以 ``NULL`` "

"结尾的字符串列表，它被用来标识形参；名称从左至右与来自 *format* 的类型信息相匹配。 "

"如果执行成功，:c:func:`PyArg_ParseTupleAndKeywords` 会返回真值，否则返回假值并引发一个适当的异常。"

#: ../../extending/extending.rst:739

msgid ""

"Nested tuples cannot be parsed when using keyword arguments! Keyword "

"parameters passed in which are not present in the *kwlist* will cause "

":exc:`TypeError` to be raised."

msgstr "嵌套的元组在使用关键字参数时无法生效，不在 *kwlist* 中的关键字参数会导致 :exc:`TypeError` 异常。"

#: ../../extending/extending.rst:745

msgid ""

"Here is an example module which uses keywords, based on an example by Geoff "

"Philbrick (philbrick@hks.com)::"

msgstr "如下例子是使用关键字参数的例子模块，作者是 Geoff Philbrick (philbrick@hks.com):"

#: ../../extending/extending.rst:800

msgid "Building Arbitrary Values"

msgstr "构造任意值"

#: ../../extending/extending.rst:802

msgid ""

"This function is the counterpart to :c:func:`PyArg_ParseTuple`. It is "

"declared as follows::"

msgstr "这个函数与 :c:func:`PyArg_ParseTuple` 很相似，声明如下："

#: ../../extending/extending.rst:807

msgid ""

"It recognizes a set of format units similar to the ones recognized by "

":c:func:`PyArg_ParseTuple`, but the arguments (which are input to the "

"function, not output) must not be pointers, just values. It returns a new "

"Python object, suitable for returning from a C function called from Python."

msgstr ""

"接受一个格式字符串，与 :c:func:`PyArg_ParseTuple` "

"相同，但是参数必须是原变量的地址指针(输入给函数，而非输出)。最终返回一个Python对象适合于返回C函数调用给Python代码。"

#: ../../extending/extending.rst:812

msgid ""

"One difference with :c:func:`PyArg_ParseTuple`: while the latter requires "

"its first argument to be a tuple (since Python argument lists are always "

"represented as tuples internally), :c:func:`Py_BuildValue` does not always "

"build a tuple. It builds a tuple only if its format string contains two or "

"more format units. If the format string is empty, it returns ``None``; if it"

" contains exactly one format unit, it returns whatever object is described "

"by that format unit. To force it to return a tuple of size 0 or one, "

"parenthesize the format string."

msgstr ""

"一个与 :c:func:`PyArg_ParseTuple` "

"的不同是，后面可能需要的要求返回一个元组(Python参数里诶包总是在内部描述为元组)，比如用于传递给其他Python函数以参数。 "

":c:func:`Py_BuildValue` 并不总是生成元组，在多于1个格式字符串时会生成元组，而如果格式字符串为空则返回 ``None`` "

"，一个参数则直接返回该参数的对象。如果要求强制生成一个长度为0的元组，或包含一个元素的元组，需要在格式字符串中加上括号。"

#: ../../extending/extending.rst:820

msgid ""

"Examples (to the left the call, to the right the resulting Python value):"

msgstr "例子(左侧是调用，右侧是Python值结果)："

#: ../../extending/extending.rst:846

msgid "Reference Counts"

msgstr "引用计数"

#: ../../extending/extending.rst:848

msgid ""

"In languages like C or C++, the programmer is responsible for dynamic "

"allocation and deallocation of memory on the heap. In C, this is done using"

" the functions :c:func:`malloc` and :c:func:`free`. In C++, the operators "

"``new`` and ``delete`` are used with essentially the same meaning and we'll "

"restrict the following discussion to the C case."

msgstr ""

"在C/C++语言中，程序员负责动态分配和回收堆heap当中的内存。在C里，通过函数 :c:func:`malloc` 和 :c:func:`free` "

"来完成。在C++里是操作 ``new`` 和 ``delete`` 来实现相同的功能。"

#: ../../extending/extending.rst:854

msgid ""

"Every block of memory allocated with :c:func:`malloc` should eventually be "

"returned to the pool of available memory by exactly one call to "

":c:func:`free`. It is important to call :c:func:`free` at the right time. "

"If a block's address is forgotten but :c:func:`free` is not called for it, "

"the memory it occupies cannot be reused until the program terminates. This "

"is called a :dfn:`memory leak`. On the other hand, if a program calls "

":c:func:`free` for a block and then continues to use the block, it creates a"

" conflict with re-use of the block through another :c:func:`malloc` call. "

"This is called :dfn:`using freed memory`. It has the same bad consequences "

"as referencing uninitialized data --- core dumps, wrong results, mysterious "

"crashes."

msgstr ""

"每个由 :c:func:`malloc` 分配的内存块，最终都要由 :c:func:`free` 退回到可用内存池里面去。而调用 "

":c:func:`free` 的时机非常重要，如果一个内存块忘了 :c:func:`free` "

"则会导致内存泄漏，这块内存在程序结束前将无法重新使用。这叫做 :dfn:`内存泄漏` 。而如果对同一内存块 :c:func:`free` "

"了以后，另外一个指针再次访问，则再次使用 :c:func:`malloc` 复用这块内存会导致冲突。这叫做 :dfn:`野指针` "

"。等同于使用未初始化的数据，core dump，错误结果，神秘的崩溃等。"

#: ../../extending/extending.rst:865

msgid ""

"Common causes of memory leaks are unusual paths through the code. For "

"instance, a function may allocate a block of memory, do some calculation, "

"and then free the block again. Now a change in the requirements for the "

"function may add a test to the calculation that detects an error condition "

"and can return prematurely from the function. It's easy to forget to free "

"the allocated memory block when taking this premature exit, especially when "

"it is added later to the code. Such leaks, once introduced, often go "

"undetected for a long time: the error exit is taken only in a small fraction"

" of all calls, and most modern machines have plenty of virtual memory, so "

"the leak only becomes apparent in a long-running process that uses the "

"leaking function frequently. Therefore, it's important to prevent leaks "

"from happening by having a coding convention or strategy that minimizes this"

" kind of errors."

msgstr ""

"内存泄露往往发生在一些并不常见的代码流程上面。比如一个函数申请了内存以后，做了些计算，然后释放内存块。现在一些对函数的修改可能增加对计算的测试并检测错误条件，然后过早的从函数返回了。这很容易忘记在退出前释放内存，特别是后期修改的代码。这种内存泄漏，一旦引入，通常很长时间都难以检测到，错误退出被调用的频度较低，而现代电脑又有非常巨大的虚拟内存，所以泄漏仅在长期运行或频繁调用泄漏函数时才会变得明显。因此，有必要避免内存泄漏，通过代码规范会策略来最小化此类错误。"

#: ../../extending/extending.rst:878

msgid ""

"Since Python makes heavy use of :c:func:`malloc` and :c:func:`free`, it "

"needs a strategy to avoid memory leaks as well as the use of freed memory. "

"The chosen method is called :dfn:`reference counting`. The principle is "

"simple: every object contains a counter, which is incremented when a "

"reference to the object is stored somewhere, and which is decremented when a"

" reference to it is deleted. When the counter reaches zero, the last "

"reference to the object has been deleted and the object is freed."

msgstr ""

"Python通过 :c:func:`malloc` 和 :c:func:`free` "

"包含大量的内存分配和释放，同样需要避免内存泄漏和野指针。他选择的方法就是 :dfn:`引用计数` "

"。其原理比较简单：每个对象都包含一个计数器，计数器的增减与对象引用的增减直接相关，当引用计数为0时，表示对象已经没有存在的意义了，对象就可以删除了。"

#: ../../extending/extending.rst:886

msgid ""

"An alternative strategy is called :dfn:`automatic garbage collection`. "

"(Sometimes, reference counting is also referred to as a garbage collection "

"strategy, hence my use of \"automatic\" to distinguish the two.) The big "

"advantage of automatic garbage collection is that the user doesn't need to "

"call :c:func:`free` explicitly. (Another claimed advantage is an "

"improvement in speed or memory usage --- this is no hard fact however.) The"

" disadvantage is that for C, there is no truly portable automatic garbage "

"collector, while reference counting can be implemented portably (as long as "

"the functions :c:func:`malloc` and :c:func:`free` are available --- which "

"the C Standard guarantees). Maybe some day a sufficiently portable automatic"

" garbage collector will be available for C. Until then, we'll have to live "

"with reference counts."

msgstr ""

"另一个叫法是 :dfn:`自动垃圾回收` "

"。(有时引用计数也被看作是垃圾回收策略，于是这里的\"自动\"用以区分两者)。自动垃圾回收的优点是用户不需要明确的调用 :c:func:`free` "

"。(另一个优点是改善速度或内存使用，然而这并不难)。缺点是对C，没有可移植的自动垃圾回收器，而引用计数则可以可移植的实现(只要 "

":c:func:`malloc` 和 :c:func:`free` "

"函数是可用的，这也是C标准担保的)。也许以后有一天会出现可移植的自动垃圾回收器，但在此前我们必须与引用计数一起工作。"

#: ../../extending/extending.rst:898

msgid ""