2.17. تلميحات الأنواع

يتيح لك Python إضافة شروح لمعاملات الدوال وقيمها المُعادة بمعلومات النوع. تُتجاهَل الشروح في وقت التشغيل -- لا شيء يتحقق منها، ولا شيء يحوّل بناءً عليها -- لكنها تخدم كتوثيق للقرّاء وللواجهة (IDE).

2.17.1. صيغة الشرح

يأتي شرح المعامل بعد نقطتين رأسيتين. ويأتي نوع القيمة المُعادة بعد -> وقبل نقطتي الجسم:

def greet(name: str) -> None:
    print("hello,", name)

def add(a: int, b: int) -> int:
    return a + b

def average(values: list) -> float:
    return sum(values) / len(values)

تصف التلميحات ما ينبغي تمريره وما سيُعاد. استدعاء add("hi", "there") لا يرفع خطأً -- إذ يشغّل Python الجسم على أي حال. التلميحات عقد، وليست تحققًا.

يمكن للمعامل أن يحمل قيمة افتراضية وشرحًا معًا:

def greet(name: str, greeting: str = "hello") -> None:
    print(greeting, name)

يملك CPython تدوينًا أغنى (Optional، Union، الأنواع العامة) عبر وحدة typing، لكن تلك ثقيلة على MicroPython ونادرًا ما تُحتاج في شيفرة الكاميرا اليومية.

2.17.2. MicroPython في وقت التشغيل

يحلل MicroPython الشروح ثم يتجاهلها. لا توجد وحدة typing لاستيرادها على الكاميرا؛ ومحاولة استخدام Optional[int] أو list[int] إما أن تفشل في الاستيراد أو تتصرف بصمت كوصول عادي إلى السمات، وذلك بحسب بناء البرنامج الثابت.

التزم بأسماء الأنواع البسيطة (int، float، str، bool، bytes، list، tuple، dict) في الشروح. فهي لا تكلف شيئًا في وقت التشغيل وتنقل القصد بوضوح.

2.17.3. كيف تستخدمها الواجهة (IDE)

تقرأ الواجهة (IDE) الشروح لتشغيل تلميحات الأدوات والإكمال التلقائي والتلميحات المضمّنة. الدالة المشروحة بـ -> int تُظهر int كنوع قيمتها المُعادة عندما يحوم المؤشر فوق الاستدعاء. والمعامل المشروح بـ : str يُكمل تلقائيًا توابع السلاسل على الوسيط داخل جسم الدالة.

هذا هو المردود العملي لكتابة الشروح على بيئة تشغيل تتجاهلها: دعم أفضل من المحرر دون أي تكلفة على الإطلاق عند تشغيل البرنامج النصي على الكاميرا.

2.17.4. شروح المتغيرات

تعمل الشروح على الإسنادات العادية بالطريقة نفسها:

threshold: float = 0.5
name: str = "OpenMV"

تُتجاهَل هذه أيضًا في وقت التشغيل. استخدامها الرئيسي هو إيضاح النوع المقصود عندما لا يوضّحه الطرف الأيمن -- وذلك عادةً عندما تكون القيمة الأولية نائبًا سيُستبدل لاحقًا.