1. Extending Python with C or C++ — Python 3.14.5 文档
Description: It is quite easy to add new built-in modules to Python, if you know how to program in C. Such extension modules can do two things that can't be done directly in Python: they can implement new ...

# 1. Extending Python with C or C++

It is quite easy to add new built-in modules to Python, if you know how to program in C. Such extension modules can do two things that can't be done directly in Python: they can implement new built-in object types, and they can call C library functions and system calls.

To support extensions, the Python API (Application Programmers Interface) defines a set of functions, macros and variables that provide access to most aspects of the Python run-time system. The Python API is incorporated in a C source file by including the header `"Python.h"`.

The compilation of an extension module depends on its intended use as well as on your system setup; details are given in later chapters.

备注

The C extension interface is specific to CPython, and extension modules do not work on other Python implementations. In many cases, it is possible to avoid writing C extensions and preserve portability to other implementations. For example, if your use case is calling C library functions or system calls, you should consider using the `ctypes` module or the cffi library rather than writing custom C code. These modules let you write Python code to interface with C code and are more portable between implementations of Python than writing and compiling a C extension module.

## 1.1. A Simple Example

Let's create an extension module called `spam` (the favorite food of Monty Python fans...) and let's say we want to create a Python interface to the C library function `system()` [1]. This function takes a null-terminated character string as argument and returns an integer. We want this function to be callable from Python as follows:

    >>> import spam
    >>> status = spam.system("ls -l")

Begin by creating a file `spammodule.c`. (Historically, if a module is called `spam`, the C file containing its implementation is called `spammodule.c`; if the module name is very long, like `spammify`, the module name can be just `spammify.c`.)

The first two lines of our file can be:

    #define PY_SSIZE_T_CLEAN
    #include <Python.h>

which pulls in the Python API (you can add a comment describing the purpose of the module and a copyright notice if you like).

备注

Since Python may define some pre-processor definitions which affect the standard headers on some systems, you must include `Python.h` before any standard headers are included.

`#define PY_SSIZE_T_CLEAN` was used to indicate that `Py_ssize_t` should be used in some APIs instead of `int`. It is not necessary since Python 3.13, but we keep it here for backward compatibility. See 字符串和缓冲区 for a description of this macro.

All user-visible symbols defined by `Python.h` have a prefix of `Py` or `PY`, except those defined in standard header files.

小技巧

For backward compatibility, `Python.h` includes several standard header files. C extensions should include the standard headers that they use, and should not rely on these implicit includes. If using the limited C API version 3.13 or newer, the implicit includes are:

- `<assert.h>`

- `<intrin.h>` (on Windows)

- `<inttypes.h>`

- `<limits.h>`

- `<math.h>`

- `<stdarg.h>`

- `<wchar.h>`

- `<sys/types.h>` (if present)

If `Py_LIMITED_API` is not defined, or is set to version 3.12 or older, the headers below are also included:

- `<ctype.h>`

- `<unistd.h>` (on POSIX)

If `Py_LIMITED_API` is not defined, or is set to version 3.10 or older, the headers below are also included:

- `<errno.h>`

- `<stdio.h>`

- `<stdlib.h>`

- `<string.h>`

