maturin ダウンロード - maturin ソースコードのダウンロード

成熟した

パイソン

v1.7.8

ダウンロード

マトゥリン

以前の pyo3 パック

最小限の構成で、pyo3、cffi、および uniffi バインディングを含むクレートと、Rust バイナリを Python パッケージとして構築して公開します。 Windows、Linux、Mac、freebsd 上の Python 3.8 以降のホイールの構築をサポートし、それらを pypi にアップロードでき、基本的な pypy と graalpy をサポートします。

ユーザーガイドをチェックしてください!

使用法

最新リリースからバイナリをダウンロードするか、pipx を使用してインストールすることができます。

pipx install maturin

注記

pipx を使用したくない場合は、 pip install maturinも機能するはずです。

主なコマンドは次の 4 つです。

maturin new maturin が設定された新しい貨物プロジェクトを作成します。
maturin publishクレートを Python パッケージにビルドし、pypi に公開します。
maturin buildホイールをビルドしてフォルダー (デフォルトではtarget/wheels ) に保存しますが、アップロードはしません。 Twine またはmaturin uploadを使用してアップロードすることが可能です。
maturin developクレートを構築し、それを Python モジュールとして現在の virtualenv に直接インストールします。 maturin develop高速ですが、 maturin build後にpip install実行するとサポートされるすべての機能をサポートするわけではないことに注意してください。

pyo3バインディングは自動的に検出されます。 cffi またはバイナリの場合は、 -b cffiまたは-b binを渡す必要があります。 maturin は追加の設定ファイルを必要とせず、既存の setuptools-rust または Milksnake 設定と衝突しません。 tox などのテストツールと統合することもできます。 test-cratesフォルダーには、さまざまなバインディングの例があります。

パッケージの名前はカーゴプロジェクトの名前、つまりCargo.tomlの[package]セクションの name フィールドになります。インポート時に使用するモジュールの名前は、 [lib]セクションのname値になります (デフォルトはパッケージの名前です)。バイナリの場合、これは単にカーゴによって生成されたバイナリの名前です。

maturin buildおよびmaturin developコマンドを使用する場合、 -rまたは--releaseフラグを追加することで、パフォーマンスが最適化されたプログラムをコンパイルできます。

Python のパッケージ化の基本

Python パッケージには 2 つの形式があります。ホイールと呼ばれるビルド形式とソースディストリビューション (sdist) で、どちらもアーカイブです。ホイールは、任意の Python バージョン、インタプリタ (主に cpython と pypy)、オペレーティングシステムおよびハードウェアアーキテクチャ (純粋な Python ホイールの場合) と互換性があり、特定のプラットフォームとアーキテクチャ (例: ctypes または cffi を使用する場合) に制限することもできます。特定のアーキテクチャおよびオペレーティングシステム (例: pyo3) 上の特定の Python インタプリタとバージョン。

パッケージでpip install使用すると、pip は一致するホイールを見つけてインストールしようとします。見つからない場合は、ソース配布をダウンロードし、現在のプラットフォーム用のホイールを構築します。これには、適切なコンパイラがインストールされている必要があります。ホイールの構築は一般的に時間がかかるため、ホイールのインストールはソースディストリビューションをインストールするよりもはるかに高速です。

pip installでインストールできるようにパッケージを公開するときは、それを公式パッケージリポジトリである pypi にアップロードします。テストには、代わりに test pypi を使用できます。これは、 pip install --index-url https://test.pypi.org/simple/で使用できます。 Linux 用に公開するには、manylinux Docker コンテナを使用する必要がありますが、リポジトリから公開するには、PyO3/maturin-action github アクションを使用できることに注意してください。

ピヨ3

pyo3 の場合、maturin はインストールされている Python バージョンのパッケージのみをビルドできます。 Linux と Mac では、 PATH内のすべての Python バージョンが使用されます。 -iを使用して独自のインタープリターを設定しない場合は、Python インストールの検索にヒューリスティックが使用されます。 Windows では、Python ランチャー (python.org インストーラーによってデフォルトでインストールされる) のすべてのバージョンと、base を除くすべての conda 環境が使用されます。 list-pythonサブコマンドを使用して、どのバージョンが選択されるかを確認できます。

pyo3 は、使用する Python インタープリターを環境変数PYTHON_SYS_EXECUTABLEに設定します。これはカスタムビルドスクリプトから使用できます。 Linux 上の pypy3.7-7.3 のみがテストされていますが、Maturin は pyo3 を使用して pypy 用のホイールを構築してアップロードできます。

