# منسق Python

URL: https://discuvr.org/python-formatter/?hl=ar
Last updated: 2026-11-07
MCP tool: `format_python`

الصق كود Python ليُنسّقه Black بطول السطر والخيارات التي تختارها. أخطاء الصياغة تُظهر السطر الدقيق. لا يُشغَّل كودك ولا يُخزَّن أبدًا.

يُشغّل هذا Black - المنسّق الذي توافقت عليه معظم مشاريع Python بالفعل - على ما تلصقه، بطول السطر ومعالجة علامات الاقتباس التي تختارها. إذا تعذّر تحليل الملف فإنه يذكر في أي سطر، وإذا كان منسّقًا بالفعل فإنه يقول ذلك أيضًا، بدلًا من التظاهر بأنه فعل شيئًا.

## ما الذي تفعله الأداة

- تنسيق Black عند 79 أو 88 أو 100 أو 120 عمودًا.
- وضع "التحقق فقط": اعرف ما إذا كان الملف سيتغيّر دون تغييره.
- احتفظ بأسلوب علامات الاقتباس الخاص بك، أو اترك Black يوحّده.
- اتبع أو تجاهل الفاصلة السحرية الأخيرة التي تحافظ على مجموعة مفتوحة غير مطوية.
- استهدف إصدار Python محددًا عندما تكون الصياغة حساسة للإصدار.
- تُبيّن أخطاء الصياغة السطر والعمود والكود المحيط.
- يُبلّغ عن عدد الأسطر المضافة والمحذوفة، بالإضافة إلى شكل الملف.

## كيف يعمل

1. الصق الكود، أو ملفًا كاملًا منه.
2. اختر طول السطر وأي خيارات تهمّك.
3. اضغط تنسيق، ثم انسخ أو نزّل النتيجة.

## كودك لا يُشغَّل مطلقًا

تنسيق Python لا يتطلّب تشغيله. يُحلَّل الكود إلى شجرة صياغة ويُعاد كتابته من تلك الشجرة، بالكامل في الذاكرة - لا يُكتب أبدًا إلى ملف، ولا يُستورد أبدًا، ولا يُشغَّل أبدًا. أي منسّق يُشغّل ما لصقته سيكون واجهة أوامر بعيدة بصندوق نص.

## لماذا Black، وليس رأيًا خاصًا بنا

Black هو تحويل يحافظ على شجرة الصياغة المجردة (AST): الكود الخارج هو نفس البرنامج الذي دخل. هذه الخاصية هي السبب الكامل في إمكانية الوثوق بمنسّق، وهي السبب في عدم تدخّل أي نموذج لغوي في أي جزء من هذه الأداة. نموذج يُطلب منه ترتيب الكود سيعيد كتابة سطر أحيانًا بينما يقوم بذلك، والتغيير الصامت لكود يعمل هو الفشل الوحيد الذي لا يمكن لمنسّق أن يتحمّله.

## التحقق فقط

نفس السؤال الذي يطرحه CI: هل سيتغيّر هذا الملف؟ وضع التحقق يُعيد كودك الأصلي دون تغيير ويُبيّن ما إذا كان Black سيُعيد تنسيقه، وبكم عدد من الأسطر. إنها الطريقة السريعة لمعرفة لماذا يفشل خط أنابيب على ملف لا يمكنك إعادة إنتاجه محليًا.

## الفاصلة الختامية السحرية و fmt: off، أمثلة محلولة

الفاصلة بعد العنصر الأخير تطلب من Black إبقاء الاستدعاء أو المجموعة عنصرًا واحدًا في كل سطر: result = compute(alpha, beta,) تعود في أربعة أسطر، وكل من alpha, و beta, في سطر مستقل. فعّل خيار تجاهل الفاصلة الختامية السحرية فيصبح الإدخال نفسه result = compute(alpha, beta) متى اتسع له طول السطر. لحماية كتلة محاذاة يدويًا مثل مصفوفة، ضع # fmt: off في السطر الذي فوقها و # fmt: on تحتها، فيترك Black كل ما بينهما كما كتبته؛ و # fmt: skip في نهاية سطر يحمي ذلك السطر وحده. هذه تعليقات Black نفسه، لذا تبقى سارية عندما يشغّل CI مشروعك Black.

## الأسئلة

**هل يُرفع كودي أو يُخزَّن؟**

يُرسل إلى الخادم، يُنسَّق في الذاكرة ويُعاد في نفس الاستجابة. لا يُكتب شيء إلى القرص ولا يُخزَّن مؤقتًا ولا يُسجَّل، وسجلّ الاستخدام يحتفظ بالعدادات فقط - الحجم، الخيارات، عدد الأسطر التي تغيّرت - ولا يحتفظ بالكود أبدًا.

**هل يغيّر التنسيق ما يفعله كودي؟**

