قراءة وكتابة JSON في Python: الفرق بين load وloads وdump وdumps

عند التعامل مع JSON في Python ستقابل أربع دوال متشابهة في الاسم: json.load() وjson.loads() وjson.dump() وjson.dumps(). التشابه بينها يجعلها مربكة للمبتدئ، لكن الفرق يصبح بسيطًا جدًا عندما تعرف سؤالين: هل أنت تقرأ أم تكتب؟ وهل البيانات موجودة في ملف أم نص String؟

باختصار: load() تقرأ JSON من ملف، وloads() تقرأ JSON من نص، وdump() تكتب البيانات إلى ملف JSON، بينما dumps() تحول كائن Python إلى نص JSON وتعيد هذا النص لك.

في هذا المقال سنطبق الدوال الأربع خطوة بخطوة، ونوضح الفرق بينها بجدول وأمثلة عملية، ثم نتعامل مع اللغة العربية وUTF-8 والأخطاء الشائعة مثل JSONDecodeError.

{alertInfo} القاعدة التي تختصر الدوال الأربع:
JSON → Python: استخدم load أو loads.
Python → JSON: استخدم dump أو dumps.
ملف: بدون s. نص String: مع s كطريقة سهلة للتذكر.

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

ما هو JSON في Python؟

JSON اختصار لـ JavaScript Object Notation، وهو تنسيق نصي شائع لتبادل وتخزين البيانات. ستراه كثيرًا في ملفات الإعدادات، والبيانات القادمة من الخدمات والـAPIs، وحفظ بيانات البرامج البسيطة.

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

import json

مثلًا، قد يحتوي ملف user.json على:

{
  "name": "Ali",
  "age": 25,
  "active": true
}

وعند قراءته في Python يتحول الكائن JSON عادة إلى dict، والمصفوفة JSON إلى list.

الفرق بين load وloads وdump وdumps بسرعة

الدالة	الاتجاه	تتعامل مع	النتيجة
json.load()	JSON → Python	ملف أو File-like object	كائن Python مثل dict أو list
json.loads()	JSON → Python	نص JSON	كائن Python
json.dump()	Python → JSON	كائن Python + ملف	تكتب JSON مباشرة إلى الملف
json.dumps()	Python → JSON	كائن Python	تعيد نص JSON من نوع str

قراءة ملف JSON باستخدام json.load()

استخدم json.load() عندما تكون بيانات JSON موجودة داخل ملف.

لنفترض أن لدينا ملفًا باسم user.json. نفتح الملف أولًا باستخدام open() ثم نمرر كائن الملف إلى json.load():

import json

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

print(data)
print(data["name"])

لاحظ أننا لم نمرر اسم الملف إلى json.load() مباشرة؛ مررنا كائن الملف المفتوح.

{alertWarning} خطأ شائع: كتابة json.load("user.json") ليست طريقة قراءة ملف باسم user.json. الدالة load() تتوقع كائنًا يمكن القراءة منه، لذلك افتح الملف أولًا.

قراءة نص JSON باستخدام json.loads()

إذا كانت بيانات JSON موجودة لديك كنص داخل متغير، فاستخدم json.loads():

import json

json_text = '{"name": "Sara", "age": 22}'

data = json.loads(
    json_text
)

print(data["name"])
print(data["age"])

هنا لا يوجد ملف نحتاج إلى فتحه. البيانات موجودة أصلًا في المتغير json_text.

{alertInfo} ملاحظة تقنية: حرف s مفيد لتذكر كلمة String، لكن json.loads() في Python الحديثة تستطيع أيضًا استقبال bytes أو bytearray يحتويان على JSON، وليست محصورة في str فقط.

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

السؤال	json.load()	json.loads()
من أين تأتي البيانات؟	من ملف أو كائن قابل للقراءة	من نص JSON موجود في الذاكرة
هل تحتاج open() عادة؟	نعم عند قراءة ملف	لا
ماذا تعيد؟	كائن Python	كائن Python
مثال الاستخدام	json.load(file)	json.loads(text)

إذًا الفرق ليس في شكل النتيجة غالبًا، بل في مصدر JSON: ملف أم نص.

كتابة JSON إلى ملف باستخدام json.dump()

عندما يكون لديك قاموس أو قائمة في Python وتريد حفظها مباشرة داخل ملف JSON، استخدم json.dump().

import json

user = {
    "name": "Ali",
    "age": 25,
    "active": True
}

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

