2.28. JSON¶

JSON (JavaScript Object Notation) é um formato de texto compacto e legível por humanos para dados estruturados. Ele define seis tipos – string, number, boolean, null, array e object – cada um dos quais mapeia diretamente para um valor Python, de modo que converter entre Python e JSON é uma única chamada de função em qualquer direção.

JSON é a língua franca de arquivos de configuração e APIs web. Recorra a ele sempre que precisar salvar um pequeno conjunto de configurações em disco em uma forma que também possa ler a olho nu, ou trocar dados estruturados com outro programa.

Duas funções cobrem a maioria das necessidades:

json.dumps() – dump string: transforma um valor Python em uma string JSON.
json.loads() – load string: analisa uma string JSON de volta para Python.

O par json.dump / json.load (sem o s) faz o mesmo trabalho, mas recebe um objeto de arquivo diretamente.

2.28.1. Codificação (dumps)¶

import json

config = {
    "name":  "OpenMV",
    "width": 320,
    "tags":  ["red", "round"],
}

text = json.dumps(config)
print(text)

Saída:

{"name": "OpenMV", "width": 320, "tags": ["red", "round"]}

O mapeamento é:

dict (chaves string) → objeto JSON.
list e tuple → array JSON.
str → string JSON.
int, float → número JSON.
True, False, None → true, false, null.

Qualquer coisa fora desse conjunto (uma classe personalizada, um buffer bytes, um set) lança TypeError. Converta o valor primeiro.

Nota

O json.dumps() do CPython aceita um argumento indent para uma saída formatada de forma legível; o do MicroPython não. O único ajuste de formatação é separators, que controla o espaçamento em linha – passe (',', ':') para a forma mais compacta. Saída com várias linhas e recuo precisa ser produzida à mão, se necessário.

2.28.2. Decodificação (loads)¶

text = '{"name": "OpenMV", "width": 320}'
config = json.loads(text)
print(config["name"], config["width"])

Saída:

OpenMV 320

Objetos JSON viram dict, arrays viram list, e o resto mapeia de volta para seus equivalentes Python. JSON inválido lança ValueError.

2.28.3. Lendo e gravando arquivos¶

O par baseado em arquivo combina bem com with:

import json

with open("config.json") as f:
    config = json.load(f)

config["width"] = 640

with open("config.json", "w") as f:
    json.dump(config, f)

Trate o arquivo JSON como um registro completo – leia-o, modifique o valor Python, grave-o de volta. Tentar editar JSON no lugar dentro de um arquivo geralmente cria mais bugs do que evita.