الدالة compile() في بايثون
تُجمّع الدّالة compile() شيفرة بايثون مصدريّةً إلى شيفرة أو كائن AST. يُمكن تنفيذ هذه الكائنات عبر استخدام الدّالة exec() أو الدّالة eval().
البنية العامة
compile(source, filename, mode, flags=0, dont_inherit=False, optimize=-1)
المعاملات
source
الشيفرة المصدريّة المرغوب تجميعها، يُمكن أن تكون قيمة المُعامل سلسلةً نصيّة، أو سلسلة بايتات نصيّة (byte string) أو كانًا من النّوع AST. انظر توثيق الوحدة ast للمزيد من المعلومات حول كائنات AST.
filename
اسم الملفّ الذي قُرِئَت منه الشيفرة. مرّر قيمةً مألوفةً إن لم تكن الشّيفرة قد قرئَت من ملفّ مُعيّن (من الشّائع استخدام القيمة '<string>').
mode
مُعاملٌ يُحدّد نمط الشيفرة المرغوب تجميعها، يُمكن أن تكون قيمته 'exec' إن كانت الشيفرة المصدريّة (أي قيمة المُعامل source) مجموعةً من الجمل (statements) البرمجيّة (مثل الشّروط وحلقات التّكرار...)، أو يُمكن أن تكون قيمته 'eval' إن كانت الشّيفرة تعبيرًا (expression) واحدًا، أو يُمكن أن تكون قيمته 'single' إن كانت الشّيفرة جملةً برمجيّة تفاعليّةً واحدة (في هذه الحالة الأخيرة، ستُطبَع الجمل التي تُعيد قيمةً غير القيمة None).
flags
مُعامل اختياريّ يُحدّد أيًّا من الجمل المستقبليّة (future statements) ستُؤثر على تجميع الشّيفرة المصدريّة. إن لم تُحدّد قيمة كلّ من المُعامل flags والمُعامل dont_inherit أو إن كانت قيمتهما تُساوي 0، فستُجمَّع الشّيفرة مع استعمال الجمل المُستقبليّة الموجودة في الشّيفرة التي تستدعي الدّالة compile(). إن مُرّر المُعامل flags ولم يُمرّر المُعامل dont_inherit (أو كانت قيمته صفرًا) فستُستخدم الجمل المُستقبليّة المُحدّدة من طرف المُعامل flags إضافةً إلى تلك التّي ستُستخدم في الأصل.
dont_inherit
مُعامل اختياريّ آخر يُحدّد كيفيّة التّعامل مع الجمل المُستقبليّة في الشّيفرة المصدريّة، (انظر المُعامل flags).
إن كانت قيمة المُعامل dont_inherit عددًا صحيحًا مُخالفًا للصّفر، فستُتجاهل الجمل المُستقبليّة التي تُؤثّر حول استدعاء الدّالة compile().
تُحدّد الجمل المُستقبليّة عبر بتّات (bits) يُمكن ربطها بعمليّة bitwise OR لتحديد جمل مُتعدّدة.
يُمكن إيجاد حقل البتّات المطلوب لتحديد ميّزة مُعيّنة في الخاصيّة compiler_flag الموجودة على النّسخة _Feature في الوحدة __future__.
optimize
يُحدّد هذا المُعامل مستوى التّحسين للمُجمّع؛ القيمة الافتراضيّة هي -1 وتختار مستوى التحسين حسب ما أُعطِيَ للمُفسّر (interpreter) عبر خيارات -O في سطر الأوامر.
مُستويات التّحسين هي كالتّالي:
0: لا تحسين، قيمة__debug__صحيحة (True).1: تُحذف التأكيدات (asserts)، وقيمة__debug__خاطئة (False).2: تُحذف السّلاسل النّصيّة الموثّقة (docstrings) كذلك.
القيمة المعادة
شيفرة أو كائن AST يُمكن تنفيذه بالدّالة exec() أو بالدّالة eval().
الاستثناءات
- استثناء SyntaxError إن كانت الشّيفرة المُجمَّعةُ غير صالحة.
- استثناء ValueError إن كانت الشّيفرة المصدريّة تحتوي على بيتات فارغة (null bytes).
أمثلة
المثال التّالي يوضّح كيفيّة عمل هذه الدّالة:
>>> eval_code = compile('2*2', '<string>', 'eval') # تعبير رياضيّ
>>> eval(eval_code)
4
>>> exec_code = compile("if 1 == True: print('Hi!')", '<string>', 'exec') # جملة شرطيّة
>>> exec(exec_code)
Hi!
ملاحظات
- عند تجميع سلسلة نصيّة تحتوي على عدّة أسطر برمجيّة في النّمط
'single'أو النّمط'eval'، فيجب على المُدخل أن ينتهي بمحرف سطر جديد (newline character) واحد على الأقل. وذلك لتسهيل التّعرف على الجمل المُكتملة وغير المُكتملة في الوحدة code. - يُمكن أن يحدث عطل مُفاجئ لمُفسّر بايثون بشيفرة مصدريّة كبيرة أو مُعقّدة عند تجميعها إلى كائن AST، وذلك بسبب القيود الموجودة في مُجمّع AST الخاصّ بلغة بايثون.