JSON to Python

Генерація Python dataclasses з JSON

Спробувати приклад
Назва кореневого класу:

Введення JSON

Виведення Python

Працює локально · Безпечно вставляти секрети
Python dataclasses з'являться тут…

Що таке конвертація JSON у Python dataclasses?

Конвертація JSON у Python dataclasses перетворює сирий JSON-об'єкт на набір визначень dataclass з точними анотаціями типів. Модуль dataclasses, представлений у PEP 557 (Python 3.7), автоматично генерує методи __init__, __repr__ та __eq__ з анотованих полів класу. Коли ви працюєте з JSON API, конфігураційними файлами або чергами повідомлень, dataclasses надають вашим даним типізовану структуру, яку редактори та засоби перевірки типів на кшталт mypy можуть верифікувати під час розробки.

Метод json.loads() у Python повертає звичайні словники та списки. Це працює, але не містить інформації про типи: помилка в назві ключа повертає None замість виключення, а редактор не може автодоповнювати імена полів. Dataclasses вирішують це, відображаючи кожен ключ JSON на іменоване типізоване поле. Вкладені JSON-об'єкти стають окремими визначеннями dataclass, масиви перетворюються на анотації List[T], а null-значення — на Optional[T] з типовим значенням None.

Написання таких визначень вручну — це механічна робота. Потрібно проаналізувати JSON, визначити тип кожного поля за його значенням, перетворити ключі з camelCase або snake_case на конвенції Python та обробити крайні випадки, як-от поля, що допускають null, і масиви зі змішаними типами. Конвертер виконує все це за мілісекунди. Ви вставляєте JSON, отримуєте коректний код dataclass і рухаєтесь далі.

Навіщо використовувати конвертер JSON to Python?

Ручне перетворення JSON-структур у визначення Python-класів означає здогадування про типи з тестових даних, впорядкування полів так, щоб обов'язкові йшли перед опціональними, та оновлення всього при зміні API. Конвертер усуває це тертя.

Миттєва генерація dataclasses
Вставте ваш JSON і отримайте типізовані визначення Python dataclass менш ніж за секунду. Вкладені об'єкти, списки й опціональні поля обробляються автоматично.
🔒
Конфіденційність даних
Конвертація виконується повністю у вашому браузері за допомогою JavaScript. Ваш JSON ніколи не залишає ваш пристрій. API-ключі, токени та записи користувачів залишаються приватними.
📝
Коректні анотації типів
Кожне згенероване поле містить анотацію типу Python, визначену з JSON-значення: str, int, float, bool, List[T] або Optional[T] для null-значень.
📦
Без встановлення та реєстрації
Відкрийте сторінку й вставте ваш JSON. Не потрібне Python-середовище, pip-пакети для встановлення або обліковий запис для створення.

Сценарії використання JSON to Python

Розробка клієнта REST API
Генеруйте dataclasses з прикладів відповідей API. Вставте JSON, повернутий стороннім REST-ендпоінтом, і отримайте типобезпечні Python-класи, готові для використання з requests або httpx.
Моделі запитів/відповідей FastAPI
Почніть з форми JSON-пейлоаду і згенеруйте визначення dataclass. Перетворіть їх на Pydantic-моделі для автоматичної валідації в обробниках маршрутів FastAPI.
Схеми конвеєрів даних
Визначте типізовані структури записів для ETL-конвеєрів. Вставте зразок JSON-повідомлення з Kafka, RabbitMQ або SQS і згенеруйте dataclasses, що документують очікувану форму даних.
Розбір конфігураційних файлів
Перетворіть JSON-конфіги на типізовані Python-класи. Завантажте конфіг за допомогою json.load(), а потім створіть екземпляр dataclass для автодоповнення у редакторі та перевірки типів.
Генерація тестових фікстур
Створюйте типізовані фікстури з прикладових JSON-даних. QA-інженери можуть вставляти знімки відповідей API і отримувати визначення dataclass для використання у тестових наборах pytest.
Вивчення анотацій типів Python
Студенти можуть вставляти будь-яку JSON-структуру і бачити, як Python представляє її за допомогою підказок типів. Згенерований код показує List, Optional, вкладені класи та значення за замовчуванням у контексті.

Таблиця відповідності типів JSON та Python

Кожне JSON-значення відображається на конкретну анотацію типу 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]

Довідник декоратора dataclass

Декоратор @dataclass приймає кілька параметрів, що змінюють поведінку згенерованого класу. Цей довідник охоплює параметри, найбільш актуальні при роботі з даними, отриманими з JSON.

Декоратор / ПолеПоведінкаКоли використовувати
@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. Кожен підходить для різних випадків використання. Dataclasses — це варіант зі стандартної бібліотеки без зовнішніх залежностей. Pydantic додає валідацію під час виконання. TypedDict анотує звичайні словники без створення нового класу.

@dataclass
Стандартна бібліотека (Python 3.7+). Генерує __init__, __repr__ та __eq__. Без валідації під час виконання. Працює з mypy та dataclasses-json для серіалізації. Найкраще підходить для внутрішніх структур даних, де ви контролюєте вхідні дані.
BaseModel (Pydantic)
Стороння бібліотека. Валідує типи та обмеження під час виконання. Розбирає JSON безпосередньо через model_validate_json(). Стандартний вибір для FastAPI, управління налаштуваннями та будь-якого коду, що отримує ненадійні вхідні дані.
TypedDict
Стандартна бібліотека (Python 3.8+). Додає підказки типів до звичайних словників. Не генерує __init__ або методи. Значення залишаються доступними як звичайний словник. Використовуйте, коли потрібна перевірка типів, але ви хочете зберегти інтерфейс словника, наприклад у застарілих кодових базах.

Приклади коду

Ці приклади показують, як використовувати згенеровані dataclasses у 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 використовує декоратор @dataclass для автоматичної генерації методів __init__, __repr__ та __eq__ з анотацій полів. Звичайний клас вимагає написання цих методів вручну. Dataclasses зменшують шаблонний код, коли клас переважно зберігає дані, що є типовим випадком для структур, отриманих з JSON.
Чи можна використовувати dataclasses безпосередньо для серіалізації 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. Глибоко вкладені структури породжують кілька визначень dataclass у порядку залежностей.
Що відбувається, коли JSON-поле має значення null?
Поля зі значенням null анотуються як Optional[str] (або відповідний тип, якщо він може бути визначений з контексту) з типовим значенням None. Поля з типовими значеннями мають розташовуватися після обов'язкових полів у dataclass, тому конвертер розміщує опціональні поля наприкінці визначення класу.
Чи є різниця між dataclasses та Pydantic-моделями для JSON?
Dataclasses входять до стандартної бібліотеки і не валідують дані під час виконання. Pydantic-моделі перевіряють типи, накладають обмеження та можуть безпосередньо розбирати сирі JSON-рядки. Якщо ви отримуєте JSON із зовнішніх джерел і потрібно відхиляти некоректні дані, Pydantic є кращим вибором. Для внутрішньої передачі даних, де ви довіряєте вхідним даним, dataclasses легші і не мають зовнішніх залежностей.
Як обробляти camelCase JSON-ключі у Python dataclasses?
Конвенція Python використовує snake_case для імен змінних. Конвертер перекладає camelCase-ключі на кшталт "firstName" у snake_case-поля на кшталт first_name. Якщо вам потрібно десеріалізувати назад з JSON, використовуйте бібліотеку dataclasses-json з конфігурацією, що відображає між двома конвенціями іменування, або напишіть власний метод __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. Таблиця відповідності типів вище показує обидві форми.