Ruff

يتحول مشروع Python الصغير بسرعة إلى سلسلة أدوات منفصلة: أداة للأخطاء، وأخرى لترتيب الاستيرادات، وثالثة للتنسيق، ثم إعداد مختلف في المحرر وCI. عند اختلاف القواعد بين البيئات تحصل على فروق تنسيق مفاجئة وفشل متأخر في طلب الدمج. Ruff أداة مفتوحة المصدر للفحص الساكن والتنسيق، تجمع تشخيصات كثيرة وإصلاحات آلية ومنسق كود في CLI واحد يمكن تشغيله محليًا وفي المحرر وCI من الإعداد نفسه.

🧭 ما Ruff وكيف تعمل؟

Ruff مشروع من Astral مكتوب بلغة Rust، لكنه يفحص ويُنسّق كود Python. «الفحص الساكن» يعني قراءة الكود لاكتشاف أنماط وأخطاء محتملة دون تشغيل البرنامج. أمر ruff check يعرض التشخيصات مع رمز القاعدة والملف والسطر، بينما ruff format يعيد كتابة التنسيق. يمكن لـ ruff check --fix تطبيق الإصلاحات المصنفة آمنة، وتبقى الإصلاحات غير الآمنة خلف خيار صريح.

تقرأ الأداة إعدادها من pyproject.toml أو ruff.toml أو .ruff.toml. وبذلك يستطيع المطور والمحرر وpre-commit وGitHub Actions استخدام القواعد نفسها. Ruff لا يشغّل اختبارات مشروعك ولا ينفذ الكود بوصفه تطبيقًا؛ هو طبقة جودة تسبق الاختبار والمراجعة البشرية.

رسم توضيحي أصلي للمسار، وليس لقطة من واجهة Ruff.

🎯 كيف ستفيدك ومتى تكون مناسبة؟

تناسب Ruff مطور Python منفردًا أو فريقًا صغيرًا يريد قاعدة موحدة للأخطاء الشائعة والاستيرادات والتنسيق، دون تركيب عدد كبير من الإضافات. ابدأ بالقواعد الافتراضية، شغّل الفحص محليًا، ثم اجعل CI يرفض الفرق غير المنسق أو التشخيصات المتفق عليها. الفائدة العملية أن المشكلة تظهر قرب وقت الكتابة، وأن قرار الجودة يصبح ملف إعداد قابلًا للمراجعة في Git بدل إعداد شخصي مخفي.

لا تناسبك بوصفها بديلًا عن pytest أو فحص الأنواع أو مراجعة منطق العمل. وبعض قواعد Flake8 أو Black والسلوكيات الطرفية لها فروق موثقة؛ المشروع الذي يعتمد تخصيصات معقدة يحتاج تجربة ترحيل على فرع ومراجعة الفرق قبل حذف الأدوات القديمة.

🌟 الميزات والقدرات الرئيسية

1. فحص سريع برموز قواعد قابلة للشرح

يشغّل ruff check . الفحص على ملفات Python المكتشفة ويعرض تشخيصًا مثل F401 للاستيراد غير المستخدم. رمز القاعدة ليس مجرد رقم؛ يمكنك تشغيل ruff rule F401 لقراءة الشرح. الأمر الأساسي يقرأ ويبلغ ولا يعدّل ملفات المصدر افتراضيًا.

• أين تجدها: CLI أو تشخيصات المحرر عبر Ruff Language Server.
• كيف تستخدمها: شغّل الفحص على مجلد محدد، اقرأ الرمز والموضع، ثم افهم السبب قبل أي إصلاح.
• مثال توضيحي: ملف يستورد os ولا يستخدمه؛ يعرض Ruff موضع الاستيراد والقاعدة.
• القيد: التشخيص يطابق قاعدة برمجية، وليس فهمًا كاملًا لنية التطبيق. وقد تحتاج إلى تجاهل ضيق ومعلل عندما يكون النمط مقصودًا.

الرسم يوضح تدفق القراءة والتشخيص؛ لا يدّعي نتيجة اختبار فعلية.

2. منسق مدمج مع وضع فحص لا يكتب

ruff format ينسّق الملفات في مكانها، بينما ruff format --check لا يكتب ويعيد حالة فشل عندما توجد ملفات تحتاج تنسيقًا. هذا يجعل الأمر الثاني مناسبًا لـCI، ويمنع أن يعدّل خط التجميع كودك بصمت.

المنسق يستهدف توافقًا قريبًا جدًا من Black، لكنه ليس مطابقًا في كل الحالات. توثق Astral فروقًا معروفة، وتنصح بعدم تشغيل Ruff وBlack بالتناوب على المشروع نفسه. كما توجد قواعد lint قد تتعارض مع المنسق إذا فُعّلت؛ راجع قائمة التعارضات الرسمية.