The next thing we add to our module file is the C function that will be called when the Python expression `spam.system(string)` is evaluated (we'll see shortly how it ends up being called):

    static PyObject *
    spam_system(PyObject *self, PyObject *args)
    {
        const char *command;
        int sts;

        if (!PyArg_ParseTuple(args, "s", &command))
            return NULL;
        sts = system(command);
        return PyLong_FromLong(sts);
    }

There is a straightforward translation from the argument list in Python (for example, the single expression `"ls -l"`) to the arguments passed to the C function. The C function always has two arguments, conventionally named self and args.

The self argument points to the module object for module-level functions; for a method it would point to the object instance.

The args argument will be a pointer to a Python tuple object containing the arguments. Each item of the tuple corresponds to an argument in the call's argument list. The arguments are Python objects --- in order to do anything with them in our C function we have to convert them to C values. The function `PyArg_ParseTuple()` in the Python API checks the argument types and converts them to C values. It uses a template string to determine the required types of the arguments as well as the types of the C variables into which to store the converted values. More about this later.

`PyArg_ParseTuple()` returns true (nonzero) if all arguments have the right type and its components have been stored in the variables whose addresses are passed. It returns false (zero) if an invalid argument list was passed. In the latter case it also raises an appropriate exception so the calling function can return `NULL` immediately (as we saw in the example).

## 1.2. Intermezzo: Errors and Exceptions

整个 Python 解释器系统有一个如下所述的重要惯例：当一个函数运行失败时，它应当设置一个异常条件并返回一个错误值（通常为 `-1` 或 `NULL` 指针）。异常信息保存在解释器线程状态的三个成员中。如果没有异常则它们的值为 `NULL`。在其他情况下它们是 `sys.exc_info()` 所返回的 Python 元组的成员的 C 对应物。它们分别是异常类型、异常实例和回溯对象。 理解它们对于理解错误是如何被传递的非常重要。

Python API 中定义了一些函数来设置这些变量。

最常用的就是 `PyErr_SetString()`。其参数是异常对象和 C 字符串。异常对象一般是像 `PyExc_ZeroDivisionError` 这样的预定义对象。C 字符串指明异常原因，并被转换为一个 Python 字符串对象存储为异常的“关联值”。

另一个有用的函数是 `PyErr_SetFromErrno()`，仅接受一个异常对象，异常描述包含在全局变量 `errno` 中。最通用的函数还是 `PyErr_SetObject()` ，包含两个参数，分别为异常对象和异常描述。你不需要使用 `Py_INCREF()` 来增加传递到其他函数的参数对象的引用计数。

你可以通过 `PyErr_Occurred()` 在不造成破坏的情况下检测是否设置了异常。这将返回当前异常对象，或者如果未发生异常则返回 `NULL`。你通常不需要调用 `PyErr_Occurred()` 来查看函数调用中是否发生了错误，因为你应该能从返回值中看出来。

当一个函数 f 调用另一个函数 g 时检测到后者出错了，f 应当自己返回一个错误值 (通常为 `NULL` 或 `-1`)。它 不应 调用某个 `PyErr_*` 函数 --- 这类函数已经被 g 调用过了。 f 的调用者随后也应当返回一个错误来提示 它的 调用者，同样 不应 调用 `PyErr_*`，依此类推 --- 错误的最详细原因已经由首先检测到它的函数报告了。一旦这个错误到达 Python 解释器的主循环，它会中止当前执行的 Python 代码并尝试找出由 Python 程序员所指定的异常处理器。

（在某些情况下模块确实能够通过调用其它 `PyErr_*` 函数来给出更为详细的错误消息，并且在这些情况下是可以这样做的。 但是按照一般规则，这是不必要的，并可能导致有关错误的信息丢失：大多数操作会由于种种原因而失败。）

想要忽略由一个失败的函数调用所设置的异常，异常条件必须通过调用 `PyErr_Clear()` 显式地被清除。C 代码应当调用 `PyErr_Clear()` 的唯一情况是如果它不想将错误传给解释器而是想完全由自己来处理它（可能是尝试其他方法，或是假装没有出错）。

每次失败的 `malloc()` 调用必须转换为一个异常。 `malloc()` (或 `realloc()` ) 的直接调用者必须调用 `PyErr_NoMemory()` 来返回错误来提示。所有对象创建函数 (例如 `PyLong_FromLong()` ) 已经这么做了，所以这个提示仅用于直接调用 `malloc()` 的情况。

还要注意的是，除了 `PyArg_ParseTuple()` 等重要的例外，返回整数状态码的函数通常都是返回正值或零来表示成功，而以 `-1` 表示失败，如同 Unix 系统调用一样。

最后，当你返回一个错误指示器时要注意清理垃圾（通过为你已经创建的对象执行 `Py_XDECREF()` 或 `Py_DECREF()` 调用）！

选择引发哪个异常完全取决于你的喜好。所有 Python 内置异常都有对应的预声明 C 对象，例如 `PyExc_ZeroDivisionError`，你可以直接使用它们。当然，你应当明智地选择异常 --- 不要使用 `PyExc_TypeError` 来表示文件无法打开（可能应该用 `PyExc_OSError` 比较好）。 如果参数列表有问题，`PyArg_ParseTuple()` 函数通常会引发 `PyExc_TypeError`。 如果你希望一个参数的值必须在特定范围内或必须满足其他条件，则适宜使用 `PyExc_ValueError`。

你也可以定义你的模块独有的新异常。做到这点的最简单方式是在文件的开头声明一个静态全局对象变量:

    static PyObject *SpamError = NULL;

并通过在模块的 `Py_mod_exec` 函数 (`spam_module_exec()`) 中调用 `PyErr_NewException()` 来初始化它:

    SpamError = PyErr_NewException("spam.error", NULL, NULL);

由于 `SpamError` 是一个全局变量，它将在模块每次重新初始化时被覆盖，即当 `Py_mod_exec` 函数被调用时。

在目前，让我们避免这个问题：我们将通过引发 `ImportError` 来阻止重复的初始化:

    static PyObject *SpamError = NULL;

    static int
    spam_module_exec(PyObject *m)
    {
        if (SpamError != NULL) {
            PyErr_SetString(PyExc_ImportError,
                            "cannot initialize spam module more than once");
            return -1;
        }
        SpamError = PyErr_NewException("spam.error", NULL, NULL);
        if (PyModule_AddObjectRef(m, "SpamError", SpamError) < 0) {
            return -1;
        }

        return 0;
    }

    static PyModuleDef_Slot spam_module_slots[] = {
        {Py_mod_exec, spam_module_exec},
        {0, NULL}
    };

    static struct PyModuleDef spam_module = {
        .m_base = PyModuleDef_HEAD_INIT,
        .m_name = "spam",
        .m_size = 0,  // non-negative
        .m_slots = spam_module_slots,
    };

    PyMODINIT_FUNC
    PyInit_spam(void)
    {
        return PyModuleDef_Init(&spam_module);
    }

请注意该异常对象的 Python 名称为 `spam.error`。 `PyErr_NewException()` 函数可以创建基类为 `Exception` 的类 (除非传入了另一个类而不是 `NULL`)，如 内置异常 中所描述的。

请注意 `SpamError` 变量保留了一个对新创建的异常类的引用；这是有意为之的！ 由于异常可能会被外部代码从模块中删除，因此需要拥有一个对该类的引用以确保它不会被丢弃，从而导致 `SpamError` 成为一个悬空指针。如果异常类成为悬空指针，则引发该异常的 C 代码可能会导致核心转储或其他预期之外的附带影响。

在目前，用于移除该引用的 `Py_DECREF()` 调用是缺失的。即使是在 Python 解释器关闭时，全局变量 `SpamError` 也不会被当作垃圾回收。它将会“泄漏”。不过，我们确实能保证这在每个进程中最多发生一次。

本样例稍后将讨论 `PyMODINIT_FUNC` 作为函数返回类型的用法。

可在扩展模块中调用 `PyErr_SetString()` 来引发 `spam.error` 异常，如下所示:

    static PyObject *
    spam_system(PyObject *self, PyObject *args)
    {
        const char *command;
        int sts;

        if (!PyArg_ParseTuple(args, "s", &command))
            return NULL;
        sts = system(command);
        if (sts < 0) {
            PyErr_SetString(SpamError, "System command failed");
            return NULL;
        }
        return PyLong_FromLong(sts);
    }

## 1.3. Back to the Example

Going back to our example function, you should now be able to understand this statement:

    if (!PyArg_ParseTuple(args, "s", &command))
        return NULL;

It returns `NULL` (the error indicator for functions returning object pointers) if an error is detected in the argument list, relying on the exception set by `PyArg_ParseTuple()`. Otherwise the string value of the argument has been copied to the local variable `command`. This is a pointer assignment and you are not supposed to modify the string to which it points (so in Standard C, the variable `command` should properly be declared as `const char *command`).

The next statement is a call to the Unix function `system()`, passing it the string we just got from `PyArg_ParseTuple()`:

    sts = system(command);

Our `spam.system()` function must return the value of `sts` as a Python object. This is done using the function `PyLong_FromLong()`.

    return PyLong_FromLong(sts);

In this case, it will return an integer object. (Yes, even integers are objects on the heap in Python!)

If you have a C function that returns no useful argument (a function returning void), the corresponding Python function must return `None`. You need this idiom to do so (which is implemented by the `Py_RETURN_NONE` macro):

    Py_INCREF(Py_None);
    return Py_None;

`Py_None` is the C name for the special Python object `None`. It is a genuine Python object rather than a `NULL` pointer, which means "error" in most contexts, as we have seen.

## 1.4. The Module's Method Table and Initialization Function

I promised to show how `spam_system()` is called from Python programs. First, we need to list its name and address in a "method table":

    static PyMethodDef spam_methods[] = {
        ...
        {"system",  spam_system, METH_VARARGS,
         "Execute a shell command."},
        ...
        {NULL, NULL, 0, NULL}        /* Sentinel */
    };

Note the third entry (`METH_VARARGS`). This is a flag telling the interpreter the calling convention to be used for the C function. It should normally always be `METH_VARARGS` or `METH_VARARGS | METH_KEYWORDS`; a value of `0` means that an obsolete variant of `PyArg_ParseTuple()` is used.

When using only `METH_VARARGS`, the function should expect the Python-level parameters to be passed in as a tuple acceptable for parsing via `PyArg_ParseTuple()`; more information on this function is provided below.

The `METH_KEYWORDS` bit may be set in the third field if keyword arguments should be passed to the function. In this case, the C function should accept a third `PyObject *` parameter which will be a dictionary of keywords. Use `PyArg_ParseTupleAndKeywords()` to parse the arguments to such a function.

The method table must be referenced in the module definition structure:

    static struct PyModuleDef spam_module = {
        ...
        .m_methods = spam_methods,
        ...
    };

This structure, in turn, must be passed to the interpreter in the module's initialization function. The initialization function must be named `PyInit_name()`, where name is the name of the module, and should be the only non-`static` item defined in the module file:

    PyMODINIT_FUNC
    PyInit_spam(void)
    {
        return PyModuleDef_Init(&spam_module);
    }

Note that `PyMODINIT_FUNC` declares the function as `PyObject *` return type, declares any special linkage declarations required by the platform, and for C++ declares the function as `extern "C"`.

`PyInit_spam()` is called when each interpreter imports its module `spam` for the first time. (See below for comments about embedding Python.) A pointer to the module definition must be returned via `PyModuleDef_Init()`, so that the import machinery can create the module and store it in `sys.modules`.

When embedding Python, the `PyInit_spam()` function is not called automatically unless there's an entry in the `PyImport_Inittab` table. To add the module to the initialization table, use `PyImport_AppendInittab()`, optionally followed by an import of the module:

    #define PY_SSIZE_T_CLEAN
    #include <Python.h>

    int
    main(int argc, char *argv[])
    {
        PyStatus status;
        PyConfig config;
        PyConfig_InitPythonConfig(&config);

        /* Add a built-in module, before Py_Initialize */
        if (PyImport_AppendInittab("spam", PyInit_spam) == -1) {
            fprintf(stderr, "Error: could not extend in-built modules table\n");
            exit(1);
        }

        /* Pass argv[0] to the Python interpreter */
        status = PyConfig_SetBytesString(&config, &config.program_name, argv[0]);
        if (PyStatus_Exception(status)) {
            goto exception;
        }

        /* Initialize the Python interpreter.  Required.
           If this step fails, it will be a fatal error. */
        status = Py_InitializeFromConfig(&config);
        if (PyStatus_Exception(status)) {
            goto exception;
        }
        PyConfig_Clear(&config);

        /* Optionally import the module; alternatively,
           import can be deferred until the embedded script
           imports it. */
        PyObject *pmodule = PyImport_ImportModule("spam");
        if (!pmodule) {
            PyErr_Print();
            fprintf(stderr, "Error: could not import module 'spam'\n");
        }

        // ... use Python C API here ...

        return 0;

      exception:
         PyConfig_Clear(&config);
         Py_ExitStatusException(status);
    }

备注

If you declare a global variable or a local static one, the module may experience unintended side-effects on re-initialisation, for example when removing entries from `sys.modules` or importing compiled modules into multiple interpreters within a process (or following a `fork()` without an intervening `exec()`). If module state is not yet fully isolated, authors should consider marking the module as having no support for subinterpreters (via `Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED`).

A more substantial example module is included in the Python source distribution as `Modules/xxlimited.c`. This file may be used as a template or simply read as an example.

## 1.5. Compilation and Linkage

There are two more things to do before you can use your new extension: compiling and linking it with the Python system. If you use dynamic loading, the details may depend on the style of dynamic loading your system uses; see the chapters about building extension modules (chapter 构建 C/C++ 扩展) and additional information that pertains only to building on Windows (chapter 在 Windows 上构建 C 和 C++ 扩展) for more information about this.

If you can't use dynamic loading, or if you want to make your module a permanent part of the Python interpreter, you will have to change the configuration setup and rebuild the interpreter. Luckily, this is very simple on Unix: just place your file (`spammodule.c` for example) in the `Modules/` directory of an unpacked source distribution, add a line to the file `Modules/Setup.local` describing your file:

    spam spammodule.o

然后在顶层目录运行 make 来重新构建解释器。你也可以在 `Modules/` 子目录使用 make，但是你必须先重建 `Makefile` 文件，然后运行 'make Makefile' 命令。（你每次修改 `Setup` 文件都需要这样操作。）

如果你的模块需要额外的链接，这些内容可以列出在配置文件里，举个实例：

    spam spammodule.o -lX11

## 1.6. 在 C 中调用 Python 函数

So far we have concentrated on making C functions callable from Python. The reverse is also useful: calling Python functions from C. This is especially the case for libraries that support so-called "callback" functions. If a C interface makes use of callbacks, the equivalent Python often needs to provide a callback mechanism to the Python programmer; the implementation will require calling the Python callback functions from a C callback. Other uses are also imaginable.

幸运的是，Python 解释器是比较方便回调的，并给标准 Python 函数提供了标准接口。(这里就不再详述解析 Python 字符串作为输入的方式，如果有兴趣可以参考 `Modules/main.c` 中的 `-c` 命令行代码。)

调用 Python 函数很简单，首先 Python 程序要传递 Python 函数对象。应该提供个函数 (或其他接口) 来实现。当调用这个函数时，用全局变量保存 Python 函数对象的指针，还要调用 (`Py_INCREF()`) 来增加引用计数，当然不用全局变量也没什么关系。举个例子，如下函数可能是模块定义的一部分：

    static PyObject *my_callback = NULL;

    static PyObject *
    my_set_callback(PyObject *dummy, PyObject *args)
    {
        PyObject *result = NULL;
        PyObject *temp;

        if (PyArg_ParseTuple(args, "O:set_callback", &temp)) {
            if (!PyCallable_Check(temp)) {
                PyErr_SetString(PyExc_TypeError, "parameter must be callable");
                return NULL;
            }
            Py_XINCREF(temp);         /* 添加一个指向新回调的引用 */
            Py_XDECREF(my_callback);  /* 丢弃之前的回调 */
            my_callback = temp;       /* 记住新的回调 */
            /* 返回 "None" 的样例 */
            Py_INCREF(Py_None);
            result = Py_None;
        }
        return result;
    }

This function must be registered with the interpreter using the `METH_VARARGS` flag; this is described in section The Module's Method Table and Initialization Function. The `PyArg_ParseTuple()` function and its arguments are documented in section 提取扩展函数的参数.

`Py_XINCREF()` 和 `Py_XDECREF()` 这两个宏可增加/减少一个对象的引用计数，并且当存在 `NULL` 指针时仍可保证安全 (但请注意在这个上下文中 temp 将不为 `NULL`)。更多相关信息请参考 引用计数 章节。

随后，当要调用此函数时，你将调用 C 函数 `PyObject_CallObject()`。该函数有两个参数，它们都属于指针，指向任意 Python 对象：即 Python 函数，及其参数列表。参数列表必须总是一个元组对象，其长度即参数的个数。要不带参数地调用 Python 函数，则传入 `NULL` 或一个空元组；要带一个参数调用它，则传入一个单元组。 `Py_BuildValue()` 会在其格式字符串包含一对圆括号内的零个或多个格式代码时返回一个元组。例如:

    int arg;
    PyObject *arglist;
    PyObject *result;
    ...
    arg = 123;
    ...
    /* 此时将调用回调 */
    arglist = Py_BuildValue("(i)", arg);
    result = PyObject_CallObject(my_callback, arglist);
    Py_DECREF(arglist);

`PyObject_CallObject()` 返回 Python 对象指针，这也是 Python 函数的返回值。 `PyObject_CallObject()` 是一个对其参数 "引用计数无关" 的函数。例子中新的元组创建用于参数列表，并且在 `PyObject_CallObject()` 之后立即使用了 `Py_DECREF()`。

`PyObject_CallObject()` 的返回值总是“新”的：要么是一个新建的对象；要么是已有对象，但增加了引用计数。所以除非你想把结果保存在全局变量中，你需要对这个值使用 `Py_DECREF()`，即使你对里面的内容（特别！）不感兴趣。

但是在你这么做之前，很重要的一点是检查返回值不是 `NULL`。如果是的话，Python 函数会终止并引发异常。如果调用 `PyObject_CallObject()` 的 C 代码是在 Python 中唤起的，它应当立即返回一个错误来告知其 Python 调用者，以便解释器能打印栈回溯信息，或者让调用方 Python 代码能处理该异常。如果这无法做到或不合本意，则应当通过调用 `PyErr_Clear()` 来清除异常。例如:

    if (result == NULL)
        return NULL; /* 回传错误 */
    ...使用 result...
    Py_DECREF(result);

依赖于具体的回调函数，你还要提供一个参数列表到 `PyObject_CallObject()` 。在某些情况下参数列表是由 Python 程序提供的，通过接口再传到回调函数对象。这样就可以不改变形式直接传递。另外一些时候你要构造一个新的元组来传递参数。最简单的方法就是 `Py_BuildValue()` 函数构造 tuple。举个例子，你要传递一个事件代码时可以用如下代码：

    PyObject *arglist;
    ...
    arglist = Py_BuildValue("(l)", eventcode);
    result = PyObject_CallObject(my_callback, arglist);
    Py_DECREF(arglist);
    if (result == NULL)
        return NULL; /* Pass error back */
    /* 可以在此使用 result */
    Py_DECREF(result);

注意 `Py_DECREF(arglist)` 所在处会立即调用，在错误检查之前。当然还要注意一些常规的错误，比如 `Py_BuildValue()` 可能会遭遇内存不足等等。

当你调用函数时还需要注意，用关键字参数调用 `PyObject_Call()`，需要支持普通参数和关键字参数。有如如上例子中，我们使用 `Py_BuildValue()` 来构造字典。

    PyObject *dict;
    ...
    dict = Py_BuildValue("{s:i}", "name", val);
    result = PyObject_Call(my_callback, NULL, dict);
    Py_DECREF(dict);
    if (result == NULL)
        return NULL; /* 回传错误 */
    /* 可以在此使用 result */
    Py_DECREF(result);

## 1.7. 提取扩展函数的参数

The `PyArg_ParseTuple()` function is declared as follows:

    int PyArg_ParseTuple(PyObject *arg, const char *format, ...);

参数 arg 必须是一个元组对象，包含从 Python 传递给 C 函数的参数列表。format 参数必须是一个格式字符串，语法请参考 Python C/API 手册中的 解析参数并构建值变量。剩余参数是各个变量的地址，类型要与格式字符串对应。

注意 `PyArg_ParseTuple()` 会检测他需要的 Python 参数类型，却无法检测传递给他的 C 变量地址，如果这里出错了，可能会在内存中随机写入东西，小心。

注意任何由调用者提供的 Python 对象引用是 借来的 引用；不要递减它们的引用计数！

一些调用的例子：

    #define PY_SSIZE_T_CLEAN
    #include <Python.h>

    int ok;
    int i, j;
    long k, l;
    const char *s;
    Py_ssize_t size;

    ok = PyArg_ParseTuple(args, ""); /* 无参数 */
        /* Python 调用：f() */

    ok = PyArg_ParseTuple(args, "s", &s); /* 一个字符串 */
        /* 可能的 Python 调用：f('whoops!') */

    ok = PyArg_ParseTuple(args, "lls", &k, &l, &s); /* 两个长整型和一个字符串 */
        /* 可能的 Python 调用：f(1, 2, 'three') */

    ok = PyArg_ParseTuple(args, "(ii)s#", &i, &j, &s, &size);
        /* 一对整数和一个字符串，其大小也将被返回 */
        /* 可能的 Python 调用：f((1, 2), 'three') */

    {
        const char *file;
        const char *mode = "r";
        int bufsize = 0;
        ok = PyArg_ParseTuple(args, "s|si", &file, &mode, &bufsize);
        /* 一个字符串，并可选择传入另一个字符串和一个整数 */
        /* 可能的 Python 调用:
           f('spam')
           f('spam', 'w')
           f('spam', 'wb', 100000) */
    }

    {
        int left, top, right, bottom, h, v;
        ok = PyArg_ParseTuple(args, "((ii)(ii))(ii)",
                 &left, &top, &right, &bottom, &h, &v);
        /* 一个矩形和一个点 */
        /* 可能的 Python 调用:
           f(((0, 0), (400, 300)), (10, 10)) */
    }

    {
        Py_complex c;
        ok = PyArg_ParseTuple(args, "D:myfunction", &c);
        /* 一个复数，并提供一个函数名用于错误处理 */
        /* 可能的 Python 调用：myfunction(1+2j) */
    }

## 1.8. 给扩展函数的关键字参数

函数 `PyArg_ParseTupleAndKeywords()` 声明如下：

    int PyArg_ParseTupleAndKeywords(PyObject *arg, PyObject *kwdict,
                                    const char *format, char * const *kwlist, ...);

arg 与 format 形参与 `PyArg_ParseTuple()` 函数所定义的一致。 kwdict 形参是作为第三个参数从 Python 运行时接收的关键字字典。 kwlist 形参是以 `NULL` 结尾的字符串列表，它被用来标识形参；名称从左至右与来自 format 的类型信息相匹配。 如果执行成功，`PyArg_ParseTupleAndKeywords()` 会返回真值，否则返回假值并引发一个适当的异常。

备注

嵌套的元组在使用关键字参数时无法生效，不在 kwlist 中的关键字参数会导致 `TypeError` 异常。

如下例子是使用关键字参数的例子模块，作者是 Geoff Philbrick (philbrick@hks.com):

    #define PY_SSIZE_T_CLEAN
    #include <Python.h>

    static PyObject *
    keywdarg_parrot(PyObject *self, PyObject *args, PyObject *keywds)
    {
        int voltage;
        const char *state = "a stiff";
        const char *action = "voom";
        const char *type = "Norwegian Blue";

        static char *kwlist[] = {"voltage", "state", "action", "type", NULL};

        if (!PyArg_ParseTupleAndKeywords(args, keywds, "i|sss", kwlist,
                                         &voltage, &state, &action, &type))
            return NULL;

        printf("-- This parrot wouldn't %s if you put %i Volts through it.\n",
               action, voltage);
        printf("-- Lovely plumage, the %s -- It's %s!\n", type, state);

        Py_RETURN_NONE;
    }

    static PyMethodDef keywdarg_methods[] = {
        /* The cast of the function is necessary since PyCFunction values
         * only take two PyObject* parameters, and keywdarg_parrot() takes
         * three.
         */
        {"parrot", (PyCFunction)(void(*)(void))keywdarg_parrot, METH_VARARGS | METH_KEYWORDS,
         "Print a lovely skit to standard output."},
        {NULL, NULL, 0, NULL}   /* sentinel */
    };

    static struct PyModuleDef keywdarg_module = {
        .m_base = PyModuleDef_HEAD_INIT,
        .m_name = "keywdarg",
        .m_size = 0,
        .m_methods = keywdarg_methods,
    };

    PyMODINIT_FUNC
    PyInit_keywdarg(void)
    {
        return PyModuleDef_Init(&keywdarg_module);
    }

## 1.9. 构造任意值

这个函数与 `PyArg_ParseTuple()` 很相似，声明如下：

    PyObject *Py_BuildValue(const char *format, ...);

它接受一系列与 `PyArg_ParseTuple()` 所识别的格式单元类似的格式单元，但其参数（作为函数的输入而非输出）不能是指针，而必须是值。它返回一个新的 Python 对象，适合于从被 Python 调用的 C 函数返回。

一个与 `PyArg_ParseTuple()` 的不同是，后者要求其第一个参数为元组（因为 Python 参数列表在内部总是表示为元组），`Py_BuildValue()` 并不总是生成元组。它只在格式字符串包含两个或更多格式单元时才生成元组。如果格式字符串为空则返回 `None` ；如果仅包含一个格式单元则返回该格式单元所描述的对象。如果要强制生成一个长度为 0 或 1 的元组，需要在格式字符串中加上括号。

例子 (左侧是调用，右侧是 Python 值结果)：

    Py_BuildValue("")                        None
    Py_BuildValue("i", 123)                  123
    Py_BuildValue("iii", 123, 456, 789)      (123, 456, 789)
    Py_BuildValue("s", "hello")              'hello'
    Py_BuildValue("y", "hello")              b'hello'
    Py_BuildValue("ss", "hello", "world")    ('hello', 'world')
    Py_BuildValue("s#", "hello", 4)          'hell'
    Py_BuildValue("y#", "hello", 4)          b'hell'
    Py_BuildValue("()")                      ()
    Py_BuildValue("(i)", 123)                (123,)
    Py_BuildValue("(ii)", 123, 456)          (123, 456)
    Py_BuildValue("(i,i)", 123, 456)         (123, 456)
    Py_BuildValue("[i,i]", 123, 456)         [123, 456]
    Py_BuildValue("{s:i,s:i}",
                  "abc", 123, "def", 456)    {'abc': 123, 'def': 456}
    Py_BuildValue("((ii)(ii)) (ii)",
                  1, 2, 3, 4, 5, 6)          (((1, 2), (3, 4)), (5, 6))

## 1.10. 引用计数

在 C/C++ 语言中，程序员负责动态分配和回收堆 heap 当中的内存。在 C 里，通过函数 `malloc()` 和 `free()` 来完成。在 C++ 里是操作 `new` 和 `delete` 来实现相同的功能。

每个使用 `malloc()` 分配的内存块最终都应当通过恰好一次对 `free()` 的调用返回到可用内存池中。调用 `free()` 的时机非常重要。如果一个块地址被遗忘而没有为它执行 `free()` 调用，它所占用的内存在程序终结之前将无法被重新使用。这就称为 内存泄漏。另一方面，如果程序为一个块地址调用了 `free()` 然后却继续使用该内存块，它将与通过另一个 `malloc()` 调用对该内存块的重新使用产生冲突。这就称为 使用已释放的内存。它所造成的后果与引用未初始化数据一样糟糕 --- 核心转储、错误结果、意外崩溃等等。

内存泄露往往发生在一些并不常见的代码流程上面。比如一个函数申请了内存以后，做了些计算，然后释放内存块。现在一些对函数的修改可能增加对计算的测试并检测错误条件，然后过早的从函数返回了。这很容易忘记在退出前释放内存，特别是后期修改的代码。这种内存泄漏，一旦引入，通常很长时间都难以检测到，错误退出被调用的频度较低，而现代电脑又有非常巨大的虚拟内存，所以泄漏仅在长期运行或频繁调用泄漏函数时才会变得明显。因此，有必要避免内存泄漏，通过代码规范会策略来最小化此类错误。

Python 通过 `malloc()` 和 `free()` 包含大量的内存分配和释放，同样需要避免内存泄漏和野指针。他选择的方法就是 引用计数 。其原理比较简单：每个对象都包含一个计数器，计数器的增减与对象引用的增减直接相关，当引用计数为 0 时，表示对象已经没有存在的意义了，对象就可以删除了。

另一个叫法是 自动垃圾回收 。(有时引用计数也被看作是垃圾回收策略，于是这里的"自动"用以区分两者)。自动垃圾回收的优点是用户不需要明确的调用 `free()` 。(另一个优点是改善速度或内存使用，然而这并不难)。缺点是对 C，没有可移植的自动垃圾回收器，而引用计数则可以可移植的实现 (只要 `malloc()` 和 `free()` 函数是可用的，这也是 C 标准担保的)。也许以后有一天会出现可移植的自动垃圾回收器，但在此前我们必须与引用计数一起工作。

Python 使用传统的引用计数实现，也提供了循环监测器，用以检测引用循环。这使得应用无需担心直接或间接的创建了循环引用，这是引用计数垃圾收集的一个弱点。引用循环是对象 (可能直接) 的引用了本身，所以循环中的每个对象的引用计数都不是 0。典型的引用计数实现无法回收处于引用循环中的对象，或者被循环所引用的对象，哪怕没有循环以外的引用了。

循环检测器能够检测垃圾回收循环并能回收它们。 `gc` 模块提供了一种运行该检测器的方式 (`collect()` 函数)，以及多个配置接口和在运行时禁用该检测器的功能。

### 1.10.1. Python 中的引用计数

有两个宏 `Py_INCREF(x)` 和 `Py_DECREF(x)`，会处理引用计数的增减。 `Py_DECREF()` 也会在引用计数到达 0 时释放对象。为了灵活，并不会直接调用 `free()`，而是通过对象的 类型对象 的函数指针来调用。为了这个目的 (或其他的)，每个对象同时包含一个指向自身类型对象的指针。

最大的问题依旧：何时使用 `Py_INCREF(x)` 和 `Py_DECREF(x)` ？我们首先引入一些概念。 没有人"拥有"一个对象，你可以 拥有一个引用 到一个对象。一个对象的引用计数定义为拥有引用的数量。 引用的拥有者有责任调用 `Py_DECREF()`，在引用不再需要时。 引用的拥有关系可以被传递。有三种办法来处置拥有的引用：传递、存储、调用 `Py_DECREF()`。 忘记处置一个拥有的引用会导致内存泄漏。

It is also possible to borrow [2] a reference to an object. The borrower of a reference should not call `Py_DECREF()`. The borrower must not hold on to the object longer than the owner from which it was borrowed. Using a borrowed reference after the owner has disposed of it risks using freed memory and should be avoided completely [3].

借用相对于引用的优点是你无需担心整条路径上代码的引用，或者说，通过借用你无需担心内存泄漏的风险。借用的缺点是一些看起来正确代码上的借用可能会在拥有者处置后使用对象。

借用可以变为拥有引用，通过调用 `Py_INCREF()`。这不会影响已经借出的拥有者的状态。 这会创建一个新的拥有引用，并给予完全的拥有者责任（新的拥有者必须恰当的处置引用，就像之前的拥有者那样）。

### 1.10.2. 拥有规则

当一个对象引用传递进出一个函数时，函数的接口应该指定拥有关系的传递是否包含引用。

大多数函数返回一个对象的引用，并传递引用拥有关系。通常，所有创建对象的函数，例如 `PyLong_FromLong()` 和 `Py_BuildValue()`，会传递拥有关系给接收者。即便是对象不是真正新的，你仍然可以获得对象的新引用。一个实例是 `PyLong_FromLong()` 维护了一个流行值的缓存，并可以返回已缓存项目的新引用。

很多另一个对象提取对象的函数，也会传递引用关系，例如 `PyObject_GetAttrString()` 。这里的情况不够清晰，一些不太常用的例程是例外的 `PyTuple_GetItem()`， `PyList_GetItem()` , `PyDict_GetItem()` , `PyDict_GetItemString()` 都是返回从元组、列表、字典里借用的引用。

函数 `PyImport_AddModule()` 也会返回借用的引用，哪怕可能会返回创建的对象：这个可能因为一个拥有的引用对象是存储在 `sys.modules` 里。

当你传递一个对象引用到另一个函数时，通常函数是借用出去的。如果需要存储，就使用 `Py_INCREF()` 来变成独立的拥有者。这个规则有两个重要的例外： `PyTuple_SetItem()` 和 `PyList_SetItem()` 。这些函数接受传递来的引用关系，哪怕会失败！(注意 `PyDict_SetItem()` 及其同类不会接受引用关系，他们是"正常的")。

当一个 C 函数被 Python 调用时，会从调用方传来的参数借用引用。调用者拥有对象的引用，所以借用的引用生命周期可以保证到函数返回。只要当借用的引用需要存储或传递时，就必须转换为拥有的引用，通过调用 `Py_INCREF()` .

Python 调用从 C 函数返回的对象引用时必须是拥有的引用---拥有关系被从函数传递给调用者。

### 1.10.3. 危险的薄冰

有少数情况下，借用的引用看起来无害，但却可能导致问题。这通常是因为解释器的隐式调用，并可能导致引用拥有者处置这个引用。

首先需要特别注意的情况是使用 `Py_DECREF()` 到一个无关对象，而这个对象的引用是借用自一个列表的元素。举个实例：

    void
    bug(PyObject *list)
    {
        PyObject *item = PyList_GetItem(list, 0);

        PyList_SetItem(list, 1, PyLong_FromLong(0L));
        PyObject_Print(item, stdout, 0); /* BUG! */
    }

这个函数首先借用一个引用 `list[0]`，然后替换 `list[1]` 为值 `0`，最后打印借用的引用。看起来无害是吧，但却不是。

让我们跟随控制流进入 `PyList_SetItem()`。该列表拥有对其全部条目的引用，因此当条目 1 被替换时，它必须丢弃原来的条目 1。现在让我们假定原来的条目 1 是某个用户自定义类的实例，并让我们假定该类定义了 `__del__()` 方法。如果该类实例的引用计数为 1，丢弃它将会调用其 `__del__()` 方法。在内部，`PyList_SetItem()` 会调用被替换条目的 `Py_DECREF()`，这将唤起被替换条目的对应的 `tp_dealloc` 函数。 在撤销分配期间，`tp_dealloc` 会调用 `tp_finalize`，它被映射到用于类实例的 `__del__()` 方法 (参见 PEP 442)。以上整个过程是在 `PyList_SetItem()` 调用内部同步发生的。

由于它是用 Python 编写的，因此 `__del__()` 方法可以执行任意 Python 代码。它是否可以使 `bug()` 中对 `item` 的引用失效呢？当然可以！假定传入 `bug()` 的列表可以被 `__del__()` 方法访问，它就可以执行一条语句实现 `del list[0]` 的效果，假定这是对该对象的最后一次引用，它就会释放与之相关联的内存，从而使 `item` 失效。

解决方法是，当你知道了问题的根源，就容易了：临时增加引用计数。正确版本的函数代码如下：

    void
    no_bug(PyObject *list)
    {
        PyObject *item = PyList_GetItem(list, 0);

        Py_INCREF(item);
        PyList_SetItem(list, 1, PyLong_FromLong(0L));
        PyObject_Print(item, stdout, 0);
        Py_DECREF(item);
    }

这是一个真实的故事。一个较旧版本的 Python 曾经包含此问题的变化形式，有人在 C 语言调试器中花费了大量时间，才弄明白为什么他的 `__del__()` 方法会失败……

有关借入引用的问题的第二种情况是涉及线程的变种。通常，Python 解释器中的多个线程不会相互影响，因为有一个 全局锁 在保护 Python 的整个对象空间。不过，有可能使用宏 `Py_BEGIN_ALLOW_THREADS` 来临时释放这个锁，并使用 `Py_END_ALLOW_THREADS` 来重新获取它。这在阻塞型 I/O 调用操作中很常见，可以让其他线程在等待 I/O 结束期间使用处理器。显然，下面的函数与之前那个存在相同的问题:

    void
    bug(PyObject *list)
    {
        PyObject *item = PyList_GetItem(list, 0);
        Py_BEGIN_ALLOW_THREADS
        ...some blocking I/O call...
        Py_END_ALLOW_THREADS
        PyObject_Print(item, stdout, 0); /* BUG! */
    }

### 1.10.4. NULL 指针

通常，接受对象引用作为参数的函数不希望你传给它们 `NULL` 指针，并且当你这样做时将会转储核心（或在以后导致核心转储）。 返回对象引用的函数通常只在要指明发生了异常时才返回 `NULL`。不检测 `NULL` 参数的原因在于这些函数经常要将它们所接收的对象传给其他函数 --- 如果每个函数都检测 `NULL`，将会导致大量的冗余检测而使代码运行得更缓慢。

更好的做法是仅在“源头”上检测 `NULL`，即在接收到一个可能为 `NULL` 的指针，例如来自 `malloc()` 或是一个可能引发异常的函数的时候。

`Py_INCREF()` 和 `Py_DECREF()` 等宏不会检测 `NULL` 指针 --- 但是，它们的变种 `Py_XINCREF()` 和 `Py_XDECREF()` 则会检测。

用于检测特定对象类型的宏 (`Pytype_Check()`) 不会检测 `NULL` 指针 --- 同样地，有大量代码会连续调用这些宏来测试一个对象是否为几种不同预期类型之一，这将会生成冗余的测试。不存在带有 `NULL` 检测的变体。

The C function calling mechanism guarantees that the argument list passed to C functions (`args` in the examples) is never `NULL` --- in fact it guarantees that it is always a tuple [4].

任何时候将 `NULL` 指针“泄露”给 Python 用户都会是个严重的错误。

## 1.11. 在 C++ 中编写扩展

还可以在 C++ 中编写扩展模块，只是有些限制。如果主程序（Python 解释器）是使用 C 编译器来编译和链接的，全局或静态对象的构造器就不能使用。而如果是 C++ 编译器来链接的就没有这个问题。函数会被 Python 解释器调用（通常就是模块初始化函数）必须声明为 `extern "C"`。而是否在 `extern "C" {...}` 里包含 Python 头文件则不是那么重要，因为如果定义了符号 `__cplusplus` 则已经是这么声明的了（所有现代 C++ 编译器都会定义这个符号）。

## 1.12. 给扩展模块提供 C API

很多扩展模块提供了新的函数和类型供 Python 使用，但有时扩展模块里的代码也可以被其他扩展模块使用。例如，一个扩展模块可以实现一个类型 "collection" 看起来是没有顺序的。就像是 Python 列表类型，拥有 C API 允许扩展模块来创建和维护列表，这个新的集合类型可以有一堆 C 函数用于给其他扩展模块直接使用。

开始看起来很简单：只需要编写函数 (无需声明为 `static`)，提供恰当的头文件，以及 C API 的文档。实际上在所有扩展模块都是静态链接到 Python 解释器时也是可以正常工作的。当模块以共享库链接时，一个模块中的符号定义对另一个模块不可见。可见的细节依赖于操作系统，一些系统的 Python 解释器使用全局命名空间（例如 Windows），有些则在链接时需要一个严格的已导入符号列表（一个例子是 AIX），或者提供可选的不同策略（如 Unix 系列）。即便是符号是全局可见的，你要调用的模块也可能尚未加载。

Portability therefore requires not to make any assumptions about symbol visibility. This means that all symbols in extension modules should be declared `static`, except for the module's initialization function, in order to avoid name clashes with other extension modules (as discussed in section The Module's Method Table and Initialization Function). And it means that symbols that should be accessible from other extension modules must be exported in a different way.

