Python 2.6 API 文档详解

需积分: 9 102 浏览量更新于2024-08-02 收藏 1.17MB PDF 举报

"Python 2.6 API指南" Python API文档是Python编程语言的一个核心组成部分，它详细描述了Python 2.6版本的接口和功能。这个文档由Guido van Rossum编写，Fred L. Drake, Jr.编辑，于2009年8月4日发布，由Python Software Foundation出版。这份PDF文档主要面向开发者，帮助他们理解和利用Python的内部机制，以创建高效的Python扩展和嵌入应用。文档内容分为多个部分，涵盖了Python的各个层面： 1. **介绍**：这部分简要介绍了Python C API（Python的C语言接口），它是用于在C语言程序中嵌入和扩展Python的工具。包括如何包含Python头文件、对象、类型和引用计数的基本概念。 2. **包括文件**：讲解了如何在C代码中引入Python头文件，这些头文件提供了访问Python API的接口。 3. **对象、类型和引用计数**：这部分深入解释了Python中的对象系统，包括对象的生命周期管理和内存管理，特别是引用计数技术。 4. **异常处理**：详述了Python的异常系统，包括如何抛出、捕获和处理异常，以及标准异常的列表。 5. **嵌入Python**：提供了关于如何将Python解释器嵌入到其他应用程序中的指导，使得非Python程序可以调用Python代码。 6. **调试构建**：讨论了如何构建带有调试信息的Python，这对于查找和修复代码问题至关重要。 7. **非常高层级层**：这部分可能涉及Python最顶层的抽象，如模块导入、系统函数等。 8. **引用计数**：进一步阐述了Python的垃圾回收机制，特别是其基于引用计数的策略。 9. **异常处理**：包括标准异常的定义和使用，以及对字符串异常弃用的讨论，这是Python 2.x向3.x过渡的一部分。 10. **实用工具**：这部分列出了各种辅助函数和模块，如操作系统工具、进程控制、数据序列化支持等。 11. **解析参数和构建值**：讲述了如何处理命令行参数、函数参数，以及构建返回值。 12. **字符串转换和格式化**：涵盖字符串操作，包括格式化输出和字符串解析。 13. **反射**：讨论了Python的元编程特性，允许程序在运行时检查和操作自身。 14. **抽象对象层**：这部分详细描述了Python对象模型，包括对象协议、数字协议、序列协议、映射协议、迭代器协议和旧的缓冲区协议。 15. **具体对象层**：涵盖了Python中的基础对象、数值对象、序列对象、映射对象和其他各种类型的对象。 16. **初始化**：可能涉及到Python对象的初始化和清理过程。通过这份文档，开发者能够掌握Python 2.6的核心API，包括如何创建自定义类型、处理异常、进行内存管理、与操作系统交互、以及实现高效的数据结构。对于那些需要在C语言环境中使用或扩展Python功能的开发人员来说，这是一个不可或缺的资源。

The Python/C API, Release 2.6.2

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. If ﬁlename is NULL, "???" is used instead. 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. If

ﬁlename is NULL, "???" is used instead. 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.6.2

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.

剩余165页未读，继续阅读

emmetyoung

粉丝: 5
资源: 16

Python 2.6 API 文档详解

jdk 6.0 API Document 文档

pythonAPI文档

apex api document

python api

python_document_c_api

python api pdf

Python 2.71 Document

Python_Document

MetaShape Python API 1.82

metashape python api 2.1.1版本

最新资源