JSON إلى Python Dataclass

توليد Python dataclasses من JSON

جرب مثالاً
اسم الكلاس الجذري:

إدخال JSON

مخرجات Python

يعمل محليًا · آمن للصق الأسرار
ستظهر Python dataclasses هنا…

ما هو تحويل JSON إلى Python Dataclass؟

يأخذ تحويل JSON إلى Python dataclass كائن JSON خامًا وينتج مجموعة من تعريفات Python dataclass مع تعليقات أنواع دقيقة. تولّد وحدة dataclasses في Python، المُقدَّمة في PEP 557 (Python 3.7)، توابع __init__ و__repr__ و__eq__ تلقائيًا من حقول الكلاس الموصوفة بالأنواع. عندما تعمل مع واجهات API من JSON أو ملفات إعداد أو طوابير رسائل، تمنح dataclasses بياناتك بنية مكتوبة بالأنواع يمكن لمحررات الكود ومدققي الأنواع مثل mypy التحقق منها أثناء التطوير.

تُعيد json.loads() في Python قواميس وقوائم عادية. وهي تؤدي الغرض، لكنها لا تحمل أي معلومات عن الأنواع: مفتاح مكتوب بشكل خاطئ يُعيد None بدلًا من إطلاق استثناء، ولا يستطيع محررك إكمال أسماء الحقول تلقائيًا. تحل dataclasses هذه المشكلة بتعيين كل مفتاح JSON إلى حقل مسمى ذي نوع محدد. تصبح كائنات JSON المتداخلة تعريفات dataclass منفصلة، وتصبح المصفوفات تعليقات List[T]، وتصبح القيم الفارغة Optional[T] مع قيمة افتراضية None.

كتابة هذه التعريفات يدويًا عمل روتيني مضنٍ. عليك قراءة JSON واستنتاج نوع كل حقل من قيمته وتحويل المفاتيح من camelCase أو snake_case إلى اصطلاحات Python والتعامل مع الحالات الاستثنائية مثل الحقول القابلة للإلغاء والمصفوفات ذات الأنواع المختلطة. يؤدي المحوّل كل هذا في أجزاء من الثانية. تلصق JSON وتحصل على كود dataclass صحيح وتكمل عملك.

لماذا تستخدم محوّل JSON إلى Python؟

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

توليد dataclass فوري
الصق JSON واحصل على تعريفات Python dataclass ذات أنواع صحيحة في أقل من ثانية. تُعالَج الكائنات المتداخلة والمصفوفات والحقول الاختيارية تلقائيًا.
🔒
المعالجة تحافظ على الخصوصية
يعمل التحويل بالكامل في متصفحك باستخدام JavaScript. لا يغادر JSON لديك جهازك. تبقى مفاتيح الـAPI والرموز المميزة وسجلات المستخدمين خاصة.
📝
تعليقات أنواع صحيحة
كل حقل مولَّد يتضمن تعليق نوع Python مستنتج من قيمة JSON: str أو int أو float أو bool أو List[T] أو Optional[T] للقيم الفارغة.
📦
بدون تثبيت أو تسجيل
افتح الصفحة والصق JSON. لا يتطلب بيئة Python، ولا حزم pip للتثبيت، ولا إنشاء حساب.

حالات استخدام تحويل JSON إلى Python

تطوير عميل REST API
ولّد dataclasses من نماذج استجابات الـAPI. الصق JSON المُعاد من نقطة نهاية REST تابعة لجهة خارجية واحصل على كلاسات Python آمنة الأنواع جاهزة للاستخدام مع requests أو httpx.
نماذج طلبات/استجابات FastAPI
ابدأ من شكل حمولة JSON وولّد تعريفات dataclass. حوّلها إلى نماذج Pydantic للحصول على التحقق التلقائي في معالجات مسارات FastAPI.
مخططات أنابيب البيانات
عرّف بنى السجلات الموصوفة بالأنواع لأنابيب ETL. الصق نموذج رسالة JSON من Kafka أو RabbitMQ أو SQS وولّد dataclasses توثّق الشكل المتوقع.
تحليل ملفات الإعداد
حوّل ملفات إعداد JSON إلى كلاسات Python موصوفة بالأنواع. حمّل الإعداد باستخدام json.load() ثم أنشئ كائن dataclass لإكمال المحرر التلقائي والتحقق من الأنواع.
توليد بيانات الاختبار
أنشئ بيانات اختبار موصوفة بالأنواع من بيانات JSON نموذجية. يستطيع مهندسو ضمان الجودة لصق لقطات استجابات الـAPI وإنتاج تعريفات dataclass للاستخدام في مجموعات اختبار pytest.
تعلّم تعليقات أنواع Python
يستطيع الطلاب لصق أي بنية JSON ورؤية كيف تمثّلها Python بتلميحات الأنواع. يوضّح الكود المولَّد List وOptional والكلاسات المتداخلة والقيم الافتراضية في سياقها.

جدول تعيين أنواع JSON إلى Python

