Python C API指南：接口详解与版本差异

需积分: 9 63 浏览量更新于2024-07-18 收藏 1MB PDF 举报

“Python/C API是Python编程语言与C语言交互的核心接口，用于扩展Python的功能或在C语言中嵌入Python解释器。这份文档详细讲解了Python C API的使用，包括不同版本（2.x和3.x）间的差异。文档涵盖了编码标准、包含文件、有用的宏、对象类型与引用计数、异常处理、程序调试、稳定的应用二进制接口（ABI）、非常高层次的层、引用计数机制、异常处理策略、标准库功能等多个方面。” 1. **编码标准**： Python/C API的开发应遵循一定的编码规范，确保代码可读性和一致性。这些规范可能包括变量命名规则、注释风格等。 2. **包含文件**：在C语言中使用Python API时，需要包含特定的头文件，如`#include <Python.h>`，这个文件包含了所有必要的定义和声明。 3. **有用宏**：文档中提到了一些常用的宏，如`Py_INCREF()`和`Py_DECREF()`，它们用于增加或减少对象的引用计数，是管理Python对象生命周期的关键。 4. **对象、类型和引用计数**： Python对象在C API中有对应的C结构体表示，每个对象都有一个引用计数，用来跟踪对象的使用情况。当引用计数为零时，对象会被自动释放。 5. **异常处理**： C API提供了处理Python异常的机制，包括打印异常、清除异常、引发异常、发出警告以及检查错误指示器等功能。 6. **嵌入Python**：通过C API，可以将Python解释器嵌入到C/C++程序中，使Python脚本能在C环境中运行。 7. **调试构建**：对于开发者来说，有调试版本的C API可以帮助定位和修复问题，它提供了额外的检查和诊断信息。 8. **稳定应用二进制接口**： Python提供了一个稳定的ABI，使得第三方库可以依赖于特定版本的Python ABI，而不需要重新编译。 9. **非常高层次的层**：这部分可能涉及Python的高级特性，如模块、类、函数等的C语言实现细节。 10. **引用计数**：引用计数是Python内存管理的核心，C API提供了相应的API来操作对象的引用计数，以实现自动内存管理。 11. **异常类和对象**： C API允许创建和操作Python的异常类和实例，包括Unicode异常对象。 12. **递归控制**：在处理递归问题时，C API提供了防止栈溢出的机制。 13. **标准异常和警告类别**： C API提供了对Python内置异常和警告类别的访问和操作。 14. **工具和实用程序**：包括操作系统工具、系统函数、进程控制、模块导入、数据序列化支持、参数解析、字符串转换和格式化、反射机制等，帮助开发者更有效地集成Python和C代码。这份文档为开发者提供了一个全面的指南，帮助他们深入理解并有效利用Python/C API进行跨语言编程，无论是为了编写Python扩展模块还是在C/C++项目中嵌入Python解释器。

The Python/C API, Release 3.7.0

(continued from previous page)

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

}

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 Embedding 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().

10 Chapter 1. Introduction

The Python/C API, Release 3.7.0

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

dard 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 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 Debugging Builds

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.

In addition to the reference count debugging described below, the following extra checks are performed:

• Extra checks are added to the object allocator.

• Extra checks are added to the parser and compiler.

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

• A number of assertions are added to the dictionary and set implementations. In addition, the set

object acquires a test_c_api() method.

• Sanity checks of the input arguments are added to frame creation.

• The storage for ints is initialized with a known invalid pattern to catch reference to uninitialized digits.

• Low-level tracing and extra exception checking are added to the runtime virtual machine.

• Extra checks are added to the memory arena implementation.

• Extra debugging is added to the thread module.

1.7. Debugging Builds 11

剩余242页未读，继续阅读

Auto_Engneer

粉丝: 1
资源: 2

Python C API指南：接口详解与版本差异

Python Guide Document--写出好的代码

Python 2.71 Document

Python Document 经典资料

Python_Document

svm-python.rar_The First_py SVM_python SVM_svm python_svmpython

python_auto_doc.zip

GNU_Document

Jiangsu-Qin-Heng-CH340G_C14267_MyDocuments_document_

some_document:一些开源文档，适合我的工作

第7-0章_XML_DOM_API_2005

最新资源