pybind11

pybind11 — การทำงานที่ราบรื่นระหว่าง C++11 และ Python

ตัวอย่างเครื่องมือติดตั้ง • ตัวอย่าง Scikit-build • ตัวอย่าง CMake

pybind11 เป็นไลบรารี่แบบส่วนหัวเท่านั้นที่มีน้ำหนักเบา ซึ่งเปิดเผยประเภท C++ ใน Python และในทางกลับกัน โดยส่วนใหญ่ใช้เพื่อสร้างการเชื่อมโยง Python ของโค้ด C++ ที่มีอยู่ เป้าหมายและไวยากรณ์ของมันคล้ายกับไลบรารี Boost.Python ที่ยอดเยี่ยมโดย David Abrahams: เพื่อลดขนาดโค้ดสำเร็จรูปในโมดูลส่วนขยายแบบดั้งเดิมโดยการอนุมานข้อมูลประเภทโดยใช้วิปัสสนาเวลาคอมไพล์

ปัญหาหลักของ Boost.Python และเหตุผลในการสร้างโปรเจ็กต์ที่คล้ายกันคือ Boost Boost เป็นชุดยูทิลิตี้ไลบรารีขนาดใหญ่และซับซ้อนขนาดใหญ่ที่ทำงานร่วมกับคอมไพเลอร์ C++ เกือบทุกตัวที่มีอยู่ ความเข้ากันได้นี้มีค่าใช้จ่าย: เทคนิคเทมเพลต arcane และวิธีแก้ปัญหามีความจำเป็นเพื่อรองรับตัวอย่างคอมไพเลอร์ที่เก่าที่สุดและบั๊กที่สุด ขณะนี้คอมไพเลอร์ที่เข้ากันได้กับ C++11 มีวางจำหน่ายอย่างแพร่หลาย เครื่องจักรหนักนี้กลายเป็นการพึ่งพาที่มากเกินไปและไม่จำเป็น

คิดว่าไลบรารี่นี้เป็น Boost.Python เวอร์ชันเล็ก ๆ ที่มีในตัวเอง โดยที่ทุกอย่างถูกแยกออกไปซึ่งไม่เกี่ยวข้องกับการสร้างการเชื่อมโยง หากไม่มีความคิดเห็น ไฟล์ส่วนหัวหลักต้องการเพียงโค้ด ~4K บรรทัด และขึ้นอยู่กับ Python (3.8+ หรือ PyPy) และไลบรารีมาตรฐาน C++ การใช้งานแบบกะทัดรัดนี้เกิดขึ้นได้ด้วยฟีเจอร์ภาษา C++11 บางอย่าง (โดยเฉพาะ: tuples, ฟังก์ชัน lambda และเทมเพลต variadic) นับตั้งแต่ก่อตั้งขึ้น ไลบรารีนี้ได้เติบโตขึ้นเหนือกว่า 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 move Constructor และย้ายตัวดำเนินการกำหนดทุกครั้งที่เป็นไปได้เพื่อถ่ายโอนประเภทข้อมูลที่กำหนดเองอย่างมีประสิทธิภาพ
• การเปิดเผยที่จัดเก็บข้อมูลภายในของประเภทข้อมูลที่กำหนดเองผ่านโปรโตคอลบัฟเฟอร์ของ Python เป็นเรื่องง่าย สิ่งนี้มีประโยชน์ เช่น สำหรับการแปลงอย่างรวดเร็วระหว่างคลาสเมทริกซ์ C++ เช่น Eigen และ NumPy โดยไม่ต้องดำเนินการคัดลอกราคาแพง
• pybind11 สามารถกำหนดฟังก์ชันเวกเตอร์ได้โดยอัตโนมัติ เพื่อให้ฟังก์ชันเหล่านั้นถูกนำไปใช้กับรายการทั้งหมดของอาร์กิวเมนต์อาร์เรย์ NumPy ตั้งแต่หนึ่งรายการขึ้นไปอย่างโปร่งใส
• การดำเนินการตามการแบ่งส่วนและการกำหนดของ Python สามารถรองรับได้โดยใช้โค้ดเพียงไม่กี่บรรทัด
• ทุกอย่างมีอยู่ในไฟล์ส่วนหัวเพียงไม่กี่ไฟล์ ไม่จำเป็นต้องเชื่อมโยงกับไลบรารีเพิ่มเติมใดๆ
• โดยทั่วไปไบนารีจะมีขนาดเล็กกว่าอย่างน้อย 2 เท่าเมื่อเทียบกับการเชื่อมโยงที่เทียบเท่าซึ่งสร้างโดย Boost.Python การแปลง pybind11 ล่าสุดของ PyRosetta ซึ่งเป็นโปรเจ็กต์การรวม Boost.Python ขนาดมหึมา รายงานว่าขนาดไบนารี่ลดลง 5.4x และลดเวลาในการคอมไพล์ลง 5.8x
• ลายเซ็นฟังก์ชันจะถูกคำนวณล่วงหน้า ณ เวลาคอมไพล์ (โดยใช้ constexpr ) ส่งผลให้ไบนารีมีขนาดเล็กลง
• ด้วยความพยายามพิเศษเพียงเล็กน้อย ประเภท C++ ก็สามารถดองและเลิกดองได้คล้ายกับอ็อบเจ็กต์ Python ทั่วไป

คอมไพเลอร์ที่รองรับ

1. Clang/LLVM 3.3 หรือใหม่กว่า (สำหรับเสียงดังกราวของ 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)

เกี่ยวกับ

โปรเจ็กต์นี้สร้างโดย 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 มาบิลเล, โทมัสซ์ มิออนสโก, ดีน มอลโดแวน, เบน พริตชาร์ด, เจสัน ไรน์แลนเดอร์, บอริส ชาลิง, พิม เชลลาร์ต, เฮนรี ชไรเนอร์, อีวาน สเมียร์นอฟ, บอริส สตาเลติก และแพทริค สจ๊วร์ต

เราขอขอบคุณ Google ที่ให้การสนับสนุนทางการเงินแก่โครงสร้างพื้นฐานการบูรณาการอย่างต่อเนื่องที่ใช้โดยโครงการนี้

มีส่วนร่วม

ดูคู่มือการสนับสนุนสำหรับข้อมูลเกี่ยวกับการสร้างและการมีส่วนร่วมใน pybind11

ใบอนุญาต

pybind11 มีให้ภายใต้ลิขสิทธิ์แบบ BSD ที่สามารถพบได้ในไฟล์ LICENSE โดยการใช้ แจกจ่าย หรือมีส่วนร่วมในโครงการนี้ แสดงว่าคุณยอมรับข้อกำหนดและเงื่อนไขของใบอนุญาตนี้