Python Academy · درس

البناء باستخدام build

أنشئ ملفات wheels وsdists

البناء باستخدام build درس مجاني في Python Academy على CoddyKit. هذا هو الدرس 2 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في Python Academy، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة Python Academy 4 دروس في المجموع.

ما المقصود بالبناء

يجب تحويل الشيفرة المصدرية إلى ملفات توزيع يمكن لـ pip تثبيتها. والأداة الحديثة لذلك هي build، وتُشغَّل باستخدام python -m build.

وتنتج نوعين من الملفات: توزيعة مصدرية وwheel.

sdist مقابل wheel

نوعا الملفات الناتجة:

sdist (.tar.gz) أرشيف مصدر؛ ينشئه pip عند التثبيت
wheel (.whl) أرشيف مبني مسبقًا؛ يفك pip ضغطه فقط

تُثبَّت ملفات wheel بسرعة أكبر، ولذلك تُفضَّل. أما sdist فهو الخيار الاحتياطي والمصدر الأساسي.

تثبيت أداة البناء

ثبّتها مرة واحدة باستخدام pip install build. فهي واجهة أمامية خفيفة: تقرأ pyproject.toml، وتُعدّ بيئة معزولة، وتستدعي واجهة البناء الخلفية لإنشاء الملفات الناتجة.

لا تستدعي الواجهة الخلفية مباشرة؛ إذ تتولى build تنسيق ذلك.

تشغيل البناء

من جذر المشروع، شغّل python -m build. ينشئ الأمر افتراضيًا توزيعة مصدرية وwheel، ويضعهما في مجلد dist/ جديد.

استخدم --wheel أو --sdist لبناء نوع واحد فقط.

args = []
targets = []
if '--sdist' in args:
    targets.append('sdist')
if '--wheel' in args:
    targets.append('wheel')
if not targets:
    targets = ['sdist', 'wheel']
print('Will build:', targets)

أسماء ملفات wheel

تشفّر أسماء ملفات wheel البيانات الوصفية: يعني mytool-0.1.0-py3-none-any.whl أن الاسم هو mytool، والإصدار 0.1.0، وأنها مخصصة لـ Python 3، ولا تتطلب ABI محددًا، وتعمل على أي منصة. تحصل الحزم المكتوبة بـ Python فقط على py3-none-any.

name = 'mytool'
version = '0.1.0'
wheel = name + '-' + version + '-py3-none-any.whl'
print(wheel)
print('Parts:', wheel[:-4].split('-'))

عزل البناء

تنشئ build افتراضيًا بيئة افتراضية جديدة، وتثبّت فيها ما يرد في requires ضمن [build-system]، ثم تبني الحزمة داخلها. يضمن ذلك ألا يعتمد البناء بالخطأ على حزم موجودة مصادفةً في بيئتك.

فحص مجلد dist

بعد البناء، يحتوي dist/ على الملفات الناتجة. يؤكد استعراضه ما أُنشئ قبل الرفع. وهذا مجرد استعراض عادي لمحتويات مجلد.

dist = ['mytool-0.1.0.tar.gz', 'mytool-0.1.0-py3-none-any.whl']
for f in dist:
    kind = 'sdist' if f.endswith('.tar.gz') else 'wheel'
    print(kind.ljust(6), f)

فحص ملف wheel

ملف wheel ليس إلا أرشيف ZIP. يمكنك فك ضغطه للتحقق من وجود الوحدات وملفات البيانات، والتأكد من عدم إغفال أي ملف مهم. فإذا كان ملف ما مفقودًا هنا، فسيكون مفقودًا بعد التثبيت أيضًا.

عمليات البناء النظيفة

قد تؤدي الملفات القديمة في build/ أو dist/ إلى نتائج مربكة. احذف هذين المجلدين قبل بناء الإصدار حتى تنشر بالضبط ما تنتجه الشيفرة المصدرية الحالية.

stale_dirs = ['build', 'dist', 'mytool.egg-info']
for d in stale_dirs:
    print('Remove before clean build:', d)

عمليات البناء القابلة لإعادة الإنتاج

يجب أن تنتج الشيفرة المصدرية نفسها الملفات الناتجة نفسها دائمًا. ثبّت إصدارات واجهة البناء الخلفية في [build-system] requires، وتجنب جلب القيم من البيئة قيد التشغيل. تعني قابلية إعادة الإنتاج أن يحصل زميلك أو خادم CI على الناتج المطابق.

وبالاقتران مع عمليات البناء النظيفة، يزيل ذلك المفاجآت من نوع «يعمل على جهازي».

البناء في CI

تبني معظم المشاريع على خادم للتكامل المستمر بدلًا من الحاسوب المحمول. تتحقق مهمة CI من الشيفرة، وتشغّل python -m build، وتحفظ الملفات الناتجة. ويضمن ذلك أن تأتي الإصدارات من حالة معروفة ونظيفة في كل مرة.

الأمر نفسه الذي تشغّله محليًا هو ما يُشغَّل في CI.

اختبار سريع

اختبر معرفتك بالبناء.

مراجعة

لقد تعلمت إنشاء الملفات الناتجة:

pip install build ثم python -m build
ينتج توزيعة مصدرية sdist (.tar.gz) وملف wheel (.whl) داخل dist/
تُجرى عمليات البناء في بيئة معزولة باستخدام [build-system] requires
افحص ملف wheel ونفّذ عمليات بناء نظيفة قبل الإصدار

الأسئلة الشائعة

هل درس «البناء باستخدام build» مجاني؟

نعم — نص درس «البناء باستخدام build» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة Python Academy، انتقل إلى CoddyKit PRO. تتضمن دورة Python Academy 4 دروس في المجموع.

ماذا ستتعلم في «البناء باستخدام build»؟

أنشئ ملفات wheels وsdists تتمرن على Python Academy مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.

هل أحتاج إلى خبرة سابقة لأبدأ Python Academy؟

لا تُشترط خبرة سابقة. Python Academy على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 2 من أصل 4.

كم من الوقت يستغرق درس «البناء باستخدام build»؟

معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.

هل يمكنني كتابة وتشغيل أكواد في درس Python Academy هذا؟

نعم. كل درس في Python Academy يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.

جميع الدروس في هذه الدورة

← العودة إلى Python Academy