maturin 下載 - maturin 原始碼下載

成熟

Python

v1.7.8

下載

馬圖林

以前的 pyo3-pack

使用 pyo3、cffi 和 uniffi 綁定以及 rust 二進位檔案以最少的配置建置和發布 crates 作為 python 套件。它支援在 windows、linux、mac 和 freebsd 上為 python 3.8+ 建立輪子，可以將它們上傳到 pypi，並具有基本的 pypy 和 graalpy 支援。

查看使用者指南！

用法

您可以從最新版本下載二進位檔案或使用 pipx 安裝它：

pipx install maturin

筆記

如果您不想使用 pipx， pip install maturin也應該可以工作。

主要有四個指令：

maturin new建立一個配置了 maturin 的新貨運項目。
maturin publish將 crate 建置到 python 套件中並將它們發佈到 pypi。
maturin build建置輪子並將它們儲存在資料夾中（預設為target/wheels ），但不上傳它們。可以使用 twine 或maturin upload上傳那些。
maturin develop建構 crate 並將其作為 python 模組直接安裝在目前的 virtualenv 中。請注意，雖然maturin develop速度更快，但它並不支援在maturin build之後運行pip install支援的所有功能。

pyo3結合會自動偵測。對於 cffi 或二進位文件，您需要傳遞-b cffi或-b bin 。 maturin 不需要額外的設定文件，並且不會與現有的 setuptools-rust 或 milksnake 配置發生衝突。您甚至可以將其與 tox 等測試工具整合。 test-crates資料夾中有不同綁定的範例。

包的名稱將是貨物項目的名稱，即Cargo.toml的[package]部分中的名稱欄位。導入時使用的模組的名稱將是[lib]部分中的name值（預設為套件的名稱）。對於二進位文件，它只是由 Cargo 產生的二進位檔案的名稱。

使用maturin build和maturin develop指令時，可以透過加入-r或--release標誌來編譯效能最佳化的程式。

Python 打包基礎知識

Python 套件有兩種格式：稱為wheel 的建構形式和來源發行版(sdist)，兩者都是存檔。輪子可以與任何Python版本、解釋器（主要是cpython和pypy）、作業系統和硬體架構（對於純Python輪子）相容，可以限於特定的平台和架構（例如，當使用ctypes或cffi時）或特定架構和作業系統上的特定python 解釋器和版本（例如pyo3）。

在軟體包上使用pip install時，pip 會嘗試找到匹配的wheel並安裝它。如果找不到，它會下載原始碼發行版並為當前平台建立一個輪子，這需要安裝正確的編譯器。安裝輪子比安裝來源發行版快得多，因為建造輪子通常很慢。

當您發布可使用pip install安裝的套件時，請將其上傳到官方套件儲存庫 pypi。對於測試，您可以使用 test pypi 代替，您可以將其與pip install --index-url https://test.pypi.org/simple/一起使用。請注意，要針對 Linux 進行發布，您需要使用 Manylinux docker 容器，而要從儲存庫進行發布，您可以使用 PyO3/maturin-action github 操作。

pyo3

對於 pyo3，maturin 只能為已安裝的 python 版本建置套件。在linux和mac上，使用PATH中的所有python版本。如果您沒有使用-i設定自己的解釋器，則會使用啟發式搜尋 python 安裝。在 Windows 上，使用 python 啟動器（預設由 python.org 安裝程式安裝）的所有版本以及除 base 之外的所有 conda 環境。您可以使用list-python子指令檢查選擇了哪些版本。

pyo3 將在環境變數PYTHON_SYS_EXECUTABLE中設定使用的 python 解釋器，可以從自訂建置腳本中使用它。 Maturin 可以使用 pyo3 為 pypy 建置和上傳輪子，儘管僅測試了 linux 上的 pypy3.7-7.3。

菲菲

Cffi 輪子與所有 python 版本相容，包括 pypy。如果未安裝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 綁定使用 uniffi-rs 從介面定義檔產生 Python ctypes綁定。 uniffi 輪子與所有 python 版本相容，包括 pypy。

混合 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 資料夾中。使用開發時，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 允許新增所謂的控制台腳本，這些腳本是在程式中執行某些功能的 shell 命令。您可以在[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進行建置。要使用它，請在Cargo.toml旁邊建立一個包含以下內容的pyproject.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的輸出。

您可以使用compatibility 、 skip-auditwheel 、 bindings 、 strip和通用 Cargo 建置選項（例如[tool.maturin]下的features ），就像直接執行 maturin 時一樣。 cffi 和 bin 專案需要bindings金鑰，因為這些項目無法自動偵測到。目前，所有版本都處於發布模式（有關詳細信息，請參閱此線程）。

對於帶有 cffi 綁定的 non-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選項也被接受作為compatibility的別名，以向後相容舊版本的 maturin。

若要在 sdist 中包含任意檔案以供編譯期間使用， include為format設為sdist的path glob 陣列：

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

有一個maturin sdist指令僅用於建構來源發行版作為 pypa/pip#6041 的解決方法。

Manylinux 和 Auditwheel

出於可移植性的原因，Linux 上的本機 Python 模組只能動態連結一組非常少的函式庫，這些函式庫基本上安裝在任何地方，因此被稱為「manylinux」。 pypa 提供特殊的 docker 映像和一個名為auditwheel 的工具，以確保遵守manylinux 規則。如果你想為 linux pypi 發布廣泛可用的wheel，你需要使用 Manylinux docker 映像。

從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 的重新實現，自動檢查生成的庫並為wheel 提供正確的平台標籤。如果你的系統的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 以取得真實世界的設定。

當為 musl 目標編譯時，maturin 本身與 Manylinux 相容。