json — Codificador y decodificador JSON

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


JSON (JavaScript Object Notation), especificado por :rfc:”7159” (que obsoleta RFC 4627) y por ECMA-404, es un formato ligero de intercambio de datos inspirado por la sintaxis literal de objetos en JavaScript (aunque no es un subconjunto estricto de JavaScript 1 ).

json expone una API familiar a los usuarios de los módulos de la biblioteca estándar marshal y pickle.

Codificación de jerarquías básicas de objetos de 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"]'

Codificación compacta:

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

Impresión linda:

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

Decodificación 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']

Decodificación personalizada de objetos 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')

Extendiendo 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 desde el shell para validación e impresión con sangría:

$ 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)

Consulte Interfaz de línea de comandos para obtener documentación detallada.

Nota

JSON es un subconjunto de YAML 1.2. El JSON producido por la configuración predeterminada de este módulo (en particular, el valor predeterminado separators) también es un subconjunto de YAML 1.0 y 1.1. Por lo tanto, este módulo también se puede utilizar como un serializador YAML.

Nota

Los codificadores y decodificadores de este módulo conservan el orden de entrada y salida de forma predeterminada. El orden solo se pierde si los contenedores subyacentes no están ordenados.

Antes de Python 3.7, no se garantizaba que dict fuera ordenado, por lo que las entradas y salidas se mezclaban a menos que collections.OrderedDict se solicitara específicamente. Comenzando con Python 3.7, la clase regular dict conserva el orden, por lo que ya no es necesario especificar collections.OrderedDict para la generación y análisis JSON.

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 obj como una secuencia con formato JSON a fp (a .write() -supporting file-like object) usando esto conversion table.

Si skipkeys es verdadero (predeterminado: False), entonces las llaves del dict que no son de un tipo básico (str, int, float, bool, None) se omitirán en lugar de generar un TypeError.

El módulo json siempre produce objetos str, no objetos bytes. Por lo tanto, fp.write() debe admitir str como entrada.

Si ensure_ascii es verdadero (el valor predeterminado), se garantiza que la salida tendrá todos los caracteres entrantes no ASCII escapados. Si ensure_ascii es falso, estos caracteres se mostrarán tal cual.

Si check_circular es falso (predeterminado: True), se omitirá la verificación de referencia circular para los tipos de contenedor y una referencia circular dará como resultado OverflowError (o peor).

Si allow_nan es falso (predeterminado: True), entonces serializar los valores fuera de rango float (nan, inf` `, ``-inf) provocará un ValueError en estricto cumplimiento de la especificación JSON. Si allow_nan es verdadero, se utilizarán sus equivalentes de JavaScript (NaN, Infinity, -Infinity).

Si indent es un entero no negativo o una cadena, los elementos del arreglo JSON y los miembros del objeto se imprimirán con ese nivel de sangría. Un nivel de sangría de 0, negativo o "" solo insertará nuevas líneas. None (el valor predeterminado) selecciona la representación más compacta. El uso de una sangría de entero positivo agrega sangrías de muchos espacios por nivel. Si indent es una cadena (como "\t"), esa cadena se usa para agregarle sangría a cada nivel.

Distinto en la versión 3.2: Permite cadenas de caracteres para indent además de enteros.

Si se especifica, separators debe ser una tupla (separador_elemento, separador_llave). El valor predeterminado es (', ', ': ') si indent es None y (', ', ': ') de lo contrario. Para obtener la representación JSON más compacta, debe especificar (', ', ': ') para eliminar espacios en blanco.

Distinto en la versión 3.4: Usa (',', ': ') como predeterminado si indent no es None.

Si se especifica, default debería ser una función que se llama para objetos que de otro modo no se pueden serializar. Debería retornar una versión codificable JSON del objeto o generar un TypeError. Si no se especifica, produce TypeError.

Si sort_keys es verdadero (predeterminado: False), la salida de los diccionarios se ordenará por llave.

Para usar una subclase personalizada de JSONEncoder (por ejemplo, una que sobre escriba el método default() para serializar tipos adicionales), se especifica mediante el argumento por palabra clave cls; de lo contrario se usa JSONEncoder.

