19.2. `json` — JSON codificador e decodificador¶

Código Fonte: Lib/json/__init__.py

JSON (JavaScript Object Notation), especificado pelo RFC 7159 (que tornou a RFC 4627 obsoleta) e pelo ECMA-404, é um formato leve de troca de dados inspirado pelo sintaxe de objeto JavaScript (embora não seja um subconjunto estrito de JavaScript 1 ).

json expõe uma API familiar para pessoas usuárias dos módulos marshal e pickle da biblioteca padrão.

Codificação de hierarquias básicas de objetos Python:

>>> import json
>>> json.dumps(['foo', {'bar': ('baz', None, 1.0, 2)}])
'["foo", {"bar": ["baz", null, 1.0, 2]}]'
>>> print(json.dumps("\"foo\bar"))
"\"foo\bar"
>>> print(json.dumps('\u1234'))
"\u1234"
>>> print(json.dumps('\\'))
"\\"
>>> print(json.dumps({"c": 0, "b": 0, "a": 0}, sort_keys=True))
{"a": 0, "b": 0, "c": 0}
>>> from io import StringIO
>>> io = StringIO()
>>> json.dump(['streaming API'], io)
>>> io.getvalue()
'["streaming API"]'

Codificação compacta:

>>> import json
>>> json.dumps([1, 2, 3, {'4': 5, '6': 7}], separators=(',', ':'))
'[1,2,3,{"4":5,"6":7}]'

Saída bonita:

>>> import json
>>> print(json.dumps({'4': 5, '6': 7}, sort_keys=True, indent=4))
{
    "4": 5,
    "6": 7
}

Decodificando JSON:

>>> import json
>>> json.loads('["foo", {"bar":["baz", null, 1.0, 2]}]')
['foo', {'bar': ['baz', None, 1.0, 2]}]
>>> json.loads('"\\"foo\\bar"')
'"foo\x08ar'
>>> from io import StringIO
>>> io = StringIO('["streaming API"]')
>>> json.load(io)
['streaming API']

Especialização em decodificação de objeto JSON:

>>> import json
>>> def as_complex(dct):
...     if '__complex__' in dct:
...         return complex(dct['real'], dct['imag'])
...     return dct
...
>>> json.loads('{"__complex__": true, "real": 1, "imag": 2}',
...     object_hook=as_complex)
(1+2j)
>>> import decimal
>>> json.loads('1.1', parse_float=decimal.Decimal)
Decimal('1.1')

Estendendo JSONEncoder:

>>> import json
>>> class ComplexEncoder(json.JSONEncoder):
...     def default(self, obj):
...         if isinstance(obj, complex):
...             return [obj.real, obj.imag]
...         # Let the base class default method raise the TypeError
...         return json.JSONEncoder.default(self, obj)
...
>>> json.dumps(2 + 1j, cls=ComplexEncoder)
'[2.0, 1.0]'
>>> ComplexEncoder().encode(2 + 1j)
'[2.0, 1.0]'
>>> list(ComplexEncoder().iterencode(2 + 1j))
['[2.0', ', 1.0', ']']

Usando json.tool para validar a partir do console e exibir formatado:

$ echo '{"json":"obj"}' | python -m json.tool
{
    "json": "obj"
}
$ echo '{1.2:3.4}' | python -m json.tool
Expecting property name enclosed in double quotes: line 1 column 2 (char 1)

Veja Interface de Linha de Comando para a documentação detalhada.

Nota

JSON é um subconjunto da YAML 1.2. O JSON gerado pelas definições padrão desse módulo (particularmente, o valor padrão dos separadores) é também um subconjunto da YAML 1.0 e 1.1. Esse módulo pode, por tanto, também ser usado para seriar YAML.

19.2.1. Uso Básico¶

json.dump(obj, fp, *, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, cls=None, indent=None, separators=None, default=None, sort_keys=False, **kw)¶

Serializa um obj formatado como um stream JSON para fp (um .write()- dando suporte a objeto arquivo ou similar) usando essa tabela de conversão.

Se skipkeys for verdadeiro (default: False), as chaves de dicionário que não forem de um tipo básico (str, int, float, bool, None) serão ignoradas ao invés de levantarem um TypeError.

