Formateador JSON / Python Formato 100% local

Formatear JSON en Python: pprint, json.dumps y la trampa del indent

Formatear JSON en Python es un one-liner que todo el mundo hace ligeramente mal. La librería estándar basta, pero pprint no sirve e indent=4 es costumbre, no decisión.

El one-liner correcto

Usa json.dumps de la stdlib. Siempre. Los dos argumentos que importan son indent y sort_keys.

indent=2 es el default moderno y coincide con lo que produce cualquier herramienta JS. indent=4 es tradición Python por PEP 8, pero PEP 8 va de código Python, no de JSON. Mezclar los dos te garantiza diffs ruidosos cuando un desarrollador JS abra tu archivo. Pon indent=2 y deja de pensarlo.

sort_keys=True separa un archivo bonito de un archivo determinista. Si dos servicios emiten el mismo JSON con las claves en distinto orden, tu diff tool grita y tus tests se vuelven flaky. Ordenar arregla las dos cosas.

Por qué pprint no es la herramienta

pprint.pprint es para objetos Python, no para JSON. Imprime {'a': True} con comillas simples y True en lugar de true, que no es JSON válido. La salida parece similar a ojo, peta cualquier parser JSON al instante.

Si necesitas una repr legible para Python, pprint vale. Si necesitas JSON, usa json.dumps. Son herramientas distintas.

Streaming y payloads grandes

json.dumps construye el string completo en memoria. Para payloads de varios gigabytes usa json.dump con un file handle y escribe incrementalmente:

with open("out.json", "w") as f:
    json.dump(huge_object, f, indent=2, sort_keys=True)

Para JSON genuinamente streaming (cuando no controlas la estructura) tira de ijson o orjson. orjson es además 2 o 3 veces más rápido que la stdlib en tamaños normales.

Cuándo saltarte Python

Si solo quieres visualizar un payload que estás depurando, abrir terminal, importar json y pegar el string son seis pasos de más. Pégalo en una herramienta web que corre en local y nunca toca un servidor, y te ahorras un minuto entero.

Ejemplo completo

python

import json

data = {
    "user": {"id": 42, "name": "Ada"},
    "tags": ["admin", "beta"],
    "active": True,
}

# JSON bonito, determinista, válido
formatted = json.dumps(data, indent=2, sort_keys=True)
print(formatted)

# Escritura streaming para payloads grandes
with open("out.json", "w") as f:
    json.dump(data, f, indent=2, sort_keys=True)

¿Solo necesitas el resultado?

Cuando solo quieres inspeccionar un payload sin abrir terminal, pégalo en el formateador online que corre en tu navegador y ve el resultado con un click. Sin instalar nada, sin subir nada, JSON válido siempre.

Abrir Formateador y Validador JSON →

Preguntas frecuentes

¿json.dumps conserva el orden de las claves por defecto?

Sí desde Python 3.7. El dict mantiene el orden de inserción y json.dumps lo respeta. Usa sort_keys=True solo cuando quieras orden alfabético para diffs.

¿Cómo manejo tipos no serializables como datetime?

Pasa un callable default: json.dumps(obj, default=str) convierte datetime, Decimal, UUID y similares a su string. Más limpio que un encoder custom para scripts puntuales.

¿Por qué mi salida tiene Unicode escapado tipo \u00e9?

json.dumps usa ensure_ascii=True por defecto. Pasa ensure_ascii=False si quieres acentos literales. La salida sigue siendo JSON válido mientras guardes el archivo como UTF-8.