概述?

代碼標(biāo)準(zhǔn)?

如果你想要編寫可包含于 CPython 的 C 代碼，你 必須 遵循在 PEP 7 中定義的指導(dǎo)原則和標(biāo)準(zhǔn)。這些指導(dǎo)原則適用于任何你所要擴(kuò)展的 Python 版本。在編寫你自己的第三方擴(kuò)展模塊時(shí)可以不必遵循這些規(guī)范，除非你準(zhǔn)備在日后向 Python 貢獻(xiàn)這些模塊。

包含文件?

使用 Python/C API 所需要的全部函數(shù)、類型和宏定義可通過下面這行語句包含到你的代碼之中：

#define PY_SSIZE_T_CLEAN
#include <Python.h>

這意味著包含以下標(biāo)準(zhǔn)頭文件：<stdio.h>，<string.h>，<errno.h>，<limits.h>，<assert.h> 和 <stdlib.h>（如果可用）。

Python.h 所定義的全部用戶可見名稱（由包含的標(biāo)準(zhǔn)頭文件所定義的除外）都帶有前綴 Py 或者 _Py。以 _Py 打頭的名稱是供 Python 實(shí)現(xiàn)內(nèi)部使用的，不應(yīng)被擴(kuò)展編寫者使用。結(jié)構(gòu)成員名稱沒有保留前綴。

頭文件通常會與 Python 一起安裝。在 Unix 上，它們位于以下目錄：prefix/include/pythonversion/ 和 exec_prefix/include/pythonversion/，其中 prefix 和 exec_prefix 是由向 Python 的 configure 腳本傳入的對應(yīng)形參所定義，而 version 則為 '%d.%d' % sys.version_info[:2]。在 Windows 上，頭文件安裝于 prefix/include，其中 prefix 是向安裝程序指定的安裝目錄。

要包含頭文件，請將兩個(gè)目錄（如果不同）都放到你所用編譯器的包含搜索路徑中。請 不要 將父目錄放入搜索路徑然后使用 #include <pythonX.Y/Python.h>；這將使得多平臺編譯不可用，因?yàn)?prefix 下平臺無關(guān)的頭文件需要包含來自 exec_prefix 下特定平臺的頭文件。

C++ 用戶應(yīng)該注意，盡管 API 是完全使用 C 來定義的，但頭文件正確地將入口點(diǎn)聲明為 extern "C"，因此 API 在 C++ 中使用此 API 不必再做任何特殊處理。

有用的宏?

Python 頭文件中定義了一些有用的宏。許多是在靠近它們被使用的地方定義的（例如 Py_RETURN_NONE）。其他更為通用的則定義在這里。這里所顯示的并不是一個(gè)完整的列表。

Py_ABS(x)?

返回 x 的絕對值。

3.3 新版功能.

Py_ALWAYS_INLINE?

Ask the compiler to always inline a static inline function. The compiler can ignore it and decides to not inline the function.

It can be used to inline performance critical static inline functions when building Python in debug mode with function inlining disabled. For example, MSC disables function inlining when building in debug mode.

Marking blindly a static inline function with Py_ALWAYS_INLINE can result in worse performances (due to increased code size for example). The compiler is usually smarter than the developer for the cost/benefit analysis.

If Python is built in debug mode (if the Py_DEBUG macro is defined), the Py_ALWAYS_INLINE macro does nothing.

It must be specified before the function return type. Usage:

static inline Py_ALWAYS_INLINE int random(void) { return 4; }

3.11 新版功能.

Py_CHARMASK(c)?

參數(shù)必須為 [-128, 127] 或 [0, 255] 范圍內(nèi)的字符或整數(shù)類型。這個(gè)宏將 c 強(qiáng)制轉(zhuǎn)換為 unsigned char 返回。

Py_DEPRECATED(version)?

棄用聲明。該宏必須放置在符號名稱前。

示例:

Py_DEPRECATED(3.8) PyAPI_FUNC(int) Py_OldFunction(void);

在 3.8 版更改: 添加了 MSVC 支持。

Py_GETENV(s)?

與 getenv(s) 類似，但是如果命令行上傳遞了 -E ，則返回 NULL （即如果設(shè)置了 Py_IgnoreEnvironmentFlag ）。

Py_MAX(x, y)?

返回 x 和 y 當(dāng)中的最大值。

3.3 新版功能.

Py_MEMBER_SIZE(type, member)?

返回結(jié)構(gòu) (type) member 的大小，以字節(jié)表示。

3.6 新版功能.

Py_MIN(x, y)?

返回 x 和 y 當(dāng)中的最小值。

3.3 新版功能.

Py_NO_INLINE?

Disable inlining on a function. For example, it reduces the C stack consumption: useful on LTO+PGO builds which heavily inline code (see bpo-33720).

Usage:

Py_NO_INLINE static int random(void) { return 4; }

3.11 新版功能.

Py_STRINGIFY(x)?