O módulo json sempre gera objetos str, e não objetos bytes . Dessa forma, fp.write() precisa suportar entradas str.

If ensure_ascii is true (the default), the output is guaranteed to have all incoming non-ASCII characters escaped. If ensure_ascii is false, these characters will be output as-is.

Se check_circular for falso (default: True), então a checagem referência circular para tipos containers será ignorada e uma referência circular resultará em um OverflowError (ou pior).

Se allow_nan for falso (padrão: True), serializar valores float fora do intervalo (nan, inf, -inf) em estrita conformidade com a especificação JSON será um ValueError . Se allow_nan for verdadeiro, seus equivalentes JavaScript (NaN, Infinity, -Infinity) serão usados.

Se indent for um inteiro não-negativo ou uma string, então elementos de um vetor JSON e membros de objetos terão uma saída formatada com este nível de identação. Um n;ivel de identação 0, negativo ou "" apenas colocará novas linhas. None (o padrão) seleciona a presentação mais compacta. Usando um inteiro positivo a identação terá alguns espaços por nível. Se indent for uma string (como "\t"), essa string será usada para identar cada nível.

Alterado na versão 3.2: Permite strings para indent, além de inteiros.

Se especificado, separators deve ser uma tupla (item_separator, key_separator). O padrão é (', ', ': ') se indent for None e (',', ': ') caso contrário. Para pegar representação JSON mais compacta, você deve especificar (',', ':') para eliminar espaços em branco.

Alterado na versão 3.4: Usa (',', ': ') como padrão se indent não for None.

Se especificado, default deve ser uma função para ser chamada para objetos que não podem ser serializados de outra forma. Deve retornar uma versão codificada JSON do objeto ou lançar uma exceção TypeError. Se não for especificada, TypeError é levantada.

Se sort_keys for verdadeiro (padrão: False), então os dicionários da saída serão ordenados pela chave.

Para usar uma subclasse de JSONEncoder personalizada (por ex., uma que sobrescreve o método default() para serializar tipos adicionais), especifique isso com argumento cls; caso contrário é usado JSONEncoder.

Alterado na versão 3.6: Todos os parâmetros opcionais agora são somente-nomeado.

Nota

Diferente de pickle e marshal, JSON não é um protocolo com datagrama, assim tentar serializar múltiplos objetos com chamadas repetidas para dump() usando o mesmo fp resultará em um arquivo JSON inválido.

json.dumps(obj, *, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, cls=None, indent=None, separators=None, default=None, sort_keys=False, **kw)¶: Serializa obj para uma str com formato JSON usando essa tabela de conversão. Os argumentos têm o mesmo significado que na função dump().

Nota

Chaves nos pares chave/valor de JSON são sempre do tipo str. Quando um dicionário é convertido para JSON, todas as chaves são convertidas para strings. Como resultado disso, se um dicionário é convertido para JSON e depois de volta para o dicionários, o dicionário pode não ser igual ao original. Isto é, loads(dumps(x)) != x se x tem chaves não-strings.

json.load(fp, *, cls=None, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, object_pairs_hook=None, **kw)¶

Desserializa fp (um arquivo texto ou arquivo binário com suporte a .read() contendo um documento JSON) para um objeto Python usando essa tabela de conversão.

object_hook é uma função opcional que será chamada com o resultado de qualquer objeto literal decodificado (um dict). O valor do retorno de object_hook será usado no lugar de dict. Esse recurso pode ser usado para implementar decodificadores personalizados (por exemplo, sugestão para classes JSON-RPC).

object_pairs_hook is an optional function that will be called with the result of any object literal decoded with an ordered list of pairs. The return value of object_pairs_hook will be used instead of the dict. This feature can be used to implement custom decoders that rely on the order that the key and value pairs are decoded (for example, collections.OrderedDict() will remember the order of insertion). If object_hook is also defined, the object_pairs_hook takes priority.

Alterado na versão 3.1: Adicionado suporte para object_pairs_hook.

parse_float, se especificado, será chamada com a string de cada ponto flutuante JSON para ser decodificado. Por padrão, é equivalente a float(num_str). Pode ser usado para qualquer outro tipo de dado ou conversor para ponto flutuante JSON (ex. decimal.Decimal).

