تعليقات توضيحية

  • 10 دقائق

لفهم كيفية بناء تطبيق مرجعي، يجب علينا أولاً إلقاء نظرة على اللبنات الأساسية لعمليات التنفيذ المرجعية: التعليقات التوضيحية. التعليقات التوضيحية هي كائنات Python التي ينشئها المدرس لتأكيد الشروط على كل إرسال ؛ يمكن أن تكون هذه الشروط أشياء مثل وجود قيمة، أو العلاقة الزمنية بين القيم، أو حتى التعقيد الزمني لكتلة من التعليمات البرمجية. يمكنك إنشاء تعليقات توضيحية عن طريق إنشاء مثيل للفئات التي توفرها الحزمة pybryt .

هناك ثلاثة أنواع رئيسية من التعليقات التوضيحية:

  • التعليقات التوضيحية القيّمة، والتي تؤكد وجود بعض القيمة في بصمة ذاكرة الطالب
  • التعليقات التوضيحية العلائقية، التي تؤكد وجود علاقة بين القيم في بصمة ذاكرة الطالب، تأسست في منطق منطقي أو مؤقت
  • التعليقات التوضيحية للتعقيد، التي تؤكد وجود تعقيد زمني على كتلة من التعليمات البرمجية

في هذه الوحدة النمطية، نناقش النوع الأول.

تعليقات توضيحية للقيمة

تؤكد التعليقات التوضيحية للقيمة وجود قيمة في بصمة ذاكرة،الطالب. يتم إنشاؤها عن طريق إنشاء مثيل للفئة pybryt.Value، والتي تأخذ القيمة التي تريد البحث عنها باعتبارها الوسيطة الموضعية الوحيدة.

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

>>> np.random.seed(42)
>>> arr = np.random.normal(size=(100,100))
>>> pybryt.Value(arr)
pybryt.Value

يتعقب PyBryt جميع التعليقات التوضيحية التي تقوم بإنشائها، لذلك ليست هناك حاجة لتعيينها إلى متغير ما لم تكن تريد استخدامها لإنشاء تعليقات توضيحية أكثر تعقيدا.

تدعم التعليقات التوضيحية للقيم، عند استخدامها للتحقق من القيم الرقمية - بما في ذلك الصفائف، وتكرار الأرقام، وإطارات البيانات - التسامح المطلق والنسبي باستخدام atol الوسيطتين و rtol :

>>> value_annotation = pybryt.Value(arr, atol=1e-3)
>>> value_annotation.check_against(arr.round(3)), value_annotation.check_against(arr.round(2))
(True, False)

يقوم الأسلوب pybryt.Value.check_against بإرجاع قيمة منطقية تشير إلى ما إذا كان الكائن الذي تم تمريره إليه يتوافق مع التعليق التوضيحي للقيمة. كما هو موضح سابقا، من خلال السماح بتحمل مطلق بقيمة $10^{-3}$، تم استيفاء القيمة عند تقريب قيم الصفيف إلى ثلاثة أماكن، ولكنها فشلت عند تقريبها إلى مكانين.

دالات التكافؤ

بينما تحدد الكائنات Value خوارزمية لتحديد ما إذا كان هناك عنصران متساويان، فإنها تسمح أيضًا للمستخدمين بتحديد وظيفة تكافؤ مخصصة لاستخدامها في المقارنة. على سبيل المثال، لنفترض أنك أردت البحث عن سلسلة في كود الطالب، لكنك لم تكن مهتمًا بكتابة هذه السلسلة بالأحرف الكبيرة. يمكنك استخدام دالة تكافؤ مخصصة تقارن التمثيل ذي الأحرف الدنيا لسلسلتين:

def str_equal_lower(s1, s2):
    return s1.lower() == s2.lower()

بعد ذلك، يمكننا استخدام هذه الوظيفة لإنشاء تعليق Value توضيحي للتحقق من السلاسل السداسية العشرية، على سبيل المثال:

>>> message = "hash me"
>>> sha1_hash = hashlib.sha1(message.encode()).hexdigest()
>>> sha1_annotation = pybryt.Value(sha1_hash, equivalence_fn=str_equal_lower)
>>> sha1_annotation.check_against(sha1_hash.upper())
True

خيارات التعليق التوضيحي

تدعم جميع التعليقات التوضيحية خيارات تسمح لك بتخصيص الملاحظات التي يتلقاها الطلاب نتيجة لتمرير هذه التعليقات التوضيحية أو فشلها. الطريقتان الأساسيتان لتقديم هذه الملاحظات هما استخدام الوسيطتين success_message وfailure_message في المُنشئ، والمتاحة لجميع التعليقات التوضيحية:

