Python کلاسز کو JSON میں تبدیل کریں!

Python (Pydantic·dataclass) کوڈ ڈالیں اور مثالی JSON حاصل کریں! Pydantic BaseModel, Field(alias), dataclass, TypedDict سپورٹ۔ API دستاویزات اور ٹیسٹ request body (sample JSON) کے لیے مفید۔
Python
نتیجہ
 

Python کلاسز کو JSON میں تبدیل کریں!

Pydantic BaseModel، @dataclass یا TypedDict سے لکھے Python ماڈلز پیسٹ کریں اور ان کے ڈھانچے پر مبنی مثالی JSON document واپس حاصل کریں۔ Field(alias=...) اور alias_generator=to_camel config پڑھے جاتے ہیں، اس لیے آپ وہ keys دیکھتے ہیں جن میں آپ کے snake_case فیلڈز اصل میں serialize ہوتے ہیں۔

یہ FastAPI endpoints کے لیے request مثالیں بنانے، کسی دوسری ٹیم کے ساتھ webhook یا queue payload کا schema شیئر کرنے، یا pytest کے لیے JSON fixtures تیار کرنے کے لیے موزوں ہے۔

استعمال کا طریقہ

  1. اپنے ماڈلز والی .py فائل کا مواد پیسٹ کریں۔ import لائنیں، methods اور @field_validator جیسے decorators چھوڑ دیے جاتے ہیں۔
  2. حوالہ دیے گئے sub-models اور Enum کلاسز شامل کریں تاکہ وہ حصے بھرے جائیں۔ string forward references ("Order") سمجھے جاتے ہیں۔
  3. خودکار پر روٹ ٹائپ وہ کلاس چنتا ہے جو کسی دوسرے ماڈل میں فیلڈ type کے طور پر استعمال نہ ہو؛ آپ فہرست سے کوئی ایک چن بھی سکتے ہیں۔
  4. JSON کو json_schema_extra کی examples، test data فائل یا اپنی API docs میں کاپی کریں۔

مثال

ان پٹ (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
}

model_config میں to_camel کی وجہ سے event_type، receipt_url اور customer_id camelCase keys بن جاتے ہیں، جبکہ retry_count کے لیے واضح alias="retries" جیتتا ہے۔ raw_payload پر Field(exclude=True) ہے اور وہ چھوڑ دیا جاتا ہے۔ Literal اپنی پہلی value payment.succeeded لیتا ہے، اور literal ڈیفالٹ "KRW" جوں کا توں رہتا ہے۔

معاون خصوصیات

  • Pydantic BaseModel (v1 اور v2)، @dataclass، TypedDict، اور auto() سمیت Enum/StrEnum/IntEnum پڑھتا ہے۔
  • key نام Field(alias=...)، serialization_alias، اور model_config = ConfigDict(...) یا اندرونی class Config: میں سیٹ کیے گئے alias_generator (to_camel، to_pascal) سے۔
  • خارج: _ سے شروع ہونے والے نام، ClassVar، model_config، اور Field(exclude=True) والے فیلڈز۔
  • types کا سلوک: Optional[X] / X | None → X کا نمونہ، Literal[...] → پہلی value، Annotated/Required/NotRequired → اندرونی type، list/set/tuple → ایک عنصر والی array، dict[str, V] → {"key": V}۔
  • Pydantic types: EmailStr، HttpUrl، SecretStr، constr → string؛ conint، PositiveInt → 0؛ Decimal اور condecimal → string "0"، جیسے Pydantic v2 کا JSON انہیں لکھتا ہے۔
  • تاریخ اور وقت: datetime → 1970-01-01T00:00:00، date → 1970-01-01، time → 00:00:00، timedelta → PT0S؛ UUID کو درست شکل والی value ملتی ہے۔
  • string، نمبر اور True/False والے literal defaults نمونوں کے طور پر استعمال ہوتے ہیں؛ Status.PAID جیسا enum ڈیفالٹ اس member کی value بنتا ہے۔

