编写绑定

CFFI提供读取C 头文件的方法，以在生成 Python 绑定时完成大部分工作。在 的文档中CFFI，执行此操作的代码放置在单独的 Python 文件中。对于此示例，您将直接将该代码放入构建工具中invoke，该工具使用 Python 文件作为输入。要使用CFFI，您首先要创建一个cffi.FFI对象，该对象提供了您需要的三种方法：

# tasks.py
import cffi
...
""" Build the CFFI Python bindings """
print_banner("Building CFFI Module")
ffi = cffi.FFI()

拥有 FFI 后，您将使用.cdef()来自动处理头文件的内容。这会为您创建包装函数以从 Python 封送数据：

# tasks.py
this_dir = pathlib.Path().absolute()
h_file_name = this_dir / "cmult.h"
with open(h_file_name) as h_file:
    ffi.cdef(h_file.read())

读取和处理头文件是第一步。之后，您需要使用.set_source()来描述CFFI将生成的源文件：

# tasks.py
ffi.set_source(
    "cffi_example",
    # Since you're calling a fully-built library directly, no custom source
    # is necessary. You need to include the .h files, though, because behind
    # the scenes cffi generates a .c file that contains a Python-friendly
    # wrapper around each of the functions.
    '#include "cmult.h"',
    # The important thing is to include the pre-built lib in the list of
    # libraries you're linking against:
    libraries=["cmult"],
    library_dirs=[this_dir.as_posix()],
    extra_link_args=["-Wl,-rpath,."],
)

以下是您传入的参数的细分：

• "cffi_example"是将在您的文件系统上创建的源文件的基本名称。CFFI将生成一个.c文件，将其编译为一个.o文件，并将其链接到一个.<system-description>.so或.<system-description>.dll文件。

• '#include "cmult.h"'是自定义 C 源代码，它将在编译之前包含在生成的源代码中。在这里，您只需包含.h要为其生成绑定的文件，但这可用于一些有趣的自定义。

• libraries=["cmult"]告诉链接器您预先存在的 C 库的名称。这是一个列表，因此您可以根据需要指定多个库。

• library_dirs=[this_dir.as_posix(),] 是一个目录列表，告诉链接器在何处查找上述库列表。

• extra_link_args=['-Wl,-rpath,.']是一组生成共享对象的选项，它将在当前路径 ( .) 中查找它需要加载的其他库。

构建 Python 绑定

调用.set_source()不会构建 Python 绑定。它只设置元数据来描述将生成的内容。要构建 Python 绑定，您需要调用.compile()：

# tasks.py
ffi.compile()

这通过生成.c文件、.o文件和共享库来完成。在invoke你刚走通过任务可以在上运行命令行构建Python绑定：

$ invoke build-cffi
==================================================
= Building C Library
* Complete
==================================================
= Building CFFI Module
* Complete

你有你的CFFIPython 绑定，所以是时候运行这段代码了！

调用你的函数

在您为配置和运行CFFI编译器所做的所有工作之后，使用生成的 Python 绑定看起来就像使用任何其他 Python 模块一样：

# cffi_test.py
import cffi_example

if __name__ == "__main__":
    # Sample data for your call
    x, y = 6, 2.3

    answer = cffi_example.lib.cmult(x, y)
    print(f"    In Python: int: {x} float {y:.1f} return val {answer:.1f}")

你导入新模块，然后就可以cmult()直接调用了。要对其进行测试，请使用以下test-cffi任务：

$ invoke test-cffi
==================================================
= Testing CFFI Module
    In cmult : int: 6 float 2.3 returning  13.8
    In Python: int: 6 float 2.3 return val 13.8

这将运行您的cffi_test.py程序，该程序会测试您使用CFFI. 关于编写和使用CFFIPython 绑定的部分到此结束。

编写绑定

与 类似CFFI，您需要创建一些代码来告诉该工具如何构建您的 Python 绑定。与 不同CFFI，此代码将使用 C++ 而不是 Python。幸运的是，只需要很少的代码：

// pybind11_wrapper.cpp
#include <pybind11/pybind11.h>
#include <cppmult.hpp>

PYBIND11_MODULE(pybind11_example, m) {
    m.doc() = "pybind11 example plugin"; // Optional module docstring
    m.def("cpp_function", &cppmult, "A function that multiplies two numbers");
}

让我们一次一个地看，因为PyBind11将大量信息打包成几行。

前两行包括pybind11.hC++ 库的文件和头文件cppmult.hpp. 之后，你就有了PYBIND11_MODULE宏。这将扩展为PyBind11源代码中详细描述的 C++ 代码块：

