Python C-API深度解析：关键接口与实现

需积分: 10 46 浏览量更新于2024-07-20 收藏 815KB PDF 举报

本文档是关于Python官方的C接口(C API)的详细指南，由Guido van Rossum和Python开发团队于2016年9月发布，适用于Python 2.7.12版本。这份文档深入探讨了如何通过C语言与Python进行交互，包括了从头到尾的关键知识点。 **1. Introduction (介绍)**：文档首先介绍了C API的基本概念，涵盖了必要的包含文件、对象类型和引用计数管理。它强调了在C程序中嵌入Python的重要性，并提到了调试构建的方法，帮助开发者理解如何在底层操作Python环境。 **2. The Very High Level Layer (高级层)**：这部分讨论了Python与C之间的高层次接口，涉及如何处理Python对象、异常处理和基本的系统功能调用，如操作系统支持、系统函数和进程控制。 **3. Reference Counting (引用计数)**： Python使用引用计数来管理对象生命周期，这部分详细解释了这个机制以及如何在C API中与之协作，确保内存管理的正确性。 **4. Exception Handling (异常处理)**：这部分着重讲解了如何在C代码中处理Python的异常，包括Unicode异常对象、递归控制、标准异常和字符串异常的处理。这些都是保证程序健壮性和错误处理的重要部分。 **5. Utilities (工具)**：涵盖了一系列实用功能，如操作系统的交互、模块导入、数据类型转换、参数解析、字符串操作、反射（用于获取类和方法信息）以及代码注册和支持函数。 **6. Abstract Objects Layer (抽象对象层)**：这部分定义了Python对象的行为规范，包括对象协议、数字协议、序列协议、映射协议以及迭代器协议等，这些协议是实现自定义Python对象的核心。 **7. Concrete Objects Layer (具体对象层)**：最后，文档深入到具体的Python对象和数据类型，如基础对象、数值类型的操作，以及如何处理更复杂的Python数据结构如列表和字典。这份Python C API文档是为C程序员设计的，它提供了实现Python扩展模块、操作Python内部机制和进行高效交互的必要知识。理解和掌握这些内容对于那些希望利用C语言与Python集成或创建高性能Python扩展的开发者来说至关重要。通过学习并实践文档中的内容，开发者可以更好地与Python的内核交互，实现丰富的功能和优化性能。

The Python/C API, Release 2.7.12

Note that if an otherwise unhandled SystemExit is raised, this function will not return -1, but exit the

process, as long as Py_InspectFlag is not set.

int PyRun_SimpleFile(FILE *fp, const char *ﬁlename)

This is a simpliﬁed interface to PyRun_SimpleFileExFlags() below, leaving closeit set to 0 and

ﬂags set to NULL.

int PyRun_SimpleFileFlags(FILE *fp, const char *ﬁlename, PyCompilerFlags *ﬂags)

This is a simpliﬁed interface to PyRun_SimpleFileExFlags() below, leaving closeit set to 0.

int PyRun_SimpleFileEx(FILE *fp, const char *ﬁlename, int closeit)

This is a simpliﬁed interface to PyRun_SimpleFileExFlags() below, leaving ﬂags set to NULL.

int PyRun_SimpleFileExFlags(FILE *fp, const char *ﬁlename, int closeit, PyCompiler-

Flags *ﬂags)

Similar to PyRun_SimpleStringFlags(), but the Python source code is read from fp instead of an

in-memory string. ﬁlename should be the name of the ﬁle. If closeit is true, the ﬁle is closed before

PyRun_SimpleFileExFlags returns.

int PyRun_InteractiveOne(FILE *fp, const char *ﬁlename)

This is a simpliﬁed interface to PyRun_InteractiveOneFlags() below, leaving ﬂags set to NULL.

int PyRun_InteractiveOneFlags(FILE *fp, const char *ﬁlename, PyCompilerFlags *ﬂags)

Read and execute a single statement from a ﬁle associated with an interactive device according to the

ﬂags argument. The user will be prompted using sys.ps1 and sys.ps2. Returns 0 when the input

was executed successfully, -1 if there was an exception, or an error code from the errcode.h include

ﬁle distributed as part of Python if there was a parse error. (Note that errcode.h is not included by

Python.h, so must be included speciﬁcally if needed.)

int PyRun_InteractiveLoop(FILE *fp, const char *ﬁlename)

