Python Academy · درس

الإصدارات والبيانات الوصفية

أدر البيانات الوصفية للحزمة

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

لماذا تهم البيانات الوصفية

البيانات الوصفية هي كل ما يتعلق بحزمتك باستثناء الشيفرة: إصدارها ووصفها وترخيصها ومؤلفها وروابطها. تستخدمها PyPI لعرض مشروعك، ويستخدمها pip لحل الاعتماديات.

تجعل البيانات الوصفية الجيدة حزمتك موثوقة وقابلة للتثبيت.

الإصدار الدلالي

تتمثل القاعدة المتّبعة في MAJOR.MINOR.PATCH:

MAJOR تغييرات غير متوافقة
MINOR ميزات جديدة متوافقة مع الإصدارات السابقة
PATCH إصلاحات أخطاء متوافقة مع الإصدارات السابقة

يعتمد المستخدمون على ذلك لمعرفة ما إذا كانت الترقية آمنة.

version = '2.4.1'
major, minor, patch = version.split('.')
print('Major', major, 'Minor', minor, 'Patch', patch)
print('Bug fix -> bump patch to', major + '.' + minor + '.' + str(int(patch) + 1))

اختيار الإصدار التالي

تحديد مقدار الزيادة قرار تحكمه القواعد: هل كسرت واجهة API، أم أضفت ميزة، أم أصلحت خطأً فقط؟ يضمن ترميز القاعدة اتساق الإصدارات.

def bump(version, kind):
    major, minor, patch = (int(x) for x in version.split('.'))
    if kind == 'major':
        return str(major + 1) + '.0.0'
    if kind == 'minor':
        return str(major) + '.' + str(minor + 1) + '.0'
    return str(major) + '.' + str(minor) + '.' + str(patch + 1)

print(bump('1.2.3', 'minor'))
print(bump('1.2.3', 'major'))

إصدارات ما قبل الإصدار وإصدارات التطوير

تسمح Python باللواحق: 1.0.0a1 (ألفا)، و1.0.0b2 (بيتا)، و1.0.0rc1 (مرشح للإصدار)، و1.0.0.dev3. ويتعامل pip معها على أنها أقدم من الإصدار النهائي 1.0.0، لذلك يمكن للمختبرين اختيارها دون التأثير في المستخدمين العاديين.

مصدر الحقيقة الوحيد

احتفظ بالإصدار في مكان واحد فقط. إما أن تعلنه بشكل ثابت في pyproject.toml، أو تضع علامة dynamic عليه وتقرأه من الشيفرة (أو من وسم) باستخدام أدوات مثل setuptools-scm. فلا بد أن تنحرف نسختان عن بعضهما بمرور الوقت.

الوصف وREADME

يظهر description القصير في نتائج البحث. أما الوصف الطويل فيأتي من readme (عادةً README.md)، ويُعرض بوصفه صفحة المشروع على PyPI. أشر إليه باستخدام readme = 'README.md'.

يُعد README الواضح أفضل وسيلة للتعريف بحزمتك.

الترخيص

popular = ['MIT', 'Apache-2.0', 'BSD-3-Clause', 'GPL-3.0-only']
for lic in popular:
    print('SPDX:', lic)

المصنّفات

المصنّفات classifiers هي وسوم موحّدة من قائمة PyPI، مثل 'Programming Language :: Python :: 3.11' أو 'Development Status :: 4 - Beta'. وهي تدعم عوامل التصفية في PyPI، وتوضح مستوى النضج والإصدارات المدعومة.

عناوين URL للمشروع

أضف ضمن [project.urls] روابط مثل الصفحة الرئيسية والتوثيق والمصدر وسجل التغييرات. تظهر هذه الروابط في شريط جانبي على PyPI، وتساعد المستخدمين في العثور على مستودعك ووثائقك.

urls = {
    'Homepage': 'https://example.com',
    'Source': 'https://github.com/me/mytool',
    'Issues': 'https://github.com/me/mytool/issues',
}
for label, link in urls.items():
    print(label.ljust(10), link)

الكلمات المفتاحية للاكتشاف

الحقل keywords عبارة عن قائمة بمصطلحات قصيرة تساعد المستخدمين في العثور على حزمتك ضمن عمليات البحث. اختر كلمات يُحتمل أن يكتبها المستخدمون فعلًا، مثل ['cli', 'automation', 'excel']، بدلًا من كلمات عامة لا تضيف فائدة.

تحسّن الكلمات المفتاحية، بالاقتران مع المصنّفات، قابلية اكتشاف مشروعك.

سجل التغييرات

حافظ على ملف CHANGELOG يسجّل ما تغيّر في كل إصدار. يقرأه المستخدمون قبل الترقية لمعرفة الميزات الجديدة والتغييرات غير المتوافقة. ويجعل ربطه ضمن [project.urls] الوصول إليه من صفحة PyPI بنقرة واحدة.

يحوّل سجل التغييرات الجيد رقم الإصدار إلى قصة يمكن للمستخدمين متابعتها.

اختبار سريع

اختبروا معرفتكم بإدارة الإصدارات.

مراجعة

لقد أدرتم بيانات التعريف الخاصة بالحزمة:

الإصدار الدلالي MAJOR.MINOR.PATCH، بالإضافة إلى لواحق ما قبل الإصدار
احتفظوا بالإصدار في مصدر واحد للحقيقة
وفّروا description ووصفًا طويلًا في README وlicense
أضيفوا classifiers و[project.urls] لكي يعرض PyPI مشروعكم بصورة جيدة

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

هل درس «الإصدارات والبيانات الوصفية» مجاني؟

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

ماذا ستتعلم في «الإصدارات والبيانات الوصفية»؟

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

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

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

كم من الوقت يستغرق درس «الإصدارات والبيانات الوصفية»؟

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

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

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

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

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