JSON do Python

Generuj dataclassy Python z JSON

Wypróbuj przykład
Nazwa głównej klasy:

Wejście JSON

Wyjście Python

Działa lokalnie · Bezpieczne do wklejania sekretów
Dataclassy Python pojawią się tutaj…

Czym jest konwersja JSON na dataclassy Python?

Konwersja JSON na dataclassy Python pobiera surowy obiekt JSON i generuje zestaw definicji dataclass z dokładnymi adnotacjami typów. Moduł dataclasses, wprowadzony w PEP 557 (Python 3.7), automatycznie generuje metody __init__, __repr__ i __eq__ na podstawie adnotowanych pól klasy. Przy pracy z API JSON, plikami konfiguracyjnymi lub kolejkami komunikatów dataclassy nadają danym typowaną strukturę, którą edytory i narzędzia do sprawdzania typów, takie jak mypy, mogą weryfikować na etapie programowania.

Funkcja json.loads() zwraca zwykłe słowniki i listy. Działają one poprawnie, ale nie mają informacji o typach: błędnie napisany klucz zwraca None zamiast zgłaszać błąd, a edytor nie może podpowiadać nazw pól. Dataclassy rozwiązują ten problem, mapując każdy klucz JSON na nazwane, typowane pole. Zagnieżdżone obiekty JSON stają się osobnymi definicjami dataclass, tablice stają się adnotacjami List[T], a wartości null stają się Optional[T] z wartością domyślną None.

Ręczne pisanie tych definicji to mechaniczna praca. Trzeba odczytać JSON, ustalić typ każdego pola na podstawie jego wartości, przekonwertować klucze z camelCase lub snake_case na konwencje Pythona i obsłużyć przypadki brzegowe, takie jak pola nullable i tablice z mieszanymi typami. Konwerter robi to wszystko w milisekundy. Wklejasz JSON, otrzymujesz poprawny kod dataclass i możesz działać dalej.

Dlaczego warto używać konwertera JSON do Python?

Ręczne tłumaczenie struktur JSON na definicje klas Python oznacza zgadywanie typów na podstawie przykładowych danych, układanie pól tak, żeby wymagane były przed opcjonalnymi, i aktualizowanie wszystkiego przy każdej zmianie API. Konwerter usuwa to tarcie.

Natychmiastowe generowanie dataclass
Wklej JSON i otrzymaj typowane definicje dataclass Python w mniej niż sekundę. Zagnieżdżone obiekty, listy i opcjonalne pola są obsługiwane automatycznie.
🔒
Przetwarzanie z zachowaniem prywatności
Konwersja odbywa się w całości w przeglądarce przy użyciu JavaScript. Twój JSON nigdy nie opuszcza Twojego urządzenia. Klucze API, tokeny i dane użytkowników pozostają prywatne.
📝
Poprawne adnotacje typów
Każde wygenerowane pole zawiera adnotację typu Python wywnioskowaną z wartości JSON: str, int, float, bool, List[T] lub Optional[T] dla wartości null.
📦
Bez instalacji i rejestracji
Otwórz stronę i wklej JSON. Nie jest wymagane środowisko Python, żadnych pakietów pip do zainstalowania, żadnego konta do założenia.

Przypadki użycia JSON do Python

Tworzenie klientów REST API
Generuj dataclassy z przykładowych odpowiedzi API. Wklej JSON zwracany przez zewnętrzny endpoint REST i otrzymaj typowane klasy Python gotowe do użycia z requests lub httpx.
Modele żądań i odpowiedzi FastAPI
Zacznij od kształtu ładunku JSON i wygeneruj definicje dataclass. Przekształć je w modele Pydantic, aby uzyskać automatyczną walidację w handlerach tras FastAPI.
Schematy potoków danych
Definiuj typowane struktury rekordów dla potoków ETL. Wklej przykładowy komunikat JSON z Kafka, RabbitMQ lub SQS i wygeneruj dataclassy dokumentujące oczekiwany kształt danych.
Parsowanie plików konfiguracyjnych
Przekształć pliki konfiguracyjne JSON w typowane klasy Python. Wczytaj konfigurację przez json.load(), a następnie skonstruuj instancję dataclass dla podpowiedzi edytora i sprawdzania typów.
Generowanie typowanych danych testowych
Twórz typowane dane testowe z przykładowych danych JSON. Inżynierowie QA mogą wklejać zrzuty odpowiedzi API i generować definicje dataclass do użycia w zestawach testów pytest.
Nauka adnotacji typów Python
Studenci mogą wklejać dowolną strukturę JSON i obserwować, jak Python reprezentuje ją za pomocą podpowiedzi typów. Wygenerowany kod pokazuje List, Optional, zagnieżdżone klasy i wartości domyślne w kontekście.

Tabela mapowania typów JSON na Python

Każda wartość JSON mapuje się na określoną adnotację typu Python. Poniższa tabela pokazuje, jak konwerter tłumaczy każdy typ JSON, uwzględniając zarówno składnię modułu typing (Python 3.7+), jak i wbudowaną składnię dostępną od Python 3.10.

Typ JSONPrzykładPython (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]

