ToolDeck

JSON به Python Dataclass

تولید dataclass های Python از JSON

یک مثال امتحان کنید
نام کلاس اصلی:

ورودی JSON

خروجی Python

به‌صورت محلی اجرا می‌شود · جای‌گذاری اسرار امن است
dataclass های Python اینجا نمایش داده می‌شوند…

تبدیل JSON به Python Dataclass چیست؟

تبدیل JSON به dataclass در Python یک شیء JSON خام را دریافت کرده و مجموعه‌ای از تعریف dataclass های Python با type annotation های دقیق تولید می‌کند. ماژول dataclasses در Python که در PEP 557 (Python 3.7) معرفی شد، متدهای __init__، __repr__ و __eq__ را از فیلدهای annotated کلاس تولید می‌کند. وقتی با JSON API ها، فایل‌های پیکربندی یا صف‌های پیام کار می‌کنید، dataclass ها ساختاری نوع‌بندی‌شده به داده‌های شما می‌دهند که ویرایشگرها و ابزارهای بررسی نوع مانند mypy می‌توانند در زمان توسعه آن را تأیید کنند.

تابع json.loads() در Python دیکشنری‌ها و لیست‌های ساده برمی‌گرداند. این‌ها کار می‌کنند، اما اطلاعات نوع ندارند: یک کلید اشتباه تایپ‌شده به‌جای ایجاد خطا مقدار None برمی‌گرداند، و ویرایشگر شما نمی‌تواند نام فیلدها را تکمیل خودکار کند. Dataclass ها این مشکل را با نگاشت هر کلید JSON به یک فیلد نام‌گذاری‌شده و نوع‌بندی‌شده حل می‌کنند. اشیاء JSON تودرتو به تعریف‌های dataclass جداگانه تبدیل می‌شوند، آرایه‌ها به annotation های List[T]، و مقادیر null به Optional[T] با مقدار پیش‌فرض None.

نوشتن این تعریف‌ها به‌صورت دستی کار مکانیکی است. باید JSON را بخوانید، نوع هر فیلد را از مقدارش تشخیص دهید، کلیدها را از camelCase یا snake_case به قراردادهای Python تبدیل کنید، و موارد لبه‌ای مانند فیلدهای nullable و آرایه‌های با نوع ترکیبی را مدیریت کنید. یک مولد همه این‌ها را در میلی‌ثانیه انجام می‌دهد. JSON را پیست کنید، کد dataclass صحیح دریافت کنید، و ادامه دهید.

چرا از مولد JSON به Python استفاده کنیم؟

تبدیل دستی ساختارهای JSON به تعریف کلاس‌های Python به معنای حدس زدن نوع‌ها از داده‌های نمونه، مرتب کردن فیلدها به‌طوری که فیلدهای اجباری قبل از اختیاری بیایند، و به‌روزرسانی همه چیز وقتی API تغییر می‌کند. یک مولد این دردسر را برطرف می‌کند.

تولید فوری dataclass
JSON را پیست کنید و تعریف‌های Python dataclass نوع‌بندی‌شده را در کمتر از یک ثانیه دریافت کنید. اشیاء تودرتو، لیست‌ها و فیلدهای اختیاری به‌طور خودکار مدیریت می‌شوند.
🔒
پردازش با اولویت حریم خصوصی
تبدیل کاملاً در مرورگر شما با استفاده از JavaScript انجام می‌شود. JSON شما هرگز از دستگاهتان خارج نمی‌شود. کلیدهای API، توکن‌ها و رکوردهای کاربران خصوصی می‌مانند.
📝
type annotation های صحیح
هر فیلد تولیدشده شامل یک type annotation در Python است که از مقدار JSON استنتاج می‌شود: str، int، float، bool، List[T] یا Optional[T] برای مقادیر null.
📦
بدون نصب یا ثبت‌نام
صفحه را باز کنید و JSON را پیست کنید. نیازی به محیط Python، نصب پکیج با pip، یا ایجاد حساب کاربری نیست.

