JSON a Python

Relacionado

Acerca de JSON a Python: Convirtiendo datos JSON en modelos dataclass ejecutables

Casos de uso

• Integración REST API: Convierte respuestas JSON del backend a @dataclass Python, usa con requests + json para análisis de peticiones HTTP fuertemente tipado. Con mypy o pyright, obtén autocompletado de atributos en tiempo real y comprobación de tipos en tu IDE para evitar errores de escritura comunes.
• Modelos petición/respuesta FastAPI: Convierte JSON de ejemplo de documentación de interfaz API en plantillas Pydantic BaseModel para unificar definiciones de modelo frontend y backend. Recomendamos habilitar el parámetro response_model en proyectos FastAPI para que la documentación OpenAPI genere automáticamente ejemplos de campo y reglas de validación.
• Serializadores Django Ninja / DRF: Convierte respuestas JSON a dataclass, luego añade manualmente ModelSerializer de DRF o clases derivadas Schema de Ninja. ModelSerializer de DRF puede autogenerar reglas de validación basadas en dataclass; Schema de Ninja también puede reutilizar directamente la salida de esta herramienta.
• Modelado de datos de web scraping: Convierte datos JSON extraídos de páginas web a dataclass para evitar omisiones de campo y errores de escritura causados por acceso dinámico a dict. Cuando se usa con bibliotecas de scraping asíncrono como requests-html, playwright, dataclass también reduce código repetitivo para deserialización JSON.
• Definición de características de machine learning: Convierte esquemas JSON para datos de entrenamiento scikit-learn / pandas a dataclass para estandarizar nombres y tipos de campos de características. sklearn Pipeline.fit(X, y) acepta estructuras de datos con anotaciones de tipo; dataclass + asdict es un puente eficiente para convertir hacia/desde pandas DataFrames.
• Deserialización de archivos de configuración: Convierte ejemplos de archivos de configuración YAML/JSON a dataclass, usa con Hydra / OmegaConf para lectura de configuración fuertemente tipada. Con la decoración @dataclass de Hydra, las configuraciones disfrutan de autocompletado en tu IDE, evitando errores de escritura comunes e inconsistencias de tipo en configuraciones YAML.
• Estructuras temporales Jupyter Notebook: Convierte muestras JSON de análisis de datos exploratorio a dataclass para fácil acceso a atributos y autocompletado IDE en Notebooks. Envolver respuestas JSON con dataclass en Notebooks mejora significativamente la legibilidad del código de análisis exploratorio, haciendo más fácil la refactorización posterior en módulos de producción.
• Definición de interfaz de microservicios: Convierte JSON de ejemplo de cuerpos de petición para servicios gRPC/HTTP a tipos Python para unificar definiciones de modelo del lado del servidor compartidas entre equipos. Después de convertir protobuf gRPC a JSON, convertir a dataclass sirve como modelo fuertemente tipado para servicios backend, alineado con tipos TypeScript del frontend.
• Desarrollo de herramientas CLI: Convierte ejemplos JSON de configuración CLI a dataclass, usa con argparse para deserialización y validación de configuración. Convertir argparse Namespace a dataclass solo requiere una línea: dataclass(**vars(args)), que es más seguro que lógica de análisis escrita a mano.
• Construcción de datos de prueba: Convierte fixtures JSON reales devueltos por el backend a tipos Python, usa dataclasses.replace para conducción de datos de prueba en pytest. El decorador parametrize de pytest combinado con dataclass construye fixtures de prueba tipados con mensajes de fallo más claros.
• Análisis estructurado de logs: Convierte logs JSON capturados por ELK / Loki a dataclass para fácil filtrado y reglas de alerta. Después de envolver logs JSON ELK con dataclass, puedes hacer filtrado de campos preciso y consultas de agregación, más seguro que acceso a dict.
• Migración de centro de configuración: Convierte configuraciones JSON de Apollo / Nacos / Consul a tipos Python para recarga en caliente de configuración del lado del servidor. Las configuraciones JSON Apollo / Nacos pueden ser validadas bidireccionalmente con dataclass, detectando inmediatamente campos faltantes, desajustes de tipo y otros problemas en cambios de configuración.
• Colaboración entre lenguajes: Al integrar backend Python con frontend TypeScript, convierte el mismo JSON a dataclass Python e interfaz TS respectivamente para mantener ambos lados consistentes. En escenarios de colaboración entre lenguajes, backend Python + frontend TS comparten la misma muestra JSON, generando dataclass e interfaz respectivamente para mantener nombres de campo consistentes.
• Migración de base de datos: Convierte documentos JSON exportados de campos MongoDB / PostgreSQL JSONB a modelos Python como referencia para definiciones de entidad ORM. Convertir exportaciones de documentos MongoDB JSONB a dataclass sirve como referencia de campo para entidades ORM, más fácil de mantener que leer documentos MongoDB directamente.
• Blockchain/Web3: Convierte respuestas JSON RPC en cadena a dataclass Python para envoltura de tipos en SDKs como web3.py. SDKs de Ethereum como web3.py, eth-brownie todos soportan valores de retorno estilo dataclass, convenientes para envoltura secundaria.
• ETL ciencia de datos: Convierte fuentes de datos JSON ascendentes a dataclass, luego usa pandas DataFrame.from_records para convertir a tablas para análisis descendente. pandas DataFrame.from_records([asdict(d) for d in dataclass_list]) convierte estructuras anidadas a tablas en una línea.
• Validación de Schema OpenAPI: Convierte JSON de ejemplo de documentación OpenAPI a modelos Python, luego escribe lógica de validación Pydantic. Los campos de ejemplo OpenAPI pueden copiarse directamente a la entrada de esta herramienta; los modelos Pydantic generados validan automáticamente la consistencia de documentación API.
• Ejemplos de enseñanza: Convierte JSON de ejemplo a dataclass en cursos Python para explicar conceptos como el módulo typing, anotaciones de tipo, generación automática __init__, etc. Al explicar conceptos como módulo typing, generación automática __init__, slots en cursos Python, dataclass es el vehículo de demostración más intuitivo.
• Conversión de nombres de campo: Convierte respuestas API JSON snake_case a dataclass, luego cambia manualmente nombres de campo o usa alias_generator de Pydantic para mapeo de campos. El alias_generator de Pydantic puede configurarse en BaseModel para mapeo automático camelCase ↔ snake_case, evitando alias escritos a mano.

