شرح JSON في بايثون: قراءة وكتابة الملفات | أساسيات بايثون 29

مكتبة json في بايثون هي الأداة القياسية لتحويل بيانات مثل dict وlist إلى JSON والعكس. إذا أردت حفظ إعدادات برنامج، تخزين بيانات بسيطة، أو قراءة بيانات JSON من ملف أو خدمة خارجية، فستستخدم غالبًا أربع دوال: dumps() لتحويل بيانات بايثون إلى نص JSON، وloads() لقراءة JSON موجود داخل البرنامج، وdump() للكتابة إلى ملف، وload() للقراءة من ملف.

JSON ليست هي Dictionary نفسها رغم تشابه الشكل؛ JSON صيغة نصية لها قواعدها، بينما القاموس كائن داخل بايثون. في هذا الدرس من أساسيات بايثون 29 ستتعلم الفرق بين الدوال الأربع، قراءة وكتابة ملفات JSON، التعامل مع العربية، وتحويل الأنواع الشائعة بأمثلة عملية للمبتدئين.

الفكرة ببساطة: استخدم dumps() وloads() عندما تتعامل مع JSON داخل البرنامج، واستخدم dump() وload() عندما تتعامل مع ملف. {alertInfo}

{getToc} $title={محتوى المقال}

ما هو JSON؟

كلمة JSON اختصار لـ JavaScript Object Notation. لا تقلق من الاسم؛ فأنت لا تحتاج إلى تعلم JavaScript حتى تستخدم JSON في Python. الفكرة ببساطة أن JSON صيغة نصية منظمة لتخزين البيانات.

مثال على بيانات JSON:

{
  "name": "Ali",
  "age": 25,
  "city": "Aden"
}

إذا لاحظت المثال، ستجد أن شكله قريب جدًا من Dictionary في Python. لذلك التعامل مع JSON في بايثون سهل ومناسب جدًا للمبتدئين.

لماذا نستخدم JSON في Python؟

نستخدم JSON عندما نريد حفظ بيانات منظمة أو نقلها من مكان إلى آخر. بدل أن تحفظ البيانات كنص عادي يصعب التعامل معه، يمكنك حفظها بصيغة منظمة يسهل قراءتها لاحقًا.

أمثلة على استخدام JSON:

• حفظ بيانات مستخدم داخل برنامج بسيط.
• حفظ إعدادات تطبيق صغير.
• قراءة بيانات من ملف خارجي.
• تبادل البيانات مع APIs.
• حفظ قائمة مهام أو منتجات أو نتائج.
• استخدامه في مشاريع بايثون الصغيرة بعد الأساسيات.

هل JSON مثل Dictionary في Python؟

JSON يشبه Dictionary من حيث الشكل، لكن هناك فرق مهم: Dictionary هو كائن داخل Python، أما JSON فهو نص منظم يمكن حفظه في ملف أو إرساله عبر الإنترنت.

العنصر	المعنى	مثال
Dictionary	نوع بيانات داخل Python	{"name": "Ali"}
JSON	نص منظم يمكن حفظه أو نقله	{"name": "Ali"}

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

استيراد مكتبة json

مكتبة json تأتي مع Python، لذلك لا تحتاج إلى تثبيتها باستخدام pip. كل ما عليك فعله هو استيرادها:

import json

بعد الاستيراد يمكنك استخدام الدوال المهمة داخل المكتبة مثل:

• json.dumps()
• json.loads()
• json.dump()
• json.load()

الدوال الأساسية في مكتبة json

قبل الدخول في الأمثلة، هذه أهم دوال مكتبة json التي ستستخدمها كثيرًا:

الدالة	وظيفتها	تتعامل مع
json.dumps()	تحويل بيانات Python إلى نص JSON	نص داخل البرنامج
json.loads()	تحويل نص JSON إلى بيانات Python	نص داخل البرنامج
json.dump()	كتابة بيانات Python داخل ملف JSON	ملف
json.load()	قراءة بيانات JSON من ملف وتحويلها إلى Python	ملف

طريقة تذكر سهلة: dumps() تعيد JSON على شكل str، وloads() تقرأ JSON موجودًا في الذاكرة — وغالبًا يكون نصًا. أما dump() وload() فتتعاملان مع كائن ملف. استخدم حرف s كتذكير عملي، لا كقاعدة لغوية رسمية. {alertSuccess}

ستقابل أيضًا مصطلحين مهمين في التوثيق: Serialization وتعني تحويل كائنات Python إلى JSON باستخدام dump() أو dumps()، وDeserialization وتعني تحويل JSON إلى كائنات Python باستخدام load() أو loads().

تحويل Dictionary إلى JSON باستخدام dumps

إذا كان لديك Dictionary في Python وتريد تحويله إلى نص JSON، استخدم json.dumps().