フィフィ

Cffi ホイールは、pypy を含むすべての Python バージョンと互換性があります。 cffiがインストールされておらず、python が virtualenv 内で実行されている場合は、maturin がそれをインストールします。それ以外の場合は、自分でインストールする必要があります ( pip install cffi )。

maturin は cbindgen を使用してヘッダーファイルを生成します。ヘッダーファイルは、プロジェクトルート内のcbindgen.tomlファイルを通じて cbindgen を構成することでカスタマイズできます。あるいは、ヘッダーファイルを$PROJECT_ROOT/target/header.hに書き込むビルドスクリプトを使用することもできます。

ヘッダーファイルに基づいて、maturin はffiと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" ) ) ;
}

ユニフィ

uniffi バインディングは、unifi-rs を使用して、インターフェイス定義ファイルから Python ctypesバインディングを生成します。 uniffi ホイールは、pypy を含むすべての Python バージョンと互換性があります。

Rust/Python 混合プロジェクト

Rust/Python 混合プロジェクトを作成するには、Cargo.toml の隣にモジュール名 (つまり、Cargo.toml のlib.name ) を持つフォルダーを作成し、そこに Python ソースを追加します。

 my-project
├── Cargo.toml
├── my_project
│   ├── __init__.py
│   └── bar.py
├── pyproject.toml
├── README.md
└── src
    └── lib.rs

たとえば、 tool.maturin.python-source設定することで、 pyproject.tomlで別の Python ソースディレクトリを指定できます。

pyproject.toml

[ tool . maturin ]
python-source = " python "
module-name = " my_project._lib_name "

その場合、プロジェクト構造は次のようになります。

 my-project
├── Cargo.toml
├── python
│   └── my_project
│       ├── __init__.py
│       └── bar.py
├── pyproject.toml
├── README.md
└── src
    └── lib.rs

注記

この構造は、一般的なImportError落とし穴を回避するために推奨されます。

maturin はネイティブ拡張機能をモジュールとして Python フォルダーに追加します。 Development を使用する場合、maturin はネイティブライブラリをコピーし、cffi の場合はグルーコードも Python フォルダーにコピーします。これらのファイルを gitignore に追加する必要があります。

cffi を使用すると、 from .my_project import lib実行してからlib.my_native_functionを使用できます。 pyo3 を使用すると、 from .my_project import my_native_function直接実行できます。

maturin develop後の pyo3 を使用したレイアウトの例:

 my-project
├── Cargo.toml
├── my_project
│   ├── __init__.py
│   ├── bar.py
│   └── _lib_name.cpython-36m-x86_64-linux-gnu.so
├── README.md
└── src
    └── lib.rs

これを行うときは、コード内のモジュール名がmodule-nameの最後の部分と一致するように設定してください (パッケージパスは含めないでください)。

, m: &PyModule) -> PyResult<()> {
    m.add_class::()?;
    Ok(())
}"> # [ pymodule ]
# [ pyo3 ( name= "_lib_name" ) ]
fn my_lib_name ( _py : Python < ' _ > , m : & PyModule ) -> PyResult < ( ) > {
    m . add_class :: < MyPythonRustClass > ( ) ? ;
    Ok ( ( ) )
} 

Python メタデータ

maturin は PEP 621 をサポートしているため、 pyproject.tomlで Python パッケージのメタデータを指定できます。 maturin はCargo.tomlとpyproject.tomlのメタデータをマージします。 pyproject.toml Cargo.tomlよりも優先されます。

Python の依存関係を指定するには、 pyproject.tomlの[project]セクションにdependenciesリストを追加します。このリストは、setuptools のinstall_requiresと同等です。

[ project ]
name = " my-project "
dependencies = [ " flask~=1.1.0 " , " toml==0.10.0 " ]

Pip を使用すると、プログラム内で何らかの機能を実行するシェルコマンドである、いわゆるコンソールスクリプトを追加できます。コンソールスクリプトはセクション[project.scripts]に追加できます。キーはスクリプト名で、値はsome.module.path:class.function形式の関数へのパスです。 class部分はオプションです。関数は引数なしで呼び出されます。例：

[ project . scripts ]
get_42 = " my_project:DummyClass.get_42 "