Cómo Usar

1. Pega contenido JSON en el editor izquierdo, o haz clic en el botón de subida para seleccionar un archivo .json / .txt
2. Espera 400ms para auto-conversión; el código dataclass Python generado aparecerá a la derecha
3. Si el JSON está malformado, haz clic en el botón "Reparar JSON" para autoreparar problemas de sintaxis comunes
4. Haz clic en "Copiar" para pegar en el directorio models/ de tu proyecto, o haz clic en "Descargar" para guardar como archivo model.py

Características

• Conversión local en navegador: El análisis JSON y generación de código Python ocurren completamente en tu navegador; los datos de entrada nunca se suben a ningún servidor, por lo que las respuestas API sensibles son seguras de usar
• Salida anotada con dataclass: Genera clases Python estándar decoradas con @dataclass, utilizables directamente en proyectos Python 3.7+ con from __future__ import annotations
• Inferencia automática de tipos: str / int / float / bool / List[T] / Dict[str, Any] / Optional[Any] se mapean automáticamente desde valores JSON sin especificación manual de tipos de campo
• División automática de objetos anidados: Los objetos JSON anidados generan clases @dataclass separadas nombradas con nombres de campo en PascalCase (ej., address -> Address), evitando definiciones de tipo duplicadas
• Expansión automática de genéricos List: Los arrays JSON se convierten automáticamente a List[T], con tipos de elemento inferidos desde el primer elemento no-nulo del array, ej., ["a","b"] -> List[str], [{...},{...}] -> List[Item]
• Campos opcionales: Los campos null generan Optional[Any] como respaldo, asegurando que las anotaciones de tipo expresen correctamente campos potencialmente faltantes
• Auto-conversión con debounce de 400ms: La conversión se activa automáticamente después de pegar, con vista previa de código Python en tiempo real a la derecha para reducir esperas y clics adicionales
• Reparación de errores JSON con un clic: Repara automáticamente errores de formato comunes como comas finales, comillas simples, comillas faltantes, luego continúa generando código una vez reparado
• Copiar y descargar: Copia todo el código Python con un clic, o descarga como archivo model.py para colocar directamente en la raíz de tu proyecto o submódulo models
• Historial de entrada localStorage: Guarda automáticamente entradas recientes localmente, para que puedas reanudar edición rápidamente después de refrescar o cerrar accidentalmente la página
• Edición de panel dividido responsivo: Ingresa JSON a la izquierda, ve código Python a la derecha; soporta arrastrar para redimensionar anchos de panel, adaptado para pantallas grandes y móviles
• Soporta adaptación secundaria a Pydantic / attrs / TypedDict: Las dataclasses generadas pueden tener decoradores BaseModel o attrs añadidos con un clic para adaptarse a FastAPI, Django Ninja, pydantic-settings y otros frameworks