parse_int, se especificado, será chamada com a string de cada inteiro JSON para ser decodificado. Por padrão, é equivalente a int(num_str). Pode ser usado para qualquer outro tipo de dado ou conversor para inteiro JSON (ex. float).

parse_constant, se especificado, será chamada para cada um das seguintes strings: '-Infinity', 'Infinity', 'NaN'. Isso pode ser usado para levantar uma exceção se forem encontrados números JSON inválidos.

Alterado na versão 3.1: parse_constant não é mais chamada para ‘null’, ‘true’, ‘false’.

Para usar uma subclasse de JSONDecoder personalizada, especifique isto com o argumento nomeado cls; caso contrário será usada JSONDecoder. Argumentos nomeados adicionais poderão ser passados para o construtor da classe.

Se os dados a serem desserializados não forem um documento JSON válido, será levantada uma exceção JSONDecodeError.

Alterado na versão 3.6: Todos os parâmetros opcionais agora são somente-nomeado.

Alterado na versão 3.6: fp agora pode ser um arquivo binário. A entrada deve estar codificada como UTF-8, UTF-16 ou UTF-32.

json.loads(s, *, encoding=None, cls=None, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, object_pairs_hook=None, **kw)¶

Desserializa s (uma instancia de str, bytes ou bytearray contendo um documento JSON) para um objeto Python essa tabela de conversão.

The other arguments have the same meaning as in load(), except encoding which is ignored and deprecated.

Se os dados a serem desserializados não forem um documento JSON válido, será levantada uma exceção JSONDecodeError.

Alterado na versão 3.6: s agora pode ser um do tipo bytes ou bytearray. A entrada deve estar codificado como UTF-8, UTF-16 ou UTF-32.

19.2.2. Codificadores e decodificadores¶

class json.JSONDecoder(*, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, strict=True, object_pairs_hook=None)¶

Decodificador JSON simples

Executa as seguintes traduções na decodificação por padrão:

JSON	Python
object (objeto)	dict
Array	list
string	str
number (int)	int
número (real)	float
true	True
false	False
null	None

Ele também entende NaN, Infinity e -Infinity como seus valores float correspondentes, que estão fora da especificação JSON.

object_hook, se especificado, será chamada com o resultado de cada objeto JSON decodificado e seu valor de retorno será usado no lugar do dict dado. Isso pode ser usado para fornecer desserializações personalizadas (por exemplo, para oferecer suporte a sugestão para classes JSON-RPC)

object_pairs_hook, if specified will be called with the result of every JSON object decoded with an ordered list of pairs. The return value of object_pairs_hook will be used instead of the dict. This feature can be used to implement custom decoders that rely on the order that the key and value pairs are decoded (for example, collections.OrderedDict() will remember the order of insertion). If object_hook is also defined, the object_pairs_hook takes priority.

Alterado na versão 3.1: Adicionado suporte para object_pairs_hook.

parse_float, se especificado, será chamada com a string de cada ponto flutuante JSON para ser decodificado. Por padrão, é equivalente a float(num_str). Pode ser usado para qualquer outro tipo de dado ou conversor para ponto flutuante JSON (ex. decimal.Decimal).

parse_int, se especificado, será chamada com a string de cada inteiro JSON para ser decodificado. Por padrão, é equivalente a int(num_str). Pode ser usado para qualquer outro tipo de dado ou conversor para inteiro JSON (ex. float).

parse_constant, se especificado, será chamada para cada um das seguintes strings: '-Infinity', 'Infinity', 'NaN'. Isso pode ser usado para levantar uma exceção se forem encontrados números JSON inválidos.

Se strict for falso (True é o padrão), os caracteres de controle serão permitidos dentro das strings. Os caracteres de controle neste contexto são aqueles com códigos de caracteres no intervalo 0-31, incluindo '\t' (tab), '\n', '\r' and '\0'.

Se os dados a serem desserializados não forem um documento JSON válido, será levantada uma exceção JSONDecodeError.

Alterado na versão 3.6: Todos os parâmetros agora são somente-nomeado.

decode(s)¶

Retorna a representação Python de s (uma instância str contendo um documento JSON).

JSONDecodeError será levantada se o documento JSON fornecido não for válido.