This is a simpliﬁed interface to PyRun_InteractiveLoopFlags() below, leaving ﬂags set to NULL.

int PyRun_InteractiveLoopFlags(FILE *fp, const char *ﬁlename, PyCompilerFlags *ﬂags)

Read and execute statements from a ﬁle associated with an interactive device until EOF is reached. The user

will be prompted using sys.ps1 and sys.ps2. Returns 0 at EOF.

struct _node* PyParser_SimpleParseString(const char *str, int start)

This is a simpliﬁed interface to PyParser_SimpleParseStringFlagsFilename() below, leav-

ing ﬁlename set to NULL and ﬂags set to 0.

struct _node* PyParser_SimpleParseStringFlags(const char *str, int start, int ﬂags)

This is a simpliﬁed interface to PyParser_SimpleParseStringFlagsFilename() below, leav-

ing ﬁlename set to NULL.

struct _node* PyParser_SimpleParseStringFlagsFilename(const char *str, const char *ﬁle-

name, int start, int ﬂags)

Parse Python source code from str using the start token start according to the ﬂags argument. The result can

be used to create a code object which can be evaluated efﬁciently. This is useful if a code fragment must be

evaluated many times.

struct _node* PyParser_SimpleParseFile(FILE *fp, const char *ﬁlename, int start)

This is a simpliﬁed interface to PyParser_SimpleParseFileFlags() below, leaving ﬂags set to 0.

struct _node* PyParser_SimpleParseFileFlags(FILE *fp, const char *ﬁlename, int start,

int ﬂags)

Similar to PyParser_SimpleParseStringFlagsFilename(), but the Python source code is read

from fp instead of an in-memory string.

PyObject* PyRun_String(const char *str, int start, PyObject *globals, PyObject *locals)

Return value: New reference. This is a simpliﬁed interface to PyRun_StringFlags() below, leaving

ﬂags set to NULL.

PyObject* PyRun_StringFlags(const char *str, int start, PyObject *globals, PyObject *locals, Py-

CompilerFlags *ﬂags)

Return value: New reference. Execute Python source code from str in the context speciﬁed by the dictio-

12 Chapter 2. The Very High Level Layer

The Python/C API, Release 2.7.12

naries globals and locals with the compiler ﬂags speciﬁed by ﬂags. The parameter start speciﬁes the start

token that should be used to parse the source code.

Returns the result of executing the code as a Python object, or NULL if an exception was raised.

PyObject* PyRun_File(FILE *fp, const char *ﬁlename, int start, PyObject *globals, PyObject *locals)

Return value: New reference. This is a simpliﬁed interface to PyRun_FileExFlags() below, leaving

closeit set to 0 and ﬂags set to NULL.

PyObject* PyRun_FileEx(FILE *fp, const char *ﬁlename, int start, PyObject *globals, PyObject *lo-

cals, int closeit)

Return value: New reference. This is a simpliﬁed interface to PyRun_FileExFlags() below, leaving

ﬂags set to NULL.

PyObject* PyRun_FileFlags(FILE *fp, const char *ﬁlename, int start, PyObject *globals, PyOb-

ject *locals, PyCompilerFlags *ﬂags)

Return value: New reference. This is a simpliﬁed interface to PyRun_FileExFlags() below, leaving

closeit set to 0.

PyObject* PyRun_FileExFlags(FILE *fp, const char *ﬁlename, int start, PyObject *globals, PyOb-

ject *locals, int closeit, PyCompilerFlags *ﬂags)

Return value: New reference. Similar to PyRun_StringFlags(), but the Python source code is read

from fp instead of an in-memory string. ﬁlename should be the name of the ﬁle. If closeit is true, the ﬁle is

closed before PyRun_FileExFlags() returns.

PyObject* Py_CompileString(const char *str, const char *ﬁlename, int start)

Return value: New reference. This is a simpliﬁed interface to Py_CompileStringFlags() below,

leaving ﬂags set to NULL.

PyObject* Py_CompileStringFlags(const char *str, const char *ﬁlename, int start, PyCompiler-

Flags *ﬂags)

Return value: New reference. Parse and compile the Python source code in str, returning the resulting code

object. The start token is given by start; this can be used to constrain the code which can be compiled

and should be Py_eval_input, Py_file_input, or Py_single_input. The ﬁlename speciﬁed

by ﬁlename is used to construct the code object and may appear in tracebacks or SyntaxError exception

messages. This returns NULL if the code cannot be parsed or compiled.