Ejemplos de Código

# requirements.txt
# requests>=2.31

from dataclasses import dataclass
from typing import Any, List, Optional
import json
import requests


@dataclass
class Address:
    city: str
    zip: str


@dataclass
class User:
    id: int
    name: str
    active: bool
    address: Address
    tags: List[str]
    label: Optional[Any] = None


def main() -> None:
    resp = requests.get("https://api.example.com/users/1", timeout=10)
    resp.raise_for_status()

    # Directly deserialize JSON string to dataclass instance
    user: User = User(**resp.json())

    # Strongly typed access: IDE completion, mypy/pyright static checking
    print(f"{user.name} lives in {user.address.city}")
    print(f"tags: {user.tags}")


if __name__ == "__main__":
    main()

# pip install fastapi 'pydantic>=2'

from typing import List, Optional
from fastapi import FastAPI
from pydantic import BaseModel


class Address(BaseModel):
    city: str
    zip: str


class User(BaseModel):
    id: int
    name: str
    email: str
    active: bool = True
    address: Address
    tags: List[str] = []
    label: Optional[str] = None


app = FastAPI()


@app.post("/users")
async def create_user(user: User) -> dict:
    # FastAPI automatically validates request body with User; field type/required errors return 422
    return {"id": user.id, "name": user.name}


@app.get("/users/{user_id}", response_model=User)
async def get_user(user_id: int) -> User:
    # response_model auto-serializes response; OpenAPI docs auto-generated
    return User(
        id=user_id,
        name="Alice",
        email="alice@example.com",
        active=True,
        address=Address(city="Beijing", zip="100000"),
        tags=["fastapi", "pydantic"],
    )

from dataclasses import dataclass, asdict
from typing import List, Optional
import json


@dataclass
class Author:
    id: int
    name: str


@dataclass
class Article:
    id: int
    title: str
    url: str
    author: Author
    score: int
    tags: List[str]
    summary: Optional[str] = None


def parse_articles(raw_json: str) -> List[Article]:
    """Deserialize scraped JSON string into list of Articles."""
    payloads = json.loads(raw_json)
    return [Article(**payload) for payload in payloads]


if __name__ == "__main__":
    raw = '''[
        {
            "id": 1,
            "title": "Hello dataclass",
            "url": "https://example.com/p/1",
            "author": {"id": 10, "name": "Alice"},
            "score": 95,
            "tags": ["python", "typing"],
            "summary": "quick intro"
        }
    ]'''

    articles = parse_articles(raw)
    for art in articles:
        # IDE autocompletes author.name, tags, summary
        print(f"[{art.score}] {art.title} - {art.author.name}")
        print(f"  tags: {art.tags}")

        # Use asdict when dict form is needed (e.g., writing to MongoDB)
        doc = asdict(art)
        print(f"  mongo doc: {doc}")

# pip install pandas scikit-learn

from dataclasses import dataclass, field, asdict
from typing import List, Optional
import json
import pandas as pd
from sklearn.ensemble import RandomForestClassifier


