ناضجة
v1.7.8
Pyo3-pack سابقًا
قم ببناء الصناديق ونشرها باستخدام روابط pyo3 وcffi وuniffi بالإضافة إلى ثنائيات الصدأ كحزم python بأقل قدر من التكوين. وهو يدعم بناء عجلات لـ python 3.8+ على أنظمة التشغيل Windows وLinux وMac وFreeBSD، ويمكن تحميلها على pypi ويتمتع بدعم أساسي من pypy وgraalpy.
تحقق من دليل المستخدم!
يمكنك إما تنزيل الثنائيات من الإصدار الأحدث أو تثبيتها باستخدام pipx:
pipx install maturinملحوظة
يجب أن يعمل pip install maturin أيضًا إذا كنت لا ترغب في استخدام pipx.
هناك أربعة أوامر رئيسية:
maturin new بإنشاء مشروع شحن جديد مع تكوين Maturin.maturin publish الصندوق في حزم بايثون وينشرها على pypi.maturin build ببناء العجلات وتخزينها في مجلد ( target/wheels افتراضيًا)، لكنه لا يقوم بتحميلها. من الممكن تحميل تلك التي تحتوي على خيوط أو maturin upload .maturin develop ببناء الصندوق وتثبيته كوحدة نمطية بيثون مباشرة في Virtualenv الحالي. لاحظ أنه على الرغم من أن 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 .
تأتي حزم بايثون في شكلين: نموذج مدمج يسمى توزيعات العجلة والمصدر (sdist)، وكلاهما عبارة عن أرشيفات. يمكن أن تكون العجلة متوافقة مع أي إصدار من إصدارات بايثون، ويمكن أن يقتصر المترجم الفوري (cpython وpypy بشكل رئيسي)، ونظام التشغيل وهندسة الأجهزة (لعجلات بايثون الخالصة)، على نظام أساسي وبنية معينة (على سبيل المثال عند استخدام ctypes أو cffi) أو مترجم وإصدار محدد لبايثون على بنية محددة ونظام تشغيل (على سبيل المثال مع pyo3).
عند استخدام pip install على حزمة، يحاول pip العثور على عجلة مطابقة وتثبيتها. إذا لم يعثر على واحد، فإنه يقوم بتنزيل التوزيعة المصدرية ويبني عجلة للنظام الأساسي الحالي، الأمر الذي يتطلب تثبيت المترجمين المناسبين. يعد تركيب العجلة أسرع بكثير من تركيب توزيع المصدر حيث أن بناء العجلات يكون بطيئًا بشكل عام.
عندما تنشر حزمة لتكون قابلة للتثبيت باستخدام pip install ، فإنك تقوم بتحميلها إلى pypi، مستودع الحزم الرسمي. للاختبار، يمكنك استخدام اختبار pypi بدلاً من ذلك، والذي يمكنك استخدامه مع pip install --index-url https://test.pypi.org/simple/ . لاحظ أنه للنشر لنظام التشغيل Linux، تحتاج إلى استخدام حاوية Manylinux docker، بينما للنشر من المستودع الخاص بك، يمكنك استخدام إجراء github PyO3/maturin-action.
بالنسبة لـ pyo3، يمكن لـ Maturin إنشاء حزم لإصدارات python المثبتة فقط. في نظامي التشغيل Linux وMac، يتم استخدام جميع إصدارات python في PATH . إذا لم تقم بتعيين المترجمين الفوريين الخاصين بك باستخدام -i ، فسيتم استخدام الاستدلال للبحث عن تثبيتات بايثون. في نظام التشغيل Windows، يتم استخدام جميع الإصدارات من مشغل python (الذي يتم تثبيته افتراضيًا بواسطة مثبت python.org) وجميع بيئات conda باستثناء القاعدة. يمكنك التحقق من الإصدارات التي تم التقاطها باستخدام الأمر الفرعي list-python .
سيقوم pyo3 بتعيين مترجم python المستخدم في متغير البيئة PYTHON_SYS_EXECUTABLE ، والذي يمكن استخدامه من البرامج النصية المخصصة للبناء. يمكن لـ Maturin إنشاء وتحميل عجلات لـ pypy باستخدام pyo3، على الرغم من أنه تم اختبار pypy3.7-7.3 فقط على Linux.
عجلات Cffi متوافقة مع جميع إصدارات Python بما في ذلك pypy. إذا لم يتم تثبيت cffi وكان بايثون يعمل داخل Virtualenv، فسيقوم Maturin بتثبيته، وإلا فسيتعين عليك تثبيته بنفسك ( pip install cffi ).
يستخدم Maturin cbindgen لإنشاء ملف رأس، والذي يمكن تخصيصه عن طريق تكوين cbindgen من خلال ملف cbindgen.toml داخل جذر مشروعك. وبدلاً من ذلك، يمكنك استخدام برنامج نصي للإنشاء يكتب ملف رأس إلى $PROJECT_ROOT/target/header.h .
استنادًا إلى ملف الرأس، يقوم ماتورين بإنشاء وحدة تقوم بتصدير كائن 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، قم بإنشاء مجلد باسم الوحدة الخاصة بك (على سبيل المثال lib.name في Cargo.toml) بجوار Cargo.toml الخاص بك وأضف مصادر python الخاصة بك هناك:
my-project
├── Cargo.toml
├── my_project
│ ├── __init__.py
│ └── bar.py
├── pyproject.toml
├── README.md
└── src
└── lib.rs
يمكنك تحديد دليل مصدر مختلف لبايثون في 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 .
لتحديد تبعيات بايثون، أضف قائمة dependencies في قسم [project] في pyproject.toml . هذه القائمة تعادل 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 :
[ 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 كمصفوفة من كرات path مع ضبط format على sdist :
[ tool . maturin ]
include = [{ path = " path/**/* " , format = " sdist " }] يوجد أمر maturin sdist لإنشاء توزيع مصدر فقط كحل بديل لـ pypa/pip#6041.
لأسباب تتعلق بقابلية النقل، يجب على وحدات بايثون الأصلية على نظام التشغيل Linux أن تربط ديناميكيًا فقط مجموعة قليلة جدًا من المكتبات التي يتم تثبيتها بشكل أساسي في كل مكان، ومن هنا جاء اسم Manylinux. يقدم pypa صورًا خاصة لوحدة الإرساء وأداة تسمى Auditwheel لضمان الامتثال لقواعد العديد من Linux. إذا كنت ترغب في نشر عجلات قابلة للاستخدام على نطاق واسع لنظام التشغيل Linux pypi، فأنت بحاجة إلى استخدام صورة عديدة من عامل إرساء Linux .
يتطلب مترجم Rust منذ الإصدار 1.64 glibc 2.17 على الأقل، لذلك تحتاج إلى استخدام العديد من Linux2014 على الأقل. للنشر، نوصي بفرض نفس إصدار Manylinux مثل الصورة التي تحمل علامة Manylinux، على سبيل المثال، استخدم --manylinux 2014 إذا كنت تقوم بالإنشاء في quay.io/pypa/manylinux2014_x86_64 . يعتني إجراء github PyO3/maturin-action بالفعل بهذا إذا قمت بتعيين، على سبيل المثال، manylinux: 2014 .
يحتوي Maturin على إعادة تنفيذ لعجلة التدقيق التي تقوم تلقائيًا بفحص المكتبة التي تم إنشاؤها وتعطي العجلة علامة النظام الأساسي المناسبة. إذا كان glibc الخاص بنظامك جديدًا جدًا أو قمت بربط مكتبات مشتركة أخرى، فسيتم تعيين علامة linux . يمكنك أيضًا تعطيل عمليات التحقق هذه يدويًا واستخدام هدف Linux الأصلي مباشرة مع --manylinux off .
للحصول على الامتثال الكامل لنظام Manylinux، تحتاج إلى التجميع في حاوية CentOS docker. تعتمد صورة pyo3/maturin على صورة Manylinux2014، وتمرر الوسائط إلى ثنائي maturin . يمكنك استخدامه مثل هذا:
docker run --rm -v $(pwd):/io ghcr.io/pyo3/maturin build --release # or other maturin arguments
لاحظ أن هذه الصورة أساسية جدًا وتحتوي فقط على الثعبان والماتورين والصدأ المستقر. إذا كنت بحاجة إلى أدوات إضافية، يمكنك تشغيل الأوامر داخل حاوية Manylinux. راجع konstin/complex-manylinux-maturin-docker للحصول على مثال تعليمي صغير أو nanoporetech/fast-ctc-decode لإعداد العالم الحقيقي.
Maturin نفسه متوافق مع Manylinux عند تجميعه لهدف MUSL.
الجميع مرحب بهم للمساهمة في ماتورين! هناك طرق عديدة لدعم المشروع مثل:
تحتوي ملاحظاتنا المساهمة على المزيد من الموارد إذا كنت ترغب في التطوع بوقت لماتورين وتبحث من أين تبدأ.
إذا لم يكن لديك الوقت للمساهمة بنفسك ولكنك لا تزال ترغب في دعم نجاح المشروع في المستقبل، فإن بعض المشرفين لدينا لديهم صفحات رعاية GitHub:
مرخصة بموجب أي من:
في خيارك.