كل قيمة JSON تتعيّن على تعليق نوع Python محدد. يوضح الجدول أدناه كيف يُترجم المحوّل كل نوع JSON، مع صياغة وحدة typing (Python 3.7+) والصياغة المدمجة المتاحة من Python 3.10 فصاعدًا.

نوع JSONمثالPython (typing)Python 3.10+
string"hello"strstr
number (integer)42intint
number (float)3.14floatfloat
booleantrueboolbool
nullnullOptional[str]str | None
object{"k": "v"}@dataclass classnested model
array of strings["a", "b"]List[str]list[str]
array of objects[{"id": 1}]List[Item]list[Item]
mixed array[1, "a"]List[Any]list[Any]

مرجع مزيّن Dataclass

يقبل المزيّن @dataclass عدة معامِلات تغيّر سلوك الكلاس المولَّد. يغطي هذا المرجع الخيارات الأكثر صلة عند العمل مع بيانات مستنتجة من JSON.

المزيّن / الحقلالسلوكمتى تستخدمه
@dataclassGenerates __init__, __repr__, __eq__ from field annotationsStandard dataclasses
@dataclass(frozen=True)Makes instances immutable (hashable, no attribute reassignment)Config objects, dict keys
@dataclass(slots=True)Uses __slots__ for lower memory and faster attribute accessPython 3.10+, large datasets
@dataclass(kw_only=True)All fields require keyword arguments in __init__Python 3.10+, many fields
field(default_factory=list)Sets a mutable default without sharing state between instancesList/dict/set defaults

dataclass مقابل Pydantic مقابل TypedDict

تقدم Python ثلاث طرق شائعة لتعريف بنى موصوفة بالأنواع من JSON. كل طريقة تناسب حالة استخدام مختلفة. dataclasses هي خيار المكتبة القياسية بدون أي تبعيات. يُضيف Pydantic التحقق أثناء التشغيل. يُعلّق TypedDict القواميس العادية بالأنواع دون إنشاء كلاس جديد.

@dataclass
مكتبة قياسية (Python 3.7+). تولّد __init__ و__repr__ و__eq__. لا تحقق أثناء التشغيل. تعمل مع mypy وdataclasses-json للتسلسل. الأنسب للبنى الداخلية حيث تتحكم في المدخلات.
BaseModel (Pydantic)
مكتبة خارجية. تتحقق من الأنواع والقيود أثناء التشغيل. تُحلل JSON مباشرةً عبر model_validate_json(). الخيار المعتمد لـFastAPI وإدارة الإعدادات وأي كود يستقبل مدخلات غير موثوقة.
TypedDict
مكتبة قياسية (Python 3.8+). تُضيف تلميحات أنواع إلى القواميس العادية. لا تولّد __init__ أو توابع. تبقى القيم قابلة للوصول كقواميس. استخدمها عندما تحتاج إلى التحقق من الأنواع مع الإبقاء على واجهة القاموس، كما في قواعد الكود القديمة.

أمثلة برمجية

تُظهر هذه الأمثلة كيفية استخدام dataclasses المولَّدة في Python، وكيفية توليدها برمجيًا من JavaScript، وكيفية استخدام أساليب بديلة مثل Pydantic وأدوات سطر الأوامر.

Python (dataclasses)
from dataclasses import dataclass
from typing import List, Optional
import json

@dataclass
class Address:
    street: str
    city: str
    zip: str

@dataclass
class User:
    id: int
    name: str
    email: str
    active: bool
    score: float
    address: Address
    tags: List[str]
    metadata: Optional[str] = None

raw = '{"id":1,"name":"Alice","email":"alice@example.com","active":true,"score":98.5,"address":{"street":"123 Main St","city":"Springfield","zip":"12345"},"tags":["admin","user"],"metadata":null}'
data = json.loads(raw)

# Reconstruct nested objects manually
addr = Address(**data["address"])
user = User(**{**data, "address": addr})
print(user.name)     # -> Alice
print(user.address)  # -> Address(street='123 Main St', city='Springfield', zip='12345')
JavaScript (generate Python from JSON)
// Minimal JSON-to-Python-dataclass generator in JS
function jsonToPython(obj, name = "Root") {
  const classes = [];
  function infer(val, fieldName) {
    if (val === null) return "Optional[str]";
    if (typeof val === "string") return "str";
    if (typeof val === "number") return Number.isInteger(val) ? "int" : "float";
    if (typeof val === "boolean") return "bool";
    if (Array.isArray(val)) {
      const first = val.find(v => v !== null);
      return first ? `List[${infer(first, fieldName + "Item")}]` : "List[Any]";
    }
    if (typeof val === "object") {
      const clsName = fieldName.charAt(0).toUpperCase() + fieldName.slice(1);
      build(val, clsName);
      return clsName;
    }
    return "Any";
  }
  function build(obj, cls) {
    const fields = Object.entries(obj).map(([k, v]) => `    ${k}: ${infer(v, k)}`);
    classes.push(`@dataclass\nclass ${cls}:\n${fields.join("\n")}`);
  }
  build(obj, name);
  return classes.join("\n\n");
}