@dataclass
class FeatureSchema:
    """Sample feature schema, fine-tuned after generation by JSON to Python tool."""
    user_id: int
    age: int
    city: str
    plan: str
    monthly_spend: float
    active: bool
    tags: List[str] = field(default_factory=list)
    last_login: Optional[str] = None


def features_to_frame(samples: List[dict]) -> pd.DataFrame:
    """Convert JSON list to DataFrame, automatically using dataclass field names as column names."""
    rows = [asdict(FeatureSchema(**row)) for row in samples]
    df = pd.DataFrame(rows)
    # One-hot encode categorical fields
    df = pd.get_dummies(df, columns=["city", "plan"], drop_first=True)
    return df


def main() -> None:
    raw = json.loads('''[
        {"user_id": 1, "age": 25, "city": "Beijing", "plan": "pro", "monthly_spend": 99.0, "active": true, "tags": ["new"]},
        {"user_id": 2, "age": 40, "city": "Shanghai", "plan": "free", "monthly_spend": 0.0, "active": false, "tags": []}
    ]''')

    X = features_to_frame(raw)
    y = [1, 0]  # Assume labels: paying user / free user

    model = RandomForestClassifier(n_estimators=100, random_state=42)
    model.fit(X, y)

    print("feature_columns:", list(X.columns))
    print("importances:", dict(zip(X.columns, model.feature_importances_)))

Best Practices

Preguntas Frecuentes

Solución de problemas

Glosario

dataclass

Decorador de biblioteca estándar Python 3.7+ (@dataclass) usado para generar automáticamente métodos mágicos como __init__, __repr__, __eq__. Esta herramienta genera clases @dataclass, ej., @dataclass class User: id: int; name: str. Esencialmente desacopla "almacenamiento de datos" de "operaciones de datos", dejando que las clases se enfoquen en describir campos de datos mientras el decorador autogenera métodos repetitivos.

módulo typing

Biblioteca estándar Python para anotaciones de tipo, proporcionando tipos genéricos como List, Dict, Optional, Any, Union. List[T], Optional[Any] generados por esta herramienta provienen del módulo typing. Python 3.9+ puede usar directamente list, dict integrados. Junto a collections.abc, contextlib, etc., es el módulo central para restricciones de tipo estático en biblioteca estándar Python; gradualmente se convirtió en estándar para grandes proyectos desde PEP 484.

Optional[T]

Tipo opcional del módulo typing, equivalente a Union[T, None], indicando que un campo puede ser None. Esta herramienta mapea JSON null a Optional[Any], que puede cambiarse manualmente a tipos más precisos como Optional[str]. Ten en cuenta que Optional[T] difiere del valor por defecto T = None: el primero es una expresión None a nivel de tipo, el segundo es una configuración por defecto a nivel de valor.

List[T]

Tipo de lista genérica Python. Esta herramienta mapea automáticamente arrays JSON a List[T], ej., arrays de cadenas se mapean a List[str], arrays de objetos a List[Item]. Python 3.9+ puede escribir list[T]. La herramienta importa desde typing por defecto, equivalente a list[T] integrado de Python 3.9+; si tu equipo prefiere sintaxis nueva, reemplaza la importación con un clic.

Any

Tipo especial del módulo typing que indica aceptación de cualquier tipo. Esta herramienta por defecto usa Any como respaldo para valores null y arrays vacíos para evitar errores de inferencia de tipos. El uso frecuente de Any desactiva la comprobación mypy / pyright; recomendamos cambiar a tipos precisos como Optional[str], List[int] después de determinar tipos de campo.

Pydantic BaseModel

Clase base de modelo de datos de la biblioteca Pydantic, proporcionando validación de datos en tiempo de ejecución, serialización y deserialización. Las dataclasses generadas por esta herramienta pueden adaptarse a BaseModel con un clic para validación de cuerpo de petición FastAPI. Pydantic v2 reescribió lógica de validación central en Rust, con mejora de rendimiento 5-50x sobre v1; las dataclasses generadas por esta herramienta también pueden heredar BaseModel para disfrutar esta aceleración.

FastAPI