استعمال کے کیس

FastAPI request مثالیں

request ماڈل سے JSON بنا کر اسے model_config = {"json_schema_extra": {"examples": [...]}} میں ڈالیں؛ پھر /docs پر مثال انہی alias keys کو استعمال کرتی ہے جن کی endpoint توقع رکھتا ہے۔

webhook اور event payloads شیئر کرنا

اگر Celery task یا Kafka message کے payloads، Pydantic میں بیان کیے گئے ہوں تو Node یا Go استعمال کرنے والی ٹیموں کو ڈھانچے پر اتفاق کے لیے Python کوڈ کے بجائے نتیجے والا JSON دیں۔

pytest fixtures کی تیاری

model_validate_json() یا API client ٹیسٹس کے لیے JSON فائل کا ڈھانچہ بنائیں، پھر edge cases شامل کرنے کے لیے انفرادی values بدلیں۔

نوٹس اور حدود

  • Optional فیلڈز اور None ڈیفالٹ والے فیلڈز کو بھی null کے بجائے typed نمونہ ملتا ہے۔
  • Decimal کو string "0" سے بھرا جاتا ہے، جو Pydantic v2 کی JSON serialization (model_dump_json) سے میل کھاتا ہے۔ اگر آپ کا پروجیکٹ اس کے بجائے نمبر دیتا ہے (Pydantic v1، یا json.dumps(default=float)) تو اسے نمبر میں بدل دیں۔
  • آؤٹ پٹ کی شکل بدلنے والا کوڈ، جیسے @computed_field، @field_serializer یا @model_serializer، نہیں چلایا جاتا۔
  • Union[A, B] پہلا غیر None member استعمال کرتا ہے؛ discriminator فیلڈ سے چنے جانے والے discriminated unions کو ماڈل نہیں کیا جاتا۔
  • default_factory اور function calls سے بننے والے defaults نہیں چلائے جاتے؛ value، type سے آتی ہے۔

عام سوالات

آؤٹ پٹ alias keys استعمال کرتا ہے، لیکن میرا model_dump_json() فیلڈ نام لکھتا ہے۔

جب تک آپ by_alias=True نہ دیں، Pydantic فیلڈ نام سے serialize کرتا ہے۔ FastAPI کا response_model بطور ڈیفالٹ by_alias=True استعمال کرتا ہے، جو اس ٹول کے آؤٹ پٹ سے میل کھاتا ہے۔ خود dump کرتے وقت model_dump_json(by_alias=True) کال کریں۔

dataclasses میں aliases نہیں ہوتے۔ کیا keys پھر بھی فیلڈ ناموں سے مختلف ہو سکتی ہیں؟

standard dataclass میں نام بدلنے کی سہولت نہیں، اس لیے فیلڈ کا نام ہی key ہے۔ اگر کسی فیلڈ کے آخر میں # JSON: "orderId" comment ہو، جیسا اس سائٹ کے JSON → Python صفحے سے بنی dataclasses میں ہوتا ہے، تو وہی نام استعمال ہوتا ہے۔

کیا TypedDict کی NotRequired keys شامل ہوتی ہیں؟

جی ہاں۔ نمونے کا مقصد ہر ممکنہ key دکھانا ہے، اس لیے NotRequired اور total=False فیلڈز شامل ہوتے ہیں۔ اپنی docs میں ان پر نشان لگائیں جو چھوڑی جا سکتی ہیں۔

کیا یہ SQLAlchemy ماڈلز سنبھالتا ہے؟

یہ صفحہ type hints پر مبنی ماڈلز کے لیے ہے۔ Column(...) یا Mapped[...] سے ڈکلیئر کیے گئے SQLAlchemy ماڈلز کے لیے SQLAlchemy → JSON صفحہ استعمال کریں۔