raw_decode(s)¶

Decodifica um documento JSON a partir de s (uma str iniciando com um documento JSON) e retornando uma tupla com 2 elementos, a representação Python e o índice em s onde o documento finaliza.

Isso pode ser usado para decodificar um documento JSON a partir de uma string que possa ter dados extras ao final.

class json.JSONEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)¶

Codificador JSON extensível para estruturas de dados Python.

Por padrão, possui suporte para os seguintes objetos e tipos:

Python	JSON
dict	object (objeto)
list, tuple	Array
str	string
int, float, int- & float-derived Enums	número
True	true
False	false
None	null

Alterado na versão 3.4: Adicionou suporte para classes Enum derivadas de int e float.

Para estender isso para reconhecer outros objetos, crie uma subclasse e implemente o método default() com outro método que retorne um objeto serializável para o se possível, caso contrário deveria chamar a implementação da superclasse (para levantar TypeError).

Se skipkeys é falso (o padrão), então será levantada uma TypeError ao tentar codificar as chaves que não são str, int, float ou None. Se skipkeys é verdadeiro, esse itens são simplesmente pulados.

If ensure_ascii is true (the default), the output is guaranteed to have all incoming non-ASCII characters escaped. If ensure_ascii is false, these characters will be output as-is.

Se check_circular é verdadeiro (o padrão), então listas, dicionários, e objetos codificados personalizados serão verificados por referências circulares durante a codificação para prevenir uma recursão infinita (que iria causar uma OverflowError). Caso contrário, nenhuma verificação será feita.

Se allow_nan for verdadeiro (o padrão), então NaN, Ìnfinity, and -Infinity serão codificados como tal. Esse comportamento não é compatível com a especificação do JSON, mas é consistente com a maioria dos codificadores e decodificadores baseados em JavaScript. Caso contrário, será um ValueError para codificar tais pontos flutuantes.

Se sort_keys for verdadeiro (padrão: False), então a saída dos dicionários serão ordenados pela chave; isto é útil para testes de regressão para certificar-se que as serializações de JSON possam ser comparadas com uma base do dia-a-dia.

Se indent for um inteiro não-negativo ou uma string, então elementos de um vetor JSON e membros de objetos terão uma saída formatada com este nível de identação. Um n;ivel de identação 0, negativo ou "" apenas colocará novas linhas. None (o padrão) seleciona a presentação mais compacta. Usando um inteiro positivo a identação terá alguns espaços por nível. Se indent for uma string (como "\t"), essa string será usada para identar cada nível.

Alterado na versão 3.2: Permite strings para indent, além de inteiros.

Se especificado, separators deve ser uma tupla (item_separator, key_separator). O padrão é (', ', ': ') se indent for None e (',', ': ') caso contrário. Para pegar representação JSON mais compacta, você deve especificar (',', ':') para eliminar espaços em branco.

Alterado na versão 3.4: Usa (',', ': ') como padrão se indent não for None.

Se especificado, default deve ser uma função para ser chamada para objetos que não podem ser serializados de outra forma. Deve retornar uma versão codificada JSON do objeto ou lançar uma exceção TypeError. Se não for especificada, TypeError é levantada.

Alterado na versão 3.6: Todos os parâmetros agora são somente-nomeado.

default(o)¶

Implemente este método em uma subclasse que retorna um objeto serializável para o, ou chame a implementação base (para levantar uma TypeError).

Por exemplo, para suporte a iteradores arbitrários, você poderia implementar default dessa forma:

def default(self, o):
   try:
       iterable = iter(o)
   except TypeError:
       pass
   else:
       return list(iterable)
   # Let the base class default method raise the TypeError
   return json.JSONEncoder.default(self, o)

encode(o)¶

Retorna uma string representando um JSON a partir da estrutura de dados Python, o. Por exemplo:

>>> json.JSONEncoder().encode({"foo": ["bar", "baz"]})
'{"foo": ["bar", "baz"]}'

iterencode(o)¶

Codifica o objeto dado, o, e produz cada representação em string assim que disponível. Por exemplo:

for chunk in json.JSONEncoder().iterencode(bigobject):
    mysocket.write(chunk)

19.2.3. Exceções¶