此宏创建入口点，当 Python 解释器导入扩展模块时将调用该入口点。模块名称作为第一个参数给出，不应用引号引起来。第二个宏参数定义了一个py::module可用于初始化模块的类型变量。（来源）

这对您来说意味着，在本例中，您正在创建一个名为的模块pybind11_example，其余代码将m用作py::module对象的名称。在下一行，在您定义的 C++ 函数中，您为模块创建一个文档字符串。虽然这是可选的，但让您的模块更加Pythonic是一个不错的选择。

最后，你有m.def()电话。这将定义一个由您的新 Python 绑定导出的函数，这意味着它将在 Python 中可见。在此示例中，您将传递三个参数：

• cpp_function是您将在 Python 中使用的函数的导出名称。如本例所示，它不需要匹配 C++ 函数的名称。
• &cppmult 获取要导出的函数的地址。
• "A function..." 是函数的可选文档字符串。

现在您已经有了 Python 绑定的代码，接下来看看如何将其构建到 Python 模块中。

构建 Python 绑定

用于构建 Python 绑定的工具PyBind11是 C++ 编译器本身。您可能需要修改编译器和操作系统的默认值。

首先，您必须构建要为其创建绑定的 C++ 库。对于这么小的示例，您可以将cppmult库直接构建到 Python 绑定库中。但是，对于大多数实际示例，您将有一个要包装的预先存在的库，因此您将cppmult单独构建该库。构建是对编译器的标准调用以构建共享库：

# tasks.py
invoke.run(
    "g++ -O3 -Wall -Werror -shared -std=c++11 -fPIC cppmult.cpp "
    "-o libcppmult.so "
)

运行这个invoke build-cppmult产生libcppmult.so：

$ invoke build-cppmult
==================================================
= Building C++ Library
* Complete

另一方面，Python 绑定的构建需要一些特殊的细节：

 1# tasks.py
 2invoke.run(
 3    "g++ -O3 -Wall -Werror -shared -std=c++11 -fPIC "
 4    "`python3 -m pybind11 --includes` "
 5    "-I /usr/include/python3.7 -I .  "
 6    "{0} "
 7    "-o {1}`python3.7-config --extension-suffix` "
 8    "-L. -lcppmult -Wl,-rpath,.".format(cpp_name, extension_name)
 9)

让我们逐行浏览一下。第 3 行包含相当标准的 C++ 编译器标志，指示几个细节，包括您希望捕获所有警告并将其视为错误、您需要共享库以及您使用的是 C++11。

第 4 行是魔法的第一步。它调用pybind11模块使其include为PyBind11. 您可以直接在控制台上运行此命令以查看它的作用：

$ python3 -m pybind11 --includes
-I/home/jima/.virtualenvs/realpython/include/python3.7m
-I/home/jima/.virtualenvs/realpython/include/site/python3.7

您的输出应该相似但显示不同的路径。

在编译调用的第 5 行，您可以看到您还添加了 Python dev 的路径includes。虽然建议您不要链接 Python 库本身，但源代码需要一些代码Python.h才能发挥其魔力。幸运的是，它使用的代码在 Python 版本中相当稳定。

第 5 行还用于-I .将当前目录添加到include路径列表中。这允许#include <cppmult.hpp>解析包装器代码中的行。

第 6 行指定源文件的名称，即pybind11_wrapper.cpp. 然后，在第 7 行，您会看到更多的构建魔法正在发生。此行指定输出文件的名称。Python 在模块命名上有一些特别的想法，包括 Python 版本、机器架构和其他细节。Python 还提供了一个工具来帮助解决这个问题python3.7-config：

$ python3.7-config --extension-suffix
.cpython-37m-x86_64-linux-gnu.so

如果您使用的是不同版本的 Python，则可能需要修改该命令。如果您使用不同版本的 Python 或在不同的操作系统上，您的结果可能会发生变化。

构建命令的最后一行，第 8 行，将链接器指向libcppmult您之前构建的库。该rpath部分告诉链接器向共享库添加信息以帮助操作系统libcppmult在运行时查找。最后，您会注意到此字符串的格式为cpp_name和extension_name。Cython在下一节中构建 Python 绑定模块时，您将再次使用此函数。

运行此命令以构建绑定：

$ invoke build-pybind11
==================================================
= Building C++ Library
* Complete
==================================================
= Building PyBind11 Module
* Complete

就是这样！您已经使用PyBind11. 是时候测试一下了！

调用你的函数

与CFFI上面的示例类似，一旦您完成了创建 Python 绑定的繁重工作，调用您的函数看起来就像普通的 Python 代码：

# pybind11_test.py
import pybind11_example

if __name__ == "__main__":
    # Sample data for your call
    x, y = 6, 2.3

    answer = pybind11_example.cpp_function(x, y)
    print(f"    In Python: int: {x} float {y:.1f} return val {answer:.1f}")

