pybind11:轻量级C++与Python无缝互操作库,简化绑定开发

Seamless operability between C++11 and Python

分支35Tags66
文件最后提交记录最后更新时间
5 天前
1 个月前
10 天前
22 天前
10 天前
1 个月前
2 年前
4 年前
6 个月前
5 年前
8 个月前
4 年前
15 天前
23 小时前
2 年前
15 天前
4 个月前
1 年前
5 年前
7 个月前
3 年前
1 年前
2 个月前

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

pybind11 (v3) — C++ 与 Python 无缝互操作

|Latest Documentation Status| |Stable Documentation Status| |Gitter chat| |GitHub Discussions|

|CI| |Build status| |SPEC 4 — Using and Creating Nightly Wheels|

|Repology| |PyPI package| |Conda-forge| |Python Versions|

Setuptools 示例Scikit-build 示例CMake 示例

.. start

pybind11 是一个轻量级的仅含头文件的库,它能将 C++ 类型暴露给 Python,反之亦然,主要用于为现有 C++ 代码创建 Python 绑定。其目标和语法与 David Abrahams 开发的优秀库 Boost.Python 相似:通过使用编译时内省推断类型信息,最大限度地减少传统扩展模块中的样板代码。

Boost.Python 的主要问题——也是创建这个类似项目的原因——在于 Boost 本身。Boost 是一个极其庞大和复杂的实用程序库套件,几乎能与所有现存的 C++ 编译器协同工作。这种兼容性是有代价的:为了支持最古老和最容易出错的编译器版本,必须使用晦涩的模板技巧和变通方法。如今,兼容 C++11 的编译器已广泛可用,这种复杂的机制已成为一个过于庞大且不必要的依赖。

可以将此库视为 Boost.Python 的一个小型独立版本,其中所有与绑定生成无关的内容都已被剥离。去除注释后,核心头文件仅需约 4000 行代码,并且仅依赖 Python(CPython 3.8+、PyPy 或 GraalPy)和 C++ 标准库。这种紧凑的实现得益于一些 C++11 语言特性(具体包括:元组、 lambda 函数和可变参数模板)。自创建以来,该库在许多方面已超越 Boost.Python,使得在许多常见情况下绑定代码显著简化。

教程和参考文档请访问 pybind11.readthedocs.io。 手册的 PDF 版本可在此处获取 here。 源代码始终可在 github.com/pybind/pybind11 获取。

核心特性

pybind11 能够将以下 C++ 核心特性映射到 Python:

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

附加功能

除核心功能外,pybind11 还提供了一些额外的实用功能:

  • 支持 CPython 3.8+、PyPy3 7.3.17+ 和 GraalPy 24.1+,并提供与实现无关的接口(旧版本的 CPython 和 PyPy 请参见更早的 pybind11 版本)。

  • 可以绑定带有捕获变量的 C++11 lambda 函数。lambda 捕获的数据存储在生成的 Python 函数对象内部。

  • pybind11 会尽可能使用 C++11 的移动构造函数和移动赋值运算符,以高效地传输自定义数据类型。

  • 很容易通过 Python 的缓冲区协议公开自定义数据类型的内部存储。这对于例如 C++ 矩阵类(如 Eigen)与 NumPy 之间的快速转换非常有用,无需进行昂贵的复制操作。

  • pybind11 可以自动向量化函数,使其透明地应用于一个或多个 NumPy 数组参数的所有元素。

  • 只需几行代码即可支持 Python 基于切片的访问和赋值操作。

  • 所有功能都包含在少数几个头文件中;无需链接任何额外的库。

  • 与 Boost.Python 生成的等效绑定相比,二进制文件通常至少小 2 倍。最近将一个庞大的 Boost.Python 绑定项目 PyRosetta 转换为 pybind11 的报告显示,二进制大小减少了 5.4 倍,编译时间减少了 5.8 倍。

  • 函数签名在编译时预计算(使用 constexpr),从而生成更小的二进制文件。

  • 只需少量额外工作,C++ 类型就可以像常规 Python 对象一样进行序列化(pickle)和反序列化(unpickle)。

支持的平台和编译器

pybind11 会在持续集成环境中对一系列操作系统、Python 版本、C++ 标准和工具链进行测试。若需了解当前测试的具体组合,请查看 pybind11 GitHub Actions 日志。

随着旧平台和编译器逐渐被淘汰,以及社区添加新的平台和编译器,测试矩阵会自然演变。实际上,经过测试的编译器或平台的相近版本通常也能正常工作,但我们无法保证验证所有可能的组合。如果您依赖的配置未包含在测试矩阵中,或者出现了功能退化,非常欢迎您提交 issue 和 pull request 来扩展测试覆盖范围。同时,我们也需要在测试矩阵的规模与可用的 CI 资源(例如 GitHub 免费套餐的并发作业限制)之间取得平衡。

关于

本项目由 Wenzel Jakob 创建。以下人员对代码贡献了重要功能和/或改进: 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 为该项目使用的持续集成基础设施提供了慷慨的资金支持。

贡献


See the `contributing
guide <https://github.com/pybind/pybind11/blob/master/.github/CONTRIBUTING.md>`_
for information on building and contributing to pybind11.

License
~~~~~~~

pybind11 is provided under a BSD-style license that can be found in the
[LICENSE](https://github.com/pybind/pybind11/blob/master/LICENSE)
file. By using, distributing, or contributing to this project, you agree
to the terms and conditions of this license.

.. |Latest Documentation Status| image:: https://readthedocs.org/projects/pybind11/badge?version=latest
   :target: http://pybind11.readthedocs.org/en/latest
.. |Stable Documentation Status| image:: https://img.shields.io/badge/docs-stable-blue.svg
   :target: http://pybind11.readthedocs.org/en/stable
.. |Gitter chat| image:: https://img.shields.io/gitter/room/gitterHQ/gitter.svg
   :target: https://gitter.im/pybind/Lobby
.. |CI| image:: https://github.com/pybind/pybind11/workflows/CI/badge.svg
   :target: https://github.com/pybind/pybind11/actions
.. |Build status| image:: https://ci.appveyor.com/api/projects/status/riaj54pn4h08xy40?svg=true
   :target: https://ci.appveyor.com/project/wjakob/pybind11
.. |PyPI package| image:: https://img.shields.io/pypi/v/pybind11.svg
   :target: https://pypi.org/project/pybind11/
.. |Conda-forge| image:: https://img.shields.io/conda/vn/conda-forge/pybind11.svg
   :target: https://github.com/conda-forge/pybind11-feedstock
.. |Repology| image:: https://repology.org/badge/latest-versions/python:pybind11.svg
   :target: https://repology.org/project/python:pybind11/versions
.. |Python Versions| image:: https://img.shields.io/pypi/pyversions/pybind11.svg
   :target: https://pypi.org/project/pybind11/
.. |GitHub Discussions| image:: https://img.shields.io/static/v1?label=Discussions&message=Ask&color=blue&logo=github
   :target: https://github.com/pybind/pybind11/discussions
.. |SPEC 4 — Using and Creating Nightly Wheels| image:: https://img.shields.io/badge/SPEC-4-green?labelColor=%23004811&color=%235CA038
   :target: https://scientific-python.org/specs/spec-0004/



项目介绍

C++11与Python之间的无缝操作性【此简介由AI生成】

定制我的领域
24717.96 K2.31 K访问 GitHub