Python/C API 3.9.1 参考手册.pdf详解及使用指南

版权申诉

76 浏览量更新于2024-03-04 收藏 1.86MB PDF 举报

PythonC API 3.9.1 参考手册.pdf是由Guido van Rossum和Python开发团队于2020年11月29日发布的。该手册旨在为开发人员提供Python/C API 3.9.1rc1的详细参考资料，帮助他们更好地理解和使用Python的C API。本手册包含了关于代码标准、包含文件、有用宏、对象、类型和引用计数等方面的内容，旨在帮助开发人员在使用Python/C API时更加便捷和高效。在该手册中，我们首先介绍了Python/C API 3.9.1的概述，其中包括了代码标准、包含文件、有用的宏等方面。通过阅读本手册，开发人员可以了解到Python/C API 3.9.1的相关规范和要求，以及具体的使用方法和注意事项。此外，手册还详细介绍了对象、类型和引用计数等内容，帮助开发人员更好地理解Python中的对象模型和内存管理机制，从而编写出更加高效、稳定的Python/C API程序。总的来说，PythonC API 3.9.1 参考手册.pdf是一份详尽而全面的文档，对于使用Python的C API进行开发的开发人员来说非常有价值。它提供了全面的信息和示例代码，能够帮助开发人员更好地利用Python的强大功能，实现各种复杂的操作和功能。通过阅读本手册，开发人员可以更加深入地了解Python/C API 3.9.1的各个方面，从而在实际开发中更加得心应手。同时，本手册还能帮助开发人员避免一些常见的错误和陷阱，从而提高开发效率并得到更加稳健和可靠的代码。总之，PythonC API 3.9.1 参考手册.pdf是一份对于Python/C API 3.9.1rc1非常有价值的参考资料，它涵盖了各个方面的内容，并且提供了大量的实例代码和示例，能够帮助开发人员更好地理解和使用Python的C API。对于希望深入掌握Python的开发人员来说，这份手册绝对是一份不可多得的宝贵资源，可以帮助他们更好地实现各种复杂的功能和操作，从而提升开发效率并写出更加高质量的代码。

The Python/C API, 发布 3.9.1rc1

int

set_all(PyObject *target, PyObject *item)

{

Py_ssize_t i, n;

n = PyObject_Length(target);

if (n < 0)

return -1;

for (i = 0; i < n; i++) {

PyObject *index = PyLong_FromSsize_t(i);

if (!index)

return -1;

if (PyObject_SetItem(target, index, item) < 0) {

Py_DECREF(index);

return -1;

}

Py_DECREF(index);

}

return 0;

}

The situation is slightly diﬀerent for function return values. While passing a reference to most functions does not change

your ownership responsibilities for that reference, many functions that return a reference to an object give you ownership of

the reference. The reason is simple: in many cases, the returned object is created on the ﬂy, and the reference you get is the

only reference to the object. Therefore, the generic functions that return object references, like PyObject_GetItem()

and PySequence_GetItem(), always return a new reference (the caller becomes the owner of the reference).

It is important to realize that whether you own a reference returned by a function depends on which function you call only

--- the plumage (the type of the object passed as an argument to the function) doesn’t enter into it! Thus, if you extract

an item from a list using PyList_GetItem(), you don’t own the reference --- but if you obtain the same item from

the same list using PySequence_GetItem() (which happens to take exactly the same arguments), you do own a

reference to the returned object.

Here is an example of how you could write a function that computes the sum of the items in a list of integers; once using

PyList_GetItem(), and once using PySequence_GetItem().

long

sum_list(PyObject *list)

{

Py_ssize_t i, n;

long total = 0, value;

PyObject *item;

n = PyList_Size(list);

if (n < 0)

return -1; /* Not a list */

for (i = 0; i < n; i++) {

item = PyList_GetItem(list, i); /* Can't fail */

if (!PyLong_Check(item)) continue; /* Skip non-integers */

value = PyLong_AsLong(item);

if (value == -1 && PyErr_Occurred())

/* Integer too big to fit in a C long, bail out */

return -1;

total += value;

}

return total;

}

8 Chapter 1. 概述

The Python/C API, 发布 3.9.1rc1

long

sum_sequence(PyObject *sequence)

