2.28. JSON¶

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

JSON é a língua franca dos ficheiros de configuração e APIs web. Recorra a ele sempre que precisar de guardar um pequeno conjunto de definições em disco num formato que também pode ler visualmente, ou para trocar dados estruturados com outro programa.

Duas funções cobrem a maioria das necessidades:

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

O par json.dump / json.load (sem s) faz o mesmo trabalho mas recebe um objeto ficheiro 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 saída formatada; o do MicroPython não. O único parâmetro de formatação é separators, que controla o espaçamento em linha – passe (',', ':') para a forma mais compacta. A saída multilinha com recuo tem de ser produzida manualmente se necessário.

2.28.2. Descodificação (loads)¶

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

Saída:

OpenMV 320

Os objetos JSON tornam-se dict, os arrays tornam-se list, e o resto mapeia de volta para os seus equivalentes Python. JSON inválido lança ValueError.

2.28.3. Leitura e escrita de ficheiros¶

O par baseado em ficheiros funciona 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 ficheiro JSON como um registo completo – leia-o, modifique o valor Python, escreva-o de volta. Tentar editar JSON diretamente dentro de um ficheiro cria geralmente mais bugs do que poupa.