2.28. JSON

JSON (JavaScript Object Notation) هو تنسيق نصي مدمج وقابل للقراءة البشرية للبيانات المهيكلة. ويُعرّف ستة أنواع -- string وnumber وboolean وnull وarray وobject -- يتطابق كل منها مباشرةً مع قيمة في Python، لذا فإن التحويل بين Python و JSON هو استدعاء دالة واحد في كلا الاتجاهين.

JSON هو اللغة المشتركة لملفات الإعداد وواجهات الويب البرمجية (web APIs). استخدمه كلما احتجت إلى حفظ حزمة صغيرة من الإعدادات على القرص بصيغة يمكنك أيضًا قراءتها بالعين، أو لتبادل بيانات مهيكلة مع برنامج آخر.

تغطّي دالتان معظم الاحتياجات:

• json.dumps() -- dump string: تحويل قيمة Python إلى سلسلة JSON.

• json.loads() -- load string: تحليل سلسلة JSON عائدةً إلى Python.

يؤدّي الزوج json.dump / json.load (دون s) المهمة نفسها لكنه يأخذ كائن ملف مباشرةً.

2.28.1. الترميز (dumps)

import json

config = {
    "name":  "OpenMV",
    "width": 320,
    "tags":  ["red", "round"],
}

text = json.dumps(config)
print(text)

المخرجات:

{"name": "OpenMV", "width": 320, "tags": ["red", "round"]}

التطابق هو:

• dict (بمفاتيح نصية) ← كائن JSON.

• list و tuple ← مصفوفة JSON.

• str ← سلسلة JSON.

• int و float ← عدد JSON.

• True و False و None ← true و false و null.

أي شيء خارج تلك المجموعة (صنف مخصّص، أو مخزن bytes، أو set) يطلق TypeError. حوّل القيمة أولًا.

ملاحظة

تقبل json.dumps() في CPython وسيط indent للحصول على مخرجات منسّقة بشكل جميل؛ أما نسخة MicroPython فلا تقبله. وأداة التنسيق الوحيدة هي separators، التي تتحكّم في التباعد ضمن السطر -- مرّر (',', ':') للحصول على أكثر شكل تراصّ. أما المخرجات المتعدّدة الأسطر والمُزاحة فيجب إنتاجها يدويًا عند الحاجة.

2.28.2. فك الترميز (loads)

text = '{"name": "OpenMV", "width": 320}'
config = json.loads(text)
print(config["name"], config["width"])

المخرجات:

OpenMV 320

تصبح كائنات JSON dict، وتصبح المصفوفات list، ويتطابق الباقي مع مكافئاته في Python. وتطلق JSON الخاطئة ValueError.

2.28.3. قراءة الملفات وكتابتها

ينسجم الزوج المعتمد على الملفات جيدًا مع with:

import json

with open("config.json") as f:
    config = json.load(f)

config["width"] = 640

with open("config.json", "w") as f:
    json.dump(config, f)

تعامل مع ملف JSON بوصفه سجلًا كاملًا -- اقرأه بالكامل، وعدّل قيمة Python، ثم اكتبه مرة أخرى. أما محاولة تحرير JSON في مكانه داخل الملف فتُحدث عادةً أخطاءً أكثر مما توفّره.