Distinto en la versión 3.6: Todos los parámetros opcionales son ahora palabra-clave-solamente.

Nota

A diferencia de pickle y marshal, JSON no es un protocolo enmarcado, por lo que intentar serializar varios objetos con llamadas repetidas a dump() utilizando el mismo fp dará como resultado un archivo JSON no vá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 en un str con formato JSON usando esta conversion table. Los argumentos tienen el mismo significado que en dump().

Nota

Las llaves de los pares llave/valor de JSON siempre son del tipo str. Cuando un diccionario se convierte en JSON, todas las llaves del diccionario se convierten en cadenas. Como resultado de esto, si un diccionario se convierte en JSON y, a continuación, se convierte nuevamente en un diccionario, el diccionario puede que no sea igual al original. Es decir, loads(dumps(x)) != x si x tiene llaves que no son de tipo cadena de caracteres.

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

Deserializa fp (un text file o binary file que soporte .read() y que contiene un documento JSON) a un objeto Python usando esta conversion table.

object_hook es una función opcional a la que se llamará con el resultado de cualquier literal de objeto decodificado (un dict). El valor de retorno de object_hook se utilizará en lugar de dict. Esta característica se puede utilizar para implementar decodificadores personalizados (por ejemplo, la sugerencia de clase JSON-RPC).

object_pairs_hook es una función opcional a la que se llamará con el resultado de cualquier literal de objeto decodificado con una lista ordenada de pares. El valor de retorno de object_pairs_hook se utilizará en lugar de dict. Esta característica se puede utilizar para implementar decodificadores personalizados. Si también se define object_hook, el object_pairs_hook tiene prioridad.

Distinto en la versión 3.1: Soporte agregado para object_pairs_hook.

parse_float, si se especifica, se llamará con la cadena de cada flotante JSON que se va a decodificar. De forma predeterminada, esto es equivalente a float(num_str). Esto se puede utilizar para hacer uso de otro tipo de datos o analizador para flotantes JSON (por ejemplo decimal. Decimal).

parse_int, si se especifica, se llamará con la cadena de cada entero JSON que se va a decodificar. De forma predeterminada, esto es equivalente a int(num_str). Esto se puede utilizar para hace uso de otro tipo de datos o analizador para enteros JSON (por ejemplo float).

parse_constant, si se especifica, se llamará con una de las siguientes cadenas: '-Infinity', 'Infinity', 'NaN'. Esto se puede utilizar para generar una excepción si se encuentran números JSON invalidos.

Distinto en la versión 3.1: parse_constant ya no es llamado en “null”, “true”, “false”.

Para utilizar una subclase personalizada de JSONDecoder, especificarlo con el argumento por llave cls; de lo contrario, se utilizará JSONDecoder. Se pasarán argumentos adicionales de palabra llave al constructor de la clase.

Si los datos que se deserializan no constituyen un documento JSON válido, se generará un JSONDecodeError.

Distinto en la versión 3.6: Todos los parámetros opcionales son ahora palabra-clave-solamente.

Distinto en la versión 3.6: fp ahora puede ser un binary file. La codificación de entrada debe ser UTF-8, UTF-16 o UTF-32.

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

Deserializa s (una instancia str, bytes o bytearray que contiene un documento JSON) en un objeto Python mediante esta conversion table.

The other arguments have the same meaning as in load().

Si los datos que se deserializan no constituyen un documento JSON válido, se generará un JSONDecodeError.

Distinto en la versión 3.6: s ahora puede ser de tipo bytes o bytearray. La codificación de entrada debe ser UTF-8, UTF-16 o UTF-32.

Distinto en la versión 3.9: The keyword argument encoding has been removed.

Codificadores y Decodificadores

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

Decodificador JSON simple.

Realiza las siguientes traducciones en la decodificación de forma predeterminada:

JSON

Python

object

dict

array

list

string

str

número (int)

int

número (real)

float

true

True

false

False

null

None

También entiende NaN, Infinity y -Infinity como sus correspondientes valores float, que está fuera de la especificación JSON.