رسم يفرق بين أمر يكتب وأمر تحقق فقط.

3. إصلاحات آمنة وحد صريح للإصلاحات غير الآمنة

يطبّق ruff check --fix الإصلاحات المصنفة آمنة للقواعد المفعلة. أما الإصلاح الذي قد يغير معنى الكود فيحتاج --unsafe-fixes أو إعدادًا صريحًا. يمكن كذلك تقييد القواعد القابلة للإصلاح عبر fixable وunfixable.

• البدء الآمن: شغّل ruff check أولًا، ثم ruff check --fix على فرع نظيف، وراجع git diff.
• متى تستخدم unsafe: فقط عندما تفهم كل قاعدة وتملك اختبارات تغطي التغيير.
• القيد: حتى التصنيف «آمن» لا يثبت صحة العمل في لغة ديناميكية؛ توصي الأسئلة الشائعة بالإبلاغ إذا كسر إصلاح آمن سلوكك.

الرسم يشرح بوابة القرار، ولا يجعل الإصلاح الآلي بديلًا عن الاختبارات.

4. إعداد هرمي للمستودعات الكبيرة

لكل ملف تستخدم Ruff أقرب ملف إعداد صالح في شجرة المجلدات. يمكن وضع أساس في جذر المستودع ثم قواعد مختلفة لخدمة أو مجلد اختبارات. تُحل مسارات الاستثناء نسبةً إلى ملف الإعداد، بينما تمرير --config مباشرة يغيّر بعض قواعد حل المسار إلى مجلد التشغيل الحالي.

الإعدادات المهمة للبداية هي target-version، وline-length، والقواعد المختارة، والاستثناءات. افتراضيًا تحترم Ruff ملفات .gitignore، لكن الملف الذي تمرره صراحة إلى CLI قد يُفحص رغم الاستثناء ما لم تستخدم force-exclude.

رسم مبسط لآلية الإعداد الأقرب كما توثقها Astral.

5. تشخيص وإصلاح وتنسيق داخل المحرر

يتضمن CLI الخادم ruff server المبني على LSP، وهو بروتوكول يربط أدوات اللغة بالمحرر. يوفر تشخيصات وإجراءات إصلاح وتنسيق، وتوجد إضافة رسمية لـVS Code وتعليمات لمحررات أخرى. التنقل والإكمال التلقائي ليسا هدف Ruff؛ توصي الوثائق باستخدام خادم ty بجانبه لهذه القدرات.

القيمة أن المحرر وCLI يقرآن إعداد المشروع نفسه. لكن إعداد الحفظ الآلي قد يغير الملفات لحظة الحفظ؛ فعّل الإصلاح أو ترتيب الاستيرادات على الحفظ بعد مراجعة الإعداد والفرق، لا لمجرد أن الخيار متاح.

رسم للعلاقة بين المحرر وLSP، وليس لقطة لواجهة محرر بعينه.

6. نفس القاعدة في pre-commit وGitHub Actions

توثق Ruff تكاملًا رسميًا مع ruff-pre-commit وإجراء astral-sh/ruff-action. ضع فحص lint قبل formatter عندما تستخدم --fix لأن الإصلاح قد ينتج تغييرًا يحتاج إعادة تنسيق. في CI استخدم ruff check وruff format --check كي تكون النتيجة قراءة وفشل/نجاح بدل كتابة.

ثبت نسخة Ruff في بيئاتك. يدعم الإعداد required-version لتفشل الأداة بوضوح عندما لا يطابق الإصدار المطلوب. وهذا مهم قبل 1.0 لأن سياسة الإصدار تسمح لبعض تغييرات القواعد المستقرة أو نمط التنسيق في إصدار فرعي.

رسم لمسار مشاركة الإعداد، وليس ضمانًا لنجاح مشروع محدد.

🪜 مثال عملي: إضافة Ruff إلى مشروع قائم

مثال توضيحي لم أنفذه على مستودع فعلي. الهدف إدخال الأداة دون تغيير جماعي غير مفهوم:

1. أنشئ فرعًا وتأكد أن اختبارات المشروع الحالية معروفة الحالة.
2. ثبّت Ruff بإصدار محدد في بيئة التطوير، ثم سجّل الإصدار في أدوات المشروع.
3. أضف الحد الأدنى التالي إلى pyproject.toml:

[tool.ruff]
target-version = "py311"
line-length = 88
required-version = "==0.17.3"

[tool.ruff.lint]
select = ["E", "F", "B", "UP", "RUF"]

