يحوّل هذا المحوّل بنية JSON إلى أصناف BaseModel في Pydantic v2 أو إلى كود @dataclass من المكتبة القياسية. تُعاد كتابة أسماء الحقول بصيغة snake_case كما يتوقع أسلوب Python، ويحصل كل كائن متداخل على صنفه الخاص.
استخدمه عند تعريف مخططات الطلبات والاستجابات في FastAPI، أو عند إضافة تلميحات الأنواع إلى بيانات تجلبها بـ requests أو httpx، أو عند ترتيب سكربتات ETL والكشط التي تنقّب في القواميس بمفاتيح نصية.
اسم النوع (مثلًا Forecast).النمط، اختر Pydantic (v2) للتحقق والأسماء البديلة (aliases)، أو dataclass لنموذج بلا اعتماديات.models.py. يُحفظ النمط واسم النوع في الرابط.{
"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" }
]
}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. وتُخرج الأصناف بدءًا بالأبناء.
Field(alias=...)، وmodel_config = ConfigDict(populate_by_name=True) يتيح لك ملأها أيضًا باسمها في Python.= None لتجنّب TypeError: non-default argument follows default argument؛ ويُحفظ المفتاح الأصلي كتعليق # JSON: "updatedAt".str وint وfloat وbool وlist[...]، وAny للقيم مختلطة الأنواع.null تصبح X | None = None.class أو from أو type تحصل على شرطة سفلية في آخرها (class_).from __future__ import annotations حتى تتمكن الأصناف من الإشارة إلى بعضها بغض النظر عن الترتيب.Root = list[RootItem].ابنِ BaseModels من JSON الذي اتفقت عليه مع الواجهة الأمامية واستخدمها في response_model= أو كمعاملات لنقاط النهاية؛ فتتبعها وثائق OpenAPI تلقائيًا.
غلّف الاستدعاءات بـ Forecast.model_validate(resp.json())، وحين يغيّر المزوّد نوع حقل ما، يشير ValidationError إلى مسار الحقل الذي تعطّل بالضبط.
تحويل data["current"]["temp"] إلى forecast.current.temp يمنحك الإكمال التلقائي في المحرر ويتيح لـ mypy أو pyright فحص الكود.
@dataclass القواميس المتداخلة إلى كائنات. بعد Forecast(**data) يبقى current قاموسًا؛ استخدم Pydantic أو أداة مساعدة مثل dacite إن احتجت إلى تحويل متداخل.updatedAt) في Pydantic، استدعِ model_dump(by_alias=True) أو model_dump_json(by_alias=True).str | None، لذا تفترض نماذج Pydantic وجود Python 3.10 أو أحدث.str. مع Pydantic يكفي تغيير التلميح إلى datetime لتحليل قيم ISO 8601.class Config، parse_obj).populate_by_name=True؟افتراضيًا لا يقبل الحقل ذو الاسم البديل إلا ذلك الاسم (updatedAt) كمدخل. مع هذا الإعداد يمكنك أيضًا كتابة Forecast(updated_at=...)، وهو مفيد في الاختبارات.
Optional[str] للحقول الاختيارية.str | None وOptional[str] يعنيان الشيء نفسه. إن احتجت إلى التوافق مع Python 3.9، فاستورد Optional من typing واستبدل التلميحات.
الأنماط المدعومة هي Pydantic v2 وdataclass. قائمة حقول dataclass تنتقل مباشرة إلى TypedDict أو صنف @attrs.define إن احتجت إلى أحدهما.
لا. حين يساوي اسم Python المفتاح الأصلي، لا يُخرج Field(alias=...) ولا ConfigDict، فتحصل على أسطر بسيطة مثل rain_mm: float.