object_hook, if specified, will be called with the result of every JSON object decoded and its return value will be used in place of the given dict. This can be used to provide custom deserializations (e.g. to support JSON-RPC class hinting).

object_pairs_hook, si se especifica se llamará con el resultado de cada objeto JSON decodificado con una lista ordenada de pares. El valor de retorno de object_pairs_hook se utilizará en lugar de dict. Esta característica se puede utilizar para implementar decodificadores personalizados. Si también se define object_hook, el object_pairs_hook tiene prioridad.

Distinto en la versión 3.1: Soporte agregado para object_pairs_hook.

parse_float, si se especifica, se llamará con la cadena de cada flotante JSON que se va a decodificar. De forma predeterminada, esto es equivalente a float(num_str). Esto se puede utilizar para hacer uso de otro tipo de datos o analizador para flotantes JSON (por ejemplo decimal. Decimal).

parse_int, si se especifica, se llamará con la cadena de cada entero JSON que se va a decodificar. De forma predeterminada, esto es equivalente a int(num_str). Esto se puede utilizar para hace uso de otro tipo de datos o analizador para enteros JSON (por ejemplo float).

parse_constant, si se especifica, se llamará con una de las siguientes cadenas: '-Infinity', 'Infinity', 'NaN'. Esto se puede utilizar para generar una excepción si se encuentran números JSON invalidos.

Si strict es falso (“”True”” es el valor predeterminado), se permitirán caracteres de control dentro de cadenas. Los caracteres de control en este contexto son aquellos con códigos de caracteres en el rango 0–31, incluyendo '\t' (tab), '\n', '\r' and '\0'.

Si los datos que se deserializan no constituyen un documento JSON válido, se generará un JSONDecodeError.

Distinto en la versión 3.6: Todos los parámetros son ahora palabra-clave-solamente.

decode(s)

Retorna la representación Python de s (una instancia str que contiene un documento JSON).

JSONDecodeError se producirá si el documento JSON entregado es invalido.

raw_decode(s)

Decodifica un documento JSON de s (un str comenzando con un documento JSON) y retorna una tupla de 2 de la representación Python y el índice en s donde terminó el documento.

Esto se puede usar para decodificar un documento JSON de una cadena de caracteres que puede tener datos extraños al 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 extensible para estructuras de datos de Python.

Admite los siguientes objetos y tipos de forma predeterminada:

Python

JSON

dict

object

list, tuple

array

str

string

int, float, Enums derivadas de int o float

number

True

true

False

false

None

null

Distinto en la versión 3.4: Compatibilidad añadida con las clases Enum derivadas de int y float.

A fin de extender esto para reconocer otros objetos, implementar una subclase con un método default() con otro método que retorna un objeto serializable para “”o”” si es posible, de lo contrario debe llamar a la implementación de superclase (para elevar TypeError).

If skipkeys is false (the default), a TypeError will be raised when trying to encode keys that are not str, int, float or None. If skipkeys is true, such items are simply skipped.

Si ensure_ascii es verdadero (el valor predeterminado), se garantiza que la salida tendrá todos los caracteres entrantes no ASCII escapados. Si ensure_ascii es falso, estos caracteres se mostrarán tal cual.

Si check_circular es cierto (valor predeterminado), se comprobarán las listas, los diccionarios y los objetos codificados personalizados en busca de referencias circulares durante la codificación para evitar una recursividad infinita (lo que provocaría un OverflowError). De lo contrario, no se realiza ninguna comprobación de este tipo.

Si allow_nan es cierto (valor predeterminado), NaN, Infinity y -Infinity se codificarán como tales. Este comportamiento no es compatible con las especificaciones JSON, pero es coherente con la mayoría de los codificadores y decodificadores basados en JavaScript. De lo contrario, codificar dichos puntos flotantes provocará un ValueError.

Si sort_keys es cierto (predeterminado: False), la salida de los diccionarios se ordenará por clave; esto es útil para las pruebas de regresión para garantizar que las serializaciones JSON se pueden comparar en el día a día.

