JSON (JavaScript Object Notation), specified byRFC 4627, is a lightweight data interchange format based on a subset ofJavaScript syntax (ECMA-262 3rdedition).
json exposes an API familiar to users of the standard librarymarshal andpickle modules.
Encoding basic Python object hierarchies:
>>>importjson>>>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}>>>fromioimportStringIO>>>io=StringIO()>>>json.dump(['streaming API'],io)>>>io.getvalue()'["streaming API"]'
Compact encoding:
>>>importjson>>>json.dumps([1,2,3,{'4':5,'6':7}],separators=(',',':'))'[1,2,3,{"4":5,"6":7}]'
Pretty printing:
>>>importjson>>>print(json.dumps({'4':5,'6':7},sort_keys=True,...indent=4,separators=(',',': '))){ "4": 5, "6": 7}
Decoding JSON:
>>>importjson>>>json.loads('["foo", {"bar":["baz", null, 1.0, 2]}]')['foo', {'bar': ['baz', None, 1.0, 2]}]>>>json.loads('"\\"foo\\bar"')'"foo\x08ar'>>>fromioimportStringIO>>>io=StringIO('["streaming API"]')>>>json.load(io)['streaming API']
Specializing JSON object decoding:
>>>importjson>>>defas_complex(dct):...if'__complex__'indct:...returncomplex(dct['real'],dct['imag'])...returndct...>>>json.loads('{"__complex__": true, "real": 1, "imag": 2}',...object_hook=as_complex)(1+2j)>>>importdecimal>>>json.loads('1.1',parse_float=decimal.Decimal)Decimal('1.1')
ExtendingJSONEncoder:
>>>importjson>>>classComplexEncoder(json.JSONEncoder):...defdefault(self,obj):...ifisinstance(obj,complex):...return[obj.real,obj.imag]...# Let the base class default method raise the TypeError...returnjson.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', ']']
Using json.tool from the shell to validate and pretty-print:
$echo'{"json":"obj"}' | python -mjson.tool{"json":"obj"}$echo'{1.2:3.4}' | python -mjson.toolExpecting property name enclosed in double quotes: line 1 column 2(char 1)
Note
JSON is a subset ofYAML 1.2. The JSON produced bythis module’s default settings (in particular, the defaultseparatorsvalue) is also a subset of YAML 1.0 and 1.1. This module can thus also beused as a YAML serializer.
Serializeobj as a JSON formatted stream tofp (a.write()-supportingfile-like object) using thisconversion table.
Ifskipkeys isTrue (default:False), then dict keys that are notof a basic type (str,int,float,bool,None) will be skipped instead of raising aTypeError.
Thejson module always producesstr objects, notbytes objects. Therefore,fp.write() must supportstrinput.
Ifensure_ascii isTrue (the default), the output is guaranteed tohave all incoming non-ASCII characters escaped. Ifensure_ascii isFalse, these characters will be output as-is.
Ifcheck_circular isFalse (default:True), then the circularreference check for container types will be skipped and a circular referencewill result in anOverflowError (or worse).
Ifallow_nan isFalse (default:True), then it will be aValueError to serialize out of rangefloat values (nan,inf,-inf) in strict compliance of the JSON specification, instead ofusing the JavaScript equivalents (NaN,Infinity,-Infinity).
Ifindent is a non-negative integer or string, then JSON array elements andobject members will be pretty-printed with that indent level. An indent levelof 0, negative, or"" will only insert newlines.None (the default)selects the most compact representation. Using a positive integer indentindents that many spaces per level. Ifindent is a string (such as"\t"),that string is used to indent each level.
Changed in version 3.2:Allow strings forindent in addition to integers.
Note
Since the default item separator is',', the output might includetrailing whitespace whenindent is specified. You can useseparators=(',',':') to avoid this.
Ifseparators is an(item_separator,dict_separator) tuple, then itwill be used instead of the default(',',':') separators.(',',':') is the most compact JSON representation.
default(obj) is a function that should return a serializable version ofobj or raiseTypeError. The default simply raisesTypeError.
Ifsort_keys isTrue (default:False), then the output ofdictionaries will be sorted by key.
To use a customJSONEncoder subclass (e.g. one that overrides thedefault() method to serialize additional types), specify it with thecls kwarg; otherwiseJSONEncoder is used.
Serializeobj to a JSON formattedstr using thisconversiontable. The arguments have the same meaning as indump().
Note
Unlikepickle andmarshal, JSON is not a framed protocol,so trying to serialize multiple objects with repeated calls todump() using the samefp will result in an invalid JSON file.
Note
Keys in key/value pairs of JSON are always of the typestr. Whena dictionary is converted into JSON, all the keys of the dictionary arecoerced to strings. As a result of this, if a dictionary is convertedinto JSON and then back into a dictionary, the dictionary may not equalthe original one. That is,loads(dumps(x))!=x if x has non-stringkeys.
Deserializefp (a.read()-supportingfile-like objectcontaining a JSON document) to a Python object using thisconversiontable.
object_hook is an optional function that will be called with the result ofany object literal decoded (adict). The return value ofobject_hook will be used instead of thedict. This feature can be usedto implement custom decoders (e.g.JSON-RPCclass hinting).
object_pairs_hook is an optional function that will be called with theresult of any object literal decoded with an ordered list of pairs. Thereturn value ofobject_pairs_hook will be used instead of thedict. This feature can be used to implement custom decoders thatrely on the order that the key and value pairs are decoded (for example,collections.OrderedDict() will remember the order of insertion). Ifobject_hook is also defined, theobject_pairs_hook takes priority.
Changed in version 3.1:Added support forobject_pairs_hook.
parse_float, if specified, will be called with the string of every JSONfloat to be decoded. By default, this is equivalent tofloat(num_str).This can be used to use another datatype or parser for JSON floats(e.g.decimal.Decimal).
parse_int, if specified, will be called with the string of every JSON intto be decoded. By default, this is equivalent toint(num_str). This canbe used to use another datatype or parser for JSON integers(e.g.float).
parse_constant, if specified, will be called with one of the followingstrings:'-Infinity','Infinity','NaN'.This can be used to raise an exception if invalid JSON numbersare encountered.
Changed in version 3.1:parse_constant doesn’t get called on ‘null’, ‘true’, ‘false’ anymore.
To use a customJSONDecoder subclass, specify it with theclskwarg; otherwiseJSONDecoder is used. Additional keyword argumentswill be passed to the constructor of the class.
Deserializes (astr instance containing a JSON document) to aPython object using thisconversion table.
The other arguments have the same meaning as inload(), exceptencoding which is ignored and deprecated.
Simple JSON decoder.
Performs the following translations in decoding by default:
| JSON | Python |
|---|---|
| object | dict |
| array | list |
| string | str |
| number (int) | int |
| number (real) | float |
| true | True |
| false | False |
| null | None |
It also understandsNaN,Infinity, and-Infinity as theircorrespondingfloat values, which is outside the JSON spec.
object_hook, if specified, will be called with the result of every JSONobject decoded and its return value will be used in place of the givendict. This can be used to provide custom deserializations (e.g. tosupport JSON-RPC class hinting).
object_pairs_hook, if specified will be called with the result of everyJSON object decoded with an ordered list of pairs. The return value ofobject_pairs_hook will be used instead of thedict. Thisfeature can be used to implement custom decoders that rely on the orderthat the key and value pairs are decoded (for example,collections.OrderedDict() will remember the order of insertion). Ifobject_hook is also defined, theobject_pairs_hook takes priority.
Changed in version 3.1:Added support forobject_pairs_hook.
parse_float, if specified, will be called with the string of every JSONfloat to be decoded. By default, this is equivalent tofloat(num_str).This can be used to use another datatype or parser for JSON floats(e.g.decimal.Decimal).
parse_int, if specified, will be called with the string of every JSON intto be decoded. By default, this is equivalent toint(num_str). This canbe used to use another datatype or parser for JSON integers(e.g.float).
parse_constant, if specified, will be called with one of the followingstrings:'-Infinity','Infinity','NaN','null','true','false'. This can be used to raise an exception if invalid JSON numbersare encountered.
Ifstrict isFalse (True is the default), then control characterswill be allowed inside strings. Control characters in this context arethose with character codes in the 0-31 range, including'\t' (tab),'\n','\r' and'\0'.
If the data being deserialized is not a valid JSON document, aValueError will be raised.
Extensible JSON encoder for Python data structures.
Supports the following objects and types by default:
| Python | JSON |
|---|---|
| dict | object |
| list, tuple | array |
| str | string |
| int, float | number |
| True | true |
| False | false |
| None | null |
To extend this to recognize other objects, subclass and implement adefault() method with another method that returns a serializable objectforo if possible, otherwise it should call the superclass implementation(to raiseTypeError).
Ifskipkeys isFalse (the default), then it is aTypeError toattempt encoding of keys that are not str, int, float or None. Ifskipkeys isTrue, such items are simply skipped.
Ifensure_ascii isTrue (the default), the output is guaranteed tohave all incoming non-ASCII characters escaped. Ifensure_ascii isFalse, these characters will be output as-is.
Ifcheck_circular isTrue (the default), then lists, dicts, and customencoded objects will be checked for circular references during encoding toprevent an infinite recursion (which would cause anOverflowError).Otherwise, no such check takes place.
Ifallow_nan isTrue (the default), thenNaN,Infinity, and-Infinity will be encoded as such. This behavior is not JSONspecification compliant, but is consistent with most JavaScript basedencoders and decoders. Otherwise, it will be aValueError to encodesuch floats.
Ifsort_keys isTrue (defaultFalse), then the output of dictionarieswill be sorted by key; this is useful for regression tests to ensure thatJSON serializations can be compared on a day-to-day basis.
Ifindent is a non-negative integer or string, then JSON array elements andobject members will be pretty-printed with that indent level. An indent levelof 0, negative, or"" will only insert newlines.None (the default)selects the most compact representation. Using a positive integer indentindents that many spaces per level. Ifindent is a string (such as"\t"),that string is used to indent each level.
Changed in version 3.2:Allow strings forindent in addition to integers.
Note
Since the default item separator is',', the output might includetrailing whitespace whenindent is specified. You can useseparators=(',',':') to avoid this.
If specified,separators should be an(item_separator,key_separator)tuple. The default is(',',':'). To get the most compact JSONrepresentation, you should specify(',',':') to eliminate whitespace.
If specified,default is a function that gets called for objects that can’totherwise be serialized. It should return a JSON encodable version of theobject or raise aTypeError.
Implement this method in a subclass such that it returns a serializableobject foro, or calls the base implementation (to raise aTypeError).
For example, to support arbitrary iterators, you could implement defaultlike this:
defdefault(self,o):try:iterable=iter(o)exceptTypeError:passelse:returnlist(iterable)# Let the base class default method raise the TypeErrorreturnjson.JSONEncoder.default(self,o)
Return a JSON string representation of a Python data structure,o. Forexample:
>>>json.JSONEncoder().encode({"foo":["bar","baz"]})'{"foo": ["bar", "baz"]}'
Encode the given object,o, and yield each string representation asavailable. For example:
forchunkinjson.JSONEncoder().iterencode(bigobject):mysocket.write(chunk)
The JSON format is specified byRFC 4627. This section details thismodule’s level of compliance with the RFC. For simplicity,JSONEncoder andJSONDecoder subclasses, and parameters otherthan those explicitly mentioned, are not considered.
This module does not comply with the RFC in a strict fashion, implementing someextensions that are valid JavaScript but not valid JSON. In particular:
Since the RFC permits RFC-compliant parsers to accept input texts that are notRFC-compliant, this module’s deserializer is technically RFC-compliant underdefault settings.
The RFC recommends that JSON be represented using either UTF-8, UTF-16, orUTF-32, with UTF-8 being the default.
As permitted, though not required, by the RFC, this module’s serializer setsensure_ascii=True by default, thus escaping the output so that the resultingstrings only contain ASCII characters.
Other than theensure_ascii parameter, this module is defined strictly interms of conversion between Python objects andUnicodestrings, and thus does not otherwise address the issueof character encodings.
The RFC specifies that the top-level value of a JSON text must be either aJSON object or array (Pythondict orlist). This module’sdeserializer also accepts input texts consisting solely of aJSON null, boolean, number, or string value:
>>>just_a_json_string='"spam and eggs"'# Not by itself a valid JSON text>>>json.loads(just_a_json_string)'spam and eggs'
This module itself does not include a way to request that such input texts beregarded as illegal. Likewise, this module’s serializer also accepts singlePythonNone,bool, numeric, andstrvalues as input and will generate output texts consisting solely of a top-levelJSON null, boolean, number, or string value without raising an exception:
>>>neither_a_list_nor_a_dict="spam and eggs">>>json.dumps(neither_a_list_nor_a_dict)# The result is not a valid JSON text'"spam and eggs"'
This module’s serializer does not itself include a way to enforce theaforementioned constraint.
The RFC does not permit the representation of infinite or NaN number values.Despite that, by default, this module accepts and outputsInfinity,-Infinity, andNaN as if they were valid JSON number literal values:
>>># 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
In the serializer, theallow_nan parameter can be used to alter thisbehavior. In the deserializer, theparse_constant parameter can be used toalter this behavior.
The RFC specifies that the names within a JSON object should be unique, butdoes not specify how repeated names in JSON objects should be handled. Bydefault, this module does not raise an exception; instead, it ignores all butthe last name-value pair for a given name:
>>>weird_json='{"x": 1, "x": 2, "x": 3}'>>>json.loads(weird_json){'x': 3}
Theobject_pairs_hook parameter can be used to alter this behavior.
19.3.mailcap — Mailcap file handling
Enter search terms or a module, class or function name.
