Lorixen.
AR

سكربت Python المجدول يفشل مع العربية: خطأ UnicodeEncodeError

باختصار: إذا كان لديك سكربت Python يعمل تلقائياً كل ليلة على الخادم، مثل إرسال تقرير المبيعات اليومي أو تصدير طلبات اليوم إلى ملف، ويعمل تماماً عندما يشغّله المطور بيده، لكنه يفشل في التشغيل التلقائي برسالة UnicodeEncodeError كلما احتوى نصاً عربياً، فالسبب غالباً أن بيئة التشغيل التلقائي لا تحمل إعدادات اللغة نفسها. توثيق Python يشرح أن ترميز المخرجات والملفات، حين لا يكون وضع UTF-8 مفعلاً، يُؤخذ من إعدادات اللغة المحلية للنظام. الحل: فعّل وضع UTF-8 بمتغير البيئة PYTHONUTF8=1 أو خيار -X utf8، أو حدّد الترميز صراحة عند فتح الملفات، علماً بأن الإصدار 3.15 جعل هذا الوضع مفعلاً افتراضياً.

كيف تظهر المشكلة؟

متجر عسل وزيت زيتون في جرش يرسل لصاحبه كل صباح ملخصاً بطلبات الأمس بالبريد، يولّده سكربت Python يعمل تلقائياً عند منتصف الليل. المطور كتب السكربت وجرّبه بنفسه عدة مرات، وكل شيء ممتاز. لكن في أول ليلة لم يصل البريد. في سجل الأخطاء رسالة طويلة تنتهي بـ UnicodeEncodeError وكلمة ascii.

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

لماذا يعمل يدوياً ويفشل تلقائياً؟

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

وهنا يأتي دور Python. توثيق دالة open يقول إن الترميز الافتراضي للملفات النصية هو UTF-8، لكن إذا كان وضع UTF-8 في Python معطلاً، فالترميز الافتراضي يعتمد على المنصة، أي ما تعيده دالة الترميز المحلي. وتوثيق sys يذكر أن الترميز ومعالجة الأخطاء للمخرجات القياسية تُهيأ من إعدادات التشغيل.

فإذا كانت اللغة المحلية في بيئة المجدول لا تدعم إلا الأحرف الإنجليزية، تحاول Python كتابة «زيت زيتون بكر» بترميز لا يعرف الأحرف العربية، فتفشل.

ما هو وضع UTF-8 في Python؟

توثيق وحدة os يشرح وضع UTF-8: أُضيف في الإصدار 3.7، وعند تفعيله يتجاهل ترميز اللغة المحلية ويفرض استخدام UTF-8:

  • يُستخدم UTF-8 كترميز لنظام الملفات.
  • دالة الترميز المفضل تعيد utf-8.
  • المدخلات والمخرجات القياسية والأخطاء كلها تستخدم UTF-8 كترميز نصي.

ويذكر التوثيق تغييراً مهماً: في الإصدار 3.15 أصبح وضع UTF-8 مفعلاً افتراضياً، ويمكن تعطيله بضبط PYTHONUTF8=0 أو بخيار -X utf8=0.

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

كيف تعرف إصدار Python وإعداده على الخادم؟

قبل اختيار الحل، اطلب من المطور معرفة أمرين على الخادم نفسه، وبالطريقة التي يعمل بها المجدول:

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

إذا أظهر السجل ترميزاً غير UTF-8، فقد تأكد التشخيص. وإذا أظهر UTF-8 والمشكلة مستمرة، فابحث في مكان آخر، مثل مكتبة البريد أو قاعدة البيانات.

الحلول، من الأبسط

1. تفعيل وضع UTF-8 للسكربت المجدول: توثيق sys يذكر أنه يمكن تجاوز ترميز الأحرف بضبط متغير البيئة PYTHONIOENCODING قبل بدء Python، أو باستخدام خيار -X utf8 ومتغير البيئة PYTHONUTF8. أضف PYTHONUTF8=1 إلى سطر المهمة المجدولة، أو شغّل Python بخيار -X utf8. هذا يحل المخرجات والملفات معاً.

2. تحديد الترميز صراحة عند فتح الملفات: في الكود، عند فتح ملف للكتابة أو القراءة، يُمرر الترميز utf-8 صراحة. هذا يجعل السكربت مستقلاً عن بيئة التشغيل في ما يخص الملفات. وهو ممارسة جيدة حتى لو فعّلت الحل الأول.

3. ضبط المخرجات فقط: إذا كانت المشكلة في رسائل الطباعة إلى السجل فقط، فمتغير PYTHONIOENCODING يكفي للمخرجات القياسية. لكن الحل الأول أشمل.

التوثيق يذكر أيضاً أن إعدادات المخرجات القياسية في وضع UTF-8 يمكن تجاوزها بمتغير PYTHONIOENCODING، تماماً كما في الوضع العادي. لذلك إذا فعّلت الوضع وما زالت المخرجات تفشل، تحقق ألا يكون هذا المتغير مضبوطاً على ترميز آخر.

انتبه للسكربتات المساعدة

السكربت الرئيسي قد يستدعي برامج أخرى، أو يقرأ ملفات أعدها نظام آخر. إذا كان ملف المدخلات نفسه بترميز غير UTF-8، فتفعيل الوضع لا يكفي، بل يجب تحديد ترميز ذلك الملف عند قراءته. اطلب من المطور توثيق ترميز كل ملف يدخل إلى السكربت أو يخرج منه.

لا تصلحها بإزالة العربية

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

ماذا عن ملفات CSV المصدّرة؟

إذا كان السكربت يصدّر ملفاً سيفتحه المحاسب في برنامج جداول، فهناك مسألة منفصلة: كيف يكتشف البرنامج الترميز عند الفتح. بعض البرامج تحتاج علامة في بداية الملف لتتعرف على UTF-8. هذا موضوع يستحق اختباراً مستقلاً مع البرنامج الذي يستخدمه فريقك فعلاً. المهم أولاً أن يُكتب الملف بترميز صحيح دون أن يفشل السكربت.

اختبر كما يعمل المجدول

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

راقب المهام الليلية

السكربت الذي يفشل ليلاً لا يراه أحد. اقتراحات بسيطة:

  • اجعل المهمة تكتب سجلاً بنجاح أو فشل كل تشغيل.
  • أرسل تنبيهاً إذا فشل التشغيل، لا تقريراً فقط عند النجاح.
  • راجع السجل بعد أي تحديث للخادم أو لإصدار Python.

أسئلة شائعة

ليش سكربت Python بيشتغل لما أشغله بإيدي وبيفشل لحاله بالليل؟

لأن بيئة التشغيل التلقائي غالباً لا تحمل إعدادات اللغة نفسها، وPython حين لا يكون وضع UTF-8 مفعلاً يأخذ الترميز من إعدادات اللغة المحلية.

شو معنى UnicodeEncodeError مع العربي؟

يعني أن Python حاولت كتابة أحرف عربية بترميز لا يدعمها.

شو أسرع حل؟

أضف PYTHONUTF8=1 إلى المهمة المجدولة أو شغّل Python بخيار -X utf8، وحدّد الترميز utf-8 عند فتح الملفات.

هل الإصدارات الجديدة من Python بتحل المشكلة؟

الإصدار 3.15 جعل وضع UTF-8 مفعلاً افتراضياً بحسب التوثيق، لكن خوادم كثيرة تعمل بإصدارات أقدم.

إذا كانت تقاريرك التلقائية تفشل أو تصل ناقصة، راسلنا ونراجع السكربتات معك.

المصادر

WhatsAppاحجز مكالمة