import json

user = {
    "name": "Ali",
    "age": 25,
    "city": "Aden"
}

json_text = json.dumps(user)

print(json_text)

الناتج:

{"name": "Ali", "age": 25, "city": "Aden"}

لاحظ أن الناتج أصبح نصًا بصيغة JSON.

جعل JSON أوضح باستخدام indent

الناتج السابق صحيح، لكنه في سطر واحد. لجعله أوضح وأسهل للقراءة، استخدم الخيار indent.

import json

user = {
    "name": "Ali",
    "age": 25,
    "city": "Aden"
}

json_text = json.dumps(user, indent=4)

print(json_text)

الناتج سيكون منسقًا بهذا الشكل:

{
    "name": "Ali",
    "age": 25,
    "city": "Aden"
}

استخدام indent=4 يجعل الملف أو النص أسهل في القراءة، خصوصًا عندما تكون البيانات كثيرة.

حل مشكلة ظهور الحروف العربية بشكل غريب

إذا كتبت بيانات عربية واستخدمت json.dumps() بالإعدادات الافتراضية، فقد تظهر الحروف غير اللاتينية بصيغة هروب مثل \u0645. هذا JSON صحيح وسيعود إلى النص العربي عند فكّه، لكنه أقل وضوحًا عند فتح الملف أو قراءة الناتج يدويًا.

مثال:

import json

user = {
    "name": "علي",
    "city": "عدن"
}

json_text = json.dumps(user, ensure_ascii=False, indent=4)

print(json_text)

الناتج:

{
    "name": "علي",
    "city": "عدن"
}

استخدم ensure_ascii=False عندما تريد أن تظهر الحروف العربية مباشرة وبشكل مقروء داخل JSON. هذا الخيار يحسن قابلية القراءة البشرية، لكنه ليس شرطًا حتى تكون البيانات العربية صحيحة. وعند حفظ ملف JSON نصي، افتحه بترميز utf-8.

تحويل نص JSON إلى بيانات Python باستخدام loads

إذا كان لديك نص JSON وتريد تحويله إلى كائن مناسب داخل Python، استخدم json.loads(). إذا كان جذر JSON كائنًا فستحصل غالبًا على dict، وإذا كان مصفوفة فستحصل على list؛ لذلك لا تفترض أن نتيجة loads() ستكون Dictionary دائمًا.

import json

json_text = '{"name": "Ali", "age": 25, "city": "Aden"}'

user = json.loads(json_text)

print(user)
print(user["name"])

الناتج:

{'name': 'Ali', 'age': 25, 'city': 'Aden'}
Ali

في هذا المثال جذر JSON كائن، لذلك أعادت loads() قاموسًا dict وأصبح بإمكاننا الوصول إلى القيم بالمفاتيح.

الفرق بين dumps و loads

الدالة	من	إلى
dumps	Dictionary أو List في Python	نص JSON
loads	نص JSON	Dictionary أو List في Python

كتابة ملف JSON باستخدام dump

حتى الآن تعاملنا مع نص JSON داخل البرنامج. الآن سنكتب البيانات في ملف حقيقي. لكتابة بيانات Python داخل ملف JSON نستخدم json.dump(). وإذا كانت أوضاع فتح الملفات وعبارة with open(...) جديدة عليك، راجع أساسيات بايثون 22: قراءة وكتابة الملفات.

import json

user = {
    "name": "Ali",
    "age": 25,
    "city": "Aden"
}

with open("user.json", "w", encoding="utf-8") as file:
    json.dump(user, file, ensure_ascii=False, indent=4)

بعد تشغيل الكود، سيتم إنشاء ملف اسمه user.json يحتوي على البيانات.

قراءة ملف JSON باستخدام load

لقراءة ملف JSON وتحويله إلى بيانات Python، نستخدم json.load().

import json

with open("user.json", "r", encoding="utf-8") as file:
    user = json.load(file)

print(user)
print(user["name"])

بعد القراءة، يصبح المتغير user عبارة عن Dictionary يمكنك التعامل معه بشكل طبيعي.

إذا كان الملف غير موجود فستواجه FileNotFoundError، وإذا كان موجودًا لكن JSON داخله غير صالح فقد يظهر JSONDecodeError. لكل خطأ سبب مختلف، لذلك افحص رسالة الخطأ قبل تعديل الكود.

الفرق بين dump و dumps

الدالة	الاستخدام	مثال
json.dump()	تكتب JSON داخل ملف	json.dump(data, file)
json.dumps()	تعيد JSON كنص داخل البرنامج	text = json.dumps(data)

الفرق بين load و loads

الدالة	الاستخدام	مثال
json.load()	تقرأ JSON من ملف	data = json.load(file)
json.loads()	تقرأ JSON من نص	data = json.loads(text)