exception json.JSONDecodeError(msg, doc, pos)¶

Subclasse de ValueError com os seguintes atributos adicionais:

msg¶: A mensagem de erro não formatada.

doc¶: O documento JSON sendo analisado.

pos¶: O índice inicial de doc em que a análise falhou.

lineno¶: A linha correspondente a pos.

colno¶: A coluna correspondente a pos.

Novo na versão 3.5.

19.2.4. Conformidade e interoperabilidade padrões¶

O formato JSON é especificado por RFC 7159 e por ECMA-404. Esta seção detalha o nível de conformidade deste módulo com a RFC. Para simplificar, as subclasses JSONEncoder e JSONDecoder, e outros parâmetros além daqueles explicitamente mencionados, não são considerados.

Este módulo não está em conformidade com a RFC de forma estrita, implementando algumas extensões que são JavaScript válidas, mas não JSON válido. Em particular:

Os valores de números infinitos e NaN são aceitos e produzidos;
Nomes repetidos em um objeto são aceitos e apenas o valor do último par nome-valor é usado.

Uma vez que a RFC permite que os analisadores compatíveis com RFC aceitem textos de entrada que não sejam compatíveis com RFC, o desserializador deste módulo é tecnicamente compatível com RFC nas configurações padrões.

19.2.4.1. Codificações de caracteres¶

A RFC requer que JSON seja representado usando UTF-8, UTF-16 ou UTF-32, com UTF-8 sendo o padrão recomendado para interoperabilidade máxima.

Conforme permitido, embora não exigido, pela RFC, o serializador deste módulo define ensure_ascii=True por padrão, escapando a saída para que as strings resultantes contenham apenas caracteres ASCII.

Além do parâmetro ensure_ascii, este módulo é definido estritamente em termos de conversão entre objetos Python e strings Unicode e, portanto, não aborda diretamente o problema de codificação de caracteres.

A RFC proíbe adicionar uma marca de ordem de byte (do inglês byte order mark - BOM) ao início de um texto JSON, e o serializador deste módulo não adiciona um BOM à sua saída. A RFC permite, mas não exige, que os desserializadores JSON ignorem um BOM inicial em sua entrada. O desserializador deste módulo levanta uma ValueError quando um BOM inicial está presente.

A RFC não proíbe explicitamente as strings JSON que contêm sequências de bytes que não correspondem a caracteres Unicode válidos (por exemplo, substitutos UTF-16 não emparelhados), mas observa que podem causar problemas de interoperabilidade. Por padrão, este módulo aceita e produz (quando presente no original str) pontos de código para tais sequências.

19.2.4.2. Valores numéricos infinitos e NaN¶

A RFC não permite a representação de valores infinitos ou numéricos NaN. Apesar disso, por padrão, este módulo aceita e produz Infinity, -Infinity e NaN como se fossem valores literais de número JSON válidos:

>>> # Neither of these calls raises an exception, but the results are not valid JSON
>>> json.dumps(float('-inf'))
'-Infinity'
>>> json.dumps(float('nan'))
'NaN'
>>> # Same when deserializing
>>> json.loads('-Infinity')
-inf
>>> json.loads('NaN')
nan

No serializador, o parâmetro allow_nan pode ser usado para alterar esse comportamento. No desserializador, o parâmetro parse_constant pode ser usado para alterar esse comportamento.

19.2.4.3. Nomes repetidos dentro de um objeto¶

A RFC especifica que os nomes em um objeto JSON devem ser exclusivos, mas não determina como os nomes repetidos em objetos JSON devem ser tratados. Por padrão, este módulo não levanta uma exceção; em vez disso, ele ignora tudo, exceto o último par nome-valor para um determinado nome:

>>> weird_json = '{"x": 1, "x": 2, "x": 3}'
>>> json.loads(weird_json)
{'x': 3}

O parâmetro object_pairs_hook pode ser usado para alterar este comportamento.

19.2.4.4. Valores não object e não array de nível superior¶

A versão antiga de JSON especificada pela obsoleta RFC 4627 exige que o valor de nível superior do texto JSON deve ser do tipo object ou array (Python dict ou list), e não poderia ser dos tipos null, boolean, number, ou string. RFC 7159 removeu essa restrição, e esse módulo não tem nenhuma implementação que faça essa restrição, seja em seus serializadores, sejam nos desserializadores.