dump() تكتب JSON مباشرة إلى الملف المفتوح. استخدمنا أيضًا:

• ensure_ascii=False حتى تبقى الأحرف العربية مكتوبة بصورة مقروءة بدل تحويلها إلى Unicode escape sequences.
• indent=4 لتنسيق JSON بمسافات بادئة تجعله أسهل للقراءة.
• encoding="utf-8" عند فتح الملف للتعامل الصحيح مع النصوص العربية.

تحويل كائن Python إلى نص JSON باستخدام json.dumps()

إذا كنت لا تريد الكتابة إلى ملف، بل تريد الحصول على نص JSON داخل متغير، فاستخدم json.dumps():

import json

user = {
    "name": "سارة",
    "age": 22
}

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

print(json_text)
print(type(json_text))

القيمة التي ترجعها dumps() هي str. هي لا تنشئ ملفًا بنفسها.

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

السؤال	json.dump()	json.dumps()
إلى أين تذهب النتيجة؟	إلى ملف أو File-like object	إلى نص str في الذاكرة
هل تحتاج كائن ملف؟	نعم	لا
هل تعيد نص JSON؟	لا، تكتب إلى الملف	نعم
مثال الاستخدام	json.dump(data, file)	json.dumps(data)

طريقة سهلة لحفظ الفرق بين الدوال الأربع

فكر فيها كمحورين:

	ملف	نص String
قراءة JSON إلى Python	load()	loads()
تحويل Python إلى JSON	dump()	dumps()

هذه المصفوفة الصغيرة أهم شيء تحفظه في المقال.

مثال كامل: قراءة JSON ثم تعديله وكتابته من جديد

هذا مثال عملي يجمع load() وdump(). سنقرأ ملفًا، نعدل قيمة، ثم نحفظ البيانات مرة أخرى:

import json

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

data["active"] = True

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

هذا النمط شائع عندما تستخدم JSON لتخزين إعدادات أو بيانات بسيطة: اقرأ الملف، عدّل كائن Python، ثم احفظه مرة أخرى.

تحويل أنواع البيانات بين JSON وPython

عند استخدام load() أو loads()، تحول مكتبة json أنواع JSON إلى الأنواع المناسبة في Python.

JSON	Python
object	dict
array	list
string	str
integer number	int
real number	float
true	True
false	False
null	None

وعند استخدام dump() أو dumps() يحدث التحويل في الاتجاه الآخر للأنواع المدعومة.

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

كتابة JSON بالعربية باستخدام ensure_ascii=False

القيمة الافتراضية لـensure_ascii هي True. لذلك قد ترى الأحرف غير ASCII ممثلة بصيغة Unicode escapes.

إذا أردت بقاء النص العربي مقروءًا في الناتج، استخدم:

import json

data = {
    "language": "العربية"
}

text = json.dumps(
    data,
    ensure_ascii=False
)

print(text)

وعند الكتابة إلى ملف نصي، استخدم أيضًا encoding="utf-8" كما فعلنا في أمثلة open().

تنسيق JSON باستخدام indent وsort_keys

إذا أردت JSON سهل القراءة، استخدم indent:

text = json.dumps(
    data,
    ensure_ascii=False,
    indent=4
)

ويمكنك إضافة sort_keys=True عندما تريد ترتيب مفاتيح الكائن أبجديًا في الناتج:

text = json.dumps(
    data,
    indent=4,
    sort_keys=True
)

هذه الخيارات مفيدة للعرض والتنظيم، لكنها لا تغير الفكرة الأساسية للفرق بين الدوال الأربع.

التعامل مع JSONDecodeError عند قراءة JSON غير صحيح

إذا كان النص أو الملف لا يحتوي على JSON صحيح، فقد ترفع load() أو loads() الخطأ JSONDecodeError.

import json

json_text = '{"name": "Ali",}'

try:
    data = json.loads(
        json_text
    )
except json.JSONDecodeError as error:
    print(
        "JSON غير صالح:",
        error
    )

في المثال توجد فاصلة زائدة قبل }، وهذا غير صالح في JSON القياسي.

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

التعامل مع ملف JSON غير موجود

عند استخدام json.load() مع ملف، قد تكون المشكلة في الملف نفسه قبل الوصول إلى JSON، مثل أن يكون اسم الملف أو المسار غير صحيح.

import json

try:
    with open(
        "data.json",
        "r",
        encoding="utf-8"
    ) as file:
        data = json.load(file)
except FileNotFoundError:
    print(
        "ملف JSON غير موجود."
    )