1. شغّل ruff check . دون --fix. صنّف النتائج: أخطاء حقيقية، ديون قديمة، أو قواعد لا تناسب المشروع.
2. شغّل ruff format --check . لمعرفة حجم فرق التنسيق دون كتابة.
3. إذا كان الفرق كبيرًا، افصل commit التنسيق عن تغييرات السلوك. بعد ذلك جرّب ruff check --fix وراجع كل فرق.
4. شغّل اختبارات المشروع وفحص الأنواع إن وجد؛ Ruff لا يحل محلهما.
5. أضف أوامر القراءة إلى CI. لا تستخدم --unsafe-fixes داخل طلب الدمج تلقائيًا.

هذا المثال يفترض أن المشروع يستهدف Python 3.11؛ غيّر القيمة وفق عقد مشروعك. لم أتحقق من توافق قواعده مع قاعدة كود بعينها.

⚖️ ماذا تضيف مقارنة بالعمل اليدوي؟

الدمج لا يعني تكافؤًا كاملاً لكل إضافة أو مشروع. إذا كنت تعتمد plugin غير مدعوم أو نمط Black دقيقًا في حالات موثقة كفروق، اختبر الهجرة ولا تحذف الأداة القديمة قبل مقارنة النتائج.

⚙️ إعدادات تستحق المراجعة

• select وignore: اختر قواعد واضحة؛ لا تبدأ بـALL ثم تخفي مئات النتائج بلا فهم.
• per-file-ignores: استثناء ضيق لملفات مثل الاختبارات، أفضل من تعطيل قاعدة على المستودع كله عندما يكون السبب محليًا.
• target-version: يؤثر في فهم الصياغة والترقيات؛ اضبطه على أقل إصدار Python يدعمه المشروع.
• preview: معطل افتراضيًا ويشغل ميزات وقواعد وتغييرات نمط غير مستقرة؛ لا تفعله في CI بلا تثبيت ومراجعة.
• required-version: يمنع اختلاف النتائج عندما يشغّل عضو الفريق إصدارًا آخر.
• cache-dir: التخزين الافتراضي .ruff_cache في جذر المشروع؛ يمكن تغييره أو تعطيل الكاش بـ--no-cache.

تغيّر الإعداد الافتراضي في Ruff 0.17.0، بما فيه مجموعة قواعد افتراضية وإصدارات Python الافتراضية عند غياب إعداد صريح. لهذا لا تعتمد على defaults الصامتة في مشروع طويل العمر؛ اكتب القرارات المهمة وثبت الإصدار.

🚀 التثبيت والبدء

الطريقة المباشرة عبر PyPI:

pip install ruff
ruff --version
ruff check .
ruff format --check .

وتوثق Astral أيضًا uv tool install ruff@latest، وuv add --dev ruff، وpipx، وHomebrew، وConda، وDocker، ومثبتات مستقلة لويندوز وmacOS وLinux. تشغيل الملف التنفيذي الجاهز لا يتطلب بناء Rust.

الإصدار المستقر الذي تحققنا منه هو 0.17.3؛ تحمل ملاحظاته تاريخ 26 أكتوبر 2026، ونشره GitHub في 27 أكتوبر. أظهر PyPI حزمًا لمنصات متعددة. لم أنفذ أمر التثبيت أو أفحص كل منصة فعليًا.

🔗 التكاملات والتوافق

يدعم المشروع Python حتى 3.15 بحسب README الحالي، ويفحص ملفات .py و.pyi ودفاتر Jupyter افتراضيًا في الإصدارات الحديثة، إضافة إلى مواضع Python المضمنة المدعومة في Markdown وpyproject.toml. توجد إضافة VS Code رسمية، وLSP لمحررات أخرى، وpre-commit وGitHub Action وصورة Docker.

التوافق لا يعني أن كل قاعدة مناسبة لكل إطار. بعض القواعد مستوحاة من إضافات Flake8 أو أدوات أخرى لكنها معاد تنفيذها داخل Ruff، وليست تشغيلًا مباشرًا لتلك الإضافات. وإذا انتقلت من ruff-lsp القديم إلى ruff server فراجع دليل الإعداد؛ تغيرت بعض الخيارات.

💰 التكلفة والتشغيل المحلي والخصوصية

Ruff بترخيص MIT، ولا تحتاج CLI إلى حساب Ruff أو اشتراك أو API مدفوع لفحص الملفات محليًا. تقرأ الأداة الملفات المحددة وإعداد المشروع وتكتب كاشًا محليًا في .ruff_cache. لا تعدّل ملفات المصدر بأمر check وحده؛ الكتابة تحصل مع --fix أو format أو إجراء محرر مكافئ.