pyproject.tomlのproject.classifiersで trove 分類子を指定することもできます。

[ project ]
name = " my-project "
classifiers = [ " Programming Language :: Python " ]

ソースの配布

maturin はpyproject.tomlによるビルドをサポートしています。これを使用するには、次の内容を含むpyproject.tomlをCargo.tomlの隣に作成します。

=1.0,<2.0"] build-backend = "maturin"">

[ build-system ]
requires = [ " maturin>=1.0,<2.0 " ]
build-backend = " maturin "

[build-system]エントリを持つpyproject.tomlが存在する場合、 --sdistが指定されている場合、maturin はパッケージのソースディストリビューションをビルドできます。ソース配布には、 cargo packageと同じファイルが含まれます。ソースディストリビューションを構築するだけの場合は、値を指定せずに--interpreterを渡します。

その後、たとえばpip install . 。 pip install . -v cargo と maturin の出力を確認できます。

maturin を直接実行する場合と同じ方法で、オプションcompatibility 、 skip-auditwheel 、 bindings 、 strip 、および[tool.maturin]の下のfeaturesなどの一般的な Cargo ビルドオプションを使用できます。 cffi プロジェクトと bin プロジェクトは自動的に検出できないため、 bindingsキーが必要です。現在、すべてのビルドはリリースモードです (詳細については、このスレッドを参照してください)。

cffi バインディングを使用した非 manylinux ビルドの場合は、次のものを使用できます。

=1.0,<2.0"] build-backend = "maturin" [tool.maturin] bindings = "cffi" compatibility = "linux"">

[ build-system ]
requires = [ " maturin>=1.0,<2.0 " ]
build-backend = " maturin "

[ tool . maturin ]
bindings = " cffi "
compatibility = " linux "

manylinuxオプションは、古いバージョンの maturin との下位互換性のためのcompatibilityのエイリアスとしても受け入れられます。

コンパイル中に使用するために sdist に任意のファイルを含めるには、 formatがsdistに設定されたpathグロブの配列としてinclude指定します。

[ tool . maturin ]
include = [{ path = " path/**/* " , format = " sdist " }]

pypa/pip#6041 の回避策として、ソースディストリビューションを構築するためだけのmaturin sdistコマンドがあります。

ManyLinux と Auditwheel

移植性の理由から、Linux 上のネイティブ Python モジュールは、基本的にどこにでもインストールされる非常に少数のライブラリのセットのみを動的にリンクする必要があるため、manylinux という名前が付けられています。 pypa は、manylinux ルールへの準拠を保証するための特別な docker イメージと、auditwheel と呼ばれるツールを提供します。 Linux pypi 用に広く使用できるホイールを公開したい場合は、 manylinux docker image を使用する必要があります。

バージョン 1.64 以降の Rust コンパイラには少なくとも glibc 2.17 が必要なので、少なくとも manylinux2014 を使用する必要があります。公開する場合は、manylinux フラグを使用してイメージと同じ manylinux バージョンを強制することをお勧めします。たとえば、 quay.io/pypa/manylinux2014_x86_64でビルドする場合は--manylinux 2014を使用します。たとえば、 manylinux: 2014を設定すると、PyO3/maturin-action github アクションがすでにこれに対応します。

maturin には、auditwheel の再実装が含まれており、生成されたライブラリを自動的にチェックし、ホイールに適切なプラットフォームタグを与えます。システムの glibc が新しすぎる場合、または他の共有ライブラリをリンクしている場合は、 linuxタグが割り当てられます。これらのチェックを手動で無効にして、 --manylinux off指定してネイティブ Linux ターゲットを直接使用することもできます。

manylinux に完全に準拠するには、CentOS Docker コンテナーでコンパイルする必要があります。 pyo3/maturin イメージは manylinux2014 イメージに基づいており、引数をmaturinバイナリに渡します。次のように使用できます。

 docker run --rm -v $(pwd):/io ghcr.io/pyo3/maturin build --release  # or other maturin arguments

このイメージは非常に基本的なものであり、Python、Maturin、Stable Rust のみが含まれていることに注意してください。追加のツールが必要な場合は、manylinux コンテナ内でコマンドを実行できます。小さな教育的な例については konstin/complex-manylinux-maturin-docker を参照し、実際のセットアップについては nanoporetech/fast-ctc-decode を参照してください。

maturin 自体は、musl ターゲット用にコンパイルされた場合、manylinux に準拠します。