موارد استفاده JSON به Python

توسعه کلاینت REST API
dataclass ها را از نمونه‌های پاسخ API تولید کنید. JSON برگشتی از یک endpoint REST شخص ثالث را پیست کنید و کلاس‌های Python نوع‌ایمن آماده استفاده با requests یا httpx دریافت کنید.
مدل‌های درخواست/پاسخ FastAPI
از شکل payload JSON شروع کنید و تعریف‌های dataclass تولید کنید. آن‌ها را به مدل‌های Pydantic تبدیل کنید تا در route handler های FastAPI اعتبارسنجی خودکار داشته باشید.
طرح‌واره‌های Pipeline داده
ساختارهای رکورد نوع‌بندی‌شده برای pipeline های ETL تعریف کنید. یک پیام JSON نمونه از Kafka، RabbitMQ یا SQS را پیست کنید و dataclass هایی تولید کنید که شکل انتظاری داده را مستند می‌کنند.
تجزیه فایل‌های پیکربندی
فایل‌های پیکربندی JSON را به کلاس‌های Python نوع‌بندی‌شده تبدیل کنید. پیکربندی خود را با json.load() بارگذاری کنید، سپس یک نمونه dataclass برای تکمیل خودکار ویرایشگر و بررسی نوع بسازید.
تولید fixture برای تست
fixture های نوع‌بندی‌شده از داده‌های JSON نمونه بسازید. مهندسان QA می‌توانند اسنپ‌شات‌های پاسخ API را پیست کنند و تعریف‌های dataclass برای استفاده در مجموعه‌های تست pytest تولید کنند.
یادگیری type annotation در Python
دانشجویان می‌توانند هر ساختار JSON را پیست کنند و ببینند Python چگونه آن را با type hint نمایش می‌دهد. کد تولیدشده List، Optional، کلاس‌های تودرتو و مقادیر پیش‌فرض را در متن نشان می‌دهد.

جدول نگاشت نوع JSON به Python

هر مقدار JSON به یک type annotation خاص در 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]

مرجع decorator های dataclass

decorator ‌ی @dataclass چندین پارامتر می‌پذیرد که نحوه رفتار کلاس تولیدشده را تغییر می‌دهند. این مرجع گزینه‌هایی را پوشش می‌دهد که هنگام کار با داده‌های مشتق‌شده از JSON بیشترین کاربرد را دارند.

Decorator / فیلدرفتارزمان استفاده
@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 دارد. هر کدام برای یک مورد استفاده متفاوت مناسب است. Dataclass ها گزینه کتابخانه استاندارد با صفر وابستگی هستند. Pydantic اعتبارسنجی در زمان اجرا اضافه می‌کند. TypedDict دیکشنری‌های ساده را بدون ایجاد کلاس جدید annotate می‌کند.

@dataclass
کتابخانه استاندارد (Python 3.7+). متدهای __init__، __repr__ و __eq__ تولید می‌کند. بدون اعتبارسنجی در زمان اجرا. با mypy و dataclasses-json برای سریال‌سازی کار می‌کند. بهترین گزینه برای ساختارهای داده داخلی که ورودی را کنترل می‌کنید.
BaseModel (Pydantic)
کتابخانه شخص ثالث. نوع‌ها و محدودیت‌ها را در زمان اجرا اعتبارسنجی می‌کند. JSON را مستقیماً از طریق model_validate_json() تجزیه می‌کند. انتخاب استاندارد برای FastAPI، مدیریت تنظیمات، و هر کدی که ورودی غیرقابل‌اعتماد دریافت می‌کند.
TypedDict
کتابخانه استاندارد (Python 3.8+). type hint ها را به دیکشنری‌های معمولی اضافه می‌کند. بدون تولید __init__ یا متد. مقادیر به‌عنوان دسترسی دیکشنری ساده می‌مانند. زمانی استفاده کنید که به بررسی نوع نیاز دارید اما می‌خواهید رابط dict را حفظ کنید، مانند در پایگاه‌کدهای قدیمی.