將 x 轉(zhuǎn)換為 C 字符串。例如 Py_STRINGIFY(123) 返回 "123"。

3.4 新版功能.

Py_UNREACHABLE()?

這個(gè)可以在你有一個(gè)設(shè)計(jì)上無法到達(dá)的代碼路徑時(shí)使用。例如，當(dāng)一個(gè) switch 語句中所有可能的值都已被 case 子句覆蓋了，就可將其用在 default: 子句中。當(dāng)你非常想在某個(gè)位置放一個(gè) assert(0) 或 abort() 調(diào)用時(shí)也可以用這個(gè)。

在 release 模式下，該宏幫助編譯器優(yōu)化代碼，并避免發(fā)出不可到達(dá)代碼的警告。例如，在 GCC 的 release 模式下，該宏使用 __builtin_unreachable() 實(shí)現(xiàn)。

Py_UNREACHABLE() 的一個(gè)用法是調(diào)用一個(gè)不會返回，但卻沒有聲明 _Py_NO_RETURN 的函數(shù)之后。

如果一個(gè)代碼路徑不太可能是正常代碼，但在特殊情況下可以到達(dá)，就不能使用該宏。例如，在低內(nèi)存條件下，或者一個(gè)系統(tǒng)調(diào)用返回超出預(yù)期范圍值，諸如此類，最好將錯誤報(bào)告給調(diào)用者。如果無法將錯誤報(bào)告給調(diào)用者，可以使用 Py_FatalError() 。

3.7 新版功能.

Py_UNUSED(arg)?

用于函數(shù)定義中未使用的參數(shù)，從而消除編譯器警告。例如： int func(int a, int Py_UNUSED(b)) { return a; } 。

3.4 新版功能.

PyDoc_STRVAR(name, str)?

創(chuàng)建一個(gè)可以在文檔字符串中使用的，名字為 name 的變量。如果不和文檔字符串一起構(gòu)建 Python，該值將為空。

如 PEP 7 所述，使用 PyDoc_STRVAR 作為文檔字符串，以支持不和文檔字符串一起構(gòu)建 Python 的情況。

示例:

PyDoc_STRVAR(pop_doc, "Remove and return the rightmost element.");

static PyMethodDef deque_methods[] = {
    // ...
    {"pop", (PyCFunction)deque_pop, METH_NOARGS, pop_doc},
    // ...
}

PyDoc_STR(str)?

為給定的字符串輸入創(chuàng)建一個(gè)文檔字符串，或者當(dāng)文檔字符串被禁用時(shí)，創(chuàng)建一個(gè)空字符串。

如 PEP 7 所述，使用 PyDoc_STR 指定文檔字符串，以支持不和文檔字符串一起構(gòu)建 Python 的情況。

示例:

static PyMethodDef pysqlite_row_methods[] = {
    {"keys", (PyCFunction)pysqlite_row_keys, METH_NOARGS,
        PyDoc_STR("Returns the keys of the row.")},
    {NULL, NULL}
};

對象、類型和引用計(jì)數(shù)?

多數(shù) Python/C API 有一個(gè)或多個(gè)參數(shù)，以及一個(gè) PyObject* 類型的返回值。這種類型是指向任意 Python 對象的不透明數(shù)據(jù)類型的指針。所有 Python 對象類型在大多數(shù)情況下都被 Python 語言由相同的方式處理（例如，賦值，作用域規(guī)則，和參數(shù)傳遞），因此將它們由單個(gè) C 類型表示才合適。幾乎所有 Python 對象存放在堆中：你不能聲明一個(gè)類型為 PyObject 的自動或靜態(tài)的變量，只能聲明類型為 PyObject* 的指針。type 對象是唯一的例外，因?yàn)樗鼈冇肋h(yuǎn)不能被釋放，所以它們通常是靜態(tài)的 PyTypeObject 對象。

所有 Python 對象（甚至 Python 整數(shù)）都有一個(gè) type 和一個(gè) reference count。對象的類型確定它是什么類型的對象（例如整數(shù)、列表或用戶定義函數(shù)；還有更多，如 標(biāo)準(zhǔn)類型層級結(jié)構(gòu) 中所述）。對于每個(gè)眾所周知的類型，都有一個(gè)宏來檢查對象是否屬于該類型；例如，當(dāng)（且僅當(dāng)） a 所指的對象是 Python 列表時(shí) PyList_Check(a) 為真。

PyObject *t;

t = PyTuple_New(3);
PyTuple_SetItem(t, 0, PyLong_FromLong(1L));
PyTuple_SetItem(t, 1, PyLong_FromLong(2L));
PyTuple_SetItem(t, 2, PyUnicode_FromString("three"));

PyObject *tuple, *list;

tuple = Py_BuildValue("(iis)", 1, 2, "three");
list = Py_BuildValue("[iis]", 1, 2, "three");

