ITADN · 发现全球开源项目

.. figure:: https://github.com/pybind/pybind11/raw/master/docs/pybind11-logo.png :alt: pybind11 logo

pybind11 (v3) — C++ 与 Python 之间的无缝互操作性

Setuptools example <https://github.com/pybind/python_example>_ • Scikit-build example <https://github.com/pybind/scikit_build_example>_ • CMake example <https://github.com/pybind/cmake_example>_

pybind11 是一个轻量级的纯头文件库，用于在 Python 中暴露 C++ 类型，反之亦然，主要用于为现有的 C++ 代码创建 Python 绑定。其目标和语法与 David Abrahams 的优秀 Boost.Python <http://www.boost.org/doc/libs/1_58_0/libs/python/doc/>_ 库相似：通过使用编译时内省来推断类型信息，从而最小化传统扩展模块中的样板代码。

Boost.Python 的主要问题——也是创建这样一个相似项目的原因——是 Boost。Boost 是一个极其庞大且复杂的实用程序库套件，几乎适用于所有现存的 C++ 编译器。这种兼容性是有代价的：需要晦涩的模板技巧和变通方法才能支持最古老且 bug 最多的编译器。如今，C++11 兼容的编译器已广泛可用，这种重型机制已成为一个过大且不必要的依赖项。

可以将此库视为 Boost.Python 的一个微小且自包含的版本，去除了所有与绑定生成无关的内容。不含注释的核心头文件仅需约 4K 行代码，并依赖于 Python（CPython 3.9+、PyPy 或 GraalPy）和 C++ 标准库。这种紧凑的实现得益于一些 C++11 语言特性（具体为：元组、lambda 函数和可变参数模板）。自创建以来，该库在许多方面已超越 Boost.Python，在许多常见情况下实现了显著更简单的绑定代码。

教程和参考文档提供于 pybind11.readthedocs.io <https://pybind11.readthedocs.io/en/latest>. 手册的 PDF 版本可在 here <https://pybind11.readthedocs.io/_/downloads/en/latest/pdf/>. 获取。源代码始终可在 github.com/pybind/pybind11 <https://github.com/pybind/pybind11>_. 获取。

核心特性

pybind11 可以将以下核心 C++ 特性映射到 Python：

按值、引用或指针接受和返回自定义数据结构的函数
实例方法和静态方法
重载函数
实例属性和静态属性
任意异常类型
枚举
回调
迭代器和范围
自定义运算符
单继承和多继承
STL 数据结构
具有引用计数的智能指针，如 std::shared_ptr
具有正确引用计数的内部引用
具有虚（和纯虚）方法的 C++ 类可以在 Python 中扩展
集成 NumPy 支持（NumPy 2 需要 pybind11 2.12+）

附加功能

除了核心功能外，pybind11 还提供了一些额外的附加功能：

支持 CPython 3.9+、PyPy3 7.3.17+ 和 GraalPy 24.1+，并采用与实现无关的接口（旧版本 CPython 和 PyPy 版本请参见旧版本）。
可以绑定带有捕获变量的 C++11 lambda 函数。lambda 捕获数据存储在生成的 Python 函数对象内部。
pybind11 尽可能使用 C++11 移动构造函数和移动赋值运算符来高效传输自定义数据类型。
通过 Python 的缓冲区协议，可以轻松地暴露自定义数据类型的内部存储。这在例如在 Eigen 等 C++ 矩阵类与 NumPy 之间进行快速转换时非常有用，无需昂贵的复制操作。
pybind11 可以自动向量化函数，使其透明地应用于一个或多个 NumPy 数组参数的所有元素。
Python 的基于切片的访问和赋值操作只需几行代码即可支持。
所有内容都包含在少数几个头文件中；无需链接任何额外的库。
与 Boost.Python 生成的等效绑定相比，二进制文件通常至少小 2 倍。最近将 PyRosetta（一个庞大的 Boost.Python 绑定项目）转换为 pybind11，reported <https://graylab.jhu.edu/Sergey/2016.RosettaCon/PyRosetta-4.pdf>_ 二进制文件大小减少了 5.4 倍，编译时间减少了 5.8 倍。
函数签名在编译时预先计算（使用 constexpr），从而生成更小的二进制文件。
只需稍加努力，C++ 类型就可以像常规 Python 对象一样进行 pickle 和 unpickle。

支持的平台和编译器

pybind11 在一系列操作系统、Python 版本、C++ 标准和工具链中通过持续集成进行测试。要查看我们当前测试的组合的最新视图，请参阅 pybind11 GitHub Actions <https://github.com/pybind/pybind11/actions?query=branch%3Amaster>_ 和 AppVeyor <https://ci.appveyor.com/project/wjakob/pybind11>_ 日志。

测试矩阵会随着旧平台和编译器逐渐退出使用以及社区添加新的平台和编译器而自然演变。经过测试的编译器或平台的紧密相关版本在实践中通常也能正常工作，但我们无法承诺验证所有可能的组合。如果您依赖的配置在矩阵中缺失或出现回归，我们非常欢迎提交问题或拉取请求以扩展覆盖范围。同时，我们需要在测试矩阵的规模与可用的 CI 资源之间取得平衡，例如 GitHub 免费层级对并发作业的限制。

关于

本项目由 Wenzel Jakob <http://rgl.epfl.ch/people/wjakob>_ 创建。代码中的重要特性和/或改进由以下人员贡献： Jonas Adler, Lori A. Burns, Sylvain Corlay, Eric Cousineau, Aaron Gokaslan, Ralf Grosse-Kunstleve, Trent Houliston, Axel Huebl, @hulucc, Yannick Jadoul, Sergey Lyskov, Johan Mabille, Tomasz Miąsko, Dean Moldovan, Ben Pritchard, Jason Rhinelander, Boris Schäling, Pim Schellart, Henry Schreiner, Ivan Smirnov, Dustin Spicuzza, Boris Staletic, Ethan Steinberg, Patrick Stewart, Ivor Wanders, 以及 Xiaofei Wang。

我们感谢 Google 为本项目使用的持续集成基础设施提供了慷慨的财务支持。

贡献


请参阅 `contributing
guide <https://github.com/pybind/pybind11/blob/master/.github/CONTRIBUTING.md>`_
以获取有关构建和贡献 pybind11 的信息。

许可证

pybind11 采用 BSD 风格的许可证提供，该许可证可在 LICENSE <https://github.com/pybind/pybind11/blob/master/LICENSE>_ 文件中找到。通过使用、分发或为本项目做出贡献，您同意接受该许可证的条款和条件。

.. |SPEC 4 — 使用和创建 Nightly Wheels| image:: https://img.shields.io/badge/SPEC-4-green?labelColor=%23004811&color=%235CA038 :target: https://scientific-python.org/specs/spec-0004/