pybind11

pybind11 — Бесшовная работа между C++11 и Python

Пример инструментов настройки • Пример сборки Scikit • Пример CMake

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

Основная проблема Boost.Python и причина создания подобного проекта — это Boost. Boost — это чрезвычайно большой и сложный набор служебных библиотек, который работает практически со всеми существующими компиляторами C++. У этой совместимости есть своя цена: для поддержки самых старых и самых ошибочных образцов компилятора необходимы хитрые шаблонные приемы и обходные пути. Теперь, когда C++11-совместимые компиляторы широко доступны, эта тяжелая техника стала чрезмерно большой и ненужной зависимостью.

Думайте об этой библиотеке как о крошечной автономной версии Boost.Python, в которой удалено все, что не имеет отношения к генерации привязок. Без комментариев основные файлы заголовков требуют всего около 4 000 строк кода и зависят от Python (3.8+ или PyPy) и стандартной библиотеки 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 предоставляет некоторые дополнительные возможности:

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

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

1. Clang/LLVM 3.3 или новее (для clang Apple Xcode это 5.0.0 или новее)
2. GCC 4.8 или новее
3. Microsoft Visual Studio 2017 или новее.
4. Компилятор Intel Classic C++ 18 или новее (ICC 20.2 протестирован в CI)
5. Cygwin/GCC (ранее протестировано на версии 2.5.1)
6. NVCC (CUDA 11.0 протестировано в CI)
7. NVIDIA PGI (20,9 протестировано в CI)

О

Этот проект создал Венцель Якоб. Значительные функции и/или улучшения кода были внесены Йонасом Адлером, Лори А. Бернсом, Сильвеном Корли, Эриком Кузино, Аароном Гокасланом, Ральфом Гросс-Кунстлеве, Трентом Хулистоном, Акселем Хюблом, @hulucc, Янником Джадулом, Сергеем Лысковым, Йоханом. Мабилле, Томаш Мьонско, Дин Молдован, Бен Притчард, Джейсон Райнлендер, Борис Шелинг, Пим Шелларт, Генри Шрайнер, Иван Смирнов, Борис Сталетич и Патрик Стюарт.

Мы благодарим Google за щедрый финансовый вклад в инфраструктуру непрерывной интеграции, используемую в этом проекте.

Содействие

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

Лицензия

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