لفهم معالجة الأخطاء بصورة أوسع، راجع شرح try وexcept في Python والتعامل مع الأخطاء.

أخطاء شائعة مع load وloads وdump وdumps

1. تمرير اسم الملف إلى json.load()

load() لا تبحث عن الملف من اسمه. افتح الملف أولًا ثم مرر كائن الملف.

2. استخدام loads() عندما لديك ملف مفتوح

إذا كان لديك ملف مفتوح بالفعل وتريد قراءة JSON منه، فـload(file) أوضح من قراءة محتوى الملف يدويًا ثم تمريره إلى loads().

3. توقع أن dumps() تنشئ ملفًا

dumps() تعيد نصًا من نوع str. إذا كنت تريد الكتابة مباشرة إلى ملف، استخدم dump().

4. كتابة JSON بعلامات تنصيص مفردة

JSON القياسي يستخدم علامات التنصيص المزدوجة للنصوص والمفاتيح. قاموس Python المكتوب بعلامات مفردة ليس نص JSON صحيحًا لمجرد أنه يشبهه.

5. تجاهل UTF-8 مع البيانات العربية

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

6. كتابة عدة كائنات مستقلة باستخدام dump في الملف نفسه

JSON ليس بروتوكولًا مؤطرًا يسمح بكتابة عدة مستندات مستقلة واحدًا بعد آخر واستعادتها تلقائيًا. تكرار dump() على الملف نفسه لإنشاء عدة جذور JSON قد ينتج ملفًا غير صالح. إذا كانت لديك عدة عناصر، اجمعها مثلًا داخل list واحدة ثم اكتبها كوثيقة JSON واحدة.

متى أستخدم كل دالة؟

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

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

• كورس أساسيات بايثون للمبتدئين
• شرح Dictionaries في Python للمبتدئين
• شرح try وexcept في Python والتعامل مع الأخطاء
• حل خطأ JSONDecodeError في Python عند قراءة ملفات JSON

المصدر الرسمي

للتوسع في كل معاملات الدوال والتحويلات المدعومة، راجع توثيق مكتبة json الرسمي في Python.

الخلاصة

الفرق بين load وloads وdump وdumps يصبح بسيطًا عندما تفصل بين اتجاه التحويل ومصدر البيانات.

• json.load(): من ملف JSON إلى كائن Python.
• json.loads(): من نص JSON إلى كائن Python.
• json.dump(): من كائن Python إلى ملف JSON.
• json.dumps(): من كائن Python إلى نص JSON.

وعند التعامل مع ملفات عربية، استخدم UTF-8 وensure_ascii=False عند الحاجة. أما إذا كانت بيانات JSON قد تكون غير صحيحة، فتعامل مع JSONDecodeError بدل افتراض أن كل إدخال صالح.

{alertSuccess} احفظها بهذه الطريقة: load / loads للقراءة والتحويل إلى Python، وdump / dumps للكتابة والتحويل إلى JSON؛ ووجود s يذكرك بأنك تتعامل مع نص بدل الكتابة أو القراءة المباشرة من ملف.

أسئلة شائعة

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

json.load() تقرأ JSON من ملف أو كائن قابل للقراءة، بينما json.loads() تحول نص JSON إلى كائن Python.

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

json.dump() تكتب JSON مباشرة إلى ملف أو كائن قابل للكتابة، بينما json.dumps() تعيد JSON كنص من نوع str.

ماذا يعني حرف s في loads وdumps؟

يمكنك استخدامه كوسيلة سهلة لتذكر String: loads() تستخدم عادة مع نص JSON، وdumps() تعيد نص JSON. تقنيًا تستطيع loads() أيضًا استقبال bytes وbytearray.

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

لا. json جزء من مكتبة Python القياسية، وتستخدمها مباشرة باستخدام import json.

كيف أكتب العربية داخل ملف JSON بدون Unicode escapes؟

افتح الملف باستخدام encoding="utf-8" واستخدم ensure_ascii=False مع dump() أو dumps().

لماذا يظهر JSONDecodeError؟

لأن البيانات التي تحاول فك ترميزها ليست JSON صحيحة، مثل وجود فاصلة زائدة أو علامات تنصيص غير صحيحة أو ملف فارغ.

هل json.dumps تنشئ ملف JSON؟

لا. هي تعيد نص JSON فقط. لإنشاء أو الكتابة مباشرة إلى ملف استخدم open() مع json.dump().