أساسيات بايثون 29: شرح مكتبة json في Python للمبتدئين

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

في هذا الدرس من كورس أساسيات بايثون سنشرح مكتبة json في Python بطريقة مناسبة للمبتدئين. سنتعلم ما معنى JSON، وكيف نحول Dictionary إلى JSON، وكيف نقرأ ونكتب ملفات JSON، وما الفرق بين dump و dumps، وبين load و loads.

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

الفكرة ببساطة: JSON طريقة منظمة لحفظ البيانات، ومكتبة json في Python تساعدك على تحويل البيانات بين كائنات Python وملفات JSON بسهولة. {alertInfo}

ما هو 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"}

قد يبدوان متشابهين، لكن Python يحتاج مكتبة 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	ملف

طريقة تذكر سهلة: إذا كان الاسم فيه حرف s مثل dumps و loads فهو يتعامل مع النصوص، أما dump و load فيتعاملان مع الملفات. {alertSuccess}

تحويل 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. هذا ليس خطأ، لكن القراءة تصبح مزعجة.

مثال:

import json

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

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

print(json_text)

الناتج:

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

الخيار ensure_ascii=False مهم جدًا إذا كنت تتعامل مع بيانات عربية.

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

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

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

بعد استخدام loads أصبح بإمكانك التعامل مع البيانات كأنها Dictionary عادي في Python.

الفرق بين dumps و loads

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

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

حتى الآن تعاملنا مع نص JSON داخل البرنامج. الآن سنكتب البيانات في ملف حقيقي. لكتابة بيانات Python داخل ملف JSON نستخدم json.dump().

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 يمكنك التعامل معه بشكل طبيعي.

الفرق بين 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

file_path = Path("data") / "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)

هذا الأسلوب مناسب جدًا بعد أن تبدأ بتنظيم ملفات مشروع Python.

ما أنواع بيانات 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 في 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. محاولة تحويل نوع غير مدعوم مباشرة

بعض الأنواع مثل 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"])

تدريب عملي

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

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"])

روابط داخلية مفيدة من بايثون العرب

• كورس أساسيات بايثون للمبتدئين
• أساسيات بايثون 22: التعامل مع الملفات في Python
• تنظيم ملفات مشروع Python بعد الأساسيات
• حل خطأ FileNotFoundError في Python عند فتح الملفات
• شرح مكتبة pathlib في Python للمبتدئين

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

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

الخلاصة

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

إذا كنت تتعامل مع نصوص عربية، لا تنس استخدام encoding="utf-8" عند فتح الملفات، و 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.