Python 提供了一个特别的机制用来从一个扩展模块向另一个扩展模块传递 C 层级的信息 (指针): Capsule。一个 Capsule 就是一个存储了指针 (void*) 的 Python 数据类型。Capsule 只能通过其 C API 来创建和访问，但它们可以像任何其他 Python 对象一样被传递。特别地，它们可以被赋值给扩展模块命名空间中的一个名称。 其他扩展模块将可以导入这个模块，获取该名称对应的值，然后从 Capsule 中获取指针。

Capsule 可以用多种方式导出 C API 给扩展模块。每个函数可以用自己的 Capsule，或者所有 C API 指针可以存储在一个数组里，数组地址再发布给 Capsule。存储和获取指针也可以用多种方式，供客户端模块使用。

无论你选择哪个方法，为你的 Capsule 指定适当的名称都很重要。函数 `PyCapsule_New()` 接受一个 name 形参 (const char*)；允许你传入一个 `NULL` 作为名称，但我们强烈推荐你指定名称。正确地命名的 Capsule 提供了一定的运行时类型安全性；没有可行的方式能区别两个未命名的 Capsule。

通常来说，Capsule 用于暴露 C API，其名字应该遵循如下规范：

    modulename.attributename

便利函数 `PyCapsule_Import()` 可以方便的载入通过 Capsule 提供的 C API，仅在 Capsule 的名字匹配时。这个行为为 C API 用户提供了高度的确定性来载入正确的 C API。