Framework web Python moderno que depende de Pydantic para validación automática de cuerpo de petición. Las dataclasses generadas por esta herramienta pueden servir como plantillas de modelo de petición/respuesta para funciones de ruta FastAPI. Basado en Starlette + Pydantic, autogenera documentación OpenAPI y es uno de los estándares de facto para frameworks API backend Python hoy en día.

PEP 557

Propuesta de Mejora Python que define la sintaxis y comportamiento del decorador dataclass. El código generado por esta herramienta cumple totalmente con las especificaciones PEP 557. La propuesta fue iniciada por Eric V. Smith en 2017, tomando ideas de diseño de soluciones existentes como attrs y registros Haskell.

Anotación de Tipo (Type Hint)

Anotaciones de tipo marcadas con : Type después de parámetros de función y variables Python. Los campos dataclass generados por esta herramienta tienen todos anotaciones de tipo, permitiendo comprobación de tipo estático con mypy / pyright. Las anotaciones en sí mismas no afectan el comportamiento en tiempo de ejecución, solo se usan para sugerencias IDE, comprobación estática mypy / pyright y bibliotecas de validación en tiempo de ejecución (como Pydantic).

PEP 484

Propuesta de especificación de anotaciones de tipo Python que define el módulo typing y sintaxis genérica. List[T], Optional[T], etc. generados por esta herramienta siguen PEP 484. Redactado por Guido van Rossum, Jukka Lehtosalo, Łukasz Langa y otros, es el documento fundacional para el sistema de anotaciones de tipo de Python.

from __future__ import annotations

Sentencia de evaluación de anotaciones diferida introducida en PEP 563, almacenando todas las anotaciones como cadenas para evitar problemas de referencia hacia adelante. Añadir esta línea a dataclasses generadas por esta herramienta hace que el orden de referencia de anotaciones de tipo sea irrelevante. Cuando se habilita, todas las anotaciones se evalúan perezosamente como cadenas, evitando problemas de referencia hacia adelante y desacoplando el orden de campos dataclass del orden de referencia.

model.py

Nombre de archivo predeterminado descargado por esta herramienta, conforme a convenciones de proyectos Python. Puede renombrarse a user.py, schemas.py u otros nombres que coincidan con la estructura del proyecto. Consistente con estilos de nomenclatura como models.py de Django, models.py de Flask; proyectos multi-modelo pueden dividirse en submódulos como user.py, order.py bajo un paquete models.

Tabla de referencia de mapeo de tipos JSON a tipos Python

La herramienta infiere automáticamente tipos Python correspondientes basados en tipos de valor JSON:

Explicación de estructura de código Python generado

El código típico que quicktype-core genera para Python incluye las siguientes partes:

Comparación de soluciones de modelado de datos Python

La herramienta genera @dataclass por defecto, pero hay múltiples opciones de modelado de datos en el ecosistema Python; elige según necesidades del proyecto:

Tabla de compatibilidad de versiones Python y características dataclass

Diferentes versiones Python tienen soporte variado para dataclass, typing, Pydantic; elige por versión:

Privacy & Security

Todas las operaciones de esta herramienta JSON a Python ocurren completamente localmente en tu navegador: análisis JSON, generación de código Python y descargas de archivos se ejecutan todas del lado del cliente vía JavaScript del navegador; ningún contenido JSON, archivos subidos o código generado se envían por la red a ningún servidor. Las subidas de archivos usan la API nativa FileReader del navegador para leer directamente en memoria sin pasar por servicios intermedios. No se usa seguimiento de Cookies, no se recopilan datos de entrada o uso del usuario. Después de cerrar o refrescar la página, todo el contenido de entrada y salida se borra automáticamente de memoria. Adecuado para procesar JSON que contiene claves API, tokens y datos de negocio sensibles.

Authoritative References

• PythonDocumentación Oficial Python - dataclasses
• PythonDocumentación Oficial Python - módulo typing
• PythonPEP 557 - Data Classes
• PydanticDocumentación Oficial Pydantic - Models
• FastAPIDocumentación Oficial FastAPI - Cuerpo Petición
• PythonDocumentación Oficial Python - módulo typing
• attrsDocumentación Oficial attrs
• PythonPEP 484 - Type Hints