Dokumentacja dekoratora dataclass

Dekorator @dataclass przyjmuje kilka parametrów, które zmieniają zachowanie generowanej klasy. Ten przewodnik opisuje opcje najbardziej przydatne przy pracy z danymi pochodzącymi z JSON.

Dekorator / poleZachowanieKiedy używać
@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 oferuje trzy popularne sposoby definiowania typowanych struktur z JSON. Każdy pasuje do innego przypadku użycia. Dataclassy to opcja ze standardowej biblioteki bez zewnętrznych zależności. Pydantic dodaje walidację w czasie wykonania. TypedDict adnotuje zwykłe słowniki bez tworzenia nowej klasy.

@dataclass
Standardowa biblioteka (Python 3.7+). Generuje __init__, __repr__ i __eq__. Brak walidacji w czasie wykonania. Działa z mypy i dataclasses-json do serializacji. Najlepszy do wewnętrznych struktur danych, gdy kontrolujesz dane wejściowe.
BaseModel (Pydantic)
Biblioteka zewnętrzna. Waliduje typy i ograniczenia w czasie wykonania. Parsuje JSON bezpośrednio przez model_validate_json(). Standardowy wybór dla FastAPI, zarządzania ustawieniami i kodu przyjmującego niezaufane dane wejściowe.
TypedDict
Standardowa biblioteka (Python 3.8+). Dodaje podpowiedzi typów do zwykłych słowników. Nie generuje __init__ ani metod. Wartości pozostają dostępne przez interfejs słownikowy. Używaj, gdy potrzebujesz sprawdzania typów, ale chcesz zachować interfejs słownikowy, np. w starszych bazach kodu.

Przykłady kodu

Poniższe przykłady pokazują, jak używać wygenerowanych dataclass w Python, jak generować je programistycznie z JavaScript oraz jak korzystać z alternatywnych podejść, takich jak Pydantic i narzędzia 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]

Często zadawane pytania

Jaka jest różnica między dataclass Python a zwykłą klasą?
Dataclass używa dekoratora @dataclass do automatycznego generowania metod __init__, __repr__ i __eq__ na podstawie adnotacji pól. Zwykła klasa wymaga ręcznego napisania tych metod. Dataclassy redukują powtarzalny kod, gdy klasa służy przede wszystkim do przechowywania danych — co jest typowym przypadkiem dla struktur pochodzących z JSON.
Czy mogę używać dataclass bezpośrednio do serializacji JSON?
Moduł json ze standardowej biblioteki domyślnie nie może serializować instancji dataclass. Użyj dataclasses.asdict(), aby przekonwertować dataclass na słownik, a następnie przekaż go do json.dumps(). Dla większej kontroli biblioteka dataclasses-json dodaje metody .to_json() i .from_json(), a modele Pydantic obsługują serializację natywnie.
Jak konwerter obsługuje zagnieżdżone obiekty JSON?
Każdy zagnieżdżony obiekt staje się osobną definicją @dataclass. Jeśli pole JSON o nazwie "address" zawiera obiekt z polami "street" i "city", konwerter tworzy dataclass Address i adnotuje pole nadrzędne jako address: Address. Głęboko zagnieżdżone struktury generują wiele definicji dataclass w kolejności zależności.
Co się dzieje, gdy pole JSON ma wartość null?
Pola null są adnotowane jako Optional[str] (lub odpowiedni typ, jeśli można go wywnioskować z kontekstu) z wartością domyślną None. Pola z wartościami domyślnymi muszą następować po polach wymaganych w dataclass, więc konwerter umieszcza pola opcjonalne na końcu definicji klasy.
Jaka jest różnica między dataclassami a modelami Pydantic dla JSON?
Dataclassy są częścią standardowej biblioteki i nie walidują danych w czasie wykonania. Modele Pydantic walidują typy, egzekwują ograniczenia i mogą bezpośrednio parsować ciągi JSON. Jeśli przyjmujesz JSON z zewnętrznych źródeł i chcesz odrzucać niepoprawne dane, Pydantic jest lepszym wyborem. Do przekazywania danych wewnętrznych, gdzie kontrolujesz dane wejściowe, dataclassy są lżejsze i nie mają zewnętrznych zależności.
Jak obsługiwać klucze JSON w camelCase w dataclassach Python?
Konwencja Pythona używa snake_case dla nazw zmiennych. Konwerter tłumaczy klucze camelCase, takie jak "firstName", na pola snake_case, takie jak first_name. Jeśli chcesz deserializować z powrotem do JSON, użyj biblioteki dataclasses-json z konfiguracją mapującą między obydwoma konwencjami nazewnictwa lub napisz własną metodę __post_init__.
Czy konwerter obsługuje składnię Python 3.10+, np. list[str] zamiast List[str]?
Konwerter generuje importy z modułu typing (List, Optional) dla maksymalnej zgodności z Python 3.7 przez 3.12. Jeśli Twój projekt celuje w Python 3.10 lub nowszy, możesz bezpiecznie zastąpić List[str] przez list[str] i Optional[str] przez str | None. Tabela mapowania typów powyżej pokazuje obydwie formy.