الفرق بين المراجعتين لصفحة: «Python/csv»
| سطر 31: | سطر 31: | ||
==أصناف الوحدة csv== | ==أصناف الوحدة csv== | ||
تقدّم وحدة <code>csv</code> الأصناف التالية: | تقدّم وحدة <code>csv</code> الأصناف التالية: | ||
===الصنف <code>csv.DictReader</code>=== | ===الصنف <code>[[Python/DictReader|csv.DictReader]]</code>=== | ||
===الصنف <code>csv.DictWriter</code>=== | تنشئ الدالة البانية لهذا الصنف كائنًا يعمل كقارئ عادي ولكنّه يربط المعلومات في كل سطر بقاموس مرتّب <code>[[Python/OrderedDict|OrderedDict]]</code> . | ||
===الصنف <code>[[Python/DictWriter|csv.DictWriter]]</code>=== | |||
تنشئ الدالة البانية لهذا الصنف كائنًا يعمل ككاتب عاديٍّ ولكنّه يربط القواميس بالأسطر الموجودة في ملف csv. | |||
===الصنف <code>csv.Dialect</code>=== | ===الصنف <code>csv.Dialect</code>=== | ||
الصنف <code>Dialect</code> هو صنف حاوٍ container class ويُستخدم عادة من أجل الخصائص التي يقدّمها والتي يمكن الاستفادة منها لتعريف المعاملات بنسخة معيّنة صنف الكتابة أو القراءة. | الصنف <code>Dialect</code> هو صنف حاوٍ container class ويُستخدم عادة من أجل الخصائص التي يقدّمها والتي يمكن الاستفادة منها لتعريف المعاملات بنسخة معيّنة صنف الكتابة أو القراءة. | ||
| سطر 88: | سطر 92: | ||
إن أخذت هذه الخاصية القيمة <code>True</code> فإنّ الوحدة ستطلق الاستثناء <code>Error</code> عند التعامل مع مدخلات <code>CSV</code> معطوبة. القيمة الافتراضية هي <code>False</code>. | إن أخذت هذه الخاصية القيمة <code>True</code> فإنّ الوحدة ستطلق الاستثناء <code>Error</code> عند التعامل مع مدخلات <code>CSV</code> معطوبة. القيمة الافتراضية هي <code>False</code>. | ||
==كائنات القراءة Reader objects== | ==كائنات القراءة Reader objects== | ||
كائنات القراءة هي نسخ الصنف DictReader وتنشأ كذلك من الدالة [[Python/csv/reader|<code>reader()</code>]]. | كائنات القراءة هي نسخ الصنف <code>[[Python/DictReader|DictReader]]</code> وتنشأ كذلك من الدالة [[Python/csv/reader|<code>reader()</code>]]. | ||
تمتلك كائنات القراءة (نسخ الصنف <code>DictReader</code> والكائنات المعادة من الدالة ) التوابع العامة التالية: | تمتلك كائنات القراءة (نسخ الصنف [[Python/DictReader|<code>DictReader</code>]] والكائنات المعادة من الدالة ) التوابع العامة التالية: | ||
===التابع <code>csvreader.__next__()</code>=== | ===التابع <code>csvreader.__next__()</code>=== | ||
يعيد التابع السطر التالي في كائن المكرّر الخاص بكائن القراءة على هيئة [[Python/list|قائمة]] (إن كان الكائن معادًا من الدالة <code>[[Python/csv/reader|reader()]]</code>) أو [[Python/dict|قاموس]] (إن كان الكائن نسخة من الصنف <code>DictReader</code>) وتكون القيمة المعادة مفسّرة بحسب اللهجة المستخدمة. يُستدعى هذا التابع عادة بهذه الطريقة <code>next(reader)</code>. | يعيد التابع السطر التالي في كائن المكرّر الخاص بكائن القراءة على هيئة [[Python/list|قائمة]] (إن كان الكائن معادًا من الدالة <code>[[Python/csv/reader|reader()]]</code>) أو [[Python/dict|قاموس]] (إن كان الكائن نسخة من الصنف [[Python/DictReader|<code>DictReader</code>]]) وتكون القيمة المعادة مفسّرة بحسب اللهجة المستخدمة. يُستدعى هذا التابع عادة بهذه الطريقة <code>next(reader)</code>. | ||
تمتلك كائنات القراءة الخصائص العامة التالية: | تمتلك كائنات القراءة الخصائص العامة التالية: | ||
| سطر 104: | سطر 108: | ||
عدد الأسطر المقروءة من المكرِّر المصدر. يختلف هذا العدد عن عدد السجلّات المعادة، إذ يمكن للسجل الواحد أن يمتدّ لعدّة أسطر. | عدد الأسطر المقروءة من المكرِّر المصدر. يختلف هذا العدد عن عدد السجلّات المعادة، إذ يمكن للسجل الواحد أن يمتدّ لعدّة أسطر. | ||
تمتلك كائنات <code>DictReader</code> الخصائص العامة التالية: | تمتلك كائنات [[Python/DictReader|<code>DictReader</code>]] الخصائص العامة التالية: | ||
<code>csvreader.fieldnames</code> | <code>csvreader.fieldnames</code> | ||
| سطر 110: | سطر 114: | ||
إن لم تمرّر هذه الخاصية كمعامل عند إنشاء الكائن، فإنّ هذه الخاصية تُهيّئ عند الوصول إليها لأول مرّة أو عند قراءة أول سجلّ من الملف. | إن لم تمرّر هذه الخاصية كمعامل عند إنشاء الكائن، فإنّ هذه الخاصية تُهيّئ عند الوصول إليها لأول مرّة أو عند قراءة أول سجلّ من الملف. | ||
==كائنات الكتابة Writer Objects== | ==كائنات الكتابة Writer Objects== | ||
تمتلك كائنات الكتابة (نسخ من الصنف <code>DictWriter</code> والكائنات المعادة من الدالة <code>[[Python/csv/writer|writer()]]</code>) التوابع العامة التالية. | تمتلك كائنات الكتابة (نسخ من الصنف [[Python/DictWriter|<code>DictWriter</code>]] والكائنات المعادة من الدالة <code>[[Python/csv/writer|writer()]]</code>) التوابع العامة التالية. | ||
يجب أن يكون الصف <code>row</code> كائنًا قابلًا للتكرار من [[Python/str|السلاسل النصية]] او الأرقام عند استخدام كائنات <code>Writer</code> وأن يكون [[Python/dict|قاموسًا]] يربط أسماء الحقول <code>fieldnames</code> بسلاسل نصية أو أرقام (عن طريق تمريرها عبر الدالة <code>[[Python/str|str()]]</code> في البداية) عند استخدام كائنات DictWriter. يجدر التنبيه إلى أنّ الأعداد المركّبة تُحاط بالأقواس، وقد يكون ذلك سببًا في حدوث بعض المشاكل في البرامج الأخرى التي تقرأ ملفات CSV (على فرض أنّها تستطيع التعامل مع الأعداد المركبة). | يجب أن يكون الصف <code>row</code> كائنًا قابلًا للتكرار من [[Python/str|السلاسل النصية]] او الأرقام عند استخدام كائنات <code>Writer</code> وأن يكون [[Python/dict|قاموسًا]] يربط أسماء الحقول <code>fieldnames</code> بسلاسل نصية أو أرقام (عن طريق تمريرها عبر الدالة <code>[[Python/str|str()]]</code> في البداية) عند استخدام كائنات <code>[[Python/DictWriter|DictWriter]]</code>. يجدر التنبيه إلى أنّ الأعداد المركّبة تُحاط بالأقواس، وقد يكون ذلك سببًا في حدوث بعض المشاكل في البرامج الأخرى التي تقرأ ملفات CSV (على فرض أنّها تستطيع التعامل مع الأعداد المركبة). | ||
=== التابع <code>csvwriter.writerow( | === التابع <code>csvwriter.writerow()</code> === | ||
يكتب التابع | يكتب التابع السطر المعطى في كائن الملف الخاص بكائن القراءة، ويُنسّق السطر بالاعتماد على اللهجة المستخدمة. | ||
'''ملاحظة:''' أضيف دعم كائنات التكرار بمختلف أنواعها في الإصدار 3.5 من بايثون. | '''ملاحظة:''' أضيف دعم كائنات التكرار بمختلف أنواعها في الإصدار 3.5 من بايثون. | ||
=== التابع <code>csvwriter.writerows( | === التابع <code>csvwriter.writerows()</code> === | ||
يكتب التابع جميع العناصر في الصفوف المعطاة (كائن تكرار يتضمّن كائنات row) في كائن الملف الخاص بكائن الكتابة، وتنسق العناصر بالاعتماد على اللهجة المستخدمة. | يكتب التابع جميع العناصر في الصفوف المعطاة (كائن تكرار يتضمّن كائنات <code>row</code>) في كائن الملف الخاص بكائن الكتابة، وتنسق العناصر بالاعتماد على اللهجة المستخدمة. | ||
تمتلك كائنات الكتابة الخصائص العامة التالية: | تمتلك كائنات الكتابة الخصائص العامة التالية: | ||
مراجعة 20:51، 26 نوفمبر 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().
تمتلك كائنات القراءة (نسخ الصنف DictReader والكائنات المعادة من الدالة ) التوابع العامة التالية:
التابع 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()
يكتب التابع السطر المعطى في كائن الملف الخاص بكائن القراءة، ويُنسّق السطر بالاعتماد على اللهجة المستخدمة.
ملاحظة: أضيف دعم كائنات التكرار بمختلف أنواعها في الإصدار 3.5 من بايثون.
التابع csvwriter.writerows()
يكتب التابع جميع العناصر في الصفوف المعطاة (كائن تكرار يتضمّن كائنات row) في كائن الملف الخاص بكائن الكتابة، وتنسق العناصر بالاعتماد على اللهجة المستخدمة.
تمتلك كائنات الكتابة الخصائص العامة التالية:
csvwriter.dialect
هذه الخاصية للقراءة فقط، وتتضمن وصفًا للهجة المستخدمة بواسطة كائن الكتابة.
تمتلك كائنات DictWriter التوابع العامة التالية:
التابع DictWriter.writeheader()
يكتب التابع صفًّا مع أسماء الحقول (كما هو محدّد في الدالة البانية).
ملاحظة: هذا التابع جديد في الإصدار 3.2.