9.3 使用 Cython 构建 C++和 Python 项目
NOTE : 此示例代码可以在 https://github.com/dev-cafe/cmake-cookbook/tree/v1.0/chapter-9/recipe-03 中找到,其中有一个 C++示例。该示例在 CMake 3.5 版(或更高版本) 中是有效的,并且已经在 GNU/Linux、macOS 和 Windows 上进行过测试。
Cython 是一个静态编译器,它允许为 Python 编写 C 扩展。Cython 是一个非常强大的工具,使用 Cython 编程语言(基于 Pyrex)。Cython 的一个典型用例是加快 Python 代码的速度,它也可以用于通过 Cython 层使 Python 与 C(++) 接口对接。本示例中,我们将重点介绍后一种用例,并演示如何在 CMake 的帮助下使用 Cython 与 C(++) 和 Python 进行对接。
准备工作
我们将使用以下 C++代码( account.cpp
):
#include "account.hpp" Account::Account() : balance(0.0) {} Account::~Account() {} void Account::deposit(const double amount) { balance += amount; } void Account::withdraw(const double amount) { balance -= amount; } double Account::get_balance() const { return balance; }
代码提供了以下接口( account.hpp
):
#pragma once class Account { public: Account(); ~Account(); void deposit(const double amount); void withdraw(const double amount); double get_balance() const; private: double balance; };
使用这个示例代码,我们可以创建余额为零的银行帐户。可以在帐户上存款和取款,还可以使用 get_balance()
查询帐户余额。余额本身是 Account
类的私有成员。
我们的目标是能够直接从 Python 与这个 C++类进行交互。换句话说,在 Python 方面,我们希望能够做到这一点:
account = Account() account.deposit(100.0) account.withdraw(50.0) balance = account.get_balance()
为此,需要一个 Cython 接口文件(调用 account.pyx
):
# describe the c++ interface cdef extern from "account.hpp": cdef cppclass Account: Account() except + void deposit(double) void withdraw(double) double get_balance() # describe the python interface cdef class pyAccount: cdef Account *thisptr def __cinit__(self): self.thisptr = new Account() def __dealloc__(self): del self.thisptr def deposit(self, amount): self.thisptr.deposit(amount) def withdraw(self, amount): self.thisptr.withdraw(amount) def get_balance(self): return self.thisptr.get_balance()
具体实施
如何生成 Python 接口:
CMakeLists.txt
定义 CMake 依赖项、项目名称和语言:# define minimum cmake version cmake_minimum_required(VERSION 3.5 FATAL_ERROR) # project name and supported language project(recipe-03 LANGUAGES CXX) # require C++11 set(CMAKE_CXX_STANDARD 11) set(CMAKE_CXX_EXTENSIONS OFF) set(CMAKE_CXX_STANDARD_REQUIRED ON)
- Windows 上,最好不要保留未定义的构建类型,这样我们就可以将该项目的构建类型与 Python 环境的构建类型相匹配。这里我们默认为 Release 类型:
if(NOT CMAKE_BUILD_TYPE) set(CMAKE_BUILD_TYPE Release CACHE STRING "Build type" FORCE) endif()
- 在示例中,还需要 Python 解释器:
find_package(PythonInterp REQUIRED)
- 下面的 CMake 代码将构建 Python 模块:
# directory cointaining UseCython.cmake and FindCython.cmake list(APPEND CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/cmake-cython) # this defines cython_add_module include(UseCython) # tells UseCython to compile this file as a c++ file set_source_files_properties(account.pyx PROPERTIES CYTHON_IS_CXX TRUE) # create python module cython_add_module(account account.pyx account.cpp) # location of account.hpp target_include_directories(account PRIVATE ${CMAKE_CURRENT_SOURCE_DIR} )
- 定义一个测试:
# turn on testing enable_testing() # define test add_test( NAME python_test COMMAND ${CMAKE_COMMAND} -E env ACCOUNT_MODULE_PATH=$<TARGET_FILE_DIR:account> ${PYTHON_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/test.py )
python_test
执行test.py
,这里进行一些存款和取款操作,并验证余额:import os import sys sys.path.append(os.getenv('ACCOUNT_MODULE_PATH')) from account import pyAccount as Account account1 = Account() account1.deposit(100.0) account1.deposit(100.0) account2 = Account() account2.deposit(200.0) account2.deposit(200.0) account1.withdraw(50.0) assert account1.get_balance() == 150.0 assert account2.get_balance() == 400.0
- 有了这个,我们就可以配置、构建和测试代码了:
$ mkdir -p build $ cd build $ cmake .. $ cmake --build . $ ctest Start 1: python_test 1/1 Test #1: python_test ...................... Passed 0.03 sec 100% tests passed, 0 tests failed out of 1 Total Test time (real) = 0.03 sec
工作原理
本示例中,使用一个相对简单的 CMakeLists.txt
文件对接了 Python 和 C++,但是是通过使用 FindCython.cmake
进行的实现。 UseCython.cmake
模块,放置在 cmake-cython
下。这些模块包括使用以下代码:
# directory contains UseCython.cmake and FindCython.cmake list(APPEND CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/cmake-cython) # this defines cython_add_module include(UseCython)
FindCython.cmake
包含在 UseCython.cmake
中,并定义了 ${CYTHON_EXECUTABLE}
变量。后一个模块定义了 cython_add_module
和 cython_add_standalone_executable
函数,它们分别用于创建 Python 模块和独立的可执行程序。这两个模块都可从 https://github.com/thewtex/cython-cmake-example/tree/master/cmake 下载。
这个示例中,使用 cython_add_module
创建一个 Python 模块库。注意,将使用非标准的 CYTHON_IS_CXX
源文件属性设置为 TRUE
,以便 cython_add_module
函数知道如何将 pyx
作为 C++
文件进行编译:
# tells UseCython to compile this file as a c++ file set_source_files_properties(account.pyx PROPERTIES CYTHON_IS_CXX TRUE) # create python module cython_add_module(account account.pyx account.cpp)
Python 模块在 ${CMAKE_CURRENT_BINARY_DIR}
中创建,为了让 Python 的 test.py
脚本找到它,我们使用一个自定义环境变量传递相关的路径,该环境变量用于在 test.py
中设置 path
变量。请注意,如何将命令设置为调用 CMake 可执行文件本身,以便在执行 Python 脚本之前设置本地环境。这为我们提供了平台独立性,并避免了环境污染:
add_test( NAME python_test COMMAND ${CMAKE_COMMAND} -E env ACCOUNT_MODULE_PATH=$<TARGET_FILE_DIR:account> ${PYTHON_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/test.py )
我们来看看 account.pyx
文件,这是 Python 与 C++之间的接口文件,并对 C++接口进行描述:
# describe the c++ interface cdef extern from "account.hpp": cdef cppclass Account: Account() except + void deposit(double) void withdraw(double) double get_balance()
可以看到 cinit
构造函数、 __dealloc__
析构函数以及 deposit
和 withdraw
方法是如何与对应的 C++实现相匹配的。
总之,发现了一种机制,通过引入对 Cython 模块的依赖来耦合 Python 和 C++。该模块可以通过 pip
安装到虚拟环境或 Pipenv 中,或者使用 Anaconda 来安装。
更多信息
C 语言可以进行类似地耦合。如果希望利用构造函数和析构函数,我们可以在 C 接口之上封装一个 C++层。
类型化 Memoryview 提供了有趣的功能,可以映射和访问由 C/C++直接在 Python 中分配的内存,而不需要任何创建: http://cython.readthedocs.io/en/latest/src/userguide/memoryviews.html 。它们使得将 NumPy 数组直接映射为 C++数组成为可能。
绑定邮箱获取回复消息
由于您还没有绑定你的真实邮箱,如果其他用户或者作者回复了您的评论,将不能在第一时间通知您!
发布评论