下面的例子演示了一种将大部分负担交给导出模块编写者的处理方式，这对于常用的库模块来说是合适的。它会将所有 C API 指针（在这个例子里只有一个！）储存到一个 void 指针数组，它将成为一个 Capsule 的值。 与模块对应的头文件提供了一个宏用来管理导入模块和获取其 C API 指针；客户端模块只需要在访问 C API 之前调用这个宏即可。

The exporting module is a modification of the `spam` module from section A Simple Example. The function `spam.system()` does not call the C library function `system()` directly, but a function `PySpam_System()`, which would of course do something more complicated in reality (such as adding "spam" to every command). This function `PySpam_System()` is also exported to other extension modules.

函数 `PySpam_System()` 是一个纯 C 函数，像其他函数一样声明为 `static`:

    static int
    PySpam_System(const char *command)
    {
        return system(command);
    }

函数 `spam_system()` 已按如下方式修改:

    static PyObject *
    spam_system(PyObject *self, PyObject *args)
    {
        const char *command;
        int sts;

        if (!PyArg_ParseTuple(args, "s", &command))
            return NULL;
        sts = PySpam_System(command);
        return PyLong_FromLong(sts);
    }

在模块开头，在此行后:

    #include <Python.h>

添加另外两行:

    #define SPAM_MODULE
    #include "spammodule.h"