Si indent es un entero no negativo o una cadena, los elementos del arreglo JSON y los miembros del objeto se imprimirán con ese nivel de sangría. Un nivel de sangría de 0, negativo o "" solo insertará nuevas líneas. None (el valor predeterminado) selecciona la representación más compacta. El uso de una sangría de entero positivo agrega sangrías de muchos espacios por nivel. Si indent es una cadena (como "\t"), esa cadena se usa para agregarle sangría a cada nivel.

Distinto en la versión 3.2: Permite cadenas de caracteres para indent además de enteros.

Si se especifica, separators debe ser una tupla (separador_elemento, separador_llave). El valor predeterminado es (', ', ': ') si indent es None y (', ', ': ') de lo contrario. Para obtener la representación JSON más compacta, debe especificar (', ', ': ') para eliminar espacios en blanco.

Distinto en la versión 3.4: Usa (',', ': ') como predeterminado si indent no es None.

Si se especifica, default debería ser una función que se llama para objetos que de otro modo no se pueden serializar. Debería retornar una versión codificable JSON del objeto o generar un TypeError. Si no se especifica, produce TypeError.

Distinto en la versión 3.6: Todos los parámetros son ahora palabra-clave-solamente.

default(o)

Implemente este método en una subclase de modo que retorne un objeto serializable para o, o llame a la implementación base (para generar un TypeError).

For example, to support arbitrary iterators, you could implement default() like this:

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 una representación de cadena de caracteres JSON de una estructura de datos de Python, o. Por ejemplo:

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

Codifica el objeto dado, o, y produce cada representación de cadena como disponible. Por ejemplo:

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

Excepciones

exception json.JSONDecodeError(msg, doc, pos)

Subclase de ValueError con los siguientes atributos adicionales:

msg

El mensaje de error sin formato.

doc

El documento JSON que se está analizando.

pos

El índice de inicio de doc donde se produjo un error en el análisis.

lineno

La línea correspondiente a pos.

colno

La columna correspondiente a pos.

Nuevo en la versión 3.5.

Cumplimiento e interoperabilidad estándar

El formato JSON se especifica mediante RFC 7159 y por ECMA-404. En esta sección se detalla el nivel de cumplimiento de este módulo con la RFC. Para simplificar, no se tienen en cuenta las subclases JSONEncoder y JSONDecoder y los parámetros distintos de los mencionados explícitamente.

Este módulo no cumple con la RFC de forma estricta, implementando algunas extensiones que son válidas en JavaScript pero no son válidas en JSON. En particular:

  • Se aceptan y se envían valores de números Infinitos y NaN;

  • Se aceptan nombres repetidos dentro de un objeto y solo se utiliza el valor del último par nombre-valor.

Puesto que el RFC permite a los analizadores compatibles con RFC aceptar textos de entrada que no son compatibles con RFC, el deserializador de este módulo es técnicamente compatible con RFC bajo la configuración predeterminada.

Codificaciones de caracteres

La RFC requiere que JSON se represente mediante UTF-8, UTF-16 o UTF-32, siendo UTF-8 el valor predeterminado recomendado para la máxima interoperabilidad.

Según lo permitido, aunque no es necesario, por la RFC, el serializador de este módulo establece ensure_ascii=True de forma predeterminada, escapando así el dato de salida para que las cadenas resultantes solo contengan caracteres ASCII.

Aparte del parámetro ensure_ascii, este módulo se define estrictamente en términos de conversión entre objetos Python y Unicode strings, y por lo tanto no aborda directamente el problema de las codificaciones de caracteres.

La RFC prohíbe agregar una marca de orden byte (BOM, por sus siglas en inglés) al inicio de un texto JSON y el serializador de este módulo no agrega una BOM a su salida. La RFC permite, pero no requiere, deserializadores JSON para omitir una BOM inicial en su entrada. El deserializador de este módulo genera un ValueError cuando hay una lista de materiales inicial.

La RFC no prohíbe explícitamente las cadenas JSON que contienen secuencias de bytes que no corresponden a caracteres Unicode válidos (por ejemplo, sustitutos UTF-16 no espaciados), pero sí tiene en cuenta que pueden causar problemas de interoperabilidad. De forma predeterminada, este módulo acepta y genera puntos de código (cuando está presente en el original str) para dichas secuencias.

