في إطار شرح مفاهيم بايثون بالعربي نُقدم لكم في هذا المقال شرحاً مبسطاً لأحد المكتبات. يندرج ما تقدمه هذه المكتبة تحت عنوان أتمتة المهام الدورية  Automate The Boring Stuff و تطبيقات البايثون .

المكتبة python-docx وهدفها منح المقدرة على التعامل مع ملفات المحرر النصي المشهور Microsoft Word من حيث الإنشاء، والتعديل، والعمليات الأخرى.

تأتي المكتبة في إطار معالجة النصوص بالبايثون  (Text Processing in Python) .

تثبيت مكتبة python-docx

مكتبة python-docx موجودة في مستودع المكتبات الخاص بلغة البايثون PyPI، وتثبيت المكتبة يُعد أمرا بسيطًا وذلك عبر استخدام أداة pip. يُمكن تثبيت المكتبة عبر تنفيذ الأمر التالي في شاشة الأوامر:

 pip install python-docx

سوف نقوم بشرح مثال لبناء ملف Microsoft Word بحيث يكون الملف النهائي بالشكل التالي:

تطبيقات البايثون في تحرير النصوص

لنبدأ في الجزء العملي مباشرة عبر استيراد المكتبات التي سنحتاجها في العمل بالشكل التالي:

from docx import Document
from docx.shared import Inches
import collections

نُعرف كائن من الفئة Document. هذا الكائن سيمثل ملف الوورد الذي سنبنيه بشكل برمجي باستخدام البايثون:

document = Document()

لإضافة عنوان في بداية الملف في الصفحة الأولى نستخدم دالة add_heading ونمرر لها العنوان الذي نريد ومستوى العنوان (من 0 إلى 9) بالشكل التالي:

document.add_heading('Document Title', 0)

لإضافة فقرة تلي العنوان السابق نستخدام الدالة add_paragraph ونمرر لها النص الذي نريده:

p = document.add_paragraph('A plain paragraph having some ')

لاحظ أن الدالة تقوم بإرجاع كائن من نوع Paragraph، بعد ذلك نقوم بتنسيق هذه الفقرة باستخدام الكائن الناتج من دالة الإضافة بالشكل التالي:

p.add_run('bold').bold = True
p.add_run(' and some ')
p.add_run('italic.').italic = True

لاضافة النص Heading, level 1 كعنوان بمستوى رقم 1:

document.add_heading('Heading, level 1', level=1)

اضافة فقرة

بعد إضافة العنوان بمستوى رقم 1، نُضيف فقرة ذات تنسيق من نوع إقتباس مكثف (Instance Quote) بإستخدام دالة add_paragraph ونمرر نص الفقرة، ونوع النمط:

document.add_paragraph('Intense quote', style='Intense Quote')

لإضافة نص ضمن قائمة غير مرتبة، نستخدم نفس الدالة السابقة، ولكن نُغير نوع التنسيق إلى List Bullet بالطريقة التالية:

document.add_paragraph('first item in unordered list',style='List Bullet')

لإضافة نص ضمن قائمة مرتبة من نوع رقم نستخدم نوع النمط List Number :

document.add_paragraph('first item in ordered list',style='List Number')

لإضافة صورة، نستخدم الدالة add_picture ونمرر لها إسم الصورة التي نريد إضافتها على الملف، ونحدد الأبعاد التي نريدها للصورة:

document.add_picture('python.jpg', width=Inches(1.25))

لإضافة جدول على الملف، نستخدم دالة add_table ونحدد عدد الصفوف والأعمدة الخاصة بالجدول:

table = document.add_table(rows=1, cols=3)

نحصل على صفوف الجدول بإستخدام خاصية rows والتي هي عبارة عن مصفوفة تحتوي على مصفوفات تُمثل صفوف الجدول، فللحصول مثلًا على الصف الأول نكتب table.rows[0], والصف الثاني table.rows[1], وهكذا.

كل صف يحتوي على خلايا يتم الوصول إليها عبر خاصية cells والتي هي أيضًا عبارة عن مصفوفة تحتوي هذه الخلايا، فللحصول على خلايا الصف الأول نكتب table.rows[0].cells.

hdr_cells = table.rows[0].cells

لتعديل قيمة الخلية الأولى في الصف الأول لتصبح Qty نكتب السطر التالي:

hdr_cells[0].text = 'Qty'

وبنفس الطريقة للخلية الثانية والثالثة:

hdr_cells[1].text = 'Id'
hdr_cells[2].text = 'Desc'

في الخطوات السابقة، عدلنا قيم الصف الأول من الجدول لتُعبر عن عناوين الجدول، الان نحتاج إلى إضافة البيانات للجدول.

نُعرف كائن من فئة Named Tuple ونُحدد إسمها بـ Record ونُحدد أسماء خصائصها الداخلية بالطريقة التالية:

Record = collections.namedtuple("Record", "qty id desc")

نقوم ببناء مصفوفة تحتوي على عناصر من نوع Record السابق، والتي تحتوي بدورها على البيانات التي نريدها:

recordset = [Record(id=1,qty=10,desc="Pythons"),                                      Record(id=2,qty=15,desc="Pythons"),                                      Record(id=3,qty=30,desc="Pythons")]

لاضافة البيانات الموجودة في recordset لابد من المرور عليها واضافتها على الجدول بشكل متتابع. نحتاج لذلك جملة تكرارية for loop مع استخدام دالة الاضافة على الجدول add_row عند كل اضافة:

for item in recordset:
    row_cells = table.add_row().cells
    row_cells[0].text = str(item.qty)
    row_cells[1].text = str(item.id)
    row_cells[2].text = item.desc

لإضافة صفحة فاصلة نستخدم دالة add_page_break كالتالي:

document.add_page_break()

إلى هذا الحد، فإن الملف الذي أنشأناه موجود في الذاكرة الخاصة بجلسة العمل. لحفظ الملف كملف Microsoft Word نستخدم دالة save ونمرر لها إسم الملف الذي نريده والمسار الخاص به.

document.save('demo.docx')

خلاصة

قدمنا لكم في هذا المقال نبذة عن مكتبة python-docx والتي تُعطي القدرة اللازمة للتعامل مع الملفات النصية المنسقة من نوع Mircrosoft Word.

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