`#define` 被用来告知头文件它被包括在导出的模块中，而不是客户端模块。最终，模块的 `mod_exec` 函数必须负责初始化 C API 指针数组:

    static int
    spam_module_exec(PyObject *m)
    {
        static void *PySpam_API[PySpam_API_pointers];
        PyObject *c_api_object;

        /* 初始化 C API 指针数组 */
        PySpam_API[PySpam_System_NUM] = (void *)PySpam_System;

        /* 创建包含 API 指针数组地址的 Capsule */
        c_api_object = PyCapsule_New((void *)PySpam_API, "spam._C_API", NULL);

        if (PyModule_Add(m, "_C_API", c_api_object) < 0) {
            return -1;
        }

        return 0;
    }

请注意 `PySpam_API` 被声明为 `static`；否则指针数组会在 `PyInit_spam()` 终结时消失！

头文件 `spammodule.h` 里的一堆工作，看起来如下所示:

    #ifndef Py_SPAMMODULE_H
    #define Py_SPAMMODULE_H
    #ifdef __cplusplus
    extern "C" {
    #endif

    /* 用于 spammodule 的头文件 */

    /* C API 函数 */
    #define PySpam_System_NUM 0
    #define PySpam_System_RETURN int
    #define PySpam_System_PROTO (const char *command)

    /* C API 指针的总数 */
    #define PySpam_API_pointers 1

    #ifdef SPAM_MODULE
    /* 该节将在编译 spammodule.c 时使用 */

    static PySpam_System_RETURN PySpam_System PySpam_System_PROTO;

    #else
    /* 该节将在使用 spammodule 的 API 的模块中使用 */

    static void **PySpam_API;

    #define PySpam_System \
     (*(PySpam_System_RETURN (*)PySpam_System_PROTO) PySpam_API[PySpam_System_NUM])

    /* 出错时返回 -1，成功时返回 0。
     * 如果有异常 PyCapsule_Import 将设置一个异常。
     */
    static int
    import_spam(void)
    {
        PySpam_API = (void **)PyCapsule_Import("spam._C_API", 0);
        return (PySpam_API != NULL) ? 0 : -1;
    }

    #endif

    #ifdef __cplusplus
    }
    #endif

    #endif /* !defined(Py_SPAMMODULE_H) */