لا. يغيّر Black التنسيق لا السلوك، لكنه يفعل أكثر من تحريك المسافات. فهو يزيل الأقواس الزائدة (x = (1) تصبح x = 1)، ويحوّل بادئات الأعداد وأسسها إلى أحرف صغيرة (0XABCDEF تصبح 0xABCDEF، و 1E5 تصبح 1e5)، ويضيف فاصلة ختامية عندما يقسم استدعاءً على عدة أسطر، ويقلّص تتابع الأسطر الفارغة، ويزيل المسافات داخل docstring (""" Doc. """ تصبح """Doc."""). هذا التغيير الأخير يغيّر نص __doc__، وهو أمر لا يهم إلا إذا كان كودك يقرأ docstrings الخاصة به.

**لماذا لم يُعِد تنسيق ملفي على الإطلاق؟**

لأنه كان منسّقًا بالفعل بطول السطر الذي اخترته. تقول الأداة "منسّق بالفعل" بدلًا من إعادة نسخة بصمت.

**هل يُرتّب عمليات الاستيراد لديّ؟**

لا. ترتيب عمليات الاستيراد هو عمل isort، لا Black، والاثنان يختلفان بما يكفي من التكرار ليُفاجئك لو حدث ذلك هنا.

**هل يمكنه تنسيق ملف فيه خطأ في الصياغة؟**

لا يمكن لأي منسّق ذلك - الملف الذي لا يمكن تحليله لا يملك بنية يُعاد كتابتها. تحصل على السطر والعمود والكود المحيط لتتمكن من تصحيحه والمحاولة مجددًا.

**هل يتبع PEP 8؟**

Black متوافق مع PEP 8 مع انحراف معروف واحد: طول سطره الافتراضي هو 88 بدلًا من 79. اختر 79 في محدّد طول السطر إذا احتجت الرقم الأكثر صرامة.

**ما أكبر حجم ملف يمكنني تنسيقه؟**

حتى 400,000 حرف في كل تشغيل. يتوقف التنسيق بعد 10 ثوانٍ، ولا تبلغ ذلك إلا الملفات الكبيرة جدًا أو شديدة التكرار، ويمكن لكل عنوان IP إجراء 30 عملية تنسيق كل 10 دقائق.

**كيف أحصل على التنسيق نفسه في محرري أو في pre-commit أو في CI؟**

تستخدم هذه الصفحة Black، ويظهر إصداره في ترويسة الصفحة على الشاشات العريضة. يقرأ Black إعدادات المشروع من pyproject.toml في القسم [tool.black] بالأسماء الطويلة للخيارات: line-length = 88 لخيار "طول السطر" الذي اخترته، و skip-string-normalization = true إذا فعّلت "الاحتفاظ بعلامات التنصيص الخاصة بي"، و skip-magic-trailing-comma = true لخيار "تجاهل الفاصلة الختامية السحرية"، و target-version = ["py311"] لقيمة ثابتة في "الهدف". تقرأ إضافات المحررات وخطاف pre-commit الملف نفسه. شغّل black . للتنسيق و black --check --diff . في CI: لا يغيّر شيئًا وينتهي برمز الخروج 1 إذا كان ملف سيُعاد تنسيقه. ثبّت إصدار Black نفسه المستخدم في هذه الصفحة، لأن أول إصدار في كل سنة ميلادية قد يغيّر النمط المستقر.

**هل النتيجة مطابقة لمنسّق Ruff (ruff format)؟**

في الغالب نعم، لكن ليس بايتًا ببايت. صُمّم منسّق Ruff ليكون بديلًا مباشرًا لـ Black، وتذكر وثائق Ruff أنه في المشاريع الكبيرة المنسّقة بـ Black مثل Django و Zulip تخرج أكثر من 99.9% من الأسطر متطابقة. يختلف أكثر في الشيفرة التي لم تمر عبر Black قط، خصوصًا في التعليقات في نهاية السطر، وتسرد وثائقه الفروق المقصودة. طول السطر الافتراضي لديه 88 أيضًا، ويُضبط بـ line-length تحت [tool.ruff]؛ ويقابل quote-style = "preserve" تحت [tool.ruff.format] خيار "الاحتفاظ بعلامات التنصيص الخاصة بي"، ويقابل skip-magic-trailing-comma = true خيار "تجاهل الفاصلة الختامية السحرية". إذا كان CI لديك يشغّل ruff format --check فاختبر الملف بـ Ruff لا بهذه الصفحة.

## المزيد في أدوات المطورين

- [عارض HTML](https://discuvr.org/html-viewer/?hl=ar)
- [حاسبة الشبكة الفرعية لـ IP](https://discuvr.org/ip-subnet-calculator/?hl=ar)
- [ترميز / فك الترميز](https://discuvr.org/encode-decode/?hl=ar)
- [محوّل طابع Unix الزمني](https://discuvr.org/timestamp-converter/?hl=ar)

## يُستخدم غالبًا مع

- [مقارنة النصوص](https://discuvr.org/text-diff/?hl=ar)
- [محوّل حالة الأحرف وأدوات الأسطر](https://discuvr.org/case-converter/?hl=ar)
- [Study Buddy](https://discuvr.org/study-buddy/?hl=ar)

---

Part of Discuvr (https://discuvr.org/): Discuvr is a collection of free, focused tools for day-to-day professional work - office and data utilities, legal and compliance helpers, privacy and security checks, and developer formatters. Every tool has its own page, and most can also be called from ChatGPT or Claude over MCP.