ملخص سريع: وجود حرف s في نهاية الدالة يعني أنها تتعامل مع نص JSON داخل البرنامج، وليس مع ملف مباشرة. {alertInfo}

مثال عملي: حفظ قائمة طلاب في JSON

لنفترض أننا نريد حفظ قائمة طلاب داخل ملف JSON. كل طالب سيكون عبارة عن Dictionary، وجميع الطلاب داخل List.

import json

students = [
    {"name": "Ali", "grade": 90},
    {"name": "Sara", "grade": 85},
    {"name": "Omar", "grade": 78}
]

with open("students.json", "w", encoding="utf-8") as file:
    json.dump(students, file, ensure_ascii=False, indent=4)

مثال عملي: قراءة الطلاب من ملف JSON

import json

with open("students.json", "r", encoding="utf-8") as file:
    students = json.load(file)

for student in students:
    print(student["name"], "-", student["grade"])

الناتج:

Ali - 90
Sara - 85
Omar - 78

هذا المثال يوضح لماذا JSON مهم في المشاريع العملية؛ لأنه يسمح لك بحفظ البيانات ثم الرجوع إليها لاحقًا.

استخدام pathlib مع ملفات JSON

في المشاريع المنظمة، من الأفضل وضع ملفات البيانات داخل مجلد مثل data. ويمكنك استخدام مكتبة pathlib في بايثون لبناء المسارات بوضوح. وإذا كان المجلد قد لا يكون موجودًا، أنشئه قبل محاولة كتابة الملف.

import json
from pathlib import Path

data_dir = Path("data")
data_dir.mkdir(exist_ok=True)

file_path = data_dir / "settings.json"

settings = {
    "theme": "dark",
    "language": "Arabic"
}

with file_path.open("w", encoding="utf-8") as file:
    json.dump(settings, file, ensure_ascii=False, indent=4)

هذا الأسلوب مناسب بعد أن تبدأ بتنظيم ملفات مشروع بايثون؛ لأنه يفصل بيانات المشروع عن ملفات الكود ويمنع فشل المثال إذا لم يكن مجلد data موجودًا مسبقًا.

ما أنواع بيانات Python التي تتحول إلى JSON؟

في Python	في JSON
dict	object
list	array
str	string
int و float	number
True	true
False	false
None	null

لاحظ أن True في Python تصبح true في JSON، و None تصبح null.

كيف أتعامل مع JSON متداخل Nested JSON؟

قد يحتوي JSON على كائنات أو قوائم داخل بعضها. بعد استخدام json.loads() أو json.load() تتعامل معها كقواميس وقوائم Python عادية، ثم تصل إلى القيم خطوة بخطوة.

import json

json_text = '{"user": {"name": "Ali", "skills": ["Python", "JSON"]}}'

data = json.loads(json_text)

print(data["user"]["name"])
print(data["user"]["skills"][0])

الناتج هو Ali ثم Python. الفكرة المهمة أن JSON المتداخل لا يحتاج مكتبة مختلفة؛ بعد فكّه تستخدم قواعد dict وlist نفسها.

أخطاء شائعة عند استخدام json في Python

1. الخلط بين dump و dumps

إذا أردت الكتابة في ملف استخدم dump. وإذا أردت الحصول على نص JSON داخل البرنامج استخدم dumps.

# يكتب في ملف
json.dump(data, file)

# يرجع نص JSON
text = json.dumps(data)

2. الخلط بين load و loads

إذا أردت القراءة من ملف استخدم load. وإذا أردت قراءة نص JSON داخل البرنامج استخدم loads.

# يقرأ من ملف
data = json.load(file)

# يقرأ من نص
data = json.loads(text)

3. نسيان encoding عند التعامل مع العربية

عند قراءة أو كتابة ملفات تحتوي على نص عربي، استخدم encoding="utf-8" حتى تظهر البيانات بشكل صحيح.

4. نسيان ensure_ascii=False

إذا أردت ظهور النص العربي بشكل طبيعي داخل ملف JSON، استخدم ensure_ascii=False عند الكتابة أو التحويل.

5. قراءة JSON غير صالح

إذا كان النص أو الملف فارغًا أو مكتوبًا بصيغة JSON غير صحيحة، فقد ترفع json.load() أو json.loads() خطأ JSONDecodeError. من الأسباب الشائعة استخدام علامات اقتباس مفردة بدل المزدوجة داخل JSON، أو فاصلة زائدة في آخر عنصر، أو ملف فارغ. لا نوسع إصلاحه هنا حتى لا نخرج عن نية الدرس؛ راجع الدليل المتخصص: حل خطأ JSONDecodeError في بايثون.

6. محاولة تحويل نوع غير مدعوم مباشرة

بعض الأنواع مثل set لا تتحول إلى JSON مباشرة.

import json

numbers = {1, 2, 3}

