black
24.10.0
"أي لون تريد."
الأسود هو منسق كود بايثون الذي لا هوادة فيه. باستخدامه، فإنك توافق على التنازل عن السيطرة على التفاصيل الدقيقة للتنسيق اليدوي. في المقابل، يمنحك اللون الأسود السرعة والحتمية والتحرر من pycodestyle بشأن التنسيق. ستوفر الوقت والطاقة العقلية لأمور أكثر أهمية.
يبدو الرمز الأسود كما هو بغض النظر عن المشروع الذي تقرأه. يصبح التنسيق شفافًا بعد فترة ويمكنك التركيز على المحتوى بدلاً من ذلك.
يجعل اللون الأسود مراجعة التعليمات البرمجية أسرع من خلال إنتاج أصغر الفروق الممكنة.
جربه الآن باستخدام Black Playground. شاهد حديث PyCon 2019 لمعرفة المزيد.
اقرأ الوثائق على ReadTheDocs!
يمكن تثبيت الأسود عن طريق تشغيل pip install black . يتطلب تشغيله إصدار Python 3.9+. إذا كنت تريد تنسيق Jupyter Notebooks، فقم بالتثبيت باستخدام pip install "black[jupyter]" .
إذا كنت لا تستطيع انتظار أحدث التحديثات وتريد التثبيت من GitHub، فاستخدم:
pip install git+https://github.com/psf/black
للبدء على الفور باستخدام الإعدادات الافتراضية المعقولة:
black {source_file_or_directory}يمكنك تشغيل Black كحزمة إذا لم يعمل تشغيله كبرنامج نصي:
python -m black {source_file_or_directory}يمكن العثور على مزيد من المعلومات في مستنداتنا:
لقد تم بالفعل استخدام اللون الأسود بنجاح في العديد من المشاريع، الصغيرة والكبيرة. يحتوي Black على مجموعة اختبارات شاملة، مع اختبارات متوازية فعالة، وتنسيق تلقائي خاص بنا ومشغل التكامل المستمر المتوازي. والآن بعد أن أصبحنا مستقرين، يجب ألا تتوقع تغييرات كبيرة في التنسيق في المستقبل. ستكون التغييرات الأسلوبية في الغالب عبارة عن ردود على تقارير الأخطاء ودعم بناء جملة Python الجديد. لمزيد من المعلومات يرجى الرجوع إلى نمط الكود الأسود.
أيضًا، كإجراء أمان يؤدي إلى إبطاء المعالجة، سيتحقق Black من أن الكود المعاد تنسيقه لا يزال ينتج AST صالحًا يعادل فعليًا النص الأصلي (راجع قسم البراغماتية للحصول على التفاصيل). إذا كنت تشعر بالثقة، استخدم --fast .
الأسود هو منسق رأي متوافق مع PEP 8. يقوم Black بإعادة تنسيق الملفات بأكملها في مكانها. خيارات تكوين النمط محدودة عمدًا ونادرًا ما تتم إضافتها. لا يأخذ التنسيق السابق في الاعتبار (انظر البراغماتية للاستثناءات).
تغطي وثائقنا نمط الكود الأسود الحالي، ولكن تم أيضًا توثيق التغييرات المخطط لها. كلاهما يستحق إلقاء نظرة على:
ترتبط التغييرات التي يتم إجراؤها على نمط الرمز الأسود بسياسة الاستقرار:
يرجى الرجوع إلى هذه الوثيقة قبل تقديم قضية. ما يبدو وكأنه خطأ قد يكون سلوكًا مقصودًا.
اعتادت الإصدارات المبكرة من الأسود أن تكون مطلقة في بعض النواحي. لقد أخذوا بعد مؤلفها الأولي. كان هذا أمرًا جيدًا في ذلك الوقت لأنه جعل التنفيذ أسهل ولم يكن هناك العديد من المستخدمين على أي حال. لم يتم الإبلاغ عن العديد من حالات الحافة. كأداة ناضجة، يقوم Black ببعض الاستثناءات للقواعد التي يفرضها.
يرجى الرجوع إلى هذا المستند قبل إرسال مشكلة تمامًا كما هو الحال مع المستند أعلاه. ما يبدو وكأنه خطأ قد يكون سلوكًا مقصودًا.
يستطيع Black قراءة القيم الافتراضية الخاصة بالمشروع لخيارات سطر الأوامر الخاصة به من ملف pyproject.toml . يعد هذا مفيدًا بشكل خاص لتحديد أنماط --include و --exclude / --force-exclude / --extend-exclude المخصصة لمشروعك.
يمكنك العثور على مزيد من التفاصيل في وثائقنا:
وإذا كنت تبحث عن المزيد من وثائق التكوين العامة:
نصيحة احترافية : إذا كنت تسأل نفسك "هل أحتاج إلى تهيئة أي شيء؟" الجواب هو "لا". الأسود يدور حول الافتراضات المعقولة. سيؤدي تطبيق هذه الإعدادات الافتراضية إلى جعل التعليمات البرمجية الخاصة بك متوافقة مع العديد من المشاريع الأخرى ذات التنسيق الأسود .
تثق المشاريع المفتوحة المصدر البارزة التالية بـ Black في فرض نمط تعليمات برمجية متسق: pytest، وtox، وPyramid، وDjango، وDjango Channels، وHypothesis، وattrs، وSQLAlchemy، وPoetry، وتطبيقات PyPA (Warehouse، Bandersnatch، Pipenv، virtualenv)، pandas، Pillow ، Twisted، LocalStack، كل تكامل وكيل Datadog، Home Assistant، Zulip، Kedro، OpenOA، وFLORIS، وORBIT، وWOMBAT، وغيرها الكثير.
تستخدم المنظمات التالية اللون الأسود : Facebook، وDropbox، وKeepTruckin، وLyft، وMozilla، وQuora، وDuolingo، وQuantumBlack، وTesla، وArcher Aviation.
هل نفتقد أحداً؟ اسمحوا لنا أن نعرف.
مايك باير ، مؤلف SQLAlchemy :
لا أستطيع التفكير في أي أداة واحدة طوال مسيرتي المهنية في مجال البرمجة والتي أعطتني زيادة أكبر في الإنتاجية من خلال تقديمها. يمكنني الآن إجراء عمليات إعادة البناء في حوالي 1% من ضغطات المفاتيح التي كان من الممكن أن يستغرقها الأمر سابقًا عندما لم يكن لدينا طريقة لتنسيق التعليمات البرمجية نفسها.
داستي فيليبس الكاتب:
الأسود عنيد لذا لا يجب أن تكون كذلك.
هاينك شلواك ، مبتكر attrs ، المطور الأساسي لـ Twisted وCPython:
المنسق التلقائي الذي لا يمتص هو كل ما أريده في عيد الميلاد!
كارل ماير ، مطور جانغو الأساسي:
على الأقل الاسم جيد.
كينيث ريتز ، منشئ requests و pipenv :
يؤدي هذا إلى تحسين تنسيق الكود الخاص بنا بشكل كبير. شكرا للطن!
استخدم الشارة الموجودة في ملف README.md الخاص بمشروعك:
[ ![ Code style: black ] ( https://img.shields.io/badge/code%20style-black-000000.svg )] ( https://github.com/psf/black )استخدام الشارة في README.rst:
.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
:target: https://github.com/psf/black
يبدو مثل هذا:
معهد ماساتشوستس للتكنولوجيا
مرحباً! يسعدني رؤيتك على استعداد لجعل المشروع أفضل. يمكنك البدء بقراءة هذا:
يمكنك أيضًا إلقاء نظرة على بقية المستندات المساهمة أو التحدث مع المطورين:
لقد أصبح السجل طويلًا إلى حد ما. وانتقل إلى الملف الخاص به.
انظر التغييرات.
قائمة المؤلفين طويلة جدًا هذه الأيام، لذا فهي موجودة في ملف خاص بها.
انظر المؤلفين.md
من المتوقع من كل شخص مشارك في مشروع Black ، وخاصة في تعقب المشكلات وطلبات السحب ونشاط الوسائط الاجتماعية، أن يعامل الأشخاص الآخرين باحترام وأن يتبع بشكل عام الإرشادات المنصوص عليها في مدونة قواعد سلوك مجتمع Python.
وفي الوقت نفسه، يتم تشجيع الفكاهة. في الواقع، من المتوقع أن يكون لديك معرفة أساسية بسيرك مونتي بايثون الطائر. نحن لسنا متوحشين.
وإذا كنت تريد حقًا أن تصفع شخصًا ما، فافعل ذلك مع سمكة أثناء الرقص.
