pyo3
PyO3 0.23.3
Pengikatan karat untuk Python, termasuk alat untuk membuat modul ekstensi asli Python. Menjalankan dan berinteraksi dengan kode Python dari biner Rust juga didukung.
Panduan Pengguna: stabil | utama
Dokumentasi API: stabil | utama
Membutuhkan Rust 1.63 atau lebih tinggi.
PyO3 mendukung distribusi Python berikut:
Anda dapat menggunakan PyO3 untuk menulis modul Python asli di Rust, atau untuk menyematkan Python dalam biner Rust. Bagian berikut menjelaskan masing-masing hal ini secara bergantian.
PyO3 dapat digunakan untuk menghasilkan modul Python asli. Cara termudah untuk mencobanya untuk pertama kali adalah dengan menggunakan maturin . maturin adalah alat untuk membuat dan menerbitkan paket Python berbasis Rust dengan konfigurasi minimal. Langkah-langkah berikut menginstal maturin , menggunakannya untuk membuat dan membangun paket Python baru, lalu meluncurkan Python untuk mengimpor dan menjalankan fungsi dari paket tersebut.
Pertama, ikuti perintah di bawah ini untuk membuat direktori baru yang berisi virtualenv Python baru, dan instal maturin ke dalam virtualenv menggunakan manajer paket Python, pip :
# (replace string_sum with the desired package name)
$ mkdir string_sum
$ cd string_sum
$ python -m venv .env
$ source .env/bin/activate
$ pip install maturin Masih di dalam direktori string_sum ini, sekarang jalankan maturin init . Ini akan menghasilkan sumber paket baru. Saat diberi pilihan binding yang akan digunakan, pilih binding pyo3:
$ maturin init
✔ ? What kind of bindings to use ? · pyo3
Done ! New project created string_sum File terpenting yang dihasilkan oleh perintah ini adalah Cargo.toml dan lib.rs , yang kira-kira akan terlihat seperti berikut:
Cargo.toml
[ package ]
name = " string_sum "
version = " 0.1.0 "
edition = " 2021 "
[ lib ]
# The name of the native library. This is the name which will be used in Python to import the
# library (i.e. `import string_sum`). If you change this, you must also change the name of the
# `#[pymodule]` in `src/lib.rs`.
name = " string_sum "
# "cdylib" is necessary to produce a shared library for Python to import from.
#
# Downstream Rust code (including code in `bin/`, `examples/`, and `tests/`) will not be able
# to `use string_sum;` unless the "rlib" or "lib" crate type is also included, e.g.:
# crate-type = ["cdylib", "rlib"]
crate-type = [ " cdylib " ]
[ dependencies ]
pyo3 = { version = " 0.23.3 " , features = [ " extension-module " ] } src/lib.rs
use pyo3 :: prelude :: * ;
/// Formats the sum of two numbers as string.
# [ pyfunction ]
fn sum_as_string ( a : usize , b : usize ) -> PyResult < String > {
Ok ( ( a + b ) . to_string ( ) )
}
/// A Python module implemented in Rust. The name of this function must match
/// the `lib.name` setting in the `Cargo.toml`, else Python will not be able to
/// import the module.
# [ pymodule ]
fn string_sum ( m : & Bound < ' _ , PyModule > ) -> PyResult < ( ) > {
m . add_function ( wrap_pyfunction ! ( sum_as_string , m ) ? ) ? ;
Ok ( ( ) )
} Terakhir, jalankan maturin develop . Ini akan membangun paket dan menginstalnya ke dalam virtualenv Python yang sebelumnya dibuat dan diaktifkan. Paket kemudian siap digunakan dari python :
$ maturin develop
# lots of progress output as maturin runs the compilation...
$ python
>>> import string_sum
>>> string_sum.sum_as_string(5, 20)
' 25 ' Untuk melakukan perubahan pada paket, cukup edit kode sumber Rust lalu jalankan kembali maturin develop untuk mengkompilasi ulang.
Untuk menjalankan semuanya sebagai satu salin dan tempel, gunakan skrip bash di bawah ini (ganti string_sum pada perintah pertama dengan nama paket yang diinginkan):
mkdir string_sum && cd " $_ "
python -m venv .env
source .env/bin/activate
pip install maturin
maturin init --bindings pyo3
maturin develop Jika Anda ingin menjalankan cargo test atau menggunakan proyek ini di ruang kerja Kargo dan mengalami masalah linker, ada beberapa solusi di FAQ.
Seperti halnya maturin , dimungkinkan untuk membangun menggunakan setuptools-rust atau secara manual. Keduanya menawarkan lebih banyak fleksibilitas daripada maturin tetapi memerlukan lebih banyak konfigurasi untuk memulai.
Untuk menyematkan Python ke biner Rust, Anda perlu memastikan bahwa instalasi Python Anda berisi perpustakaan bersama. Langkah-langkah berikut menunjukkan cara memastikan hal ini (untuk Ubuntu), dan kemudian memberikan beberapa contoh kode yang menjalankan interpreter Python tertanam.
Untuk menginstal perpustakaan bersama Python di Ubuntu:
sudo apt install python3-dev Untuk menginstal pustaka bersama Python pada distribusi berbasis RPM (misalnya Fedora, Red Hat, SuSE), instal paket python3-devel .
Mulai proyek baru dengan cargo new dan tambahkan pyo3 ke Cargo.toml seperti ini:
[ dependencies . pyo3 ]
version = " 0.23.3 "
features = [ " auto-initialize " ] Contoh program yang menampilkan nilai sys.version dan nama pengguna saat ini:
use pyo3 :: prelude :: * ;
use pyo3 :: types :: IntoPyDict ;
use pyo3 :: ffi :: c_str ;
fn main ( ) -> PyResult < ( ) > {
Python :: with_gil ( |py| {
let sys = py . import ( "sys" ) ? ;
let version : String = sys . getattr ( "version" ) ? . extract ( ) ? ;
let locals = [ ( "os" , py . import ( "os" ) ? ) ] . into_py_dict ( py ) ? ;
let code = c_str ! ( "os.getenv('USER') or os.getenv('USERNAME') or 'Unknown'" ) ;
let user : String = py . eval ( code , None , Some ( & locals ) ) ? . extract ( ) ? ;
println ! ( "Hello {}, I'm Python {}" , user , version ) ;
Ok ( ( ) )
} )
}Panduan ini memiliki bagian dengan banyak contoh tentang topik ini.
built sebagai PyDictSetiap orang dipersilakan untuk berkontribusi pada PyO3! Ada banyak cara untuk mendukung proyek ini, seperti:
Catatan kontribusi dan panduan arsitektur kami memiliki lebih banyak sumber daya jika Anda ingin menyumbangkan waktu untuk PyO3 dan sedang mencari cara untuk memulai.
Jika Anda tidak punya waktu untuk berkontribusi tetapi masih ingin mendukung kesuksesan proyek di masa depan, beberapa pengelola kami memiliki halaman sponsor GitHub:
PyO3 dilisensikan di bawah lisensi Apache-2.0 atau lisensi MIT, sesuai pilihan Anda.
Python dilisensikan di bawah Lisensi Python.
Kecuali jika Anda secara eksplisit menyatakan sebaliknya, setiap kontribusi yang dengan sengaja Anda kirimkan untuk dimasukkan ke dalam PyO3, sebagaimana didefinisikan dalam Lisensi Apache, akan memiliki lisensi ganda seperti di atas, tanpa syarat atau ketentuan tambahan apa pun.
