Conversor JSON para Python
Gere dataclasses Python a partir de JSON
Entrada JSON
Saída Python
O que é a conversão de JSON para dataclass Python?
A conversão de JSON para dataclass Python pega um objeto JSON bruto e produz um conjunto de definições de dataclass Python com anotações de tipo precisas. O módulo dataclasses do Python, introduzido na PEP 557 (Python 3.7), gera os métodos __init__, __repr__ e __eq__ a partir dos campos anotados da classe. Ao trabalhar com APIs JSON, arquivos de configuração ou filas de mensagens, dataclasses oferecem à sua estrutura de dados uma forma tipada que editores e verificadores de tipos como mypy conseguem verificar em tempo de desenvolvimento.
O json.loads() do Python retorna dicts e listas simples. Isso funciona, mas sem informação de tipo: uma chave com erro de digitação retorna None em vez de lançar um erro, e o editor não consegue autocompletar nomes de campos. Dataclasses resolvem isso mapeando cada chave JSON para um campo nomeado e tipado. Objetos JSON aninhados se tornam definições separadas de dataclass, arrays se tornam anotações List[T], e valores null se tornam Optional[T] com valor padrão None.
Escrever essas definições manualmente é um trabalho mecânico. Você lê o JSON, determina o tipo de cada campo a partir do seu valor, converte chaves de camelCase ou snake_case para as convenções Python, e trata casos especiais como campos anuláveis e arrays de tipos mistos. Um conversor faz tudo isso em milissegundos. Você cola o JSON, obtém o código de dataclass correto e segue em frente.
Por que usar um conversor de JSON para Python?
Traduzir estruturas JSON em definições de classes Python manualmente significa adivinhar tipos a partir de dados de amostra, reordenar campos para que os obrigatórios venham antes dos opcionais, e atualizar tudo quando a API muda. Um conversor elimina esse atrito.
Casos de uso de JSON para Python
Mapeamento de Tipos JSON para Python
Cada valor JSON mapeia para uma anotação de tipo Python específica. A tabela abaixo mostra como o conversor traduz cada tipo JSON, com a sintaxe do módulo typing (Python 3.7+) e a sintaxe built-in disponível a partir do Python 3.10.
| Tipo JSON | Exemplo | Python (typing) | Python 3.10+ |
|---|---|---|---|
| string | "hello" | str | str |
| number (integer) | 42 | int | int |
| number (float) | 3.14 | float | float |
| boolean | true | bool | bool |
| null | null | Optional[str] | str | None |
| object | {"k": "v"} | @dataclass class | nested 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] |
Referência do Decorator @dataclass
O decorator @dataclass aceita vários parâmetros que alteram o comportamento da classe gerada. Esta referência cobre as opções mais relevantes ao trabalhar com dados derivados de JSON.
| Decorator / Campo | Comportamento | Usar Quando |
|---|---|---|
| @dataclass | Generates __init__, __repr__, __eq__ from field annotations | Standard 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 access | Python 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 instances | List/dict/set defaults |
dataclass vs Pydantic vs TypedDict
Python tem três formas comuns de definir estruturas tipadas a partir de JSON. Cada uma se encaixa em um caso de uso diferente. Dataclasses são a opção da biblioteca padrão sem dependências externas. Pydantic adiciona validação em tempo de execução. TypedDict anota dicts simples sem criar uma nova classe.
Exemplos de Código
Estes exemplos mostram como usar dataclasses geradas em Python, como produzi-las programaticamente a partir de JavaScript, e como usar abordagens alternativas como Pydantic e ferramentas de linha de comando.
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')// 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]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# 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]