Python/csv

تعد صيغة CSV (القيم المفصولة بفاصلة Comma Separated Values) أكثر صيغ الملفات شيوعًا والتي تستخدم لتصدير واستيراد البيانات من جداول البيانات spreadsheets وقواعد البيانات. وقد استخدمت هذه الصيغة لفترة طويلة قبل أي محاولة لوصف هذه الصيغة بطريقة معيارية عبر المعيار RFC 4180. إن غياب معيار محدّد ومعروف يعني وجود اختلافات طفيفة بين البيانات التي الناتجة أو المستخدمة من قبل التطبيقات المختلفة، ما يجعل من التعامل مع ملفات CSV القادمة من مصادر مختلفة أمرًا مزعجًا في بعض الأحيان. وعلى الرغم من أنّ الفواصل delimiters ومحارف علامات الاقتباس quoting characters مختلفة بين تطبيق وآخر، ولكنّ النسق العام لهذه الملفات متشابه بما يكفي لإنشاء وحدة يمكن استخدامها للتعامل مع مثل هذه البيانات بكفاءة عالية، وإخفاء تفاصيل كتابة البيانات وقرائتها عن المبرمج.

تقدّم وحدة csv عددًا من الأصناف التي تساعد في قراءة البيانات المجدولة وكتابتها بصيغة CSV، ويمكن القول بأنّ هذه الوحدة تساعد المبرمجين على كتابة البيانات بالصيغة المفضّلة في برنامج Excel، أو قراءة البيانات من الملفات التي ينتجها هذا البرنامج، دون الخوض في تفاصيل هذه الصيغة المستخدمة في برنامج Excel. ويمكن للمبرمجين كذلك إنشاء ووصف صيغ CSV يمكن لتطبيقات أخرى أن تتعامل معها، ويمكنهم كذلك إنشاء صيغ CSV لأغراضهم الخاصة.

تقرأ كائنات القراءة والكتابة في هذه الوحدة وتكتب التسلسلات، ويمكن للمبرمجين قراءة البيانات وكتابتها في قواميس باستخدام الصنفين DictReader و DictWriter.

دوال الوحدة csv

تقدّم وحدة csv الدوال التالية:

الدالة csv.reader()‎

تعيد الدالة كائن قراءة مهمّته هي المرور على جميع الأسطر في ملف csv المعطى.

الدالة csv.writer()‎

تعيد الدالة كائن كتابة وظيفته تحويل بيانات المستخدم إلى سلاسل نصية مفصولة عن بعضها البعض وكتابتها في الكائن المعطى.

الدالة csv.register_dialect()‎

تربط الدالة اللهجة المعطاة بالاسم المحدّد.

الدالة csv.unregister_dialect()‎

تحذف الدالة اللهجة المرتبطة بالاسم المعطى من سجلّ اللهجات.

الدالة csv.get_dialect()‎

تعيد الدالة اللهجة المرتبطة بالاسم المعطى. 

الدالة csv.list_dialects()‎

تعيد الدالة قائمة باللهجات المسجّلة.

الدالة csv.field_size_limit()‎

تعيد الدالة الحجم الأقصى للحقل والذي يسمح المحلّل باستخدامه.

أصناف الوحدة csv

تقدّم وحدة csv الأصناف التالية:

الصنف csv.DictReader

تنشئ الدالة البانية لهذا الصنف كائنًا يعمل كقارئ عادي ولكنّه يربط المعلومات في كل سطر بقاموس مرتّب OrderedDict .

الصنف csv.DictWriter

تنشئ الدالة البانية لهذا الصنف كائنًا يعمل ككاتب عاديٍّ ولكنّه يربط القواميس بالأسطر الموجودة في ملف csv. 

الصنف csv.Dialect

الصنف Dialect هو صنف حاوٍ container class ويُستخدم عادة من أجل الخصائص التي يقدّمها والتي يمكن الاستفادة منها لتعريف المعاملات بنسخة معيّنة صنف الكتابة أو القراءة.

الصنف csv.excel

يعرّف هذا الصنف الخصائص الاعتيادية في ملفات CSV الناتجة من برنامج Excel. يسجّل هذا الصنف تحت اسم اللهجة 'excel'.

الصنف csv.excel_tab

يعرّف هذا الصنف الخصائص الاعتيادية للملفات التي تتضمّن بيانات مفصولة بعلامة جدولة والناتجة من برنامج Excel. يسجّل هذا الصنف تحت اسم اللهجة 'excel-tab'.

الصنف csv.unix_dialect

يعرّف الصنف الخصائص الاعتيادية لملفات CSV التي أنشئت في أنظمة UNIX، بمعنّى أن علامة نهاية السطر هي ‎'\n'‎ وأنّ جميع الحقول محاطة بعلامات اقتباس. يسجّل هذا الصنف تحت اسم اللهجة 'unix'.

ملاحظة: هذا الصنف جديد في الإصدار 3.2 من بايثون.

الصنف csv.Sniffer

يستخدم هذا الصنف لتخمين الصيغة المستخدمة في ملف CSV.

ثوابت الوحدة csv

تقدّم الوحدة csv الثوابت التالية:

csv.QUOTE_ALL

يؤدي استخدام هذا الثابت إلى إحاطة جميع الحقول بعلامات اقتباس.

csv.QUOTE_MINIMAL

يؤدي استخدام هذا الثابت إلى توجيه كائنات الكتابة بإحاطة الحقول التي تتضمّن محارف خاصة دون غيرها (مثل الفواصل delimiters أو محارف علامات الاقتباس quotechar أو محرف من محارف إنهاء السطر lineterminator).

