Python JSON: Codificação, Decodificação e Manipulação de Arquivos – Guia Prático

Python JSON: Codificação, Decodificação e Manipulação de Arquivos – Guia Prático

O que é JSON em Python?

JSON — abreviação de JavaScript Object Notation — é o formato de intercâmbio de dados baseado em texto mais amplamente usado. Em Python, mapeia diretamente para estruturas de dados nativas: objetos tornam-se dicts, arrays tornam-se lists, strings, números, booleanos e null traduzem para str, int/float, bool e None respectivamente. O módulo json na biblioteca padrão lida com todas as conversões.

Biblioteca JSON em Python

Importe o módulo uma vez no seu script:

import json

O módulo oferece quatro métodos principais:

Método	Descrição
dumps()	Converte objeto Python para string JSON.
dump()	Escreve string JSON diretamente em objeto arquivo.
loads()	Analisa string JSON em objeto Python.
load()	Lê e analisa arquivo JSON em objeto Python.

Python para JSON (Codificação)

Codificação é o processo de converter tipos de dados Python em JSON. O mapeamento padrão é mostrado abaixo:

Python	JSON
dict	Object
list	Array
str/unicode	String
int/long	Number (int)
float	Number (real)
True	true
False	false
None	null

Exemplo usando json.dumps():

import json
x = {
    "name": "Ken",
    "age": 45,
    "married": True,
    "children": ("Alice", "Bob"),
    "pets": ["Dog"],
    "cars": [
        {"model": "Audi A1", "mpg": 15.1},
        {"model": "Zeep Compass", "mpg": 18.1}
    ]
}
# Pretty-print com chaves ordenadas
string_ordenada = json.dumps(x, indent=4, sort_keys=True)
print(string_ordenada)

Saída:

{
    "age": 45,
    "cars": [
        { "model": "Audi A1", "mpg": 15.1 },
        { "model": "Zeep Compass", "mpg": 18.1 }
    ],
    "children": [ "Alice", "Bob" ],
    "married": true,
    "name": "Ken",
    "pets": [ "Dog" ]
}

Escrever objeto JSON em arquivo é direto com json.dump():

with open('arquivo_json.json', 'w') as arquivo_escrita:
    json.dump(x, arquivo_escrita, indent=4, sort_keys=True)

Após executar o script, arquivo_json.json conterá os dados serializados.

JSON para Python (Decodificação)

Decodificação inverte o mapeamento, transformando string ou arquivo JSON de volta em objetos Python nativos. A tabela de conversão espelha a tabela de codificação:

JSON	Python
Object	dict
Array	list
String	str
Number (int)	int
Number (real)	float
true	True
false	False
null	None

Exemplo usando json.loads():

import json
dados_pessoa = '{"pessoa": {"name": "Kenn", "sex": "male", "age": 28}}'
obj = json.loads(dados_pessoa)
print(obj)
print(type(obj))
print(obj.get('pessoa'))

Saída:

{'pessoa': {'name': 'Kenn', 'sex': 'male', 'age': 28}}
<class 'dict'>
{'name': 'Kenn', 'sex': 'male', 'age': 28}

Lendo arquivo JSON diretamente:

with open('arquivo_json.json') as f:
    dados = json.load(f)
    print(dados)

Saída: {'name': 'Ken', 'age': 45, ...}

Codificação Compacta e Pretty-Print

Para transmissão em rede, codificação compacta remove espaços em branco:

lst = ['a', 'b', 'c', {"4": 5, "6": 7}]
compacto = json.dumps(lst, separators=(',', ':'))
print(compacto)

Saída: ["a","b","c",{"4":5,"6":7}]

Para legibilidade humana, pretty-printing usa indentação:

dic = {"a": 4, "b": 5}
bonito = json.dumps(dic, indent=4, separators=(',', ': '))
print(bonito)

Saída:

{
    "a": 4,
    "b": 5
}

Codificando Objetos Complexos