int
set_all(PyObject *target, PyObject *item)
{
    Py_ssize_t i, n;

    n = PyObject_Length(target);
    if (n < 0)
        return -1;
    for (i = 0; i < n; i++) {
        PyObject *index = PyLong_FromSsize_t(i);
        if (!index)
            return -1;
        if (PyObject_SetItem(target, index, item) < 0) {
            Py_DECREF(index);
            return -1;
        }
        Py_DECREF(index);
    }
    return 0;
}

long
sum_list(PyObject *list)
{
    Py_ssize_t i, n;
    long total = 0, value;
    PyObject *item;

    n = PyList_Size(list);
    if (n < 0)
        return -1; /* Not a list */
    for (i = 0; i < n; i++) {
        item = PyList_GetItem(list, i); /* Can't fail */
        if (!PyLong_Check(item)) continue; /* Skip non-integers */
        value = PyLong_AsLong(item);
        if (value == -1 && PyErr_Occurred())
            /* Integer too big to fit in a C long, bail out */
            return -1;
        total += value;
    }
    return total;
}

long
sum_sequence(PyObject *sequence)
{
    Py_ssize_t i, n;
    long total = 0, value;
    PyObject *item;
    n = PySequence_Length(sequence);
    if (n < 0)
        return -1; /* Has no length */
    for (i = 0; i < n; i++) {
        item = PySequence_GetItem(sequence, i);
        if (item == NULL)
            return -1; /* Not a sequence, or other failure */
        if (PyLong_Check(item)) {
            value = PyLong_AsLong(item);
            Py_DECREF(item);
            if (value == -1 && PyErr_Occurred())
                /* Integer too big to fit in a C long, bail out */
                return -1;
            total += value;
        }
        else {
            Py_DECREF(item); /* Discard reference ownership */
        }
    }
    return total;
}

異常?

Python程序員只需要處理特定需要處理的錯誤異常；未處理的異常會自動傳遞給調(diào)用者，然后傳遞給調(diào)用者的調(diào)用者，依此類推，直到他們到達(dá)頂級解釋器，在那里將它們報(bào)告給用戶并伴隨堆?；厮?。

For C programmers, however, error checking always has to be explicit. All functions in the Python/C API can raise exceptions, unless an explicit claim is made otherwise in a function's documentation. In general, when a function encounters an error, it sets an exception, discards any object references that it owns, and returns an error indicator. If not documented otherwise, this indicator is either NULL or -1, depending on the function's return type. A few functions return a Boolean true/false result, with false indicating an error. Very few functions return no explicit error indicator or have an ambiguous return value, and require explicit testing for errors with PyErr_Occurred(). These exceptions are always explicitly documented.

Exception state is maintained in per-thread storage (this is equivalent to using global storage in an unthreaded application). A thread can be in one of two states: an exception has occurred, or not. The function PyErr_Occurred() can be used to check for this: it returns a borrowed reference to the exception type object when an exception has occurred, and NULL otherwise. There are a number of functions to set the exception state: PyErr_SetString() is the most common (though not the most general) function to set the exception state, and PyErr_Clear() clears the exception state.

The full exception state consists of three objects (all of which can be NULL): the exception type, the corresponding exception value, and the traceback. These have the same meanings as the Python result of sys.exc_info(); however, they are not the same: the Python objects represent the last exception being handled by a Python try ... except statement, while the C level exception state only exists while an exception is being passed on between C functions until it reaches the Python bytecode interpreter's main loop, which takes care of transferring it to sys.exc_info() and friends.

Note that starting with Python 1.5, the preferred, thread-safe way to access the exception state from Python code is to call the function sys.exc_info(), which returns the per-thread exception state for Python code. Also, the semantics of both ways to access the exception state have changed so that a function which catches an exception will save and restore its thread's exception state so as to preserve the exception state of its caller. This prevents common 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

下面是對應(yīng)的閃耀榮光的 C 代碼：

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

This example represents an endorsed use of the goto statement in C! It illustrates the use of PyErr_ExceptionMatches() and PyErr_Clear() to handle specific 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 final call made is successful.

嵌入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 finalization, 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, setting PyConfig.argv and PyConfig.parse_argv must be set: see Python Initialization Configuration.

On most systems (in particular, on Unix and Windows, although the details are slightly different), 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 fixed 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 file 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 defined 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.

調(diào)試構(gòu)建?

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 file Misc/SpecialBuilds.txt in the Python source distribution. Builds are available that support tracing of reference counts, debugging the memory allocator, or low-level profiling 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 defined 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-specific _DEBUG macro. When Py_DEBUG is enabled in the Unix build, compiler optimization is disabled.

In addition to the reference count debugging described below, extra checks are performed, see Python Debug Build.

Defining Py_TRACE_REFS enables reference tracing (see the configure --with-trace-refs option). When defined, a circular doubly linked list of active objects is maintained by adding two extra fields to every PyObject. Total allocations are tracked as well. Upon exit, all existing references are printed. (In interactive mode this happens after every statement run by the interpreter.)

有關(guān)更多詳細(xì)信息，請參閱Python源代碼中的 Misc/SpecialBuilds.txt 。