ما الذي تفعله هذه الأداة
يعيد منسّق Python كتابة شيفرة Python بأسلوب Black واسع الانتشار: مسافات بادئة متسقة، ومسافات حول العوامل، وعلامات اقتباس مزدوجة، وسطران فارغان بين التعريفات في المستوى الأعلى، ولفّ الأسطر الطويلة في مواضع معقولة.
يعمل في الخلفية منسّق Ruff، أداة الفحص والتنسيق السريعة لـ Python المكتوبة بـ Rust، مُصرَّفًا إلى WebAssembly. تطابق مخرجات Ruff مخرجات Black سطرًا بسطر تقريبًا، لذا لن يعيد خطاف pre-commit في مشروعك تنسيق الشيفرة التي نسّقتها هنا.
طريقة الاستخدام
- الصق شيفرة Python، أو افتح ملف
.py. - تظهر الشيفرة المنسّقة على اليسار أثناء الكتابة.
- اضبط الخيارات إذا كان مشروعك يستخدم أسلوبًا مختلفًا:
- المسافة البادئة: 4 مسافات هي معيار PEP 8 والقيمة الافتراضية؛ وتتوفر مسافتان وعلامات Tab.
- عرض السطر: 88 هي قيمة Black الافتراضية، و79 هي حد PEP 8، و100 أو 120 تناسب الشاشات الأعرض.
- علامات الاقتباس: مزدوجة أو مفردة أو إبقاء علامات الاقتباس التي يستخدمها كل نص.
- احترام الفواصل اللاحقة: إبقاء المجموعات المنتهية بفاصلة موسّعة.
- انسخ النتيجة أو نزّلها.
عندما يتعذّر تحليل الشيفرة، تُظهر رسالة الخطأ الموضع الذي توقف عنده المحلّل، مثل Expected `,`, found `=` في السطر 4، ويمكنك الانتقال إلى ذلك السطر.
مثال
المثال وحدة صغيرة مكتوبة بإهمال: عبارات استيراد في سطر واحد دون مسافات، وdataclass بمسافة قبل النقطتين، ودالة بمسافة بادئة من مسافتين، وعبارة if في سطر واحد. بعد التنسيق تستخدم كل كتلة مسافة بادئة من أربع مسافات، وينتقل جسم if إلى سطر مستقل، وتحصل العوامل على مسافات، وتصبح علامات الاقتباس المفردة مزدوجة، وتُضاف أسطر فارغة بين الصنف والدوال. أما القائمة المنتهية بفاصلة لاحقة فتُوسَّع بقاموس واحد في كل سطر.
ما الذي لا يفعله المنسّق
لا يغيّر التنسيق إلا التخطيط. فهو لا يرتّب عبارات الاستيراد، ولا يزيل المتغيرات غير المستخدمة، ولا يعيد تسمية أي شيء؛ فهذه مهام أداة الفحص (ruff check --fix تتولاها). تُحفظ التعليقات وسلاسل التوثيق (docstrings)، ويرفض المنسّق تغيير شيفرة لا يستطيع تحليلها بدلًا من التخمين.
نصائح
- استخدم عرض السطر نفسه المضبوط في
pyproject.tomlالخاص بمشروعك كي تطابق النتيجة ما يفعله CI. - تنسيق مقتطف قبل نشره في سؤال أو مراجعة يجعله أسهل قراءة بكثير.
- إذا جاءت الشيفرة من دفتر (notebook) أو دردشة وفيها خليط من علامات Tab والمسافات، فإن المنسّق يوحّدها بخطوة واحدة.
الأسئلة الشائعة
› هل المخرجات مطابقة لـ Black؟
صُمّم منسّق Ruff ليكون بديلًا مباشرًا لـ Black، ويطابق مخرجاته في أكثر من 99.9% من الأسطر في مشاريع حقيقية كبيرة. والإعدادات الافتراضية هنا (مسافة بادئة من 4 مسافات، و88 عمودًا، وعلامات اقتباس مزدوجة) هي إعدادات Black الافتراضية.
› ما «الفاصلة اللاحقة السحرية» (magic trailing comma)؟
إذا انتهت قائمة أو استدعاء أو تعريف بفاصلة لاحقة، يُبقيها Black وRuff موسّعة بعنصر واحد في كل سطر حتى لو كانت تتسع في سطر واحد. أوقف هذا المفتاح لطيّ هذه المجموعات كلما اتسع لها سطر واحد.
› ما إصدارات Python المدعومة؟
يفهم المحلّل صياغة Python 3 الحديثة، بما فيها عبارات match وقوائم معاملات الأنواع وf-strings ذات علامات الاقتباس المتداخلة. أما شيفرة Python 2 مثل `print "x"` فتُعد خطأً صياغيًا.
› هل تُرفع شيفرتي؟
لا. تُنزَّل وحدة Ruff بصيغة WebAssembly مرة واحدة، ويجري التنسيق في متصفحك.