print(json.dumps(numbers))

قد يظهر خطأ مثل:

TypeError: Object of type set is not JSON serializable

الحل أن تحول set إلى list أولًا:

import json

numbers = {1, 2, 3}
numbers_list = list(numbers)

print(json.dumps(numbers_list))

مثال كامل: برنامج بسيط لحفظ إعدادات المستخدم

هذا مثال يجمع ما تعلمناه. سننشئ إعدادات مستخدم ونحفظها في ملف JSON، ثم نقرأها مرة أخرى.

import json

settings = {
    "username": "Ali",
    "theme": "dark",
    "notifications": True
}

with open("settings.json", "w", encoding="utf-8") as file:
    json.dump(settings, file, ensure_ascii=False, indent=4)

with open("settings.json", "r", encoding="utf-8") as file:
    loaded_settings = json.load(file)

print(loaded_settings["username"])
print(loaded_settings["theme"])

بعد أن تفهم هذا المثال، يمكنك رؤية استخدام JSON داخل برنامج أكبر في مشروع إدارة مخزون ببايثون، حيث تُستخدم ملفات JSON لحفظ البيانات مع معالجة الأخطاء قبل الكتابة. وللمزيد من التطبيق يمكنك اختيار فكرة مناسبة من 100 مشروع بايثون صغير.

تدريب عملي

حاول تنفيذ هذه التمارين بنفسك:

1. أنشئ Dictionary يحتوي على اسمك وعمرك ومدينتك، ثم حوله إلى JSON باستخدام dumps.
2. استخدم indent=4 لجعل JSON منسقًا.
3. احفظ البيانات في ملف باسم profile.json.
4. اقرأ الملف مرة أخرى باستخدام json.load.
5. اطبع قيمة الاسم من الملف بعد قراءته.

حل مختصر للتدريب

import json

profile = {
    "name": "Ali",
    "age": 25,
    "city": "Aden"
}

with open("profile.json", "w", encoding="utf-8") as file:
    json.dump(profile, file, ensure_ascii=False, indent=4)

with open("profile.json", "r", encoding="utf-8") as file:
    loaded_profile = json.load(file)

print(loaded_profile["name"])

مصادر خارجية مفيدة للتوسع

• توثيق Python الرسمي لمكتبة json
• توثيق Python حول حفظ البيانات المنظمة باستخدام JSON

الخلاصة

مكتبة json في Python تساعدك على حفظ البيانات المنظمة وقراءتها بسهولة. يمكنك استخدام dumps لتحويل بيانات Python إلى نص JSON، و loads لتحويل نص JSON إلى بيانات Python. أما عند التعامل مع الملفات، فاستخدم dump للكتابة و load للقراءة.

عند حفظ ملفات JSON استخدم encoding="utf-8". وإذا أردت ظهور العربية مباشرة داخل JSON بدل تحويلها إلى Unicode escapes، أضف ensure_ascii=False عند الكتابة أو التحويل.

الخلاصة العملية: إذا أردت حفظ بيانات منظمة في مشروع Python، فغالبًا سيكون JSON خيارًا مناسبًا وبسيطًا، خصوصًا مع القواميس والقوائم. وبعد تثبيت هذا الدرس يمكنك متابعة كورس أساسيات بايثون بالترتيب. {alertSuccess}

أسئلة شائعة مع إجاباتها

ما هي مكتبة json في Python؟

هي مكتبة مدمجة في Python تستخدم لقراءة وكتابة بيانات JSON وتحويلها من وإلى أنواع بيانات Python مثل Dictionary و List.

هل أحتاج إلى تثبيت مكتبة json؟

لا. مكتبة json تأتي مع Python، لذلك يكفي أن تكتب import json.

ما الفرق بين dump و dumps؟

dump تستخدم للكتابة داخل ملف، أما dumps فتستخدم لتحويل البيانات إلى نص JSON داخل البرنامج.

ما الفرق بين load و loads؟

load تستخدم للقراءة من ملف JSON، أما loads فتستخدم لتحويل نص JSON إلى بيانات Python.

كيف أجعل العربية تظهر بشكل صحيح في JSON؟

استخدم encoding="utf-8" عند فتح الملف، واستخدم ensure_ascii=False عند الكتابة أو التحويل.

هل يمكن حفظ List داخل ملف JSON؟

نعم. يمكنك حفظ قائمة تحتوي على أرقام أو نصوص أو قواميس داخل ملف JSON باستخدام json.dump.

هل JSON يتحول دائمًا إلى Dictionary في بايثون؟

لا. إذا كان جذر JSON كائنًا فغالبًا يتحول إلى dict، وإذا كان مصفوفة فيتحول إلى list. وقد يتحول أيضًا إلى str أو رقم أو bool أو None بحسب القيمة الموجودة في JSON.