dewasa
v1.7.8
sebelumnya paket pyo3
Bangun dan publikasikan peti dengan pengikatan pyo3, cffi dan uniffi serta binari karat sebagai paket python dengan konfigurasi minimal. Ini mendukung roda bangunan untuk python 3.8+ di windows, linux, mac dan freebsd, dapat mengunggahnya ke pypi dan memiliki dukungan dasar pypy dan graalpy.
Lihat Panduan Pengguna!
Anda dapat mengunduh binari dari rilis terbaru atau menginstalnya dengan pipx:
pipx install maturinCatatan
pip install maturin juga akan berfungsi jika Anda tidak ingin menggunakan pipx.
Ada empat perintah utama:
maturin new membuat proyek kargo baru dengan konfigurasi maturin.maturin publish membuat peti menjadi paket python dan menerbitkannya ke pypi.maturin build membuat roda dan menyimpannya dalam folder ( target/wheels secara default), tetapi tidak mengunggahnya. Dimungkinkan untuk mengunggahnya dengan maturin upload .maturin develop membangun peti dan menginstalnya sebagai modul python langsung di virtualenv saat ini. Perhatikan bahwa meskipun maturin develop lebih cepat, ia tidak mendukung semua fitur yang menjalankan pip install setelah dukungan maturin build . pengikatan pyo3 terdeteksi secara otomatis. Untuk cffi atau binari, Anda harus meneruskan -b cffi atau -b bin . maturin tidak memerlukan file konfigurasi tambahan dan tidak berbenturan dengan konfigurasi setuptools-rust atau milksnake yang ada. Anda bahkan dapat mengintegrasikannya dengan alat pengujian seperti tox. Ada contoh untuk pengikatan yang berbeda di folder test-crates .
Nama paket akan menjadi nama proyek kargo, yaitu kolom nama di bagian [package] di Cargo.toml . Nama modul yang Anda gunakan saat mengimpor akan menjadi nilai name di bagian [lib] (yang defaultnya adalah nama paket). Untuk biner, ini hanyalah nama biner yang dihasilkan oleh kargo.
Saat menggunakan perintah maturin build dan maturin develop , Anda dapat mengkompilasi program yang kinerjanya dioptimalkan dengan menambahkan flag -r atau --release .
Paket Python hadir dalam dua format: Formulir bawaan yang disebut distribusi roda dan sumber (sdist), keduanya merupakan arsip. Roda dapat kompatibel dengan versi python apa pun, penerjemah (terutama cpython dan pypy), sistem operasi dan arsitektur perangkat keras (untuk roda python murni), dapat dibatasi pada platform dan arsitektur tertentu (misalnya saat menggunakan ctypes atau cffi) atau dengan juru bahasa python tertentu dan versi pada arsitektur dan sistem operasi tertentu (misalnya dengan pyo3).
Saat menggunakan pip install pada sebuah paket, pip mencoba menemukan roda yang cocok dan menginstalnya. Jika tidak menemukannya, ia mengunduh distribusi sumber dan membangun roda untuk platform saat ini, yang memerlukan instalasi kompiler yang tepat. Memasang roda jauh lebih cepat daripada memasang distribusi sumber karena roda bangunan umumnya lambat.
Saat Anda memublikasikan sebuah paket agar dapat diinstal dengan pip install , Anda mengunggahnya ke pypi, repositori paket resmi. Untuk pengujian, Anda dapat menggunakan test pypi, yang dapat Anda gunakan dengan pip install --index-url https://test.pypi.org/simple/ . Perhatikan bahwa untuk menerbitkan untuk linux, Anda perlu menggunakan wadah buruh pelabuhan manylinux, sedangkan untuk menerbitkan dari repositori Anda, Anda dapat menggunakan tindakan github PyO3/maturin-action.
Untuk pyo3, maturin hanya dapat membuat paket untuk versi python yang diinstal. Di linux dan mac, semua versi python di PATH digunakan. Jika Anda tidak menyetel penerjemah Anda sendiri dengan -i , heuristik digunakan untuk mencari instalasi python. Di windows semua versi dari peluncur python (yang diinstal secara default oleh penginstal python.org) dan semua lingkungan conda kecuali basis digunakan. Anda dapat memeriksa versi mana yang diambil dengan subperintah list-python .
pyo3 akan mengatur juru bahasa python yang digunakan dalam variabel lingkungan PYTHON_SYS_EXECUTABLE , yang dapat digunakan dari skrip build khusus. Maturin dapat membuat dan mengunggah roda untuk pypy dengan pyo3, meskipun hanya pypy3.7-7.3 di linux yang diuji.
Roda Cffi kompatibel dengan semua versi python termasuk pypy. Jika cffi tidak diinstal dan python berjalan di dalam virtualenv, maturin akan menginstalnya, jika tidak, Anda harus menginstalnya sendiri ( pip install cffi ).
maturin menggunakan cbindgen untuk menghasilkan file header, yang dapat dikustomisasi dengan mengkonfigurasi cbindgen melalui file cbindgen.toml di dalam root proyek Anda. Alternatifnya, Anda dapat menggunakan skrip build yang menulis file header ke $PROJECT_ROOT/target/header.h .
Berdasarkan file header maturin menghasilkan modul yang mengekspor objek ffi dan lib .
use cbindgen ;
use std :: env ;
use std :: path :: Path ;
fn main ( ) {
let crate_dir = env :: var ( "CARGO_MANIFEST_DIR" ) . unwrap ( ) ;
let bindings = cbindgen :: Builder :: new ( )
. with_no_includes ( )
. with_language ( cbindgen :: Language :: C )
. with_crate ( crate_dir )
. generate ( )
. unwrap ( ) ;
bindings . write_to_file ( Path :: new ( "target" ) . join ( "header.h" ) ) ;
} pengikatan uniffi menggunakan uniffi-rs untuk menghasilkan pengikatan ctypes Python dari file definisi antarmuka. roda uniffi kompatibel dengan semua versi python termasuk pypy.
Untuk membuat proyek campuran karat/python, buat folder dengan nama modul Anda (yaitu lib.name di Cargo.toml) di sebelah Cargo.toml Anda dan tambahkan sumber python Anda di sana:
my-project
├── Cargo.toml
├── my_project
│ ├── __init__.py
│ └── bar.py
├── pyproject.toml
├── README.md
└── src
└── lib.rs
Anda dapat menentukan direktori sumber python yang berbeda di pyproject.toml dengan mengatur tool.maturin.python-source , misalnya
proyek py.toml
[ tool . maturin ]
python-source = " python "
module-name = " my_project._lib_name "maka struktur proyek akan terlihat seperti ini:
my-project
├── Cargo.toml
├── python
│ └── my_project
│ ├── __init__.py
│ └── bar.py
├── pyproject.toml
├── README.md
└── src
└── lib.rs
Catatan
Struktur ini disarankan untuk menghindari jebakan ImportError yang umum
maturin akan menambahkan ekstensi asli sebagai modul di folder python Anda. Saat menggunakan pengembangan, maturin akan menyalin perpustakaan asli dan untuk cffi juga kode lem ke folder python Anda. Anda harus menambahkan file-file itu ke gitignore Anda.
Dengan cffi Anda dapat melakukan from .my_project import lib dan kemudian menggunakan lib.my_native_function , dengan pyo3 Anda dapat langsung from .my_project import my_native_function .
Contoh tata letak dengan pyo3 setelah maturin develop :
my-project
├── Cargo.toml
├── my_project
│ ├── __init__.py
│ ├── bar.py
│ └── _lib_name.cpython-36m-x86_64-linux-gnu.so
├── README.md
└── src
└── lib.rs
Saat melakukan ini juga pastikan untuk mengatur nama modul dalam kode Anda agar cocok dengan bagian terakhir module-name (jangan sertakan jalur paket):
# [ pymodule ] # [ pyo3 ( name= "_lib_name" ) ] fn my_lib_name ( _py : Python < ' _ > , m : & PyModule ) -> PyResult < ( ) > { m . add_class :: < MyPythonRustClass > ( ) ? ; Ok ( ( ) ) }
maturin mendukung PEP 621, Anda dapat menentukan metadata paket python di pyproject.toml . maturin menggabungkan metadata dari Cargo.toml dan pyproject.toml , pyproject.toml lebih diutamakan daripada Cargo.toml .
Untuk menentukan dependensi python, tambahkan daftar dependencies di bagian [project] di pyproject.toml . Daftar ini setara dengan install_requires di setuptools:
[ project ]
name = " my-project "
dependencies = [ " flask~=1.1.0 " , " toml==0.10.0 " ] Pip memungkinkan penambahan skrip konsol, yang merupakan perintah shell yang menjalankan beberapa fungsi dalam program Anda. Anda dapat menambahkan skrip konsol di bagian [project.scripts] . Kuncinya adalah nama skrip sedangkan nilainya adalah jalur ke fungsi dalam format some.module.path:class.function , dengan bagian class bersifat opsional. Fungsi ini dipanggil tanpa argumen. Contoh:
[ project . scripts ]
get_42 = " my_project:DummyClass.get_42 " Anda juga dapat menentukan pengklasifikasi trove di pyproject.toml di bawah project.classifiers :
[ project ]
name = " my-project "
classifiers = [ " Programming Language :: Python " ] maturin mendukung pembangunan melalui pyproject.toml . Untuk menggunakannya, buat pyproject.toml di samping Cargo.toml Anda dengan konten berikut:
[ build-system ]
requires = [ " maturin>=1.0,<2.0 " ]
build-backend = " maturin " Jika ada pyproject.toml dengan entri [build-system] , maturin dapat membangun distribusi sumber paket Anda ketika --sdist ditentukan. Distribusi sumber akan berisi file yang sama dengan cargo package . Untuk hanya membangun distribusi sumber, berikan --interpreter tanpa nilai apa pun.
Anda kemudian dapat menginstal paket Anda dengan pip install . . Dengan pip install . -v Anda dapat melihat keluaran kargo dan maturin.
Anda dapat menggunakan opsi compatibility , skip-auditwheel , bindings , strip dan opsi pembuatan Cargo yang umum seperti features di bawah [tool.maturin] dengan cara yang sama seperti saat menjalankan maturin secara langsung. Kunci bindings diperlukan untuk proyek cffi dan bin karena proyek tersebut tidak dapat dideteksi secara otomatis. Saat ini, semua build berada dalam mode rilis (lihat thread ini untuk detailnya).
Untuk build non-manylinux dengan binding cffi Anda dapat menggunakan yang berikut ini:
[ build-system ]
requires = [ " maturin>=1.0,<2.0 " ]
build-backend = " maturin "
[ tool . maturin ]
bindings = " cffi "
compatibility = " linux " Opsi manylinux juga diterima sebagai alias compatibility untuk kompatibilitas mundur dengan maturin versi lama.
Untuk memasukkan file arbitrer ke dalam sdist untuk digunakan selama kompilasi, tentukan include sebagai array gumpalan path dengan format yang disetel ke sdist :
[ tool . maturin ]
include = [{ path = " path/**/* " , format = " sdist " }] Ada perintah maturin sdist untuk hanya membangun distribusi sumber sebagai solusi untuk pypa/pip#6041.
Untuk alasan portabilitas, modul python asli di linux harus secara dinamis menghubungkan sekumpulan perpustakaan yang sangat sedikit yang pada dasarnya diinstal di mana saja, oleh karena itu dinamakan manylinux. Pypa menawarkan gambar buruh pelabuhan khusus dan alat yang disebut auditwheel untuk memastikan kepatuhan terhadap aturan manylinux. Jika Anda ingin mempublikasikan roda yang dapat digunakan secara luas untuk linux pypi, Anda perlu menggunakan gambar buruh pelabuhan manylinux .
Kompiler Rust sejak versi 1.64 memerlukan setidaknya glibc 2.17, jadi Anda perlu menggunakan setidaknya manylinux2014. Untuk penerbitan, kami sarankan untuk menerapkan versi manylinux yang sama dengan gambar dengan flag manylinux, misalnya gunakan --manylinux 2014 jika Anda membuat di quay.io/pypa/manylinux2014_x86_64 . Tindakan github PyO3/maturin-action sudah menangani hal ini jika Anda menyetel misalnya manylinux: 2014 .
maturin berisi implementasi ulang auditwheel yang secara otomatis memeriksa perpustakaan yang dihasilkan dan memberikan tag platform yang tepat pada wheel tersebut. Jika glibc sistem Anda terlalu baru atau Anda menautkan pustaka bersama lainnya, glibc akan menetapkan tag linux . Anda juga dapat menonaktifkan pemeriksaan tersebut secara manual dan langsung menggunakan target linux asli dengan --manylinux off .
Untuk kepatuhan penuh dengan manylinux, Anda perlu mengkompilasinya dalam wadah buruh pelabuhan CentOS. Gambar pyo3/maturin didasarkan pada gambar manylinux2014, dan meneruskan argumen ke biner maturin . Anda dapat menggunakannya seperti ini:
docker run --rm -v $(pwd):/io ghcr.io/pyo3/maturin build --release # or other maturin arguments
Perhatikan bahwa gambar ini sangat mendasar dan hanya berisi python, maturin, dan karat stabil. Jika Anda memerlukan alat tambahan, Anda dapat menjalankan perintah di dalam container manylinux. Lihat konstin/complex-manylinux-maturin-docker untuk contoh pendidikan kecil atau nanoporetech/fast-ctc-decode untuk pengaturan dunia nyata.
maturin sendiri sesuai dengan manylinux ketika dikompilasi untuk target musl.
Setiap orang dipersilakan untuk berkontribusi pada maturin! Ada banyak cara untuk mendukung proyek ini, seperti:
Catatan kontribusi kami memiliki lebih banyak sumber daya jika Anda ingin meluangkan waktu untuk menjadi dewasa dan mencari tempat 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:
Berlisensi di bawah salah satu dari:
sesuai pilihan Anda.