由于您pybind11_example在PYBIND11_MODULE宏中用作模块的名称，因此这就是您导入的名称。在m.def()您告诉PyBind11将cppmult函数导出为 的调用中cpp_function，这就是您用来从 Python 调用它的方法。

你也可以测试它invoke：

$ invoke test-pybind11
==================================================
= Testing PyBind11 Module
    In cppmul: int: 6 float 2.3 returning  13.8
    In Python: int: 6 float 2.3 return val 13.8

这就是PyBind11看起来的样子。接下来，您将了解何时以及为何PyBind11是适合该工作的工具。

编写绑定

声明模块的最常见形式Cython是使用.pyx文件：

 1# cython_example.pyx
 2""" Example cython interface definition """
 3
 4cdef extern from "cppmult.hpp":
 5    float cppmult(int int_param, float float_param)
 6
 7def pymult( int_param, float_param ):
 8    return cppmult( int_param, float_param )

这里有两个部分：

1. 线3和4告诉Cython您使用的是cppmult()从cppmult.hpp。
2. 第 6 行和第 7 行创建了一个包装函数pymult()，以调用cppmult()。

这里使用的语言是 C、C++ 和 Python 的特殊组合。不过，对于 Python 开发人员来说，它看起来相当熟悉，因为其目标是使过程更容易。

第一部分 withcdef extern...告诉Cython下面的函数声明也可以在cppmult.hpp文件中找到。这对于确保根据与 C++ 代码相同的声明构建 Python 绑定非常有用。第二部分看起来像一个普通的 Python 函数——因为它是！本节创建一个可以访问 C++ 函数的 Python 函数cppmult。

现在您已经定义了 Python 绑定，是时候构建它们了！

构建 Python 绑定

的构建过程Cython与您使用的构建过程相似PyBind11。您首先Cython在.pyx文件上运行以生成.cpp文件。完成此操作后，您可以使用用于以下内容的相同函数对其进行编译PyBind11：

 1# tasks.py
 2def compile_python_module(cpp_name, extension_name):
 3    invoke.run(
 4        "g++ -O3 -Wall -Werror -shared -std=c++11 -fPIC "
 5        "`python3 -m pybind11 --includes` "
 6        "-I /usr/include/python3.7 -I .  "
 7        "{0} "
 8        "-o {1}`python3.7-config --extension-suffix` "
 9        "-L. -lcppmult -Wl,-rpath,.".format(cpp_name, extension_name)
10    )
11
12def build_cython(c):
13    """ Build the cython extension module """
14    print_banner("Building Cython Module")
15    # Run cython on the pyx file to create a .cpp file
16    invoke.run("cython --cplus -3 cython_example.pyx -o cython_wrapper.cpp")
17
18    # Compile and link the cython wrapper library
19    compile_python_module("cython_wrapper.cpp", "cython_example")
20    print("* Complete")

您首先运行cython您的.pyx文件。您可以在此命令上使用几个选项：

• --cplus 告诉编译器生成 C++ 文件而不是 C 文件。
• -3切换Cython到生成 Python 3 语法而不是 Python 2。
• -o cython_wrapper.cpp 指定要生成的文件的名称。

生成 C++ 文件后，您可以使用 C++ 编译器生成 Python 绑定，就像您为PyBind11. 请注意，include使用该pybind11工具生成额外路径的调用仍在该函数中。在这里不会有任何伤害，因为您的来源不需要这些。

在 中运行此任务invoke会产生以下输出：

$ invoke build-cython
==================================================
= Building C++ Library
* Complete
==================================================
= Building Cython Module
* Complete

可以看到它构建了cppmult库，然后构建了cython模块来包装它。现在你有了CythonPython 绑定。（试着说的是迅速...）它的时间来测试一下吧！

调用你的函数

调用新 Python 绑定的 Python 代码与用于测试其他模块的代码非常相似：

 1# cython_test.py
 2import cython_example
 3
 4# Sample data for your call
 5x, y = 6, 2.3
 6
 7answer = cython_example.pymult(x, y)
 8print(f"    In Python: int: {x} float {y:.1f} return val {answer:.1f}")

第 2 行导入新的 Python 绑定模块，并pymult()在第 7 行调用。请记住，该.pyx文件提供了一个 Python 包装器cppmult()并将其重命名为pymult. 使用 invoke 运行您的测试会产生以下结果：

$ invoke test-cython
==================================================
= Testing Cython Module
    In cppmul: int: 6 float 2.3 returning  13.8
    In Python: int: 6 float 2.3 return val 13.8

你得到和以前一样的结果！