зрелый
v1.7.8
ранее pyo3-pack
Создавайте и публикуйте крейты с привязками pyo3, cffi и uniffi, а также двоичные файлы Rust в виде пакетов Python с минимальной настройкой. Он поддерживает создание колес для Python 3.8+ в Windows, Linux, Mac и FreeBSD, может загружать их в pypi и имеет базовую поддержку pypy и graalpy.
Ознакомьтесь с Руководством пользователя!
Вы можете либо загрузить двоичные файлы последней версии, либо установить их с помощью pipx:
pipx install maturinПримечание
pip install maturin также должен работать, если вы не хотите использовать pipx.
Существует четыре основные команды:
maturin new создает новый грузовой проект с настроенным maturin.maturin publish собирает крейт в пакеты Python и публикует их в pypi.maturin build собирает колеса и сохраняет их в папке (по умолчанию target/wheels ), но не загружает их. Возможна загрузка шпагатом или maturin upload .maturin develop собирает крейт и устанавливает его как модуль Python непосредственно в текущую виртуальную среду. Обратите внимание: хотя maturin develop выполняется быстрее, она не поддерживает все функции, которые поддерживает запуск pip install после maturin build . Привязки pyo3 обнаруживаются автоматически. Для cffi или двоичных файлов вам необходимо передать -b cffi или -b bin . maturin не нуждается в дополнительных файлах конфигурации и не конфликтует с существующей конфигурацией setuptools-rust или Milksnake. Вы даже можете интегрировать его с такими инструментами тестирования, как tox. В папке test-crates есть примеры различных привязок.
Именем пакета будет имя грузового проекта, т. е. поле имени в разделе [package] файла Cargo.toml . Имя модуля, который вы используете при импорте, будет значением name в разделе [lib] (которое по умолчанию соответствует имени пакета). Для двоичных файлов это просто имя двоичного файла, сгенерированного грузом.
При использовании команд maturin build и maturin develop вы можете скомпилировать программу, оптимизированную по производительности, добавив флаг -r или --release .
Пакеты Python выпускаются в двух форматах: встроенная форма, называемая «колесо», и дистрибутивы исходного кода (sdist), оба из которых являются архивами. Колесо может быть совместимо с любой версией Python, интерпретатором (в основном cpython и pypy), операционной системой и аппаратной архитектурой (для колес чистого Python), может быть ограничено конкретной платформой и архитектурой (например, при использовании ctypes или cffi) или конкретный интерпретатор Python и его версия для конкретной архитектуры и операционной системы (например, с pyo3).
При использовании pip install для пакета pip пытается найти подходящее колесо и установить его. Если он его не находит, он загружает исходный дистрибутив и создает колесо для текущей платформы, для чего необходимо установить правильные компиляторы. Установка колеса происходит намного быстрее, чем установка исходного дистрибутива, поскольку создание колес обычно занимает много времени.
Когда вы публикуете пакет, который можно будет установить с помощью pip install , вы загружаете его в pypi, официальный репозиторий пакетов. Для тестирования вместо этого вы можете использовать test pypi, который вы можете использовать с pip install --index-url https://test.pypi.org/simple/ . Обратите внимание, что для публикации в Linux вам необходимо использовать Docker-контейнер ManyLinux, а для публикации из вашего репозитория вы можете использовать действие GitHub PyO3/maturin-action.
Для pyo3 maturin может собирать пакеты только для установленных версий Python. В Linux и Mac используются все версии Python в PATH . Если вы не устанавливаете свои собственные интерпретаторы с помощью -i , для поиска установок Python используется эвристика. В Windows используются все версии из программы запуска Python (которая по умолчанию устанавливается установщиком python.org) и все среды conda, кроме базовой. Вы можете проверить, какие версии выбраны, с помощью подкоманды list-python .
pyo3 установит используемый интерпретатор Python в переменную среды PYTHON_SYS_EXECUTABLE , которую можно использовать из пользовательских сценариев сборки. Мэтьюрин может создавать и загружать колеса для pypy с помощью pyo3, хотя тестируется только pypy3.7-7.3 в Linux.
Колеса Cffi совместимы со всеми версиями Python, включая pypy. Если cffi не установлен и Python работает внутри виртуальной среды, maturin установит его, в противном случае вам придется установить его самостоятельно ( pip install cffi ).
maturin использует cbindgen для создания файла заголовка, который можно настроить, настроив cbindgen через файл cbindgen.toml внутри корня вашего проекта. В качестве альтернативы вы можете использовать сценарий сборки, который записывает файл заголовка в $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 для генерации привязок ctypes Python из файла определения интерфейса. Колеса uniffi совместимы со всеми версиями Python, включая pypy.
Чтобы создать смешанный проект Rust/Python, создайте папку с именем вашего модуля (т. е. lib.name в Cargo.toml) рядом с вашим Cargo.toml и добавьте туда исходники Python:
my-project
├── Cargo.toml
├── my_project
│ ├── __init__.py
│ └── bar.py
├── pyproject.toml
├── README.md
└── src
└── lib.rs
Вы можете указать другой исходный каталог Python в pyproject.toml , установив, например, tool.maturin.python-source
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 .
Пример макета с pyo3 после 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
При этом также обязательно установите имя модуля в своем коде так, чтобы оно соответствовало последней части module-name (не включайте путь к пакету):
# [ pymodule ] # [ pyo3 ( name= "_lib_name" ) ] fn my_lib_name ( _py : Python < ' _ > , m : & PyModule ) -> PyResult < ( ) > { m . add_class :: < MyPythonRustClass > ( ) ? ; Ok ( ( ) ) }
maturin поддерживает PEP 621, вы можете указать метаданные пакета Python в pyproject.toml . maturin объединяет метаданные из Cargo.toml и pyproject.toml , pyproject.toml имеет приоритет над Cargo.toml .
Чтобы указать зависимости Python, добавьте список dependencies в раздел [project] в pyproject.toml . Этот список эквивалентен install_requires в setuptools:
[ 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 " Вы также можете указать классификаторы Trove в своем pyproject.toml в разделе project.classifiers :
[ project ]
name = " my-project "
classifiers = [ " Programming Language :: Python " ] maturin поддерживает сборку через pyproject.toml . Чтобы использовать его, создайте pyproject.toml рядом с вашим Cargo.toml со следующим содержимым:
[ build-system ]
requires = [ " maturin>=1.0,<2.0 " ]
build-backend = " maturin " Если присутствует pyproject.toml с записью [build-system] , maturin может собрать исходный дистрибутив вашего пакета, если указан --sdist . Дистрибутив с исходным кодом будет содержать те же файлы, что и cargo package . Чтобы собрать только исходный дистрибутив, передайте --interpreter без каких-либо значений.
Затем вы можете, например, установить свой пакет с помощью pip install . . С pip install . -v вы можете увидеть выход груза и матьюрина.
Вы можете использовать параметры compatibility , skip-auditwheel , bindings , strip и общие параметры сборки Cargo, такие как features в [tool.maturin] так же, как и при непосредственном запуске Maturin. Ключ bindings необходим для проектов cffi и bin, поскольку они не могут быть обнаружены автоматически. В настоящее время все сборки находятся в режиме выпуска (подробности см. в этой теме).
Для сборки не-manylinux с привязками cffi вы можете использовать следующее:
[ build-system ]
requires = [ " maturin>=1.0,<2.0 " ]
build-backend = " maturin "
[ tool . maturin ]
bindings = " cffi "
compatibility = " linux " Опция manylinux также принимается как псевдоним compatibility для обратной совместимости со старой версией Maturin.
Чтобы включить произвольные файлы в sdist для использования во время компиляции, укажите include как массив glob- path с format , установленным в sdist :
[ tool . maturin ]
include = [{ path = " path/**/* " , format = " sdist " }] Существует команда maturin sdist только для создания исходного дистрибутива в качестве обходного пути для pypa/pip#6041.
По соображениям переносимости собственные модули Python в Linux должны динамически связывать только набор очень немногих библиотек, которые установлены практически повсюду, отсюда и название Manylinux. pypa предлагает специальные образы докеров и инструмент под названием Auditwheel для обеспечения соблюдения многих правил Linux. Если вы хотите опубликовать широко используемые колеса для linux pypi, вам нужно использовать образ докера ManyLinux .
Компилятор Rust, начиная с версии 1.64, требует как минимум glibc 2.17, поэтому вам нужно использовать как минимум многоlinux2014. Для публикации мы рекомендуем использовать ту же версию ManyLinux, что и образ, с флагом ManyLinux, например, используйте --manylinux 2014 если вы собираете в quay.io/pypa/manylinux2014_x86_64 . Действие github PyO3/maturin-action уже позаботится об этом, если вы установите, например, manylinux: 2014 .
maturin содержит повторную реализацию Auditwheel, автоматически проверяет сгенерированную библиотеку и присваивает колесу соответствующий тег платформы. Если glibc вашей системы слишком новый или вы связываете другие общие библиотеки, он присвоит тег linux . Вы также можете вручную отключить эти проверки и напрямую использовать встроенную цель Linux с --manylinux off .
Для полного соответствия требованиям многих Linux вам необходимо скомпилировать его в док-контейнере CentOS. Образ pyo3/maturin основан на образе Manylinux2014 и передает аргументы в двоичный файл maturin . Вы можете использовать его следующим образом:
docker run --rm -v $(pwd):/io ghcr.io/pyo3/maturin build --release # or other maturin arguments
Обратите внимание, что этот образ очень простой и содержит только Python, Maturin и стабильную ржавчину. Если вам нужны дополнительные инструменты, вы можете запускать команды внутри контейнера ManyLinux. См. konstin/complex-manylinux-maturin-docker для небольшого образовательного примера или nanoporetech/fast-ctc-decode для реальной настройки.
Maturin сам по себе совместим со многими Linux при компиляции для цели musl.
Приглашаем всех внести свой вклад в развитие Maturin! Поддержать проект можно разными способами, например:
В наших заметках есть больше ресурсов, если вы хотите добровольно посвятить время учебе и ищете, с чего начать.
Если у вас нет времени внести свой вклад, но вы все же хотите поддержать будущий успех проекта, у некоторых из наших сопровождающих есть спонсорские страницы GitHub:
Лицензия:
по вашему выбору.
