pybind11 (версия 3) — Безшовная совместимость между C++ и Python

|Статус последней документации| |Статус документации версии Stable| |Обсуждения GitHub|

|Пакет PyPI|

Пример использования Setuptools • Пример использования Scikit-build • Пример использования CMake

pybind11 — это легковесная библиотека с заголовочными файлами, которая позволяет экспортировать типы C++ в Python и наоборот, главным образом для создания Python-обвязок существующего C++ кода. Её цели и синтаксис аналогичны замечательной библиотеке Boost.Python Дэвида Абрахамса: минимизация шаблонного кода в традиционных модулях расширения путём вывода информации о типах при компиляции.

Основная проблема с Boost.Python и причиной создания такой похожей библиотеки — это Boost. Boost — это огромный и сложный набор утилитарных библиотек, который работает с почти каждым существующим компилятором C++. Эта совместимость имеет свою цену: необходимы арканиумные трюки с шаблонами и временные меры для поддержки самых старых и багоносных компиляторов. Теперь, когда компиляторы, поддерживающие C++11, широко доступны, эта тяжелая машина стала излишне большой и ненужной зависимостью.Рассмотрите эту библиотеку как компактную версию Boost.Python с минимальным количеством необходимого кода для генерации обвязок. Без комментариев основные заголовочные файлы требуют всего около 4К строк кода и зависят от Python (CPython 3.8+, PyPy или GraalPy) и стандартной библиотеки C++. Такое компактное исполнение стало возможным благодаря некоторым возможностям языка C++11 (в частности: кортежи, лямбда-функции и вариативные шаблоны). С момента создания эта библиотека превзошла Boost.Python во многих аспектах, что привело к значительно более простому коду обвязок в большинстве распространённых ситуаций.

Учебник и справочная документация доступны по адресу pybind11.readthedocs.io. PDF-версия руководства доступна здесь. И исходный код всегда доступен по адресу github.com/pybind/pybind11.

Основные возможности

pybind11 может отображать следующие основные возможности C++ в Python:- Функции, принимающие и возвращающие пользовательские данные структуры по значению, ссылке или указателю - Экземплярные методы и статические методы - Перегруженные функции - Экземплярные атрибуты и статические атрибуты - Произвольные типы исключений - Перечисления - Коллбэки - Итераторы и диапазоны - Пользовательские операторы - Одиночное и множественное наследование - STL структуры данных - Умные указатели с подсчетом ссылок, такие как std::shared_ptr - Внутренние ссылки с правильным подсчетом ссылок - C++ классы с виртуальными (и чисто виртуальными) методами могут быть расширены в Python - Интегрированная поддержка NumPy (NumPy 2 требует pybind11 2.12+)Дополнительные возможности --------------------------

Кроме основных функциональностей, pybind11 предоставляет некоторые дополнительные возможности:

• Поддерживается CPython 3.8+, PyPy3 7.3.17+ и GraalPy 24.1+ с интерфейсом, независимым от реализации (см. более ранние версии для старых версий CPython и PyPy).
• Возможность привязки C++11 лямбда-функций с захваченными переменными. Данные захвата лямбды хранятся внутри результирующего объекта функции Python.
• pybind11 использует C++11 конструкторы перемещения и операторы перемещения назначения, когда это возможно, для эффективного передачи пользовательских данных типов.
• Легко вывести внутреннее хранилище пользовательских данных типов через протоколы буферов Python. Это полезно, например, для быстрого преобразования между C++ классами матриц, такими как Eigen и NumPy, без дорогостоящих операций копирования.
• pybind11 может автоматически векторизировать функции, чтобы они были прозрачно применены ко всем элементам одного или нескольких аргументов массива NumPy.
• Операции доступа и назначения срезов Python могут быть поддержаны всего несколькими строками кода.
• Все содержится в нескольких заголовочных файлах; нет необходимости связывать с любыми дополнительными библиотеками.- Бинарники обычно меньше на фактор 2 по сравнению с эквивалентными привязками, сгенерированными Boost.Python. Недавний перевод проекта PyRosetta, огромного проекта привязки Boost.Python, сообщил, о снижении размера бинарника в 5,4 раза и уменьшении времени компиляции в 5,8 раза.- Подписи функций предвычисняются во время компиляции (используя constexpr), что приводит к более компактным бинарникам. - С небольшими дополнительными усилиями типы C++ могут быть сериализованы и десериализованы аналогично обычным объектам Python.

Поддерживаемые компиляторы

1. Clang/LLVM 3.3 или новее (для компилятора clang в Apple Xcode это версия OnClickListener 5.0.0 или новее)
2. GCC 4.8 или новее
3. Microsoft Visual Studio 2022 или новее (версия 2019, вероятно, работает, но была удалена из CI)
4. Intel классический компилятор C++ 18 или новее (ICC 20.2 протестирован в CI)
5. Cygwin/GCC (ранее тестировался на версии 2.5.1)
6. NVCC (CUDA 11.0 протестирована в CI)
7. NVIDIA PGI (20.9 протестировано в CI)

Поддерживаемые платформы

• Windows, Linux, macOS и iOS
• CPython 3.8+, Pyodide, PyPy и GraalPy
• C++11, C++14, C++17, C++20 и C++23

О проекте

Этот проект был создан 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 за щедрую финансовую помощь в инфраструктуре непрерывной интеграции, используемой этим проектом.

Участие

См. руководство по участию для информации о сборке и участии в pybind11.Лицензия

pybind11 предоставляется под лицензией типа BSD, которая может быть найдена в файле LICENSE. Используя, распространяя или участвуя в этом проекте, вы соглашаетесь с условиями этой лицензии...