قراءة قائمة المستلمين من ملف

1. فهم تنسيق CSV والتعامل معه

ملفات CSV (اختصار لـ Comma-Separated Values أو "القيم المفصولة بفواصل") هي واحدة من أبسط الطرق لتخزين البيانات الجدولية. تخيل جدول بيانات بسيط في Excel، ولكن محفوظ كملف نصي عادي، حيث يمثل كل سطر صفًا في الجدول، وتفصل الفواصل بين الخلايا.

على سبيل المثال، يمكن أن تبدو قائمة المستلمين لدينا في ملف recipients.csv بهذا الشكل:

name,email,city
أحمد,ahmad@example.com,الرياض
فاطمة,fatima@example.com,جدة
يوسف,youssef@example.com,دبي

لغة بايثون توفر مكتبة مدمجة اسمها csv تجعل قراءة هذه الملفات والتعامل معها أمرًا سهلاً وآمنًا، وتتجنب المشاكل التي قد تحدث عند محاولة تقسيم السطور يدويًا (على سبيل المثال، ماذا لو كان أحد الحقول يحتوي على فاصلة؟).

الفيديو التالي يقدم شرحًا ممتازًا لكيفية استخدام مكتبة csv في بايثون.

كما رأيت في الفيديو، استخدام csv.DictReader هو الطريقة المثلى لنا. لماذا؟ لأنه يقرأ كل سطر في الملف كقاموس (Dictionary)، ويستخدم الصف الأول (الترويسة أو Header) كمفاتيح للقاموس. هذا يجعل الكود أكثر وضوحًا وقابلية للصيانة، حيث يمكنك الوصول إلى البيانات باستخدام أسماء ذات معنى مثل row['email'] بدلاً من الفهارس الرقمية المبهمة مثل row[1].

للحصول على شرح نصي مفصل باللغة العربية، يمكنك مراجعة المقال التالي من أكاديمية حسوب.

2. فهم تنسيق JSON والتعامل معه

تنسيق JSON (اختصار لـ JavaScript Object Notation) هو تنسيق شائع آخر لتبادل البيانات، وهو مفضل بشكل خاص في واجهات برمجة التطبيقات (APIs). يعتمد على بنية "مفتاح-قيمة" (key-value) تشبه إلى حد كبير قواميس بايثون.

نفس قائمة المستلمين السابقة يمكن تمثيلها في ملف recipients.json بهذا الشكل:

[
  {
    "name": "أحمد",
    "email": "ahmad@example.com",
    "city": "الرياض"
  },
  {
    "name": "فاطمة",
    "email": "fatima@example.com",
    "city": "جدة"
  },
  {
    "name": "يوسف",
    "email": "youssef@example.com",
    "city": "دبي"
  }
]

هل تلاحظ التشابه؟ هذا الهيكل هو عبارة عن قائمة (list) من القواميس (dictionaries)، وهو نفس الهيكل الذي نسعى للحصول عليه من ملفات CSV! هذه الميزة تجعل التعامل مع JSON في بايثون سهلاً للغاية باستخدام مكتبة json المدمجة.

شاهد هذا المقطع القصير لترى كيف يتم ذلك.

بسطرين فقط، يمكننا قراءة ملف JSON بأكمله وتحويله إلى بنية بيانات بايثون أصلية، جاهزة للاستخدام الفوري.

3. بناء أداة قراءة الملفات

الآن، دعنا نجمع ما تعلمناه لبناء دالة ذكية يمكنها قراءة قائمة المستلمين بغض النظر عما إذا كانت مخزنة في ملف CSV أو JSON. سنضيف هذه الدالة إلى ملف tools.py الذي أنشأناه في الدرس السابق.

ستقوم الدالة بالخطوات التالية:

1. تستقبل مسار الملف كمدخل.
2. تتحقق من امتداد الملف (.csv أو .json).
3. تستخدم الطريقة المناسبة لقراءة الملف بناءً على امتداده.
4. تعالج الأخطاء المحتملة، مثل عدم العثور على الملف.
5. تعيد البيانات دائمًا بنفس التنسيق: قائمة من القواميس.

افتح ملف tools.py وأضف الكود التالي إليه:

# tools.py
# (الكود السابق الخاص بـ send_email موجود هنا)
# ...

import csv # استيراد مكتبة CSV
import json # استيراد مكتبة JSON

