Python C API 接口详解

需积分: 10 16 浏览量更新于2024-07-24 1 收藏 1.41MB PDF 举报

"Python_C_API 接口文档是Python编程语言的一个重要参考资料，它详细介绍了如何使用C语言来与Python交互，包括了Python的核心机制、对象类型、异常处理、引用计数、模块导入以及字符串处理等多个方面。这个文档适用于想要在C程序中嵌入Python解释器或扩展Python功能的开发者。" 1. **Python/C API简介** Python/C API提供了一种方式，让开发者可以使用C语言来编写Python扩展模块，或者在现有的C/C++程序中嵌入Python解释器。这使得开发者能够利用Python的高级特性同时利用C的高性能。 2. **包含文件** 开发者需要包含Python头文件，如`#include <Python.h>`，来访问Python的API函数和数据结构。 3. **对象、类型和引用计数** Python的所有对象都有一个引用计数，表示该对象被引用的次数。当引用计数为0时，对象会被自动释放，这是Python内存管理的关键部分。开发者需要理解如何正确地增加和减少对象的引用计数以避免内存泄漏。 4. **异常处理** C API提供了处理Python异常的机制。异常在C代码中表现为`PyObject*`类型的对象，可以通过`PyErr_Occurred()`检查是否发生异常，`PyErr_Fetch()`和`PyErr_Restore()`用于保存和恢复异常状态。 5. **嵌入Python** 在C程序中嵌入Python涉及到创建和初始化Python解释器，执行Python脚本，以及将结果返回到C环境中。 6. **调试构建** 对于开发和调试Python C扩展，文档还提到了特别编译的调试版本，它们包含额外的检查和调试信息。 7. **非常高层次的层** 这一部分涵盖了最基础的API接口，使得开发者可以轻松地与Python环境交互。 8. **引用计数** 引用计数是Python内存管理的核心，C API提供了相关函数如`Py_INCREF()`和`Py_DECREF()`来管理对象的生命周期。 9. **异常处理** 除了基本的异常检测，还包括了Unicode异常对象、递归控制、标准异常和字符串异常的处理。 10. **实用工具** - 操作系统工具：提供与操作系统交互的函数，如文件操作。 - 系统函数：包括时间、进程控制等。 - 进程控制：支持多线程和进程操作。 - 模块导入：允许在C代码中导入和使用Python模块。 - 数据序列化支持：用于序列化和反序列化Python对象。 - 解析参数和构建值：用于处理命令行参数和生成Python值。 - 字符串转换和格式化：提供了类似`printf`风格的字符串格式化方法。 - 反射：允许检查Python对象的属性和类型。 - 代码注册和支持函数：用于管理Python代码对象。 11. **抽象对象层** 这部分详细描述了Python对象的抽象接口，包括对象协议、数字协议、序列协议、映射协议、迭代器协议和旧版缓冲区协议，这些协议定义了对象的基本行为。 12. **具体对象层** 具体对象层涉及Python的内置对象，如基本类型（整数、浮点数、字符串等）、数值类型和序列、映射等的C API。 Python/C API接口文档是深入理解和使用Python的底层机制的宝贵资源，对于开发Python扩展和嵌入式应用至关重要。

The Python/C API, Release 2.7.1

Note that if an otherwise unhandled SystemError 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, PyCompilerFlags *ﬂ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 dictionaries globals and locals with the

12 Chapter 2. The Very High Level Layer

The Python/C API, Release 2.7.1

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 *locals,

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, PyObject

*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, PyObject

*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, PyCompilerFlags

*ﬂ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, PyObject

**args, int argcount, PyObject **kws, int kwcount, PyObject **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.

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.

剩余184页未读，继续阅读

cxiong02

粉丝: 0
资源: 1

Python C API 接口详解

Python api函数手册

pythonAPI（帮助文档）

python-pptx库英文文档完整版.pdf

Spire.Pdf.dll python pdf 转excel 调用dll实现

python实现翻译pdf

python win32api打印机打印pdf文件

python api文档下载

关于python怎么操作盖章

帮我下载一下使用python调用EPM hfm API接口的参考文档

python3.10 官方文档(全) api参考 最新pdf中文版

最新资源

python3.10 官方文档(全) api参考最新pdf中文版