reifen
v1.7.8
früher pyo3-pack
Erstellen und veröffentlichen Sie Crates mit Pyo3-, Cffi- und Uniffi-Bindungen sowie Rust-Binärdateien als Python-Pakete mit minimaler Konfiguration. Es unterstützt das Erstellen von Rädern für Python 3.8+ unter Windows, Linux, Mac und FreeBSD, kann sie auf Pypi hochladen und verfügt über grundlegende Pypy- und Graalpy-Unterstützung.
Schauen Sie sich das Benutzerhandbuch an!
Sie können entweder Binärdateien von der neuesten Version herunterladen oder sie mit pipx installieren:
pipx install maturinNotiz
pip install maturin sollte auch funktionieren, wenn Sie pipx nicht verwenden möchten.
Es gibt vier Hauptbefehle:
maturin new erstellt ein neues Frachtprojekt mit konfiguriertem maturin.maturin publish baut die Kiste in Python-Pakete ein und veröffentlicht sie auf Pypi.maturin build erstellt die Räder und speichert sie in einem Ordner (standardmäßig target/wheels ), lädt sie jedoch nicht hoch. Es ist möglich, diese mit Bindfaden oder maturin upload hochzuladen.maturin develop erstellt die Kiste und installiert sie als Python-Modul direkt in der aktuellen virtuellen Umgebung. Beachten Sie, dass maturin develop zwar schneller ist, aber nicht alle Funktionen unterstützt, die das Ausführen pip install nach maturin build unterstützt. pyo3 Bindungen werden automatisch erkannt. Für cffi oder Binärdateien müssen Sie -b cffi oder -b bin übergeben. Maturin benötigt keine zusätzlichen Konfigurationsdateien und kollidiert nicht mit einer vorhandenen Setuptools-Rust- oder Milksnake-Konfiguration. Sie können es sogar in Testtools wie tox integrieren. Beispiele für die verschiedenen Bindungen finden Sie im test-crates -Ordner.
Der Name des Pakets ist der Name des Frachtprojekts, also das Namensfeld im Abschnitt [package] von Cargo.toml . Der Name des Moduls, das Sie beim Importieren verwenden, ist der name im Abschnitt [lib] (der standardmäßig der Name des Pakets ist). Bei Binärdateien ist es einfach der Name der von Cargo generierten Binärdatei.
Wenn Sie die Befehle maturin build und maturin develop verwenden, können Sie ein leistungsoptimiertes Programm kompilieren, indem Sie das Flag -r oder --release hinzufügen.
Python-Pakete gibt es in zwei Formaten: Eine erstellte Form namens Wheel und Quelldistributionen (sdist), die beide Archive sind. Ein Rad kann mit jeder Python-Version, jedem Interpreter (hauptsächlich Cpython und Pypy), jedem Betriebssystem und jeder Hardwarearchitektur (für reine Python-Räder) kompatibel sein, kann auf eine bestimmte Plattform und Architektur beschränkt sein (z. B. bei Verwendung von ctypes oder cffi) oder auf ein bestimmter Python-Interpreter und eine Version auf einer bestimmten Architektur und einem bestimmten Betriebssystem (z. B. mit Pyo3).
Wenn pip install für ein Paket verwendet wird, versucht pip, ein passendes Rad zu finden und dieses zu installieren. Wenn es keinen findet, lädt es die Quelldistribution herunter und erstellt ein Rad für die aktuelle Plattform, was die Installation der richtigen Compiler erfordert. Die Installation eines Rads ist viel schneller als die Installation einer Quelldistribution, da die Erstellung von Rädern im Allgemeinen langsam ist.
Wenn Sie ein Paket veröffentlichen, damit es mit pip install installierbar ist, laden Sie es auf pypi, das offizielle Paket-Repository, hoch. Zum Testen können Sie stattdessen test pypi verwenden, das Sie mit pip install --index-url https://test.pypi.org/simple/ verwenden können. Beachten Sie, dass Sie für die Veröffentlichung unter Linux den Manylinux-Docker-Container verwenden müssen, während Sie für die Veröffentlichung aus Ihrem Repository die Github-Aktion PyO3/maturin-action verwenden können.
Für Pyo3 kann Maturin nur Pakete für installierte Python-Versionen erstellen. Unter Linux und Mac werden alle Python-Versionen in PATH verwendet. Wenn Sie mit -i keine eigenen Interpreter festlegen, wird eine Heuristik zur Suche nach Python-Installationen verwendet. Unter Windows werden alle Versionen des Python-Launchers (der standardmäßig vom python.org-Installationsprogramm installiert wird) und alle Conda-Umgebungen außer Base verwendet. Sie können mit dem Unterbefehl list-python überprüfen, welche Versionen erfasst werden.
pyo3 legt den verwendeten Python-Interpreter in der Umgebungsvariablen PYTHON_SYS_EXECUTABLE fest, die von benutzerdefinierten Build-Skripten verwendet werden kann. Maturin kann mit Pyo3 Räder für Pypy erstellen und hochladen, obwohl nur Pypy3.7-7.3 unter Linux getestet wurde.
Cffi-Räder sind mit allen Python-Versionen einschließlich Pypy kompatibel. Wenn cffi nicht installiert ist und Python in einer virtuellen Umgebung ausgeführt wird, wird Maturin es installieren, andernfalls müssen Sie es selbst installieren ( pip install cffi ).
Maturin verwendet cbindgen, um eine Header-Datei zu generieren, die durch die Konfiguration von cbindgen über eine cbindgen.toml Datei in Ihrem Projektstamm angepasst werden kann. Alternativ können Sie ein Build-Skript verwenden, das eine Header-Datei in $PROJECT_ROOT/target/header.h schreibt.
Basierend auf der Header-Datei generiert Maturin ein Modul, das ein ffi und ein lib -Objekt exportiert.
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" ) ) ;
} Uniffi-Bindungen verwenden uniffi-rs, um Python ctypes Bindungen aus einer Schnittstellendefinitionsdatei zu generieren. Uniffi-Räder sind mit allen Python-Versionen einschließlich Pypy kompatibel.
Um ein gemischtes Rust/Python-Projekt zu erstellen, erstellen Sie einen Ordner mit Ihrem Modulnamen (z. B. lib.name in Cargo.toml) neben Ihrer Cargo.toml und fügen Sie dort Ihre Python-Quellen hinzu:
my-project
├── Cargo.toml
├── my_project
│ ├── __init__.py
│ └── bar.py
├── pyproject.toml
├── README.md
└── src
└── lib.rs
Sie können in pyproject.toml ein anderes Python-Quellverzeichnis angeben, indem Sie beispielsweise tool.maturin.python-source festlegen
pyproject.toml
[ tool . maturin ]
python-source = " python "
module-name = " my_project._lib_name "dann würde die Projektstruktur so aussehen:
my-project
├── Cargo.toml
├── python
│ └── my_project
│ ├── __init__.py
│ └── bar.py
├── pyproject.toml
├── README.md
└── src
└── lib.rs
Notiz
Diese Struktur wird empfohlen, um eine häufige ImportError Falle zu vermeiden
Maturin fügt die native Erweiterung als Modul in Ihrem Python-Ordner hinzu. Bei Verwendung von Develop kopiert Maturin die native Bibliothek und für cffi auch den Glue-Code in Ihren Python-Ordner. Sie sollten diese Dateien zu Ihrem Gitignore hinzufügen.
Mit cffi können Sie from .my_project import lib und dann lib.my_native_function verwenden, mit pyo3 können Sie direkt from .my_project import my_native_function .
Beispiellayout mit Pyo3 nach 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
Stellen Sie dabei auch sicher, dass der Modulname in Ihrem Code mit dem letzten Teil von module-name übereinstimmt (schließen Sie nicht den Paketpfad ein):
# [ pymodule ] # [ pyo3 ( name= "_lib_name" ) ] fn my_lib_name ( _py : Python < ' _ > , m : & PyModule ) -> PyResult < ( ) > { m . add_class :: < MyPythonRustClass > ( ) ? ; Ok ( ( ) ) }
maturin unterstützt PEP 621, Sie können Python-Paketmetadaten in pyproject.toml angeben. Maturin führt Metadaten aus Cargo.toml und pyproject.toml zusammen, pyproject.toml hat Vorrang vor Cargo.toml .
Um Python-Abhängigkeiten anzugeben, fügen Sie eine Liste dependencies in einem Abschnitt [project] in pyproject.toml hinzu. Diese Liste entspricht install_requires in setuptools:
[ project ]
name = " my-project "
dependencies = [ " flask~=1.1.0 " , " toml==0.10.0 " ] Pip ermöglicht das Hinzufügen sogenannter Konsolenskripte, bei denen es sich um Shell-Befehle handelt, die eine Funktion in Ihrem Programm ausführen. Sie können Konsolenskripte in einem Abschnitt [project.scripts] hinzufügen. Die Schlüssel sind die Skriptnamen, während die Werte der Pfad zur Funktion im Format some.module.path:class.function sind, wobei der class optional ist. Die Funktion wird ohne Argumente aufgerufen. Beispiel:
[ project . scripts ]
get_42 = " my_project:DummyClass.get_42 " Sie können Trove-Klassifizierer auch in Ihrer pyproject.toml unter project.classifiers angeben:
[ project ]
name = " my-project "
classifiers = [ " Programming Language :: Python " ] maturin unterstützt das Erstellen über pyproject.toml . Um es zu verwenden, erstellen Sie neben Ihrer Cargo.toml eine pyproject.toml mit folgendem Inhalt:
[ build-system ]
requires = [ " maturin>=1.0,<2.0 " ]
build-backend = " maturin " Wenn eine pyproject.toml mit einem [build-system] -Eintrag vorhanden ist, kann Maturin eine Quelldistribution Ihres Pakets erstellen, wenn --sdist angegeben ist. Die Quelldistribution enthält dieselben Dateien wie cargo package . Um nur eine Quelldistribution zu erstellen, übergeben Sie --interpreter ohne Werte.
Anschließend können Sie Ihr Paket beispielsweise mit pip install . . Mit pip install . -v Sie können die Ausgabe von Fracht und Maturin sehen.
Sie können die Optionen compatibility , skip-auditwheel , bindings , strip und allgemeine Cargo-Build-Optionen wie features unter [tool.maturin] auf die gleiche Weise verwenden, wie Sie es tun würden, wenn Sie Maturin direkt ausführen würden. Der bindings ist für cffi- und bin-Projekte erforderlich, da diese nicht automatisch erkannt werden können. Derzeit befinden sich alle Builds im Release-Modus (weitere Informationen finden Sie in diesem Thread).
Für einen Nicht-Manylinux-Build mit cffi-Bindungen könnten Sie Folgendes verwenden:
[ build-system ]
requires = [ " maturin>=1.0,<2.0 " ]
build-backend = " maturin "
[ tool . maturin ]
bindings = " cffi "
compatibility = " linux " Die Option manylinux wird auch als compatibility für die Abwärtskompatibilität mit der alten Version von Maturin akzeptiert.
Um beliebige Dateien zur Verwendung während der Kompilierung in die SDIST-Datei einzuschließen, include als Array von path Globs mit dem auf sdist eingestellten format an:
[ tool . maturin ]
include = [{ path = " path/**/* " , format = " sdist " }] Als Problemumgehung für pypa/pip#6041 gibt es einen maturin sdist Befehl, mit dem nur eine Quelldistribution erstellt werden kann.
Aus Portabilitätsgründen dürfen native Python-Module unter Linux nur eine Reihe sehr weniger Bibliotheken dynamisch verknüpfen, die praktisch überall installiert sind, daher der Name Manylinux. Um die Einhaltung der Manylinux-Regeln sicherzustellen, bietet Pypa spezielle Docker-Images und ein Tool namens Auditwheel an. Wenn Sie weit verbreitete Räder für Linux Pypi veröffentlichen möchten, müssen Sie ein Manylinux-Docker-Image verwenden .
Der Rust-Compiler benötigt seit Version 1.64 mindestens Glibc 2.17, Sie müssen also mindestens Manylinux2014 verwenden. Für die Veröffentlichung empfehlen wir, die gleiche Manylinux-Version wie das Image mit dem Manylinux-Flag zu erzwingen, z. B. --manylinux 2014 zu verwenden, wenn Sie in quay.io/pypa/manylinux2014_x86_64 erstellen. Die Github-Aktion PyO3/maturin-action kümmert sich bereits darum, wenn Sie z. B. manylinux: 2014 festlegen.
Maturin enthält eine Neuimplementierung von Auditwheel, überprüft automatisch die generierte Bibliothek und gibt dem Wheel das richtige Plattform-Tag. Wenn die glibc Ihres Systems zu neu ist oder Sie andere gemeinsam genutzte Bibliotheken verknüpfen, wird das linux Tag zugewiesen. Sie können diese Prüfungen auch manuell deaktivieren und mit --manylinux off direkt das native Linux-Ziel verwenden.
Für vollständige Manylinux-Konformität müssen Sie in einem CentOS-Docker-Container kompilieren. Das Pyo3/Maturin-Image basiert auf dem Manylinux2014-Image und übergibt Argumente an die maturin Binärdatei. Sie können es so verwenden:
docker run --rm -v $(pwd):/io ghcr.io/pyo3/maturin build --release # or other maturin arguments
Beachten Sie, dass dieses Bild sehr einfach ist und nur Python, Maturin und Stable Rust enthält. Wenn Sie zusätzliche Tools benötigen, können Sie Befehle im Manylinux-Container ausführen. Ein kleines pädagogisches Beispiel finden Sie unter konstin/complex-manylinux-maturin-docker oder unter nanoporetech/fast-ctc-decode für ein reales Setup.
Maturin selbst ist Manylinux-kompatibel, wenn es für das Musl-Ziel kompiliert wird.
Jeder ist willkommen, einen Beitrag zu maturin zu leisten! Es gibt viele Möglichkeiten, das Projekt zu unterstützen, wie zum Beispiel:
In unseren Beitragsnotizen finden Sie weitere Ressourcen, wenn Sie ehrenamtlich Zeit für die Matura aufwenden möchten und suchen, wo Sie anfangen sollen.
Wenn Sie keine Zeit haben, selbst einen Beitrag zu leisten, aber dennoch den zukünftigen Erfolg des Projekts unterstützen möchten, haben einige unserer Betreuer GitHub-Sponsorseiten:
Lizenziert unter:
nach Ihrer Wahl.
