Python C API 接口详解

需积分: 7 100 浏览量更新于2024-07-14 收藏 1.86MB PDF 举报

"Python C API 接口" 是Python编程语言提供的一种低级接口，允许开发者使用C语言直接操作和扩展Python解释器。这个文档详细介绍了如何使用C语言编写Python扩展模块，以及在C代码中与Python对象交互的各种机制。文档涵盖了多个主题，包括： 1. **概述**：这部分介绍了Python C API的基本概念，强调了代码标准和包含文件的使用，以及如何遵循Python的编码规范。 2. **代码标准**：详细说明了在编写C语言扩展时应遵循的编码和风格指南，确保代码与Python环境的兼容性。 3. **包含文件**：列出了一些关键的头文件，如`#include <Python.h>`，这些头文件提供了访问Python API的必要定义和函数声明。 4. **有用的宏**：介绍了用于处理Python对象和引用计数的一些常用宏，例如`Py_INCREF`和`Py_DECREF`，它们用于增加或减少对象的引用计数。 5. **对象、类型和引用计数**：详细讨论了Python对象的生命周期管理，包括引用计数的工作原理，以及如何创建和操作自定义类型。 6. **异常**：讲解了如何在C代码中捕获、处理和抛出自定义Python异常，以及如何与Python的异常系统交互。 7. **嵌入Python**：解释了如何在C程序中嵌入Python解释器，使得C代码能够执行Python脚本和交互。 8. **调试构建**：提供了关于如何构建带有调试信息的Python库，以便于在C扩展中进行调试的指导。 9. **稳定的应用程序二进制接口 (ABI)**：讨论了Python ABI的稳定性，这对于确保不同版本的Python之间扩展模块的兼容性至关重要。 10. **The Very High Level Layer**：介绍了一些高级API，使得C程序员可以更方便地操作Python对象。 11. **引用计数**、**异常处理**、**工具**、**抽象对象层**等章节分别深入探讨了各自的主题，包括异常的打印、清除、抛出、警告处理、信号处理、标准异常和警告类别、操作系统接口、数据序列化、字符串转换、反射、编解码器注册等功能。 12. **对象协议**、**调用协议**、**数字协议**、**序列协议**和**映射协议**：详细阐述了Python对象在C API中的行为规范，包括如何实现自定义类型的方法调用、数字操作、序列操作和映射操作。通过这个文档，开发者能够学习到如何高效且安全地在C语言环境中利用Python的强大功能，创建高性能的Python扩展模块，或者在已有的C/C++项目中集成Python。

The Python/C API, 发布 3.9.2

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;

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 */

(下页继续)

10 Chapter 1. 概述

The Python/C API, 发布 3.9.2

(续上页)

}

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 in-

terpreter 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 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.

1.6. 嵌入 Python 11

剩余278页未读，继续阅读

钱玉璞

粉丝: 0
资源: 13

Python C API 接口详解

Python_C_API_接口文档.pdf

MOSEK_API_for_Python.pdf

PythonC API 3.9.1 参考手册.pdf

C_CPP_python.pdf.zip_C python_pdf_python C#_python pdf

python_c__api.pdf

Python C API指南：接口设计与对象管理

MATLAB C_C++, Fortran, Java, and Python API.pdf

Python_developer‘s_handbook.pdf.pdf

c-api.pdf

08.扩展和嵌入python.pdf

最新资源