Basic Usage¶

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

Serializeobj as a JSON formatted stream tofp (a.write()-supportingfile-like object) using thisconversion table.

Ifskipkeys is true (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 is true (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 is false (default:True), then the circularreference check for container types will be skipped and a circular referencewill result in anRecursionError (or worse).

Ifallow_nan is false (default:True), then it will be aValueError to serialize out of rangefloat values (nan,inf,-inf) in strict compliance of the JSON specification.Ifallow_nan is true, their JavaScript equivalents (NaN,Infinity,-Infinity) will be used.

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.

If specified,separators should be an(item_separator,key_separator)tuple. The default is(',',':') ifindent isNone and(',',':') otherwise. To get the most compact JSON representation,you should specify(',',':') to eliminate whitespace.

Changed in version 3.4:Use(',',':') as default ifindent is notNone.

If specified,default should be a function that gets called for objects thatcan’t otherwise be serialized. It should return a JSON encodable version ofthe object or raise aTypeError. If not specified,TypeErroris raised.

Ifsort_keys is true (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.

Changed in version 3.6:All optional parameters are nowkeyword-only.

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.

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

Serializeobj to a JSON formattedstr using thisconversiontable. The arguments have the same meaning as indump().

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.

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

Deserializefp (a.read()-supportingtext file orbinary file containing a JSON document) to a Python object usingthisconversion table.

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

Changed in version 3.9.14:The defaultparse_int ofint() now limits the maximum length ofthe integer string via the interpreter’sinteger stringconversion length limitation to help avoid denialof service attacks.

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.

If the data being deserialized is not a valid JSON document, aJSONDecodeError will be raised.

Changed in version 3.6:All optional parameters are nowkeyword-only.

Changed in version 3.6:fp can now be abinary file. The input encoding should beUTF-8, UTF-16 or UTF-32.

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

Deserializes (astr,bytes orbytearrayinstance containing a JSON document) to a Python object using thisconversion table.

The other arguments have the same meaning as inload().

If the data being deserialized is not a valid JSON document, aJSONDecodeError will be raised.

Changed in version 3.6:s can now be of typebytes orbytearray. Theinput encoding should be UTF-8, UTF-16 or UTF-32.

Changed in version 3.9:The keyword argumentencoding has been removed.

Encoders and Decoders¶

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

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. tosupportJSON-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. Ifobject_hook is alsodefined, 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.

Ifstrict is false (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, aJSONDecodeError will be raised.

Changed in version 3.6:All parameters are nowkeyword-only.

decode(s)¶

Return the Python representation ofs (astr instancecontaining a JSON document).

JSONDecodeError will be raised if the given JSON document is notvalid.

raw_decode(s)¶

Decode a JSON document froms (astr beginning with aJSON document) and return a 2-tuple of the Python representationand the index ins where the document ended.

This can be used to decode a JSON document from a string that may haveextraneous data at the end.

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

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, int- & float-derived Enums	number
True	true
False	false
None	null

Changed in version 3.4:Added support for int- and float-derived Enum classes.

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 is false (the default), aTypeError will be raised whentrying to encode keys that are notstr,int,floatorNone. Ifskipkeys is true, such items are simply skipped.

Ifensure_ascii is true (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 is true (the default), then lists, dicts, and customencoded objects will be checked for circular references during encoding toprevent an infinite recursion (which would cause anRecursionError).Otherwise, no such check takes place.

Ifallow_nan is true (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 is true (default:False), 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.

If specified,separators should be an(item_separator,key_separator)tuple. The default is(',',':') ifindent isNone and(',',':') otherwise. To get the most compact JSON representation,you should specify(',',':') to eliminate whitespace.

Changed in version 3.4:Use(',',':') as default ifindent is notNone.

If specified,default should be a function that gets called for objects thatcan’t otherwise be serialized. It should return a JSON encodable version ofthe object or raise aTypeError. If not specified,TypeErroris raised.

Changed in version 3.6:All parameters are nowkeyword-only.

default(o)¶

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 implementdefault() like 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)

encode(o)¶

Return a JSON string representation of a Python data structure,o. Forexample:

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

iterencode(o)¶

Encode the given object,o, and yield each string representation asavailable. For example:

forchunkinjson.JSONEncoder().iterencode(bigobject):mysocket.write(chunk)

Exceptions¶

exceptionjson.JSONDecodeError(msg,doc,pos)¶

Subclass ofValueError with the following additional attributes:

msg¶

The unformatted error message.

doc¶

The JSON document being parsed.

pos¶

The start index ofdoc where parsing failed.

lineno¶

The line corresponding topos.

colno¶

The column corresponding topos.

New in version 3.5.

Standard Compliance and Interoperability¶

The JSON format is specified byRFC 7159 and byECMA-404.This section details this module’s level of compliance with the RFC.For simplicity,JSONEncoder andJSONDecoder subclasses, andparameters other than 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:

• Infinite and NaN number values are accepted and output;

• Repeated names within an object are accepted, and only the value of the lastname-value pair is used.

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.

>>># 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

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

Command Line Interface¶

Source code:Lib/json/tool.py

Thejson.tool module provides a simple command line interface to validateand pretty-print JSON objects.

If the optionalinfile andoutfile arguments are notspecified,sys.stdin andsys.stdout will be used respectively:

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