pybind11

pybind11 — Pengoperasian yang mulus antara C++11 dan Python

Contoh setuptools • Contoh pembuatan Scikit • Contoh CMake

pybind11 adalah pustaka ringan khusus header yang mengekspos tipe C++ dengan Python dan sebaliknya, terutama untuk membuat binding Python dari kode C++ yang ada. Sasaran dan sintaksisnya mirip dengan pustaka Boost.Python yang luar biasa karya David Abrahams: untuk meminimalkan kode boilerplate dalam modul ekstensi tradisional dengan menyimpulkan informasi tipe menggunakan introspeksi waktu kompilasi.

Masalah utama dengan Boost.Python—dan alasan pembuatan proyek serupa—adalah Boost. Boost adalah rangkaian pustaka utilitas yang sangat besar dan kompleks yang bekerja dengan hampir semua kompiler C++ yang ada. Kompatibilitas ini ada konsekuensinya: trik dan solusi templat yang rumit diperlukan untuk mendukung spesimen kompiler yang paling tua dan paling bermasalah. Sekarang kompiler yang kompatibel dengan C++11 tersedia secara luas, alat berat ini telah menjadi ketergantungan yang sangat besar dan tidak perlu.

Bayangkan perpustakaan ini sebagai versi kecil Boost.Python yang mandiri dengan segala sesuatu yang tidak relevan untuk pembuatan pengikatan dihilangkan. Tanpa komentar, file header inti hanya memerlukan ~4K baris kode dan bergantung pada Python (3.8+, atau PyPy) dan pustaka standar C++. Implementasi ringkas ini dimungkinkan berkat beberapa fitur bahasa C++11 (khususnya: tupel, fungsi lambda, dan templat variadik). Sejak pembuatannya, perpustakaan ini telah berkembang melampaui Boost.Python dalam banyak hal, sehingga menghasilkan kode pengikatan yang jauh lebih sederhana dalam banyak situasi umum.

Dokumentasi tutorial dan referensi disediakan di pybind11.readthedocs.io. Versi PDF dari manual ini tersedia di sini. Dan kode sumbernya selalu tersedia di github.com/pybind/pybind11.

Fitur inti

pybind11 dapat memetakan fitur inti C++ berikut ke Python:

• Fungsi menerima dan mengembalikan struktur data khusus per nilai, referensi, atau penunjuk
• Metode instan dan metode statis
• Fungsi yang kelebihan beban
• Atribut instan dan atribut statis
• Jenis pengecualian sewenang-wenang
• Pencacahan
• Panggilan balik
• Iterator dan rentang
• Operator khusus
• Warisan tunggal dan ganda
• Struktur data STL
• Pointer cerdas dengan penghitungan referensi seperti std::shared_ptr
• Referensi internal dengan penghitungan referensi yang benar
• Kelas C++ dengan metode virtual (dan virtual murni) dapat diperluas dengan Python
• Dukungan NumPy terintegrasi (NumPy 2 memerlukan pybind11 2.12+)

Barang

Selain fungsi inti, pybind11 menyediakan beberapa manfaat tambahan:

• Python 3.8+, dan PyPy3 7.3 didukung dengan antarmuka agnostik implementasi (pybind11 2.9 adalah versi terakhir yang mendukung Python 2 dan 3.5).
• Dimungkinkan untuk mengikat fungsi lambda C++11 dengan variabel yang ditangkap. Data tangkapan lambda disimpan di dalam objek fungsi Python yang dihasilkan.
• pybind11 menggunakan konstruktor pemindahan C++11 dan memindahkan operator penugasan bila memungkinkan untuk mentransfer tipe data khusus secara efisien.
• Sangat mudah untuk mengekspos penyimpanan internal tipe data khusus melalui protokol buffer Python. Ini berguna misalnya untuk konversi cepat antara kelas matriks C++ seperti Eigen dan NumPy tanpa operasi penyalinan yang mahal.
• pybind11 dapat secara otomatis melakukan vektorisasi fungsi sehingga diterapkan secara transparan ke semua entri dari satu atau lebih argumen array NumPy.
• Operasi akses dan penugasan berbasis irisan Python dapat didukung hanya dengan beberapa baris kode.
• Semuanya terkandung hanya dalam beberapa file header; tidak perlu menautkan ke perpustakaan tambahan apa pun.
• Biner umumnya lebih kecil dengan faktor minimal 2 dibandingkan dengan binding setara yang dihasilkan oleh Boost.Python. Konversi pybind11 baru-baru ini dari PyRosetta, sebuah proyek pengikatan Boost.Python yang sangat besar, melaporkan pengurangan ukuran biner sebesar 5,4x dan pengurangan waktu kompilasi sebesar 5,8x .
• Tanda tangan fungsi dihitung sebelumnya pada waktu kompilasi (menggunakan constexpr ), sehingga menghasilkan biner yang lebih kecil.
• Dengan sedikit usaha ekstra, tipe C++ dapat diasamkan dan dipisahkan seperti objek Python biasa.

Kompiler yang didukung

1. Dentang/LLVM 3.3 atau lebih baru (untuk dentang Apple Xcode, ini 5.0.0 atau lebih baru)
2. GCC 4.8 atau lebih baru
3. Microsoft Visual Studio 2017 atau lebih baru
4. Kompiler Intel C++ klasik 18 atau lebih baru (ICC 20.2 diuji di CI)
5. Cygwin/GCC (sebelumnya diuji pada 2.5.1)
6. NVCC (CUDA 11.0 diuji di CI)
7. NVIDIA PGI (20.9 diuji di CI)

Tentang

Proyek ini dibuat oleh Wenzel Jakob. Fitur signifikan dan/atau perbaikan pada kode disumbangkan oleh 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, Boris Staletic, dan Patrick Stewart.

Kami berterima kasih kepada Google atas kontribusi finansial yang besar terhadap infrastruktur integrasi berkelanjutan yang digunakan oleh proyek ini.

Berkontribusi

Lihat panduan berkontribusi untuk informasi tentang membangun dan berkontribusi pada pybind11.

Lisensi

pybind11 disediakan di bawah lisensi gaya BSD yang dapat ditemukan di file LICENSE. Dengan menggunakan, mendistribusikan, atau berkontribusi pada proyek ini, Anda menyetujui syarat dan ketentuan lisensi ini.