JSON in Python

Genera dataclass Python da JSON

Prova un esempio
Nome classe radice:

Input JSON

Output Python

Esegue in locale · Sicuro per incollare segreti
Le dataclass Python appariranno qui…

Cos'è la conversione da JSON a dataclass Python?

La conversione da JSON a dataclass Python prende un oggetto JSON grezzo e produce un insieme di definizioni di dataclass Python con annotazioni di tipo accurate. Il modulo dataclasses di Python, introdotto in PEP 557 (Python 3.7), genera i metodi __init__, __repr__ e __eq__ a partire dai campi della classe annotati. Quando lavori con API JSON, file di configurazione o code di messaggi, le dataclass danno ai tuoi dati una struttura tipizzata che editor e type checker come mypy possono verificare durante lo sviluppo.

json.loads() di Python restituisce dizionari e liste semplici. Funzionano, ma non hanno informazioni sui tipi: una chiave scritta male restituisce None invece di sollevare un errore, e l'editor non può completare automaticamente i nomi dei campi. Le dataclass risolvono questo problema mappando ogni chiave JSON su un campo con nome e tipo. Gli oggetti JSON annidati diventano definizioni di dataclass separate, gli array diventano annotazioni List[T], e i valori null diventano Optional[T] con un valore predefinito di None.

Scrivere queste definizioni a mano è un lavoro meccanico. Devi leggere il JSON, dedurre il tipo di ogni campo dal suo valore, convertire le chiavi da camelCase o snake_case alle convenzioni Python, e gestire casi particolari come campi nullable e array di tipo misto. Un convertitore fa tutto questo in pochi millisecondi. Incolli il JSON, ottieni codice dataclass corretto e vai avanti.

Perché usare un convertitore da JSON a Python?

Tradurre strutture JSON in definizioni di classi Python a mano significa indovinare i tipi dai dati di esempio, riordinare i campi in modo che quelli obbligatori vengano prima di quelli opzionali, e aggiornare tutto quando l'API cambia. Un convertitore elimina questa attrito.

Generazione immediata di dataclass
Incolla il tuo JSON e ottieni definizioni di dataclass Python tipizzate in meno di un secondo. Oggetti annidati, liste e campi opzionali vengono gestiti automaticamente.
🔒
Elaborazione orientata alla privacy
La conversione avviene interamente nel browser tramite JavaScript. Il tuo JSON non lascia mai il tuo computer. Chiavi API, token e dati degli utenti rimangono privati.
📝
Annotazioni di tipo corrette
Ogni campo generato include un'annotazione di tipo Python dedotta dal valore JSON: str, int, float, bool, List[T] o Optional[T] per i valori null.
📦
Nessuna installazione né registrazione
Apri la pagina e incolla il tuo JSON. Non è necessario un ambiente Python, nessun pacchetto pip da installare, nessun account da creare.

Casi d'uso di JSON in Python

Sviluppo di client REST API
Genera dataclass da campioni di risposta API. Incolla il JSON restituito da un endpoint REST di terze parti e ottieni classi Python type-safe pronte per requests o httpx.
Modelli di richiesta/risposta FastAPI
Parti dalla forma di un payload JSON e genera definizioni di dataclass. Convertile in modelli Pydantic per ottenere la validazione automatica nei route handler di FastAPI.
Schemi per pipeline di dati
Definisci strutture di record tipizzate per le pipeline ETL. Incolla un messaggio JSON di esempio da Kafka, RabbitMQ o SQS e genera dataclass che documentano la forma attesa.
Parsing di file di configurazione
Trasforma i file di configurazione JSON in classi Python tipizzate. Carica la configurazione con json.load(), poi costruisci un'istanza della dataclass per il completamento automatico dell'editor e il controllo dei tipi.
Generazione di fixture di test
Crea fixture tipizzate da dati JSON di esempio. I QA engineer possono incollare snapshot di risposte API e produrre definizioni di dataclass da usare nelle suite di test pytest.
Imparare le annotazioni di tipo Python
Gli studenti possono incollare qualsiasi struttura JSON e vedere come Python la rappresenta con i type hint. Il codice generato mostra List, Optional, classi annidate e valori predefiniti nel contesto.

Mappatura dei tipi da JSON a Python

Ogni valore JSON si mappa a una specifica annotazione di tipo Python. La tabella seguente mostra come il convertitore traduce ogni tipo JSON, con la sintassi del modulo typing (Python 3.7+) e la sintassi built-in disponibile da Python 3.10 in poi.

Tipo JSONEsempioPython (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]

Riferimento al decoratore Dataclass