Independentemente, para máxima interoperabilidade, você poderia querer aderir voluntariamente a restrição.

19.2.4.5. Limitações de implementação¶

Algumas implementações de desserializadores JSON podem definir limites em:

o tamanho de textos JSON aceitos
o máximo de níveis de aninhamentos de objetos e vetores JSON
o intervalo e a precisão de números JSON
o conteúdo e o tamanho máximo de strings JSON

Esse módulo não impõe nenhum limite além daqueles já colocados pelas estruturas de dados Python ou pelo interpretador Python em si.

Quando serializando para JSON, tenha cuidado com qualquer limitação nas aplicações que irão consumir seu JSON. Em particular, é comum para números JSON serem desserializados com a precisão dupla definida em IEEE 754, portanto sujeito aos intervalos de representação e limitações de precisão. Isso é especialmente relevante quando serializando valores Python int de magnitude extremamente grande, ou quando serializando instâncias de tipos números “exóticos” como decimal.Decimal.

19.2.5. Interface de Linha de Comando¶

Código-fonte: Lib/json/tool.py

O módulo json.tool fornece uma interface de linha de comando simples para validação e embelezamento de saída para objetos JSON.

Se os argumentos opcionais infile e outfile não forem especificados, sys.stdin e sys.stdout serão usados respectivamente:

$ echo '{"json": "obj"}' | python -m json.tool
{
    "json": "obj"
}
$ echo '{1.2:3.4}' | python -m json.tool
Expecting property name enclosed in double quotes: line 1 column 2 (char 1)

Alterado na versão 3.5: A saída agora está na mesma ordem da entrada. Use a opção --sort-keys para ordenar a saída de dicionários alfabeticamente pela chave.

19.2.5.1. Opções da linha de comando¶

infile¶

O arquivo JSON para ser validado ou saída embelezada:

$ python -m json.tool mp_films.json
[
    {
        "title": "And Now for Something Completely Different",
        "year": 1971
    },
    {
        "title": "Monty Python and the Holy Grail",
        "year": 1975
    }
]

Se infile não é especificado, lê de sys.stdin.

outfile¶: Escreve a saída de infile para o outfile dado. Caso contrário, escreve em sys.stdout.

--sort-keys¶: Ordena a saída de dicionários alfabeticamente pela chave.

Novo na versão 3.5.

-h, --help¶: Exibe a mensagem de ajuda.

Notas de rodapé

1: Como apresentado na errata para RFC 7159, JSON permite os caracteres literais U+2028 (SEPARADOR DE LINHA) e U+2029 (SEPARADOR DE PARÁGRAFO) em strings, enquanto que JavaScript (ECMAScript Edition 5.1) não.

19.2. `json` — JSON codificador e decodificador¶

19.2.1. Uso Básico¶

19.2.2. Codificadores e decodificadores¶

19.2.3. Exceções¶

19.2.4. Conformidade e interoperabilidade padrões¶

19.2.4.1. Codificações de caracteres¶

19.2.4.2. Valores numéricos infinitos e NaN¶

19.2.4.3. Nomes repetidos dentro de um objeto¶

19.2.4.4. Valores não object e não array de nível superior¶

19.2.4.5. Limitações de implementação¶

19.2.5. Interface de Linha de Comando¶

19.2.5.1. Opções da linha de comando¶

Tabela de Conteúdo

Tópico anterior

Próximo tópico

Essa Página

19.2. json — JSON codificador e decodificador¶

19.2.1. Uso Básico¶

19.2.2. Codificadores e decodificadores¶

19.2.3. Exceções¶

19.2.4. Conformidade e interoperabilidade padrões¶

19.2.4.1. Codificações de caracteres¶

19.2.4.2. Valores numéricos infinitos e NaN¶

19.2.4.3. Nomes repetidos dentro de um objeto¶

19.2.4.4. Valores não object e não array de nível superior¶

19.2.4.5. Limitações de implementação¶

19.2.5. Interface de Linha de Comando¶

19.2.5.1. Opções da linha de comando¶

19.2. `json` — JSON codificador e decodificador¶