De Python para JSON com json.dumps

O primeiro json.dumps

Converter dados do Python em JSON é o primeiro passo para salvar em arquivo ou enviar pela rede. A função que faz isso é json.dumps. Você entrega um objeto Python e recebe de volta uma string com o mesmo conteúdo escrito no formato JSON. Comece importando o módulo e convertendo um dicionário simples. Observe que o resultado é uma string, mesmo que se pareça com o dicionário original.

import json

pessoa = {"nome": "João", "idade": 34, "assinante": True}

texto = json.dumps(pessoa)
print(texto)
# {"nome": "Jo\u00e3o", "idade": 34, "assinante": true}

print(type(texto))
# <class 'str'>

json.dumps devolve uma string. Note que True virou true e o acento saiu escapado.

Duas coisas chamam a atenção nesse resultado. Primeiro, o True do Python virou true em minúsculas, que é a forma do JSON: a tradução dos tipos acontece sozinha. Segundo, o João apareceu como Jo\u00e3o. Isso não está errado, é só o jeito padrão de escapar acentos, mas fica ilegível. As próximas duas partes resolvem a legibilidade: uma cuida da indentação, a outra dos acentos.

Deixando legível: indent e ensure_ascii

Por padrão, json.dumps espreme tudo em uma linha só, o que é ótimo para a máquina e ruim para os olhos. O argumento indent resolve: passe indent=2 e o JSON ganha quebras de linha e recuo de dois espaços por nível. Junte com ensure_ascii=False para manter os acentos legíveis. Essa dupla é a receita padrão sempre que você quer inspecionar ou salvar um JSON em português.

import json

pessoa = {
    "nome": "João",
    "cidade": "São Paulo",
    "idade": 34,
    "cursos": ["Python básico", "Python intermediário"],
}

texto = json.dumps(pessoa, indent=2, ensure_ascii=False)
print(texto)
# {
#   "nome": "João",
#   "cidade": "São Paulo",
#   "idade": 34,
#   "cursos": [
#     "Python básico",
#     "Python intermediário"
#   ]
# }

Com indent=2 e ensure_ascii=False, o JSON fica indentado e com acentos preservados.

Vale entender por que o ensure_ascii existe. Nos primórdios, nem todo sistema lidava bem com acentos, então o padrão foi jogar pelo seguro e escapar tudo para caracteres ASCII simples. Hoje, com tudo em UTF-8, isso raramente é necessário e só atrapalha a leitura. Por isso, na prática do dia a dia com texto em português, ensure_ascii=False é quase sempre a escolha certa. O JSON gerado continua válido dos dois jeitos.

Qual tipo do Python vira o quê no JSON

A conversão de tipos segue uma tabela fixa, e vale conhecê-la para não se surpreender. Dicionário vira objeto, lista e tupla viram array, str vira texto, int e float viram número, True e False viram true e false, e None vira null. Repare que a tupla vira array e não volta como tupla: ela perde a identidade de tupla no caminho de ida. Tipos sem equivalente, como conjuntos, dão erro e precisam ser convertidos antes.

import json

dados = {
    "texto": "olá",
    "inteiro": 10,
    "decimal": 3.5,
    "verdadeiro": True,
    "vazio": None,
    "lista": [1, 2],
    "tupla": (3, 4),
}

print(json.dumps(dados, ensure_ascii=False))
# {"texto": "olá", "inteiro": 10, "decimal": 3.5, "verdadeiro": true, "vazio": null, "lista": [1, 2], "tupla": [3, 4]}

Todos os tipos básicos convertidos de uma vez. A tupla (3, 4) virou o array [3, 4].