Il decoratore @dataclass accetta diversi parametri che cambiano il comportamento della classe generata. Questo riferimento copre le opzioni più rilevanti quando si lavora con dati derivati da JSON.

Decoratore / CampoComportamentoUsare quando
@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 offre tre metodi comuni per definire strutture tipizzate a partire da JSON. Ognuno si adatta a un caso d'uso diverso. Le dataclass sono l'opzione della libreria standard senza dipendenze esterne. Pydantic aggiunge la validazione a runtime. TypedDict annota dizionari semplici senza creare una nuova classe.

@dataclass
Libreria standard (Python 3.7+). Genera __init__, __repr__ e __eq__. Nessuna validazione a runtime. Funziona con mypy e dataclasses-json per la serializzazione. Ideale per strutture dati interne dove si controlla l'input.
BaseModel (Pydantic)
Libreria di terze parti. Valida tipi e vincoli a runtime. Analizza il JSON direttamente tramite model_validate_json(). Scelta standard per FastAPI, gestione delle impostazioni e qualsiasi codice che riceve input non attendibile.
TypedDict
Libreria standard (Python 3.8+). Aggiunge type hint ai normali dizionari. Non genera __init__ né metodi. I valori rimangono accessibili come un normale dict. Da usare quando si vuole il controllo dei tipi ma si desidera mantenere l'interfaccia dict, ad esempio nelle codebase legacy.

Esempi di codice

Questi esempi mostrano come usare le dataclass generate in Python, come produrle programmaticamente da JavaScript, e come usare approcci alternativi come Pydantic e strumenti 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]

Domande frequenti

Qual è la differenza tra una dataclass Python e una classe normale?
Una dataclass usa il decoratore @dataclass per generare automaticamente i metodi __init__, __repr__ e __eq__ dalle annotazioni dei campi. Una classe normale richiede di scrivere questi metodi manualmente. Le dataclass riducono il codice ripetitivo quando la classe contiene principalmente dati, che è il caso tipico delle strutture derivate da JSON.
Posso usare le dataclass con la serializzazione JSON direttamente?
Il modulo json della libreria standard non può serializzare le istanze di dataclass per impostazione predefinita. Usa dataclasses.asdict() per convertire una dataclass in un dizionario, poi passalo a json.dumps(). Per un maggiore controllo, la libreria dataclasses-json aggiunge i metodi .to_json() e .from_json(), e i modelli Pydantic gestiscono la serializzazione nativamente.
Come gestisce il convertitore gli oggetti JSON annidati?
Ogni oggetto annidato diventa una definizione @dataclass separata. Se un campo JSON chiamato "address" contiene un oggetto con "street" e "city", il convertitore crea una dataclass Address e annota il campo del genitore come address: Address. Le strutture con molti livelli di annidamento producono più definizioni di dataclass in ordine di dipendenza.
Cosa succede quando un campo JSON è null?
I campi null vengono annotati come Optional[str] (o il tipo appropriato se può essere dedotto dal contesto) con un valore predefinito di None. I campi con valori predefiniti devono venire dopo i campi obbligatori in una dataclass, quindi il convertitore posiziona i campi opzionali alla fine della definizione della classe.
C'è differenza tra dataclass e modelli Pydantic per JSON?
Le dataclass fanno parte della libreria standard e non validano i dati a runtime. I modelli Pydantic validano i tipi, impongono vincoli e possono analizzare stringhe JSON grezze direttamente. Se ricevi JSON da fonti esterne e devi rifiutare dati malformati, Pydantic è la scelta migliore. Per il passaggio interno di dati dove ti fidi dell'input, le dataclass sono più leggere e non hanno dipendenze esterne.
Come gestisco le chiavi JSON in camelCase nelle dataclass Python?
La convenzione Python usa snake_case per i nomi delle variabili. Il convertitore traduce le chiavi camelCase come "firstName" in campi snake_case come first_name. Se hai bisogno di deserializzare di nuovo da JSON, usa la libreria dataclasses-json con una configurazione che mappa tra le due convenzioni di denominazione, oppure scrivi un metodo personalizzato __post_init__.
Questo convertitore supporta la sintassi Python 3.10+ come list[str] invece di List[str]?
Il convertitore genera import dal modulo typing (List, Optional) per la massima compatibilità con Python 3.7 fino a 3.12. Se il tuo progetto supporta Python 3.10 o successivo, puoi tranquillamente sostituire List[str] con list[str] e Optional[str] con str | None. La tabella di mappatura dei tipi mostrata sopra riporta entrambe le forme.