حوّل أصناف Python إلى JSON!

الصق شيفرة Python (Pydantic·dataclass) واحصل على مثال JSON! يدعم Pydantic BaseModel, Field(alias), dataclass, TypedDict. مفيد لتوثيق واجهات API وأجسام الطلبات التجريبية (mock request body).
Python
النتيجة
 

حوّل أصناف Python إلى JSON!

الصق نماذج Python المكتوبة بـ BaseModel من Pydantic أو @dataclass أو TypedDict، لتحصل على مستند JSON نموذجي يتبع بنيتها. يُقرأ Field(alias=...) وإعداد alias_generator=to_camel، فترى المفاتيح التي تُسلسَل إليها حقولك المكتوبة بـ snake_case فعلًا.

يناسب بناء أمثلة الطلبات لنقاط نهاية FastAPI، أو مشاركة مخطط payload لـ webhook أو طابور رسائل مع فريق آخر، أو تجهيز بيانات JSON ثابتة لـ pytest.

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

  1. الصق محتوى ملف .py الذي يحوي نماذجك. تُتخطى أسطر import والدوال والـ decorators مثل @field_validator.
  2. ضمّن النماذج الفرعية المشار إليها وأصناف Enum حتى تُملأ تلك الأجزاء. والإشارات الأمامية النصية ("Order") مفهومة.
  3. حين يكون على تلقائي، يختار النوع الجذري الصنف الذي لا يستخدمه نموذج آخر نوعًا لحقل؛ ويمكنك أيضًا اختيار صنف من القائمة.
  4. انسخ JSON إلى examples في json_schema_extra أو إلى ملف بيانات اختبار أو إلى وثائق الـ API.

مثال

المدخلات (Python · Pydantic)
class Payer(BaseModel):
    model_config = ConfigDict(alias_generator=to_camel)
    customer_id: str
    email_address: str

class PaymentEvent(BaseModel):
    model_config = ConfigDict(alias_generator=to_camel)
    event_type: Literal["payment.succeeded", "payment.failed"]
    amount: Decimal
    currency: str = "KRW"
    payer: Payer
    receipt_url: Optional[str] = None
    retry_count: int = Field(default=0, alias="retries")
    raw_payload: dict = Field(exclude=True)
المخرجات (JSON)
{
  "eventType": "payment.succeeded",
  "amount": "0",
  "currency": "KRW",
  "payer": {
    "customerId": "",
    "emailAddress": ""
  },
  "receiptUrl": "",
  "retries": 0
}

بسبب to_camel في model_config، تتحول event_type وreceipt_url وcustomer_id إلى مفاتيح camelCase، بينما يفوز alias="retries" الصريح في retry_count. ويُحذف raw_payload لأن عليه Field(exclude=True). ويأخذ الـ Literal قيمته الأولى، payment.succeeded، وتُحفظ القيمة الافتراضية الحرفية "KRW" كما هي.

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

  • يقرأ BaseModel من Pydantic (v1 وv2)، و@dataclass، وTypedDict، وEnum/StrEnum/IntEnum بما فيها auto().
  • أسماء المفاتيح من Field(alias=...) وserialization_alias وalias_generator (to_camel، to_pascal) المضبوطة في model_config = ConfigDict(...) أو في class Config: داخلي.
  • المستبعد: الأسماء التي تبدأ بـ _، وClassVar، وmodel_config، وحقول Field(exclude=True).
  • معالجة الأنواع: Optional[X] / X | None → عيّنة من X، وLiteral[...] → القيمة الأولى، وAnnotated/Required/NotRequired → النوع الداخلي، وlist/set/tuple → مصفوفة من عنصر واحد، وdict[str, V] → {"key": V}.
  • أنواع Pydantic: EmailStr وHttpUrl وSecretStr وconstr → سلسلة نصية؛ وconint وPositiveInt → 0؛ وDecimal وcondecimal → السلسلة "0"، كما يكتبها JSON في Pydantic v2.
  • التواريخ والأوقات: datetime → 1970-01-01T00:00:00، وdate → 1970-01-01، وtime → 00:00:00، وtimedelta → PT0S؛ ويحصل UUID على قيمة سليمة الصيغة.
  • تُستخدم القيم الافتراضية الحرفية النصية والرقمية وTrue/False عيّناتٍ؛ والقيمة الافتراضية من enum مثل Status.PAID تصبح قيمة ذلك العضو.

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

أمثلة الطلبات في FastAPI

ولّد JSON من نموذج طلب وضعه في model_config = {"json_schema_extra": {"examples": [...]}}؛ فيستخدم المثال في /docs عندها مفاتيح الأسماء البديلة نفسها التي تتوقعها نقطة النهاية.

مشاركة payloads الـ webhooks والأحداث

إن كانت payloads مهام Celery أو رسائل Kafka معرَّفة بـ Pydantic، فأعطِ فرق المستهلكين على Node أو Go ملف JSON الناتج بدلًا من كود Python للاتفاق على البنية.

تجهيز بيانات pytest الثابتة

أنشئ هيكل ملف JSON لاختبارات model_validate_json() أو عميل الـ API، ثم غيّر قيمًا بعينها لإضافة الحالات الحدّية.

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

  • الحقول Optional والحقول ذات القيمة الافتراضية None تحصل مع ذلك على عيّنة من نوعها بدلًا من null.
  • يُملأ Decimal بالسلسلة "0"، بما يطابق تسلسل JSON في Pydantic v2 (model_dump_json). إن كان مشروعك يُخرج أرقامًا بدلًا من ذلك (Pydantic v1، أو json.dumps(default=float))، فغيّره إلى رقم.
  • الكود الذي يعيد تشكيل الناتج، مثل @computed_field أو @field_serializer أو @model_serializer، لا يُنفَّذ.
  • يستخدم Union[A, B] أول عضو ليس None؛ ولا تُنمذَج الاتحادات المميَّزة التي يُختار عضوها بحقل discriminator.
  • لا يُشغَّل default_factory ولا القيم الافتراضية الناتجة عن استدعاءات دوال؛ بل تأتي القيمة من النوع.

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

يستخدم الناتج مفاتيح الأسماء البديلة، لكن model_dump_json() عندي يطبع أسماء الحقول.

يُسلسِل Pydantic بأسماء الحقول ما لم تمرّر by_alias=True. ويستخدم response_model في FastAPI by_alias=True افتراضيًا، وهذا يطابق ناتج هذه الأداة. وعند التفريغ بنفسك، استدعِ model_dump_json(by_alias=True).

الـ dataclasses ليس لها أسماء بديلة. هل يمكن أن تختلف المفاتيح عن أسماء الحقول مع ذلك؟

لا توجد إعادة تسمية في dataclass القياسي، فاسم الحقل هو المفتاح. لكن إن حمل حقلٌ تعليقًا لاحقًا # JSON: "orderId"، كما في الـ dataclasses التي تنتجها صفحة JSON → Python في هذا الموقع، يُستخدم ذلك الاسم.

هل تُضمَّن مفاتيح NotRequired في TypedDict؟

نعم. العيّنة مقصود بها إظهار كل المفاتيح الممكنة، لذا تُضمَّن حقول NotRequired وtotal=False. حدّد في وثائقك تلك التي قد تُحذف.

هل يتعامل مع نماذج SQLAlchemy؟

هذه الصفحة للنماذج المبنية على تلميحات الأنواع. لنماذج SQLAlchemy المعرَّفة بـ Column(...) أو Mapped[...]، استخدم صفحة SQLAlchemy → JSON.