const data = { id: 1, name: "Alice", scores: [98, 85] };
console.log(jsonToPython(data, "User"));
// @dataclass
// class User:
//     id: int
//     name: str
//     scores: List[int]
Python (Pydantic BaseModel alternative)
from pydantic import BaseModel
from typing import List, Optional

class Address(BaseModel):
    street: str
    city: str
    zip: str

class User(BaseModel):
    id: int
    name: str
    email: str
    active: bool
    score: float
    address: Address
    tags: List[str]
    metadata: Optional[str] = None

# Pydantic parses and validates JSON in one step
raw = '{"id":1,"name":"Alice","email":"alice@example.com","active":true,"score":98.5,"address":{"street":"123 Main St","city":"Springfield","zip":"12345"},"tags":["admin","user"],"metadata":null}'
user = User.model_validate_json(raw)
print(user.name)              # -> Alice
print(user.model_dump_json()) # -> re-serializes to JSON
CLI (datamodel-code-generator)
# Install the generator
pip install datamodel-code-generator

# Generate dataclasses from a JSON file
datamodel-codegen --input data.json --output models.py --output-model-type dataclasses.dataclass

# Generate Pydantic models instead
datamodel-codegen --input data.json --output models.py

# From a JSON string via stdin
echo '{"id": 1, "name": "Alice", "tags": ["admin"]}' | \
  datamodel-codegen --output-model-type dataclasses.dataclass
# Output:
# @dataclass
# class Model:
#     id: int
#     name: str
#     tags: List[str]

الأسئلة الشائعة

ما الفرق بين Python dataclass والكلاس العادي؟
يستخدم dataclass المزيّن @dataclass لتوليد توابع __init__ و__repr__ و__eq__ تلقائيًا من تعليقات الحقول. يتطلب الكلاس العادي كتابة هذه التوابع يدويًا. تقلل dataclasses من الكود المتكرر عندما يكون الكلاس مخصصًا أساسًا لحفظ البيانات، وهو الحال النموذجي للبنى المستنتجة من JSON.
هل يمكن استخدام dataclasses مع تسلسل JSON مباشرةً؟
لا تستطيع وحدة json القياسية تسلسل كائنات dataclass افتراضيًا. استخدم dataclasses.asdict() لتحويل dataclass إلى قاموس ثم مرّره إلى json.dumps(). للتحكم الأكبر، تُضيف مكتبة dataclasses-json توابع .to_json() و.from_json()، وتتعامل نماذج Pydantic مع التسلسل بشكل مدمج.
كيف يتعامل المحوّل مع كائنات JSON المتداخلة؟
كل كائن متداخل يصبح تعريف @dataclass منفصلًا. إذا كان حقل JSON المسمى "address" يحتوي على كائن بحقلي "street" و"city"، ينشئ المحوّل كلاس Address ويضع تعليق النوع address: Address على الحقل الأب. تُنتج البنى المتداخلة بعمق تعريفات dataclass متعددة مرتبة حسب ترتيب التبعية.
ماذا يحدث عندما يكون حقل JSON فارغًا (null)؟
تُعلَّق الحقول الفارغة بـOptional[str] (أو النوع المناسب إن أمكن استنتاجه من السياق) مع قيمة افتراضية None. يجب أن تأتي الحقول ذات القيم الافتراضية بعد الحقول الإلزامية في dataclass، لذا يضع المحوّل الحقول الاختيارية في نهاية تعريف الكلاس.
هل ثمة فرق بين dataclasses ونماذج Pydantic لـJSON؟
dataclasses جزء من المكتبة القياسية ولا تتحقق من البيانات أثناء التشغيل. تتحقق نماذج Pydantic من الأنواع وتطبّق القيود ويمكنها تحليل نصوص JSON الخام مباشرةً. إذا كنت تستقبل JSON من مصادر خارجية وتحتاج إلى رفض البيانات المشوهة، فـPydantic هو الخيار الأنسب. للتمرير الداخلي للبيانات حيث تثق بالمدخلات، تكون dataclasses أخف وزنًا وبلا تبعيات خارجية.
كيف أتعامل مع مفاتيح JSON بصيغة camelCase في Python dataclasses؟
يستخدم Python اصطلاح snake_case لأسماء المتغيرات. يحوّل المحوّل مفاتيح camelCase مثل "firstName" إلى حقول snake_case مثل first_name. إذا أردت التسلسل العكسي من JSON، استخدم مكتبة dataclasses-json مع إعداد يربط بين الاصطلاحين، أو اكتب تابع __post_init__ مخصصًا.
هل يدعم هذا المحوّل صياغة Python 3.10+ مثل list[str] بدلًا من List[str]؟
يولّد المحوّل استيرادات وحدة typing (List وOptional) لضمان أقصى توافق مع Python 3.7 حتى 3.12. إذا كان مشروعك يستهدف Python 3.10 أو أحدث، يمكنك بأمان استبدال List[str] بـlist[str] وOptional[str] بـstr | None. يوضح جدول تعيين الأنواع أعلاه كلتا الصيغتين.