def read_recipients_from_file(file_path):
    """
    تقرأ قائمة المستلمين من ملف CSV أو JSON.

    :param file_path: مسار الملف (e.g., 'data/recipients.csv').
    :return: قائمة من القواميس، حيث يمثل كل قاموس مستلمًا.
             تعيد قائمة فارغة في حالة حدوث خطأ.
    """
    recipients = []
    try:
        # التحقق من امتداد الملف لتحديد كيفية القراءة
        if file_path.endswith('.csv'):
            with open(file_path, mode='r', encoding='utf-8') as file:
                reader = csv.DictReader(file)
                for row in reader:
                    recipients.append(dict(row))
        
        elif file_path.endswith('.json'):
            with open(file_path, mode='r', encoding='utf-8') as file:
                recipients = json.load(file)
        
        else:
            print(f"خطأ: تنسيق الملف غير مدعوم: {file_path}. يرجى استخدام .csv أو .json.")
            return []
            
    except FileNotFoundError:
        print(f"خطأ: لم يتم العثور على الملف في المسار: {file_path}")
        return []
    except Exception as e:
        print(f"حدث خطأ غير متوقع أثناء قراءة الملف: {e}")
        return []
        
    print(f"تم بنجاح قراءة {len(recipients)} مستلم من ملف {file_path}")
    return recipients

# --- قسم الاختبار ---
# يمكنك استخدام هذا الجزء لاختبار الدالة الجديدة
if __name__ == "__main__":
    # --- اختبار دالة إرسال البريد (من الدرس السابق) ---
    # print("بدء اختبار إرسال البريد...")
    # send_email("test@example.com", "Subject", "Body")
    
    # --- اختبار دالة قراءة المستلمين (الجديدة) ---
    print("\n--- بدء اختبار قراءة الملفات ---")
    
    # أنشئ هذه الملفات للاختبار
    recipients_csv = read_recipients_from_file('recipients.csv')
    if recipients_csv:
        print("البيانات من ملف CSV:")
        print(recipients_csv)

    print("-" * 20)

    recipients_json = read_recipients_from_file('recipients.json')
    if recipients_json:
        print("البيانات من ملف JSON:")
        print(recipients_json)

    print("-" * 20)
    
    # اختبار ملف غير موجود
    read_recipients_from_file('non_existent_file.txt')

للتحضير للاختبار:

1. في نفس المجلد الذي يوجد به ملف tools.py، أنشئ ملفًا جديدًا باسم recipients.csv والصق المحتوى التالي فيه:

   name,email,city
   أحمد,ahmad@example.com,الرياض
   فاطمة,fatima@example.com,جدة
   

2. أنشئ ملفًا آخر باسم recipients.json والصق المحتوى التالي فيه:

   [
     {
       "name": "يوسف",
       "email": "youssef@example.com",
       "city": "دبي"
     },
     {
       "name": "نورة",
       "email": "noura@example.com",
       "city": "الدمام"
     }
   ]
   

3. الآن، قم بتشغيل ملف tools.py من الطرفية:

   python tools.py
   

يجب أن ترى مخرجات تؤكد قراءة البيانات بنجاح من كلا الملفين، بالإضافة إلى رسالة خطأ عند محاولة قراءة ملف غير موجود، مما يثبت أن معالجة الأخطاء لدينا تعمل بشكل صحيح!

with open(file_path, mode='r', encoding='utf-8') as file:
    # نحدد أن الفاصل هو tab
    reader = csv.DictReader(file, delimiter='\t') 
    for row in reader:
        recipients.append(dict(row))

خلاصة الدرس

لقد قطعنا شوطًا مهمًا آخر في بناء مشروعنا. في هذا الدرس:

• تعلمنا أساسيات تنسيقي البيانات CSV و JSON.
• استكشفنا مكتبات بايثون المدمجة (csv و json) لقراءة هذه الملفات بكفاءة.
• أعطينا الأولوية لقراءة البيانات في هيكل منظم (قائمة من القواميس) باستخدام csv.DictReader.
• قمنا ببناء أداة مرنة (read_recipients_from_file) يمكنها التعامل مع كلا التنسيقين، معالجة الأخطاء، وإرجاع البيانات بشكل متسق.

الآن، يمتلك وكيلنا "ذراعًا" للتصرف (send_email) و"عينًا" للإدراك (read_recipients_from_file). لقد أصبح جاهزًا لتلقي التعليمات ومعالجة البيانات.

ماذا بعد؟

بعد أن جهزنا الأدوات، حان الوقت لتشغيل "العقل". في الدرس القادم، سنبدأ بالجزء الأكثر إثارة: "تطوير منطق الوكيل لاستخدام LLM في تخصيص محتوى البريد لكل مستلم". سنقوم بربط الأدوات التي بنيناها مع نموذج لغوي كبير (LLM)، وسنرى كيف يمكن للوكيل أن يقرأ قائمة المستلمين، ويفكر، ثم يكتب رسالة مخصصة لكل شخص قبل استخدام أداة إرسال البريد. استعد لترى وكيلك يبدأ في "التفكير" لأول مرة