typeshed
1.0.0
يحتوي Typeshed على تعليقات توضيحية للنوع الخارجي لمكتبة Python القياسية ومكونات Python، بالإضافة إلى حزم الجهات الخارجية التي ساهم بها أشخاص من خارج تلك المشاريع.
يمكن استخدام هذه البيانات، على سبيل المثال، للتحليل الثابت، وفحص النوع، واستدلال النوع، والإكمال التلقائي.
للحصول على معلومات حول كيفية استخدام typeshed، اقرأ أدناه. يمكن العثور على معلومات للمساهمين في CONTRIBUTING.md. يرجى قراءتها قبل تقديم طلبات السحب؛ لا تقم بالإبلاغ عن المشكلات المتعلقة بالتعليقات التوضيحية للمشروع التي تتعلق بها البذرة، ولكن بدلاً من ذلك قم بالإبلاغ عنها هنا للكتابة عليها.
يمكن أيضًا العثور على مزيد من الوثائق حول ملفات كعب الروتين، والطباعة، ونظام الكتابة في Python بشكل عام، على https://typing.readthedocs.io/en/latest/.
يدعم Typeshed إصدارات Python 3.8 إلى 3.13.
إذا كنت تستخدم مدقق النوع فقط (mypy، pyright، pytype، PyCharm، ...)، بدلاً من تطويره، فلن تحتاج إلى التفاعل مع الريبو المكتوب على الإطلاق: نسخة من جزء المكتبة القياسية من يتم تجميع typeshed مع أدوات التحقق من النوع. ويمكن تثبيت بذرة النوع لحزم ووحدات الطرف الثالث التي تستخدمها من PyPI. على سبيل المثال، إذا كنت تستخدم html5lib و requests ، فيمكنك تثبيت النوع الذي تستخدمه
$ pip install types-html5lib types-requestsتتبع حزم PyPI هذه PEP 561 ويتم إصدارها تلقائيًا (حتى مرة واحدة يوميًا) بواسطة الآلات الداخلية المطبوعة.
يجب أن تكون أدوات فحص النوع قادرة على استخدام حزم كعب الروتين هذه عند تثبيتها. لمزيد من التفاصيل، راجع الوثائق الخاصة بمدقق النوع الخاص بك.
تتكون أرقام إصدارات حزم كعب روتين الطرف الثالث من أربعة أجزاء على الأقل. تتوافق جميع أجزاء الإصدار الأساسي، باستثناء الجزء الأخير، مع إصدار حزمة وقت التشغيل التي تم إيقافها. على سبيل المثال، إذا كانت حزمة types-foo تحتوي على الإصدار 1.2.0.20240309 ، فهذا يضمن أن حزمة types-foo تحتوي على بذرة مستهدفة ضد foo==1.2.* واختبارها مقابل أحدث إصدار من foo المطابق لذلك المحدد. في هذا المثال، يشير العنصر الأخير من رقم الإصدار (20240309) إلى أنه تم دفع حزمة كعب الروتين في 9 مارس 2024.
في typeshed، نحاول الحفاظ على الحد الأدنى من التغييرات. ومع ذلك، ونظرًا لطبيعة الجذور، فإن أي زيادة في الإصدار يمكن أن تؤدي إلى تغييرات قد تؤدي إلى فشل التعليمات البرمجية الخاصة بك في التحقق من الكتابة.
هناك العديد من الاستراتيجيات المتاحة لتحديد إصدار الحزمة التي تستخدمها، ولكل منها مقايضاتها الخاصة:
استخدم نفس الحدود التي تستخدمها للحزمة التي يتم إيقافها. على سبيل المثال، إذا كنت تستخدم requests>=2.30.0,<2.32 ، فيمكنك استخدام types-requests>=2.30.0,<2.32 . يضمن هذا أن تكون البذرة متوافقة مع الحزمة التي تستخدمها، ولكنها تنطوي على خطر بسيط يتمثل في كسر التحقق من النوع بسبب التغييرات في البذرة.
هناك خطر آخر لهذه الإستراتيجية وهو أن بذرة غالبًا ما تتخلف عن الحزمة التي يتم بذرها. قد ترغب في إجبار الحزمة التي يتم إيقافها على حد أدنى معين من الإصدار لأنها تعمل على إصلاح خطأ فادح، ولكن إذا لم يتم إصدار كعب الروتين المحدث بشكل مماثل، فقد لا تكون نتائج التحقق من النوع دقيقة تمامًا.
قم بتثبيت كعب الروتين بإصدار جيد معروف وقم بتحديث الدبوس من وقت لآخر (إما يدويًا أو باستخدام أداة مثل التابع أو التجديد).
على سبيل المثال، إذا كنت تستخدم types-requests==2.31.0.1 ، فيمكنك أن تكون واثقًا من أن ترقية التبعيات لن تؤدي إلى تعطيل التحقق من النوع. ومع ذلك، سوف تفوت التحسينات في كعب الروتين التي من المحتمل أن تؤدي إلى تحسين التحقق من النوع حتى تقوم بتحديث الدبوس. تنطوي هذه الإستراتيجية أيضًا على خطر أن تصبح البذرة التي تستخدمها غير متوافقة مع الحزمة التي يتم بذرةها.
لا تعلق بذرة. هذا هو الخيار الذي يتطلب أقل قدر من العمل منك عندما يتعلق الأمر بتحديث دبابيس الإصدار، وله ميزة أنك ستستفيد تلقائيًا من البذرة المحسنة كلما تم إصدار إصدار جديد من حزمة البذرة. ومع ذلك، فإنه ينطوي على خطر أن تصبح بذرة غير متوافقة مع الحزمة التي يتم بذرها.
على سبيل المثال، إذا تم إصدار إصدار رئيسي جديد من الحزمة، فهناك احتمال أن يتم تحديث كعب الروتين لتعكس الإصدار الجديد من حزمة وقت التشغيل قبل تحديث الحزمة التي يتم كعبها.
يمكنك أيضًا التبديل بين الاستراتيجيات المختلفة حسب الحاجة. على سبيل المثال، يمكنك استخدام الإستراتيجية (1) بشكل افتراضي، ولكن يمكنك الرجوع إلى الإستراتيجية (2) عند ظهور مشكلة لا يمكن حلها بسهولة.
_typeshed يتضمن typeshed حزمة _typeshed كجزء من المكتبة القياسية. تحتوي هذه الحزمة ووحداتها الفرعية على أنواع أدوات مساعدة، ولكنها غير متوفرة في وقت التشغيل. لمزيد من المعلومات حول كيفية استخدام هذه الحزمة، راجع الدليل stdlib/_typeshed .
إذا واجهت سلوكًا في مدقق النوع يشير إلى أن جذور الكتابة لمكتبة معينة غير صحيحة أو غير مكتملة، فنحن نريد أن نسمع منك!
المنتدى الرئيسي للمناقشة هو متتبع مشكلات GitHub الخاص بالمشروع. هذا هو المكان المناسب لبدء مناقشة أي من المواضيع المذكورة أعلاه أو أي موضوع آخر يتعلق بالمشروع.
إذا كانت لديك أسئلة عامة حول الكتابة باستخدام Python، أو كنت بحاجة إلى مراجعة التعليقات التوضيحية للكتابة أو بذرة خارج الكتابة المكتوبة، فتوجه إلى منتدى المناقشة الخاص بنا. لإجراء مناقشات أقل رسمية، جرب غرفة الدردشة الكتابية على gitter.im. بعض المشرفين على الكتابة يكونون موجودين دائمًا تقريبًا؛ لا تتردد في العثور علينا هناك ويسعدنا الدردشة. سيتم توجيه المناقشة الفنية الموضوعية إلى متتبع المشكلة.