客户端模块要访问函数 `PySpam_System()` 所必须做的全部事情就是在其 `mod_exec` 函数中调用函数 `import_spam()` (更准确地说是宏):

    static int
    client_module_exec(PyObject *m)
    {
        if (import_spam() < 0) {
            return -1;
        }
        /* 额外的初始化可在此进行 */
        return 0;
    }

这种方法的主要缺点是，文件 `spammodule.h` 过于复杂。当然，对每个要导出的函数，基本结构是相似的，所以只需要学习一次。

最后需要提醒的是 Capsule 提供了额外的功能，用于存储在 Capsule 里的指针的内存分配和释放。细节参考 Python/C API 参考手册的章节 Capsule 对象 和 Capsule 的实现 (在 Python 源码发行包的 `Include/pycapsule.h` 和 `Objects/pycapsule.c` ).

备注

[1]

An interface for this function already exists in the standard module `os` --- it was chosen as a simple and straightforward example.

[2]

术语"借用"一个引用是不完全正确的：拥有者仍然有引用的拷贝。

[3]

检查引用计数至少为 1 没有用 ，引用计数本身可以在已经释放的内存里，并有可能被其他对象所用。

[4]

当你使用 "旧式" 风格调用约定时，这些保证不成立，尽管这依旧存在于很多旧代码中。