حوّل JSON إلى Pydantic model بلغة Python!

أدخل JSON لتوليد كود Pydantic model بلغة Python بما في ذلك الكائنات المتداخلة! يدعم Pydantic v2 BaseModel, dataclass, FastAPI. SQLAlchemy في التبويبات أعلاه.
JSON
النتيجة
 

حوّل JSON إلى Pydantic model بلغة Python!

يحوّل هذا المحوّل بنية JSON إلى أصناف BaseModel في Pydantic v2 أو إلى كود @dataclass من المكتبة القياسية. تُعاد كتابة أسماء الحقول بصيغة snake_case كما يتوقع أسلوب Python، ويحصل كل كائن متداخل على صنفه الخاص.

استخدمه عند تعريف مخططات الطلبات والاستجابات في FastAPI، أو عند إضافة تلميحات الأنواع إلى بيانات تجلبها بـ requests أو httpx، أو عند ترتيب سكربتات ETL والكشط التي تنقّب في القواميس بمفاتيح نصية.

طريقة الاستخدام

  1. الصق JSON الذي تريد نمذجته.
  2. أدخل اسم النموذج على المستوى الأعلى في اسم النوع (مثلًا Forecast).
  3. من النمط، اختر Pydantic (v2) للتحقق والأسماء البديلة (aliases)، أو dataclass لنموذج بلا اعتماديات.
  4. انسخ النتيجة إلى وحدة مثل models.py. يُحفظ النمط واسم النوع في الرابط.

مثال

المدخلات (JSON)
{
  "city": "Seoul",
  "updatedAt": "2024-05-01T09:00:00+09:00",
  "current": { "temp": 18.5, "humidity": 40 },
  "hourly": [
    { "hour": 10, "temp": 19, "rain_mm": 0 },
    { "hour": 11, "temp": 20.5, "rain_mm": 0.4, "alert": "shower" }
  ]
}
المخرجات (Python · Pydantic v2)
from __future__ import annotations

from pydantic import BaseModel, ConfigDict, Field


class Hourly(BaseModel):
    hour: int
    temp: float
    rain_mm: float
    alert: str | None = None


class Current(BaseModel):
    temp: float
    humidity: int


class Forecast(BaseModel):
    model_config = ConfigDict(populate_by_name=True)

    city: str
    updated_at: str = Field(alias="updatedAt")
    current: Current
    hourly: list[Hourly]

يصبح updatedAt الحقل updated_at، المرتبط بالمفتاح الأصلي عبر Field(alias="updatedAt"). في hourly يخلط temp بين أعداد صحيحة وعشرية فيصبح float، وalert الموجود في العنصر الثاني فقط يكون str | None = None. وتُخرج الأصناف بدءًا بالأبناء.

الميزات المدعومة

  • Pydantic v2: الحقول المعاد تسميتها تستخدم Field(alias=...)، وmodel_config = ConfigDict(populate_by_name=True) يتيح لك ملأها أيضًا باسمها في Python.
  • dataclass: تُنقل الحقول التي لا قيم افتراضية لها قبل حقول = None لتجنّب TypeError: non-default argument follows default argument؛ ويُحفظ المفتاح الأصلي كتعليق # JSON: "updatedAt".
  • الأنواع: str وint وfloat وbool وlist[...]، وAny للقيم مختلطة الأنواع.
  • الحقول الغائبة في بعض العناصر أو التي تحوي null تصبح X | None = None.
  • الكلمات المحجوزة في Python مثل class أو from أو type تحصل على شرطة سفلية في آخرها (class_).
  • يُضمَّن from __future__ import annotations حتى تتمكن الأصناف من الإشارة إلى بعضها بغض النظر عن الترتيب.
  • المصفوفة على المستوى الأعلى تُنتج اسمًا بديلًا مثل Root = list[RootItem].

حالات الاستخدام

نماذج الاستجابة وأجسام الطلبات في FastAPI

ابنِ BaseModels من JSON الذي اتفقت عليه مع الواجهة الأمامية واستخدمها في response_model= أو كمعاملات لنقاط النهاية؛ فتتبعها وثائق OpenAPI تلقائيًا.

التحقق من استجابات APIs خارجية

غلّف الاستدعاءات بـ Forecast.model_validate(resp.json())، وحين يغيّر المزوّد نوع حقل ما، يشير ValidationError إلى مسار الحقل الذي تعطّل بالضبط.

استبدال البحث في القواميس داخل السكربتات

تحويل data["current"]["temp"] إلى forecast.current.temp يمنحك الإكمال التلقائي في المحرر ويتيح لـ mypy أو pyright فحص الكود.

ملاحظات وقيود

  • لا يحوّل @dataclass القواميس المتداخلة إلى كائنات. بعد Forecast(**data) يبقى current قاموسًا؛ استخدم Pydantic أو أداة مساعدة مثل dacite إن احتجت إلى تحويل متداخل.
  • لإعادة التسلسل بمفاتيح JSON الأصلية (updatedAt) في Pydantic، استدعِ model_dump(by_alias=True) أو model_dump_json(by_alias=True).
  • يستخدم الناتج الصيغة str | None، لذا تفترض نماذج Pydantic وجود Python 3.10 أو أحدث.
  • تخرج سلاسل التاريخ والوقت على شكل str. مع Pydantic يكفي تغيير التلميح إلى datetime لتحليل قيم ISO 8601.
  • لا تُولَّد تراكيب Pydantic v1 (class Config، parse_obj).

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

ما فائدة populate_by_name=True؟

افتراضيًا لا يقبل الحقل ذو الاسم البديل إلا ذلك الاسم (updatedAt) كمدخل. مع هذا الإعداد يمكنك أيضًا كتابة Forecast(updated_at=...)، وهو مفيد في الاختبارات.

أفضّل Optional[str] للحقول الاختيارية.

str | None وOptional[str] يعنيان الشيء نفسه. إن احتجت إلى التوافق مع Python 3.9، فاستورد Optional من typing واستبدل التلميحات.

هل يمكنه إخراج TypedDict أو أصناف attrs؟

الأنماط المدعومة هي Pydantic v2 وdataclass. قائمة حقول dataclass تنتقل مباشرة إلى TypedDict أو صنف @attrs.define إن احتجت إلى أحدهما.

هل تُضاف أسماء بديلة حين تكون المفاتيح بصيغة snake_case أصلًا؟

لا. حين يساوي اسم Python المفتاح الأصلي، لا يُخرج Field(alias=...) ولا ConfigDict، فتحصل على أسطر بسيطة مثل rain_mm: float.