الوحدة csv‎‎ في بايثون

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

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

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

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

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

تقدّم وحدة 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()‎) التوابع العامة التالية:

التابع ‎csvreader.__next__()‎

يعيد التابع السطر التالي في كائن المكرّر الخاص بكائن القراءة على هيئة قائمة (إن كان الكائن معادًا من الدالة reader()‎) أو قاموس (إن كان الكائن نسخة من الصنف DictReader) وتكون القيمة المعادة مفسّرة بحسب اللهجة المستخدمة. يُستدعى هذا التابع عادة بهذه الطريقة next(reader).

تمتلك كائنات القراءة الخصائص العامة التالية:

csvreader.dialect

هذه الخاصية للقراءة فقط، وتتضمن وصفًا للهجة المستخدمة بواسطة المفسر.

csvreader.line_num

عدد الأسطر المقروءة من المكرِّر المصدر. يختلف هذا العدد عن عدد السجلّات المعادة، إذ يمكن للسجل الواحد أن يمتدّ لعدّة أسطر.

تمتلك كائنات DictReader الخصائص العامة التالية:

csvreader.fieldnames

إن لم تمرّر هذه الخاصية كمعامل عند إنشاء الكائن، فإنّ هذه الخاصية تُهيّئ عند الوصول إليها لأول مرّة أو عند قراءة أول سجلّ من الملف.

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

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

يجب أن يكون الصف row كائنًا قابلًا للتكرار من السلاسل النصية او الأرقام عند استخدام كائنات Writer وأن يكون قاموسًا يربط أسماء الحقول fieldnames بسلاسل نصية أو أرقام (عن طريق تمريرها عبر الدالة str()‎ في البداية) عند استخدام كائنات DictWriter. يجدر التنبيه إلى أنّ الأعداد المركّبة تُحاط بالأقواس، وقد يكون ذلك سببًا في حدوث بعض المشاكل في البرامج الأخرى التي تقرأ ملفات CSV (على فرض أنّها تستطيع التعامل مع الأعداد المركبة).

csvwriter.writerow(row)

يكتب التابع المعامل row في كائن الملف الخاص بكائن القراءة، ويُنسّق المعامل بالاعتماد على اللهجة المستخدمة.

ملاحظة: أضيف دعم كائنات التكرار بمختلف أنواعها في الإصدار 3.5 من بايثون.

csvwriter.writerows(rows)

يكتب التابع جميع العناصر في الصفوف المعطاة (كائن تكرار يتضمّن كائنات row) في كائن الملف الخاص بكائن الكتابة، وتنسق العناصر بالاعتماد على اللهجة المستخدمة.

تمتلك كائنات الكتابة الخصائص العامة التالية:

csvwriter.dialect

هذه الخاصية للقراءة فقط، وتتضمن وصفًا للهجة المستخدمة بواسطة كائن الكتابة.

تمتلك كائنات DictWriter التوابع العامة التالية:

DictWriter.writeheader()

يكتب التابع صفًّا مع أسماء الحقول (كما هو محدّد في الدالة البانية). ملاحظة: هذا التابع جديد في الإصدار 3.2.

مصادر

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