الفرق بين المراجعتين ل"Python/csv"
(أنشأ الصفحة ب'<noinclude>{{DISPLAYTITLE:الوحدة <code>csv</code> في بايثون}}</noinclude> تعد صيغة CSV (القيم المفصولة بفاصلة Comma Separat...') |
|||
| (11 مراجعة متوسطة بواسطة نفس المستخدم غير معروضة) | |||
| سطر 1: | سطر 1: | ||
<noinclude>{{DISPLAYTITLE:الوحدة <code>csv</code> في بايثون}}</noinclude> | <noinclude>{{DISPLAYTITLE:الوحدة <code>csv</code> في بايثون}}</noinclude> | ||
| − | تعد صيغة CSV (القيم المفصولة بفاصلة Comma Separated Values) أكثر صيغ الملفات شيوعًا والتي تستخدم لتصدير واستيراد البيانات من جداول البيانات spreadsheets وقواعد البيانات. وقد استخدمت هذه الصيغة لفترة طويلة قبل أي محاولة لوصف هذه الصيغة بطريقة معيارية عبر المعيار RFC 4180. إن غياب معيار محدّد ومعروف يعني وجود اختلافات طفيفة بين البيانات التي الناتجة أو المستخدمة من قبل التطبيقات المختلفة، ما يجعل من التعامل مع ملفات CSV القادمة من مصادر مختلفة أمرًا مزعجًا في بعض الأحيان. وعلى الرغم من أنّ الفواصل delimiters ومحارف | + | تعد صيغة CSV (القيم المفصولة بفاصلة Comma Separated Values) أكثر صيغ الملفات شيوعًا والتي تستخدم لتصدير واستيراد البيانات من جداول البيانات spreadsheets وقواعد البيانات. وقد استخدمت هذه الصيغة لفترة طويلة قبل أي محاولة لوصف هذه الصيغة بطريقة معيارية عبر المعيار RFC 4180. إن غياب معيار محدّد ومعروف يعني وجود اختلافات طفيفة بين البيانات التي الناتجة أو المستخدمة من قبل التطبيقات المختلفة، ما يجعل من التعامل مع ملفات CSV القادمة من مصادر مختلفة أمرًا مزعجًا في بعض الأحيان. وعلى الرغم من أنّ الفواصل delimiters ومحارف علامات الاقتباس quoting characters مختلفة بين تطبيق وآخر، ولكنّ النسق العام لهذه الملفات متشابه بما يكفي لإنشاء وحدة يمكن استخدامها للتعامل مع مثل هذه البيانات بكفاءة عالية، وإخفاء تفاصيل كتابة البيانات وقرائتها عن المبرمج. |
| − | تقدّم وحدة csv عددًا من الأصناف التي تساعد في قراءة البيانات المجدولة وكتابتها بصيغة CSV، ويمكن القول بأنّ هذه الوحدة تساعد المبرمجين على كتابة البيانات بالصيغة المفضّلة في برنامج Excel، أو قراءة البيانات من الملفات التي ينتجها هذا البرنامج، دون الخوض في تفاصيل هذه الصيغة المستخدمة في برنامج Excel. ويمكن للمبرمجين كذلك إنشاء ووصف صيغ CSV يمكن لتطبيقات أخرى أن تتعامل معها، ويمكنهم كذلك إنشاء صيغ CSV لأغراضهم الخاصة. | + | تقدّم وحدة <code>csv</code> عددًا من الأصناف التي تساعد في قراءة البيانات المجدولة وكتابتها بصيغة CSV، ويمكن القول بأنّ هذه الوحدة تساعد المبرمجين على كتابة البيانات بالصيغة المفضّلة في برنامج Excel، أو قراءة البيانات من الملفات التي ينتجها هذا البرنامج، دون الخوض في تفاصيل هذه الصيغة المستخدمة في برنامج Excel. ويمكن للمبرمجين كذلك إنشاء ووصف صيغ CSV يمكن لتطبيقات أخرى أن تتعامل معها، ويمكنهم كذلك إنشاء صيغ CSV لأغراضهم الخاصة. |
| − | تقرأ كائنات القراءة والكتابة في هذه الوحدة وتكتب التسلسلات، ويمكن للمبرمجين قراءة البيانات وكتابتها في قواميس باستخدام الصنفين DictReader و DictWriter. | + | تقرأ كائنات القراءة والكتابة في هذه الوحدة وتكتب التسلسلات، ويمكن للمبرمجين قراءة البيانات وكتابتها في قواميس باستخدام الصنفين <code>[[Python/DictReader|DictReader]]</code> و <code>[[Python/DictWriter|DictWriter]]</code>. |
| − | دوال الوحدة csv | + | == دوال الوحدة <code>csv</code> == |
| − | تقدّم وحدة csv الدوال التالية: | + | تقدّم وحدة <code>csv</code> الدوال التالية: |
| + | ===الدالة <code>[[Python/csv/reader|csv.reader()]]</code>=== | ||
| + | تعيد الدالة كائن قراءة مهمّته هي المرور على جميع الأسطر في ملف csv المعطى. | ||
| − | === الدالة csv. | + | ===الدالة <code>[[Python/csv/writer|csv.writer()]]</code>=== |
| + | تعيد الدالة كائن كتابة وظيفته تحويل بيانات المستخدم إلى سلاسل نصية مفصولة عن بعضها البعض وكتابتها في الكائن المعطى. | ||
| − | === الدالة csv. | + | ===الدالة <code>[[Python/csv/register dialect|csv.register_dialect()]]</code>=== |
| + | تربط الدالة اللهجة المعطاة بالاسم المحدّد. | ||
| − | === الدالة csv. | + | === الدالة <code>[[Python/csv/unregister dialect|csv.unregister_dialect()]]</code> === |
| + | تحذف الدالة اللهجة المرتبطة بالاسم المعطى من سجلّ اللهجات. | ||
| − | === الدالة csv.get_dialect() === | + | ===الدالة <code>[[Python/csv/get dialect|csv.get_dialect()]]</code>=== |
| + | تعيد الدالة اللهجة المرتبطة بالاسم المعطى. | ||
| − | === الدالة csv.list_dialects() === | + | ===الدالة <code>[[Python/csv/list dialects|csv.list_dialects()]]</code>=== |
| + | تعيد الدالة قائمة باللهجات المسجّلة. | ||
| − | === الدالة csv.field_size_limit() === | + | ===الدالة [[Python/csv/field size limit|<code>csv.field_size_limit()</code>]]=== |
| + | تعيد الدالة الحجم الأقصى للحقل والذي يسمح المحلّل باستخدامه. | ||
| + | ==أصناف الوحدة csv== | ||
| + | تقدّم وحدة <code>csv</code> الأصناف التالية: | ||
| + | ===الصنف <code>[[Python/DictReader|csv.DictReader]]</code>=== | ||
| + | تنشئ الدالة البانية لهذا الصنف كائنًا يعمل كقارئ عادي ولكنّه يربط المعلومات في كل سطر بقاموس مرتّب <code>[[Python/OrderedDict|OrderedDict]]</code> . | ||
| − | == | + | ===الصنف <code>[[Python/DictWriter|csv.DictWriter]]</code>=== |
| + | تنشئ الدالة البانية لهذا الصنف كائنًا يعمل ككاتب عاديٍّ ولكنّه يربط القواميس بالأسطر الموجودة في ملف csv. | ||
| − | + | ===الصنف <code>csv.Dialect</code>=== | |
| + | الصنف <code>Dialect</code> هو صنف حاوٍ container class ويُستخدم عادة من أجل الخصائص التي يقدّمها والتي يمكن الاستفادة منها لتعريف المعاملات بنسخة معيّنة صنف الكتابة أو القراءة. | ||
| + | ===الصنف <code>csv.excel</code>=== | ||
| + | يعرّف هذا الصنف الخصائص الاعتيادية في ملفات CSV الناتجة من برنامج Excel. يسجّل هذا الصنف تحت اسم اللهجة <code>'excel'</code>. | ||
| + | ===الصنف <code>csv.excel_tab</code>=== | ||
| + | يعرّف هذا الصنف الخصائص الاعتيادية للملفات التي تتضمّن بيانات مفصولة بعلامة جدولة والناتجة من برنامج Excel. يسجّل هذا الصنف تحت اسم اللهجة <code>'excel-tab'</code>. | ||
| + | ===الصنف <code>csv.unix_dialect</code>=== | ||
| + | يعرّف الصنف الخصائص الاعتيادية لملفات CSV التي أنشئت في أنظمة UNIX، بمعنّى أن علامة نهاية السطر هي <code>'\n'</code> وأنّ جميع الحقول محاطة بعلامات اقتباس. يسجّل هذا الصنف تحت اسم اللهجة <code>'unix'</code>. | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
'''ملاحظة:''' هذا الصنف جديد في الإصدار 3.2 من بايثون. | '''ملاحظة:''' هذا الصنف جديد في الإصدار 3.2 من بايثون. | ||
| − | === الصنف csv.Sniffer === | + | ===الصنف <code>[[Python/Sniffer|csv.Sniffer]]</code>=== |
| − | يستخدم هذا الصنف لتخمين الصيغة المستخدمة في ملف CSV | + | يستخدم هذا الصنف لتخمين الصيغة المستخدمة في ملف CSV. |
| − | == ثوابت الوحدة csv == | + | ==ثوابت الوحدة <code>csv</code>== |
| − | تقدّم الوحدة csv الثوابت التالية: | + | تقدّم الوحدة <code>csv</code> الثوابت التالية: |
| − | + | ===<code>csv.QUOTE_ALL</code>=== | |
| − | === csv.QUOTE_ALL === | ||
يؤدي استخدام هذا الثابت إلى إحاطة جميع الحقول بعلامات اقتباس. | يؤدي استخدام هذا الثابت إلى إحاطة جميع الحقول بعلامات اقتباس. | ||
| + | ===<code>csv.QUOTE_MINIMAL</code>=== | ||
| + | يؤدي استخدام هذا الثابت إلى توجيه كائنات الكتابة بإحاطة الحقول التي تتضمّن محارف خاصة دون غيرها (مثل الفواصل <code>delimiters</code> أو محارف علامات الاقتباس <code>quotechar</code> أو محرف من محارف إنهاء السطر <code>lineterminator</code>). | ||
| + | ===<code>csv.QUOTE_NONNUMERIC</code>=== | ||
| + | يؤدي استخدام هذا الثابت إلى توجيه كائنات الكتابة بإحاطة جميع الحقول غير العددية بعلامات اقتباس، وتوجيه كائنات القراءة إلى تحويل جميع الحقول غير المحاطة بعلامات اقتباس إلى النوع <code>[[Python/float|float]]</code>. | ||
| + | ===<code>csv.QUOTE_NONE</code>=== | ||
| + | يوجّه هذا الثابت كائنات الكتابة إلى عدم إحاطة الحقول بعلامات الاقتباس. إن كان الفاصل <code>delimiter</code> الحالي موجودًا في المخرجات فإنّه يُسبق بمحرف التهريب <code>escapechar</code> الحالي. | ||
| − | + | وفي حال عدم تعيين محرف تهريب، يُطلق كائن الكتابة الاستثناء <code>Error</code> عندما يواجه محرفًا يحتاج إلى التهريب. | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | وفي حال عدم تعيين محرف تهريب، يُطلق كائن الكتابة الاستثناء Error عندما يواجه محرفًا يحتاج إلى التهريب. | ||
يوجّه هذا الثابت كائنات القراءة إلى عدم إجراء أي معالجة خاصة لمحارف الاقتباس. | يوجّه هذا الثابت كائنات القراءة إلى عدم إجراء أي معالجة خاصة لمحارف الاقتباس. | ||
| − | + | ==استثناءات الوحدة csv== | |
| − | + | تقدّم وحدة <code>csv</code> [[Python/exceptions|استثناءً]] وحيدًا هو: | |
| − | == استثناءات الوحدة csv == | + | ===الاستثناء <code>csv.Error</code>=== |
| − | تقدّم وحدة csv استثناءً وحيدًا هو: | ||
| − | |||
| − | === الاستثناء csv.Error === | ||
يُطلق هذا الاستثناء من قبل دوال الوحدة عند حدوث أيّ خطأ. | يُطلق هذا الاستثناء من قبل دوال الوحدة عند حدوث أيّ خطأ. | ||
| + | ==اللهجات ومعاملات التنسيق== | ||
| + | اللهجات dialects هي مجموعة محدّدة من معاملات التنسيق، والهدف منها تسهيل اختيار التنسيق المعتمد لمدخلات ومخرجات هذه الوحدة. اللهجة هي صنف متفرّع من الصنف <code>Dialect</code> ويمتلك مجموعة من التوابع الخاصة وتابع <code>validate()</code> وحيد. يمكن للمبرمج أن يختار سلسلة نصية أو صنفًا متفرّعًا من الصنف <code>Dialect</code> كمعامل لهجة وذلك عند إنشاء كائنات الكتابة أو القراءة. وإلى جانب ما سبق يمكن للمبرمج أن يحدّد معاملات تنسيق مفردة - إضافة إلى المعاملات المجموعة في اللهجة أو عوضًا عنها - وتحمل هذه المعاملات نفس أسماء الخصائص المعرّفة أدناه في الصنف <code>Dialect</code>. | ||
| − | + | تقدّم كائنات <code>Dialect</code> الخصائص التالية: | |
| − | + | ===<code>Dialect.delimiter</code>=== | |
| − | + | [[Python/str|سلسلة نصية]] ذات حرف واحد تستخدم في فصل الحقول عن بعضها البعض. القيمة الافتراضية لهذه السلسلة هي <code>','</code>. | |
| − | + | ===<code>Dialect.doublequote</code>=== | |
| − | تقدّم كائنات Dialect الخصائص التالية: | + | تتحكّم هذه الخاصية في الطريقة المتّبعة لإحاطة علامات الاقتباس <code>quotechar</code> التي ترد ضمن الحقول بعلامات اقتباس. عندما تحمل هذه الخاصية القيمة <code>True</code> (وهي القيمة الافتراضية)، تجري مضاعفة الحرف. وعندما تحمل القيمة <code>False</code>، يستخدم الحرف المحدّد في <code>escapechar</code> كسابقة للحرف <code>quotechar</code>. |
| − | |||
| − | === Dialect.delimiter === | ||
| − | |||
| − | سلسلة نصية ذات حرف واحد تستخدم في فصل الحقول عن بعضها البعض. القيمة الافتراضية لهذه | ||
| − | |||
| − | === Dialect.doublequote === | ||
| − | تتحكّم هذه الخاصية في الطريقة المتّبعة لإحاطة علامات الاقتباس quotechar التي ترد ضمن الحقول بعلامات اقتباس. عندما تحمل هذه الخاصية القيمة True (وهي القيمة الافتراضية)، تجري مضاعفة الحرف. وعندما تحمل القيمة | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | هذه الخاصية | + | إن كانت الخاصية <code>doublequote</code> تحمل القيمة <code>False</code> ولم يعيّن أي حرف تهريب في الخاصية <code>escapechar</code>، يؤدي عرض المخرجات إلى إطلاق الاستثناء <code>Error</code> إن لم يُعثر على الحرف <code>quotechar</code> في الحقل المراد عرضه. |
| + | ===<code>Dialect.escapechar</code>=== | ||
| + | [[Python/str|سلسلة نصية]] ذات حرف واحد تستخدمها كائنات الكتابة لتهريب الفاصل <code>delimiter</code> إن استخدم الثابت <code>QUOTE_NONE</code> للخاصية <code>quoting</code>، ولتهريب علامة الاقتباس <code>quotechar</code> إن كانت الخاصية <code>doublequote</code> تحمل القيمة <code>Flase</code>. أما عند القراءة تحذف الخاصية <code>escapechar</code> أي معنى خاصّ يحمله الحرف اللاحق. تأخذ هذه الخاصية القيمة None كقيمة افتراضية، وهذا يعني إبطال عملية تهريب المحارف. | ||
| + | ===<code>Dialect.lineterminator</code>=== | ||
| + | السلسلة النصية التي تُستخدم لإنهاء الأسطر التي تنتجها كائنات الكتابة. تأخذ القيمة الافتراضية <code>'\r\n'</code>. | ||
| − | + | '''ملاحظة''': كائنات القراءة معدّة يدويًا للتمييز بين نهاية السطر <code>'\r'</code> أو <code>'\n'</code>، وتتجاهل قيمة الخاصية <code>lineterminator</code>. قد يتغيّر هذا السلوك في المستقبل. | |
| + | ===<code>Dialect.quotechar</code>=== | ||
| + | سلسلة نصية ذات حرف واحد تستخدم لإحاطة الحقول التي تحتوي على محارف خاصة بعلامات اقتباس، مثل الفاصل <code>delimiter</code> أو حرف علامة الاقتباس <code>quotechar</code> أو الحقول التي تحتوي على محارف السطر الجديد. القيمة الافتراضية لهذه الخاصية هي <code>'"'</code>. | ||
| + | ===<code>Dialect.quoting</code>=== | ||
| + | تتحكّم هذه الخاصية بعملية إدراج علامات الاقتباس بواسطة كائنات الكتابة وعملية التعرف عليها بواسطة كائنات القراءة. تصلح جميع الثوابت <code>QUOTE_*</code> كقيمة لهذه الخاصية، والقيمة <code>QUOTE_MINIMAL</code> هي القيمة الافتراضية. | ||
| + | ===<code>Dialect.skipinitialspace</code>=== | ||
| + | إن أخذت هذه الخاصية القيمة <code>True</code> سيجري تجاهل المسافات البيضاء whitespace التي تأتي بعد الفاصل <code>delimiter</code> مباشرة. القيمة الافتراضية لهذه الخاصية هي <code>False</code>. | ||
| + | ===<code>Dialect.strict</code>=== | ||
| + | إن أخذت هذه الخاصية القيمة <code>True</code> فإنّ الوحدة ستطلق الاستثناء <code>Error</code> عند التعامل مع مدخلات <code>CSV</code> معطوبة. القيمة الافتراضية هي <code>False</code>. | ||
| + | ==[[Python/csvreader|كائنات القراءة Reader objects]]== | ||
| + | كائنات القراءة هي نسخ الصنف <code>[[Python/DictReader|DictReader]]</code> وتنشأ كذلك من الدالة [[Python/csv/reader|<code>reader()</code>]]. | ||
| + | ==[[Python/csvwriter|كائنات الكتابة Writer Objects]]== | ||
| + | كائنات الكتابة هي نسخ من الصنف [[Python/DictWriter|<code>DictWriter</code>]] وتنشأ كذلك من استدعاء الدالة <code>[[Python/csv/writer|writer()]]</code>. | ||
| − | + | ==مصادر== | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | == مصادر == | ||
[https://docs.python.org/3/library/csv.html#module-csv صفحة CSV File Reading and Writing في توثيق بايثون الرسمي.] | [https://docs.python.org/3/library/csv.html#module-csv صفحة CSV File Reading and Writing في توثيق بايثون الرسمي.] | ||
| − | |||
[[تصنيف:Python]] | [[تصنيف:Python]] | ||
[[تصنيف:Python Modules]] | [[تصنيف:Python Modules]] | ||
المراجعة الحالية بتاريخ 08:07، 3 ديسمبر 2018
تعد صيغة 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().