v = pybryt.Value(1, success_message="Found 1!", failure_message="Didn't find 1 :(")

إذا تم العثور على القيمة في بصمة ذاكرة الطالب، success_message يتم تضمين في التقرير الذي ينشئه مدقق تنفيذ الطلاب في PyBryt؛ إذا لم يتم العثور عليه، failure_message يتم تضمين . إذا لم يتم توفير هذه الوسيطات، فلن يتم عرض أي رسالة.

يمكن أيضًا تعيين هذه الرسائل عن طريق تحديث الحقول المسماة بالمقابل في كائن التعليق التوضيحي:

v.success_message = "Congrats!"
v.failure_message = "Try again"

التعليقات التوضيحية للمجموعة

النوع الأساسي من التعليقات التوضيحية العلائقية هو التعليق التوضيحي للمجموعة، والذي يجمع ببساطة مجموعة من التعليقات التوضيحية معًا بحيث يمكن تشغيلها كوحدة واحدة. من الممكن فرض ترتيب التعليقات التوضيحية في المجموعة (بناءً على أمر الإدراج)، لكن هذا التنفيذ اختياري. مثل جميع التعليقات التوضيحية الأخرى، يمكن تقديم التعليقات بناءً على ما إذا كانت المجموعة راضية عن استخدام الوسيطتين success_message وfailure_message.

لإنشاء مجموعة، قم بإنشاء pybryt.Collection. يأخذ المنشئ أي عدد من الوسائط الموضعية، والتي تتوافق مع المجموعة الأولية من التعليقات التوضيحية في المجموعة. لتهيئة مجموعة فارغة، لا تقدم أي وسيطات موضعية.

col = pybryt.Collection(pybryt.Value(1))

لفرض ترتيب التعليقات التوضيحية في المجموعة، قم بتمرير enforce_order=True:

col = pybryt.Collection(pybryt.Value(1), enforce_order=True)

يمكن إضافة التعليقات التوضيحية إلى المجموعة باستخدام pybryt.Collection.add:

col.add(pybryt.Value(2))

يتم استيفاء مجموعة التعليقات التوضيحية عندما يتم استيفاء جميع توابعها، وإذا كان صحيحا، إذا enforce_order كانت الطوابع الزمنية المرضية لأطفالها تحدث بترتيب غير محدد. على سبيل المثال، دعنا نتحقق من col تجاه بصمتين للذاكرة: أحدهما يظهر فيه 1 قبل 2، والآخر يظهر فيه 2 قبل 1.

>>> col.check(pybryt.MemoryFootprint.from_values(1, 1, 2, 2)), col.check(pybryt.MemoryFootprint.from_values(2, 1, 1, 2))
(AnnotationResult(satisfied=True, annotation=pybryt.Collection),
 AnnotationResult(satisfied=False, annotation=pybryt.Collection))

يمكن أن تكون مجموعات التعليقات التوضيحية مفيدة في تجميع التعليقات التوضيحية معاً والتي تمثل أجزاء من المشكلة لتوفير ملاحظات متماسكة. على سبيل المثال، إذا كنت تكتب مرجعا لجمع قائمة من الأرقام، فقد تضع تعليقا توضيحيا لكل مجموع جزئي في مجموعة لها رسالة نجاح وفشل خاصة بها. ثم يحصل الطلاب على رسالة واحدة في ملاحظاتهم للتحقق من صحة مجموعهم. يمكنك أيضاً استخدام هذه المجموعة لفرض ترتيب التكرار على القائمة، للتأكد من أن الطلاب يسيرون وفق الترتيب الصحيح.

هناك عدة أنواع أخرى من التعليقات التوضيحية العلائقية بخلاف المجموعات فقط. يمكنك معرفة المزيد في وحدة PyBryt المتقدمة.

‏‫اختبر معلوماتك

1.

أي نوع من التعليقات التوضيحية يتحقق من وجود قيمة معينة في بصمة ذاكرة الطالب؟

2.

أي من الاستدعاءات التالية ينشئ تعليقًا توضيحيًا بقيمة لقائمة من القيم، مع تجاهل ترتيب القائمة؟

3.

ما هو السلوك الافتراضي لتعليقات المجموعة فيما يتعلق بفرض ترتيب العناصر الفرعية؟