csv.QUOTE_NONNUMERIC

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

csv.QUOTE_NONE

يوجّه هذا الثابت كائنات الكتابة إلى عدم إحاطة الحقول بعلامات الاقتباس. إن كان الفاصل delimiter الحالي موجودًا في المخرجات فإنّه يُسبق بمحرف التهريب escapechar الحالي.

وفي حال عدم تعيين محرف تهريب، يُطلق كائن الكتابة الاستثناء Error عندما يواجه محرفًا يحتاج إلى التهريب.

يوجّه هذا الثابت كائنات القراءة إلى عدم إجراء أي معالجة خاصة لمحارف الاقتباس.

استثناءات الوحدة csv

تقدّم وحدة csv استثناءً وحيدًا هو:

الاستثناء csv.Error

يُطلق هذا الاستثناء من قبل دوال الوحدة عند حدوث أيّ خطأ.

اللهجات ومعاملات التنسيق

اللهجات dialects هي مجموعة محدّدة من معاملات التنسيق، والهدف منها تسهيل اختيار التنسيق المعتمد لمدخلات ومخرجات هذه الوحدة. اللهجة هي صنف متفرّع من الصنف Dialect ويمتلك مجموعة من التوابع الخاصة وتابع validate()‎ وحيد. يمكن للمبرمج أن يختار سلسلة نصية أو صنفًا متفرّعًا من الصنف Dialect كمعامل لهجة وذلك عند إنشاء كائنات الكتابة أو القراءة. وإلى جانب ما سبق يمكن للمبرمج أن يحدّد معاملات تنسيق مفردة - إضافة إلى المعاملات المجموعة في اللهجة أو عوضًا عنها - وتحمل هذه المعاملات نفس أسماء الخصائص المعرّفة أدناه في الصنف Dialect.

تقدّم كائنات Dialect الخصائص التالية:

Dialect.delimiter

سلسلة نصية ذات حرف واحد تستخدم في فصل الحقول عن بعضها البعض. القيمة الافتراضية لهذه السلسلة هي ','.

Dialect.doublequote

تتحكّم هذه الخاصية في الطريقة المتّبعة لإحاطة علامات الاقتباس quotechar التي ترد ضمن الحقول بعلامات اقتباس. عندما تحمل هذه الخاصية القيمة True (وهي القيمة الافتراضية)، تجري مضاعفة الحرف. وعندما تحمل القيمة False، يستخدم الحرف المحدّد في escapechar كسابقة للحرف quotechar.

إن كانت الخاصية doublequote تحمل القيمة False ولم يعيّن أي حرف تهريب في الخاصية escapechar، يؤدي عرض المخرجات إلى إطلاق الاستثناء Error إن لم يُعثر على الحرف quotechar في الحقل المراد عرضه.

Dialect.escapechar

سلسلة نصية ذات حرف واحد تستخدمها كائنات الكتابة لتهريب الفاصل delimiter إن استخدم الثابت QUOTE_NONE للخاصية quoting، ولتهريب علامة الاقتباس quotechar إن كانت الخاصية doublequote تحمل القيمة Flase. أما عند القراءة تحذف الخاصية escapechar أي معنى خاصّ يحمله الحرف اللاحق. تأخذ هذه الخاصية القيمة None كقيمة افتراضية، وهذا يعني إبطال عملية تهريب المحارف.

Dialect.lineterminator

السلسلة النصية التي تُستخدم لإنهاء الأسطر التي تنتجها كائنات الكتابة. تأخذ القيمة الافتراضية ‎'\r\n'‎.

ملاحظة: كائنات القراءة معدّة يدويًا للتمييز بين نهاية السطر ‎'\r'‎ أو ‎'\n'‎، وتتجاهل قيمة الخاصية lineterminator. قد يتغيّر هذا السلوك في المستقبل.

Dialect.quotechar

سلسلة نصية ذات حرف واحد تستخدم لإحاطة الحقول التي تحتوي على محارف خاصة بعلامات اقتباس، مثل الفاصل delimiter أو حرف علامة الاقتباس quotechar أو الحقول التي تحتوي على محارف السطر الجديد. القيمة الافتراضية لهذه الخاصية هي '"'.

Dialect.quoting

تتحكّم هذه الخاصية بعملية إدراج علامات الاقتباس بواسطة كائنات الكتابة وعملية التعرف عليها بواسطة كائنات القراءة. تصلح جميع الثوابت QUOTE_*‎ كقيمة لهذه الخاصية، والقيمة QUOTE_MINIMAL هي القيمة الافتراضية.

Dialect.skipinitialspace

إن أخذت هذه الخاصية القيمة True سيجري تجاهل المسافات البيضاء whitespace التي تأتي بعد الفاصل delimiter مباشرة. القيمة الافتراضية لهذه الخاصية هي False.

Dialect.strict

إن أخذت هذه الخاصية القيمة True فإنّ الوحدة ستطلق الاستثناء Error عند التعامل مع مدخلات CSV معطوبة. القيمة الافتراضية هي False.

كائنات القراءة Reader objects

كائنات القراءة هي نسخ الصنف DictReader وتنشأ كذلك من الدالة reader()‎.

كائنات الكتابة Writer Objects

كائنات الكتابة هي نسخ من الصنف DictWriter وتنشأ كذلك من استدعاء الدالة writer()‎.

مصادر

صفحة CSV File Reading and Writing في توثيق بايثون الرسمي.