PyObject* PyEval_EvalCode(PyCodeObject *co, PyObject *globals, PyObject *locals)

Return value: New reference. This is a simpliﬁed interface to PyEval_EvalCodeEx(), with just the

code object, and the dictionaries of global and local variables. The other arguments are set to NULL.

PyObject* PyEval_EvalCodeEx(PyCodeObject *co, PyObject *globals, PyObject *locals, PyOb-

ject **args, int argcount, PyObject **kws, int kwcount, PyOb-

ject **defs, int defcount, PyObject *closure)

Evaluate a precompiled code object, given a particular environment for its evaluation. This environment

consists of dictionaries of global and local variables, arrays of arguments, keywords and defaults, and a

closure tuple of cells.

PyObject* PyEval_EvalFrame(PyFrameObject *f )

Evaluate an execution frame. This is a simpliﬁed interface to PyEval_EvalFrameEx, for backward compat-

ibility.

PyObject* PyEval_EvalFrameEx(PyFrameObject *f, int throwﬂag)

This is the main, unvarnished function of Python interpretation. It is literally 2000 lines long. The code ob-

ject associated with the execution frame f is executed, interpreting bytecode and executing calls as needed.

The additional throwﬂag parameter can mostly be ignored - if true, then it causes an exception to immedi-

ately be thrown; this is used for the throw() methods of generator objects.

int PyEval_MergeCompilerFlags(PyCompilerFlags *cf )

This function changes the ﬂags of the current evaluation frame, and returns true on success, false on failure.

int Py_eval_input

The start symbol from the Python grammar for isolated expressions; for use with

Py_CompileString().

CHAPTER

THREE

REFERENCE COUNTING

The macros in this section are used for managing reference counts of Python objects.

void Py_INCREF(PyObject *o)

Increment the reference count for object o. The object must not be NULL; if you aren’t sure that it isn’t

NULL, use Py_XINCREF().

void Py_XINCREF(PyObject *o)

Increment the reference count for object o. The object may be NULL, in which case the macro has no effect.

void Py_DECREF(PyObject *o)

Decrement the reference count for object o. The object must not be NULL; if you aren’t sure that it isn’t

NULL, use Py_XDECREF(). If the reference count reaches zero, the object’s type’s deallocation function

(which must not be NULL) is invoked.

Warning: The deallocation function can cause arbitrary Python code to be invoked (e.g. when a class

instance with a __del__() method is deallocated). While exceptions in such code are not propagated,

the executed code has free access to all Python global variables. This means that any object that is

reachable from a global variable should be in a consistent state before Py_DECREF() is invoked. For

example, code to delete an object from a list should copy a reference to the deleted object in a temporary

variable, update the list data structure, and then call Py_DECREF() for the temporary variable.

void Py_XDECREF(PyObject *o)

Decrement the reference count for object o. The object may be NULL, in which case the macro has no

effect; otherwise the effect is the same as for Py_DECREF(), and the same warning applies.

void Py_CLEAR(PyObject *o)

Decrement the reference count for object o. The object may be NULL, in which case the macro has no effect;

otherwise the effect is the same as for Py_DECREF(), except that the argument is also set to NULL. The

warning for Py_DECREF() does not apply with respect to the object passed because the macro carefully

uses a temporary variable and sets the argument to NULL before decrementing its reference count.

It is a good idea to use this macro whenever decrementing the value of a variable that might be traversed

during garbage collection.

New in version 2.4.

The following functions are for runtime dynamic embedding of Python: Py_IncRef(PyObject

o),

Py_DecRef(PyObject

o). They are simply exported function versions of Py_XINCREF() and

Py_XDECREF(), respectively.

The following functions or macros are only for use within the interpreter core: _Py_Dealloc(),

_Py_ForgetReference(), _Py_NewReference(), as well as the global variable _Py_RefTotal.

剩余188页未读，继续阅读

qq_21443919

粉丝: 0
资源: 2

Python C-API深度解析：关键接口与实现

C语言和python3.0的资料

cpython-3.10.2-1.5.7-API文档-中文版.zip

python/c API 参考手册

python3-dev

python2-dev是什么

如何使用Python-C API在C++中调用Python函数？

Python-dev包是什么东西

python3-dev bash: /usr/lib/command-not-found: /usr/bin/python3: bad interpreter: No such file or directory

树莓派pico-python-sdk-中文版

如何让安装python-ipopt

最新资源