Valores de número infinito y NaN

El RFC no permite la representación de los valores de número infinito o NaN. A pesar de eso, de forma predeterminada, este módulo acepta y genera Infinity, -Infinity y NaN como si fueran valores literales 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

En el serializador, el parámetro allow_nan se puede utilizar para modificar este comportamiento. En el deserializador, se puede utilizar el parámetro parse_constant para modificar este comportamiento.

Nombres repetidos dentro de un objeto

La RFC especifica que los nombres dentro de un objeto JSON deben ser únicos, pero no exige cómo se deben controlar los nombres repetidos en los objetos JSON. De forma predeterminada, este módulo no genera una excepción; en su lugar, ignora todo excepto el último par nombre-valor para un nombre dado:

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

El parámetro object_pairs_hook se puede utilizar para alterar este comportamiento.

Valores de nivel superior No-Objeto , No-Arreglo

La versión anterior de JSON especificada por el obsoleto RFC 4627 requería que el valor de nivel superior de un texto JSON fuera un objeto JSON o un arreglo (Python dict o list), y no podía ser un valor JSON nulo, booleano, numérico o de cadena. RFC 7159 eliminó esa restricción, y este módulo no ha implementado ni ha implementado nunca esa restricción en su serializador o en su deserializador.

Independientemente, para lograr la máxima interoperabilidad, es posible que usted desee adherirse voluntariamente a la restricción.

Limitaciones de la implementación

Algunas implementaciones del deserializador JSON pueden establecer límites en:

  • el tamaño de los textos JSON aceptados

  • el nivel máximo de anidamiento de objetos y arreglos JSON

  • el rango y precisión de los números JSON

  • el contenido y la longitud máxima de las cadenas de caracteres JSON

Este módulo no impone tales límites más allá de los propios tipos de datos de Python relevantes o del propio intérprete de Python.

Al serializar en JSON, tenga en cuenta las limitaciones en las aplicaciones que pueden consumir su JSON. En particular, es común que los números JSON se deserialicen en números de doble precisión IEEE 754 y, por lo tanto, estén sujetos al rango y las limitaciones de precisión de esa representación. Esto es especialmente relevante cuando se serializan valores de Python int de magnitud extremadamente grande, o cuando se serializan instancias de tipos numéricos «exóticos» como decimal. Decimal.

Interfaz de línea de comandos

Código fuente: Lib/json/tool.py


El módulo json.tool proporciona una interfaz de línea de comandos simple para validar e imprimir objetos JSON.

Si no se especifican los argumentos opcionales infile y outfile, se utilizarán sys.stdin y sys.stdout 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)

Distinto en la versión 3.5: La salida está ahora en el mismo orden que la entrada. Utilice la opción --sort-keys para ordenar la salida de los diccionarios alfabéticamente por llave.

Opciones de línea de comandos

infile

El archivo JSON que se va a validar o imprimir con impresión linda:

$ 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
    }
]

Si no se especifica infile, lee sys.stdin.

outfile

Escribe la salida de infile en el outfile dado. De lo contrario, lo escribe en sys.stdout.

--sort-keys

Ordena la salida de los diccionarios alfabéticamente por llave.

Nuevo en la versión 3.5.

--no-ensure-ascii

Disable escaping of non-ascii characters, see json.dumps() for more information.

Nuevo en la versión 3.9.

--json-lines

Analiza cada línea de entrada como objeto JSON independiente.

Nuevo en la versión 3.8.

--indent, --tab, --no-indent, --compact

Mutually exclusive options for whitespace control.

Nuevo en la versión 3.9.

-h, --help

Muestra el mensaje de ayuda.

Notas de pie de página

1

Como se indica en la errata para RFC 7159, JSON permite caracteres literales U+2028 (SEPARADOR DE LINEA) y U+2029 (SEPARADOR DE PÁRRAFO) en cadenas, mientras que JavaScript (a partir de ECMAScript Edición 5.1) no lo hace.