التشغيل المحلي لا يعني أن كل المسار بلا شبكة: التثبيت ينزّل حزمة، وGitHub Action أو pre-commit قد ينزلان أداة أو صورة، ورفع الكود إلى مستودع بعيد يخضع لخدمتك. لم أجد في صفحات التشغيل التي راجعتها توثيقًا لقياس عن بعد داخل CLI، لكني لم أنفذ التقاط شبكة أو تدقيقًا مستقلًا، لذلك لا أزعم انعدام كل اتصال في كل تكامل.

🔐 الأمان والصلاحيات

عامل إعداد Ruff وإجراءات CI ككود مشروع. يستطيع شخص يغير pyproject.toml توسيع الملفات المفحوصة أو تشغيل إصلاحات مختلفة عبر سكربتات CI. ثبّت الإصدار أو المرجع، راجع تغييرات الإعداد، واجعل صلاحيات GitHub Action في الحد الأدنى الذي يحتاجه الفحص.

ruff check يحتاج قراءة كود المشروع وكتابة الكاش. --fix وruff format يكتبان الملفات؛ راجعهما في Git وشغّل الاختبارات. لا ترسل أسرارًا إلى المخرجات أو التعليقات، فالتشخيص ومسار الملف قد يظهران في سجل CI. يوجّه المشروع بلاغات الثغرات إلى بريد أمن Astral، ولم تعرض صفحة GitHub Security إرشادات منشورة وقت الفحص؛ هذا لا يساوي ضمان عدم وجود ثغرات.

رسم توضيحي لحدود الصلاحيات، وليس تدقيقًا أمنيًا.

⚠️ الحدود ومتى لا تستخدمها

• Ruff لا يشغّل اختباراتك ولا يفهم صحة منطق العمل مثل مراجعة بشرية.
• هو ليس مدقق أنواع كاملًا؛ استخدم أداة مناسبة عندما تحتاج تحقق الأنواع.
• التوافق مع Black قريب جدًا وليس مطابقًا؛ لا تشغّل المنسقين بالتناوب.
• الإصلاحات غير الآمنة قد تغير السلوك، وحتى الإصلاحات الآمنة تحتاج اختبارات.
• قواعد preview ونمطها قابلة للتغير، والإصدارات قبل 1.0 تحتاج تثبيتًا واعيًا.
• أقرب إعداد أو إعداد مستخدم قد يجعل النتيجة مختلفة بين مجلدات أو أجهزة إذا لم تثبت المسار.
• الملفات التي تمررها صراحة قد تتجاوز استثناءات gitignore ما لم تضبط force-exclude.
• دمج أدوات متعددة في Ruff يقلل عددها، لكنه لا يثبت أنه يغطي كل plugin قديم تعتمد عليه.

🔎 لماذا اخترناه اليوم؟

قورنت Ruff من مجال جودة Python مع Worktrunk من مجال Git وإدارة worktrees. Worktrunk مشروع نشط ومفيد لإدارة فروع وكلاء متوازيين، وظهر في GitHub Trending يوم الفحص، لكنه قريب من سير عمل وكلاء البرمجة الذي غطته بطاقة Cline أمس. Ruff يخدم مرحلة مختلفة: فحص الكود وتنسيقه محليًا وفي CI، وله توثيق أوسع ونضج أكبر لفرد أو فريق صغير. وجود uv من الناشر نفسه في الدليل قديم وليس ضمن آخر سبع بطاقات، لذلك لا يوجد تتابع يومي للمنظومة.

وقت الفحص عرض GitHub نحو 50.4 ألف نجمة و2.6 ألف تفرع، وآخر نشاط ظاهر على الفرع الرئيسي في 5 نوفمبر 2026 عند 00:03:38 UTC. هذه مؤشرات انتشار متغيرة وليست تقييم جودة.

📚 المصادر وتاريخ التحقق

تم التحقق في 5 نوفمبر 2026 من:

• المستودع الأصلي والترخيص وREADME
• الإصدار 0.17.3
• التثبيت الرسمي
• الإعدادات واكتشاف الملفات
• الفاحص والإصلاحات الآمنة وغير الآمنة
• المنسق وفروق Black
• تكامل المحررات
• التكاملات مع pre-commit وGitHub Actions
• سياسة الإصدارات
• صفحة الأمان
• صفحة Worktrunk الرسمية للمقارنة

استُخدمت GitHub Trending/Topics وclaudeskills.info وdshmarket.com للاكتشاف فقط. لم أثبت Ruff، أو أشغّل المثال، أو أختبر الأداء، أو أدقق الشبكة والأمان؛ لذلك لم أنقل ادعاءات السرعة التسويقية إلى نتيجة قياس خاصة.