返回介绍

9.3 使用 Cython 构建 C++和 Python 项目

发布于 2025-05-06 21:45:59 字数 6916 浏览 0 评论 0 收藏

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 接口:

  1. 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)
  2. Windows 上,最好不要保留未定义的构建类型,这样我们就可以将该项目的构建类型与 Python 环境的构建类型相匹配。这里我们默认为 Release 类型:
    if(NOT CMAKE_BUILD_TYPE)
        set(CMAKE_BUILD_TYPE Release CACHE STRING "Build type" FORCE)
    endif()
  3. 在示例中,还需要 Python 解释器:
    find_package(PythonInterp REQUIRED)
  4. 下面的 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}
      )
  5. 定义一个测试:
    # 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
      )
  6. 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
  7. 有了这个,我们就可以配置、构建和测试代码了:
    $ 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_modulecython_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__ 析构函数以及 depositwithdraw 方法是如何与对应的 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++数组成为可能。

发布评论

需要 登录 才能够评论, 你可以免费 注册 一个本站的账号。
列表为空,暂无数据
    我们使用 Cookies 和其他技术来定制您的体验包括您的登录状态等。通过阅读我们的 隐私政策 了解更多相关信息。 单击 接受 或继续使用网站,即表示您同意使用 Cookies 和您的相关数据。