O módulo json não consegue serializar objetos arbitrários. Para lidar com número complex, forneça função default:

def codificar_complexo(o):
    if isinstance(o, complex):
        return [o.real, o.imag]
    raise TypeError(f"{repr(o)} não é serializável JSON")

print(json.dumps(4 + 5j, default=codificar_complexo))

Saída: [4.0, 5.0]

Decodificando Objetos Complexos

Use object_hook para detectar marcador personalizado e reconstruir número complexo:

def eh_complexo(obj):
    if "__complex__" in obj:
        return complex(obj["real"], obj["img"])
    return obj

complexo_obj = json.loads('{"__complex__": true, "real": 4, "img": 5}', object_hook=eh_complexo)
print(complexo_obj)

Saída: (4+5j)

Classes de Serialização e Desserialização

As classes JSONEncoder e JSONDecoder fornecem controle granular:

• JSONEncoder.default(o) – sobrescreva para serializar objetos personalizados.
• JSONEncoder.encode(o) – retorna string JSON.
• JSONEncoder.iterencode(o) – itera sobre string de saída.
• JSONDecoder.decode(s) – analisa string JSON.
• JSONDecoder.raw_decode(s) – analisa começando em índice dado.

Exemplo:

from json.encoder import JSONEncoder
print(JSONEncoder().encode({"cor": ["vermelho", "amarelo", "verde"]}))

Buscando JSON de uma URL

Usando requests para baixar feed JSON ao vivo (ex.: CityBike NYC):

import json, requests
response = requests.get("https://feeds.citibikenyc.com/stations/stations.json")
bike_dict = json.loads(response.text)
print(bike_dict['stationBeanList'][0])

Saída:

{ 'id': 487, 'stationName': 'E 20 St & FDR Drive', 'availableDocks': 24, ... }

Tratando Exceções JSON

A exceção principal é json.JSONDecodeError, subclasse de ValueError. Exemplo de tratamento:

try:
    with open('ruim.json') as f:
        dados = json.load(f)
except json.JSONDecodeError as e:
    print(f"JSON inválido: {e}")

Valores Numéricos Especiais

RFC 8259 não permite Infinity ou NaN, mas o encoder Python os representa como strings:

print(json.dumps(float('inf')))
print(json.dumps(float('nan')))

Saída: Infinity e NaN

Chaves Repetidas em JSON

Quando uma chave aparece múltiplas vezes, json.loads() do Python mantém apenas a última ocorrência:

json.loads('{"a": 1, "a": 2, "a": 3}')  # -> {'a': 3}

Ferramentas de Linha de Comando

O módulo json.tool formata e valida JSON da linha de comando:

$ echo '{"name": "Rei Arthur"}' | python3 -m json.tool
{ "name": "Rei Arthur" }

Vantagens do JSON em Python

• Suporte nativo via módulo json.
• Legível por humanos com pretty-printing.
• Amplamente adotado para APIs, configuração e armazenamento de dados.
• Independente de linguagem e leve.

Limitações

• Não suporta tipos de dados personalizados sem encoder customizado.
• Profundidade máxima de recursão limita estruturas profundamente aninhadas.
• Documentos grandes podem ser intensivos em memória para carregar totalmente.

Folha de Referência Rápida Python JSON

Função	Descrição
json.dumps(obj)	Serializa objeto Python para string JSON.
json.dump(obj, arquivo)	Escreve string JSON em arquivo.
json.dumps(obj, separators=(",", ":"))	Representação compacta sem espaços.
json.dumps(obj, indent=4)	JSON pretty-print com indentação.
json.dumps(obj, sort_keys=True)	Ordena chaves de dicionário alfabeticamente.
json.dumps(obj, default=custom)	Codifica objetos não suportados.
JSONEncoder().encode(obj)	Serialização manual via classe encoder.
json.loads(s)	Analisa string JSON para objeto Python.
json.loads(s, object_hook=custom)	Desserialização customizada.
JSONDecoder().decode(s)	Desserialização manual via classe decoder.