JSON to Python

Генерация Python dataclass из JSON

Попробовать пример
Имя корневого класса:

Ввод JSON

Вывод Python

Работает локально · Безопасно вставлять секреты
Python dataclass появятся здесь…

Что такое конвертация JSON в Python dataclass?

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

Python's json.loads() возвращает обычные словари и списки. Они работают, но не несут информации о типах: опечатка в имени ключа вернёт None вместо исключения, а редактор не сможет предложить автодополнение. Dataclasses решают эту проблему, сопоставляя каждый ключ JSON с именованным типизированным полем. Вложенные JSON-объекты становятся отдельными определениями dataclass, массивы — аннотациями 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-ключи, токены и пользовательские данные остаются приватными.
📝
Корректные аннотации типов
Каждое сгенерированное поле включает аннотацию типа 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-payload и сгенерируйте определения 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 vs Pydantic vs 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. Обе формы представлены в таблице соответствия типов выше.