نمونه کد

این مثال‌ها نشان می‌دهند چگونه از dataclass های تولیدشده در Python استفاده کنید، چگونه آن‌ها را به‌صورت برنامه‌نویسی از JavaScript تولید کنید، و چگونه از رویکردهای جایگزین مانند Pydantic و ابزارهای CLI استفاده کنید.

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 از decorator ‌ی @dataclass برای تولید خودکار متدهای __init__، __repr__ و __eq__ از annotation های فیلد استفاده می‌کند. یک کلاس معمولی نیاز دارد این متدها را خودتان بنویسید. Dataclass ها کد تکراری را کاهش می‌دهند وقتی کلاس عمدتاً داده نگه می‌دارد، که حالت معمول برای ساختارهای مشتق‌شده از JSON است.
آیا می‌توانم از dataclass ها مستقیماً برای سریال‌سازی JSON استفاده کنم؟
ماژول json کتابخانه استاندارد به‌طور پیش‌فرض نمی‌تواند نمونه‌های dataclass را سریال کند. از dataclasses.asdict() برای تبدیل یک dataclass به دیکشنری استفاده کنید، سپس آن را به json.dumps() بدهید. برای کنترل بیشتر، کتابخانه dataclasses-json متدهای .to_json() و .from_json() اضافه می‌کند، و مدل‌های Pydantic سریال‌سازی را به‌صورت بومی مدیریت می‌کنند.
مولد چگونه اشیاء JSON تودرتو را مدیریت می‌کند؟
هر شیء تودرتو به یک تعریف @dataclass جداگانه تبدیل می‌شود. اگر یک فیلد JSON به نام «address» شامل شیئی با «street» و «city» باشد، مولد یک dataclass با نام Address ایجاد می‌کند و فیلد والد را به‌صورت address: Address annotate می‌کند. ساختارهای تودرتو عمیق چندین تعریف dataclass به ترتیب وابستگی تولید می‌کنند.
وقتی یک فیلد JSON مقدار null دارد چه اتفاقی می‌افتد؟
فیلدهای null به‌صورت Optional[str] (یا نوع مناسب اگر از متن قابل استنتاج باشد) با مقدار پیش‌فرض None annotate می‌شوند. فیلدهایی که مقدار پیش‌فرض دارند باید بعد از فیلدهای اجباری در یک dataclass بیایند، بنابراین مولد فیلدهای اختیاری را در انتهای تعریف کلاس قرار می‌دهد.
آیا بین dataclass ها و مدل‌های Pydantic برای JSON تفاوتی وجود دارد؟
Dataclass ها بخشی از کتابخانه استاندارد هستند و داده را در زمان اجرا اعتبارسنجی نمی‌کنند. مدل‌های Pydantic نوع‌ها را اعتبارسنجی می‌کنند، محدودیت‌ها را اعمال می‌کنند، و می‌توانند رشته‌های JSON خام را مستقیماً تجزیه کنند. اگر JSON از منابع خارجی دریافت می‌کنید و باید داده‌های ناقص را رد کنید، Pydantic گزینه بهتری است. برای انتقال داده داخلی که به ورودی اعتماد می‌کنید، dataclass ها سبک‌تر بوده و وابستگی خارجی ندارند.
چگونه با کلیدهای JSON با فرمت camelCase در Python dataclass ها کار کنم؟
قرارداد Python از snake_case برای نام متغیرها استفاده می‌کند. مولد کلیدهای camelCase مانند «firstName» را به فیلدهای snake_case مانند first_name ترجمه می‌کند. اگر نیاز دارید دوباره از JSON deserialize کنید، از کتابخانه dataclasses-json با یک config که بین دو قرارداد نام‌گذاری نگاشت می‌کند استفاده کنید، یا یک متد سفارشی __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 جایگزین کنید. جدول نگاشت نوع بالا هر دو فرم را نشان می‌دهد.