Python Academy · درس

بنية المشروع وpyproject.toml

Q: هل درس «بنية المشروع وpyproject.toml» مجاني؟

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

Q: ماذا ستتعلم في «بنية المشروع وpyproject.toml»؟

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

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

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

Q: كم من الوقت يستغرق درس «بنية المشروع وpyproject.toml»؟

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

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

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

نظّم حزمة

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

لماذا تُحزِّم شيفرتك

يعيش البرنامج النصي على جهازك، أما الحزمة فيمكن لأي شخص تثبيتها باستخدام pip install. يحوّل التغليف مجلدًا من الشيفرة إلى وحدة قابلة للتوزيع وإدارة الإصدارات وإعادة الاستخدام.

الخطوة الأولى هي اعتماد تخطيط نظيف للمشروع وملف إعدادات.

هيكل src

يضع الهيكل الموصى به الشيفرة القابلة للاستيراد داخل المجلد src/:

src/mypackage/__init__.py
src/mypackage/core.py
pyproject.toml
README.md وtests/

يمنع هيكل src استيراد شيفرتك بالخطأ من جذر المشروع بدلًا من النسخة المثبّتة.

ملف init.py

يشير __init__.py إلى أن المجلد حزمة قابلة للاستيراد، ويُنفَّذ عند استيراد الحزمة لأول مرة. ويُستخدم أيضًا لإتاحة واجهة API العامة من خلال استيراد الأسماء الأساسية.

حتى ملف __init__.py الفارغ يكفي لإنشاء حزمة.

package_dir = 'src/mypackage'
files = ['__init__.py', 'core.py', 'utils.py']
for f in files:
    print(package_dir + '/' + f)
print('Importable as:', 'mypackage')

ما هو pyproject.toml

يُعدّ pyproject.toml ملف الإعدادات الموحّد الوحيد (PEP 518/621) لتغليف Python الحديث. وهو يحل محل setup.py القديم في معظم المشاريع، وتقرأه أدوات البناء.

يستخدم تنسيق TOML: أقسام بين قوسين مربعين، وأسطرًا على هيئة key = value.

جدول build-system

يخبر جدول [build-system] الأدوات بكيفية بناء حزمتك. ومن الخيارات الشائعة:

requires = ['setuptools', 'wheel']
build-backend = 'setuptools.build_meta'

تشمل الواجهات الخلفية الأخرى Hatchling وFlit؛ والفكرة واحدة.

جدول project

يحتوي جدول [project] على البيانات الوصفية: name وversion وdescription وauthors وreadme وrequires-python وdependencies. هذه هي المعلومات التي يراها المستخدمون على PyPI.

فكّر فيه بوصفه بطاقة هوية حزمتك.

project = {
    'name': 'mytool',
    'version': '0.1.0',
    'requires-python': '>=3.9',
    'dependencies': ['requests>=2.0'],
}
for k, v in project.items():
    print(k, '=', v)

قواعد التسمية

يجب أن يكون اسم الحزمة فريدًا على PyPI، ويخضع للتطبيع: فهو غير حساس لحالة الأحرف، وتُعامل الشرطات والشرطات السفلية بالطريقة نفسها. تحقّق من توفر الاسم قبل اعتماده لتجنب تعارض عند الرفع.

name = 'My_Cool.Tool'
normalized = name.lower().replace('_', '-').replace('.', '-')
print('PyPI normalized name:', normalized)

تحديد الاعتماديات

أدرج الاعتماديات المطلوبة أثناء التشغيل ضمن dependencies مع قيود على الإصدارات مثل 'requests>=2.28,<3'. وتُدرج الإضافات الاختيارية ضمن [project.optional-dependencies]، ويمكن تثبيتها باستخدام pip install mytool[dev].

اجعل القيود متساهلة قدر الإمكان مع الحفاظ على الأمان، حتى تتوافق حزمتك مع الحزم الأخرى.

نقاط الدخول

لشحن أداة لسطر الأوامر، أضف إدخالًا ضمن [project.scripts] مثل mytool = 'mypackage.cli:main'. بعد التثبيت، يؤدي إدخال mytool إلى تشغيل تلك الدالة. هكذا تتيح أدوات CLI مثل black وpytest أوامرها.

تضمين الملفات غير البرمجية

لا تُضمَّن ملفات البيانات (مثل القوالب وJSON) تلقائيًا. اضبط بيانات الحزمة في واجهة البناء الخلفية حتى تُضمَّن الملفات داخل wheel. ويُعد نسيان ذلك سببًا شائعًا للأخطاء التي تجعل الشيفرة تعمل محليًا لكنها تتعطل عند تثبيتها.

التثبيتات القابلة للتحرير أثناء التطوير

أثناء التطوير، ثبّت حزمتك في الوضع القابل للتحرير باستخدام pip install -e .. تسري التغييرات التي تجريها على المصدر فورًا من دون إعادة التثبيت. ويتطلب ذلك ملف pyproject.toml صحيحًا، وهو سبب آخر لإعداده مبكرًا.

توفر التثبيتات القابلة للتحرير أسرع دورة للحصول على الملاحظات أثناء تطوير الحزمة.

اختبار سريع

اختبر معرفتك بهيكل المشروع.

مراجعة

لقد أنشأت هيكل حزمة:

استخدم هيكل src مع __init__.py لتحديد الحزم
يُعدّ pyproject.toml ملف الإعدادات القياسي، ويحتوي على [build-system] و[project]
حدّد name وversion وrequires-python وdependencies
أضف نقاط دخول [project.scripts] لأدوات CLI واضبط بيانات الحزمة

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

هل درس «بنية المشروع وpyproject.toml» مجاني؟