{

Py_ssize_t i, n;

long total = 0, value;

PyObject *item;

n = PySequence_Length(sequence);

if (n < 0)

return -1; /* Has no length */

for (i = 0; i < n; i++) {

item = PySequence_GetItem(sequence, i);

if (item == NULL)

return -1; /* Not a sequence, or other failure */

if (PyLong_Check(item)) {

value = PyLong_AsLong(item);

Py_DECREF(item);

if (value == -1 && PyErr_Occurred())

/* Integer too big to fit in a C long, bail out */

return -1;

total += value;

}

else {

Py_DECREF(item); /* Discard reference ownership */

}

return total;

}

1.4.2 类型

There are few other data types that play a signiﬁcant role in the Python/C API; most are simple C types such as int,

long, double and char*. A few structure types are used to describe static tables used to list the functions exported

by a module or the data attributes of a new object type, and another is used to describe the value of a complex number.

These will be discussed together with the functions that use them.

1.5 异常

Python 程序员只需要处理特定需要处理的错误异常；未处理的异常会自动传递给调用者，然后传递给调用者

的调用者，依此类推，直到他们到达顶级解释器，在那里将它们报告给用户并伴随堆栈回溯。

For C programmers, however, error checking always has to be explicit. All functions in the Python/C API can raise

exceptions, unless an explicit claim is made otherwise in a function’s documentation. In general, when a function en-

counters an error, it sets an exception, discards any object references that it owns, and returns an error indicator. If not

documented otherwise, this indicator is either NULL or -1, depending on the function’s return type. A few functions

return a Boolean true/false result, with false indicating an error. Very few functions return no explicit error indicator or

have an ambiguous return value, and require explicit testing for errors with PyErr_Occurred(). These exceptions

are always explicitly documented.

Exception state is maintained in per-thread storage (this is equivalent to using global storage in an unthreaded application).

A thread can be in one of two states: an exception has occurred, or not. The function PyErr_Occurred() can be used

to check for this: it returns a borrowed reference to the exception type object when an exception has occurred, and NULL

otherwise. There are a number of functions to set the exception state: PyErr_SetString() is the most common

(though not the most general) function to set the exception state, and PyErr_Clear() clears the exception state.

1.5. 异常 9

The Python/C API, 发布 3.9.1rc1

The full exception state consists of three objects (all of which can be NULL): the exception type, the corresponding

exception value, and the traceback. These have the same meanings as the Python result of sys.exc_info(); however,

they are not the same: the Python objects represent the last exception being handled by a Python try ... except

statement, while the C level exception state only exists while an exception is being passed on between C functions until

it reaches the Python bytecode interpreter’s main loop, which takes care of transferring it to sys.exc_info() and

friends.

Note that starting with Python 1.5, the preferred, thread-safe way to access the exception state from Python code is to call

the function sys.exc_info(), which returns the per-thread exception state for Python code. Also, the semantics of

both ways to access the exception state have changed so that a function which catches an exception will save and restore

its thread’s exception state so as to preserve the exception state of its caller. This prevents common bugs in exception

handling code caused by an innocent-looking function overwriting the exception being handled; it also reduces the often

unwanted lifetime extension for objects that are referenced by the stack frames in the traceback.

As a general principle, a function that calls another function to perform some task should check whether the called function

raised an exception, and if so, pass the exception state on to its caller. It should discard any object references that it owns,

and return an error indicator, but it should not set another exception --- that would overwrite the exception that was just

raised, and lose important information about the exact cause of the error.

A simple example of detecting exceptions and passing them on is shown in the sum_sequence() example above. It so

happens that this example doesn’t need to clean up any owned references when it detects an error. The following example

function shows some error cleanup. First, to remind you why you like Python, we show the equivalent Python code:

def incr_item(dict, key):

try:

item = dict[key]

except KeyError:

item = 0

dict[key] = item + 1

Here is the corresponding C code, in all its glory:

int

incr_item(PyObject *dict, PyObject *key)

{

/* Objects all initialized to NULL for Py_XDECREF */

PyObject *item = NULL, *const_one = NULL, *incremented_item = NULL;

int rv = -1; /* Return value initialized to -1 (failure) */

item = PyObject_GetItem(dict, key);

if (item == NULL) {

/* Handle KeyError only: */

if (!PyErr_ExceptionMatches(PyExc_KeyError))

goto error;

/* Clear the error and use zero: */

PyErr_Clear();

item = PyLong_FromLong(0L);

if (item == NULL)

goto error;

}

const_one = PyLong_FromLong(1L);

if (const_one == NULL)

goto error;

incremented_item = PyNumber_Add(item, const_one);

if (incremented_item == NULL)

goto error;

(下页继续)

10 Chapter 1. 概述

The Python/C API, 发布 3.9.1rc1

(续上页)

if (PyObject_SetItem(dict, key, incremented_item) < 0)

goto error;

rv = 0; /* Success */

/* Continue with cleanup code */

error:

/* Cleanup code, shared by success and failure path */

/* Use Py_XDECREF() to ignore NULL references */

Py_XDECREF(item);

Py_XDECREF(const_one);

Py_XDECREF(incremented_item);

return rv; /* -1 for error, 0 for success */

}

This example represents an endorsed use of the goto statement in C! It illustrates the use of

PyErr_ExceptionMatches() and PyErr_Clear() to handle speciﬁc exceptions, and the use of

Py_XDECREF() to dispose of owned references that may be NULL (note the 'X' in the name; Py_DECREF()

would crash when confronted with a NULL reference). It is important that the variables used to hold owned references

are initialized to NULL for this to work; likewise, the proposed return value is initialized to -1 (failure) and only set to

success after the ﬁnal call made is successful.

1.6 嵌入 Python

The one important task that only embedders (as opposed to extension writers) of the Python interpreter have to worry

about is the initialization, and possibly the ﬁnalization, of the Python interpreter. Most functionality of the interpreter

can only be used after the interpreter has been initialized.

The basic initialization function is Py_Initialize(). This initializes the table of loaded modules, and creates the

fundamental modules builtins, __main__, and sys. It also initializes the module search path (sys.path).

Py_Initialize() does not set the ”script argument list” (sys.argv). If this variable is needed by Python code that

will be executed later, it must be set explicitly with a call to PySys_SetArgvEx(argc, argv, updatepath)

after the call to Py_Initialize().

On most systems (in particular, on Unix and Windows, although the details are slightly diﬀerent), Py_Initialize()

calculates the module search path based upon its best guess for the location of the standard Python interpreter executable,

assuming that the Python library is found in a ﬁxed location relative to the Python interpreter executable. In particular, it

looks for a directory named lib/pythonX.Y relative to the parent directory where the executable named python is

found on the shell command search path (the environment variable PATH).

For instance, if the Python executable is found in /usr/local/bin/python, it will assume that the libraries are in /

usr/local/lib/pythonX.Y. (In fact, this particular path is also the ”fallback” location, used when no executable

ﬁle named python is found along PATH.) The user can override this behavior by setting the environment variable

PYTHONHOME, or insert additional directories in front of the standard path by setting PYTHONPATH.

The embedding application can steer the search by calling Py_SetProgramName(file) before calling

Py_Initialize(). Note that PYTHONHOME still overrides this and PYTHONPATH is still inserted in front of the

standard path. An application that requires total control has to provide its own implementation of Py_GetPath(),

Py_GetPrefix(), Py_GetExecPrefix(), and Py_GetProgramFullPath() (all deﬁned in Modules/

getpath.c).

Sometimes, it is desirable to ”uninitialize” Python. For instance, the application may want to start over (make another call

1.6. 嵌入 Python 11

The Python/C API, 发布 3.9.1rc1

to Py_Initialize()) or the application is simply done with its use of Python and wants to free memory allocated by

Python. This can be accomplished by calling Py_FinalizeEx(). The function Py_IsInitialized() returns

true if Python is currently in the initialized state. More information about these functions is given in a later chapter.

Notice that Py_FinalizeEx() does not free all memory allocated by the Python interpreter, e.g. memory allocated

by extension modules currently cannot be released.

1.7 调试构建

Python can be built with several macros to enable extra checks of the interpreter and extension modules. These checks

tend to add a large amount of overhead to the runtime so they are not enabled by default.

A full list of the various types of debugging builds is in the ﬁle Misc/SpecialBuilds.txt in the Python source

distribution. Builds are available that support tracing of reference counts, debugging the memory allocator, or low-level

proﬁling of the main interpreter loop. Only the most frequently-used builds will be described in the remainder of this

section.

Compiling the interpreter with the Py_DEBUG macro deﬁned produces what is generally meant by ”a debug build” of

Python. Py_DEBUG is enabled in the Unix build by adding --with-pydebug to the ./configure command. It is

also implied by the presence of the not-Python-speciﬁc _DEBUG macro. When Py_DEBUG is enabled in the Unix build,

compiler optimization is disabled.

除了前面描述的引用计数调试之外，还执行以下额外检查：

• 额外检查将添加到对象分配器。

• 额外的检查将添加到解析器和编译器中。

• Downcasts from wide types to narrow types are checked for loss of information.

• 许多断言被添加到字典和集合实现中。另外，集合对象需要 test_c_api() 方法。

• 输入参数的完整性检查被添加到框架创建中。

• 使用已知的无效模式初始化整型的存储，以捕获对未初始化数字的引用。

• 添加底层跟踪和额外的异常检查到虚拟机的运行时中。

• Extra checks are added to the memory arena implementation.

• 添加额外调试到线程模块。

这里可能没有提到的额外的检查。

Deﬁning Py_TRACE_REFS enables reference tracing. When deﬁned, a circular doubly linked list of active objects

is maintained by adding two extra ﬁelds to every PyObject. Total allocations are tracked as well. Upon exit, all

existing references are printed. (In interactive mode this happens after every statement run by the interpreter.) Implied

by Py_DEBUG.

有关更多详细信息，请参阅 Python 源代码中的 Misc/SpecialBuilds.txt 。

12 Chapter 1. 概述

剩余291页未读，继续阅读

omyligaga

粉丝: 88
资源: 2万+

Python/C API 3.9.1 参考手册.pdf详解及使用指南

Python 3.9.1 语言参考.pdf

Python 3.9.1 标准库参考.pdf

Python库的参考手册.pdf

Python3.9.1中文文档.pdf

最新版linux Python-3.9.1.tar.xz

Python编程-python-3.9.1中文文档.zip

python-3.9.1-cn.CHM

PyPI 官网下载 | futu-api-3.9.1.tar.gz

python-urlgrabber-3.9.1-8.el6.noarch.rpm

python-urlgrabber-3.9.1-11.el6.noarch.rpm

最新资源