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 thisPython-to-JSON conversion table.

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.

Parameters:

• obj (object) – The Python object to be serialized.

• fp (file-like object) – The file-like objectobj will be serialized to.Thejson module always producesstr objects,notbytes objects,thereforefp.write() must supportstr input.

• skipkeys (bool) – IfTrue, keys that are not of a basic type(str,int,float,bool,None)will be skipped instead of raising aTypeError.DefaultFalse.

• ensure_ascii (bool) – IfTrue (the default), the output is guaranteed tohave all incoming non-ASCII characters escaped.IfFalse, these characters will be outputted as-is.

• check_circular (bool) – IfFalse, the circular reference check for container types is skippedand a circular reference will result in aRecursionError (or worse).DefaultTrue.

• allow_nan (bool) – IfFalse, serialization of out-of-rangefloat values(nan,inf,-inf) will result in aValueError,in strict compliance with the JSON specification.IfTrue (the default), their JavaScript equivalents(NaN,Infinity,-Infinity) are used.

• cls (aJSONEncoder subclass) – If set, a custom JSON encoder with thedefault() method overridden,for serializing into custom datatypes.IfNone (the default),JSONEncoder is used.

• indent (int |str |None) – If a positive integer or string, JSON array elements andobject members will be pretty-printed with that indent level.A positive integer indents that many spaces per level;a string (such as"\t") is used to indent each level.If zero, negative, or"" (the empty string),only newlines are inserted.IfNone (the default), the most compact representation is used.

• separators (tuple |None) – A two-tuple:(item_separator,key_separator).IfNone (the default),separators defaults to(',',':') ifindent isNone,and(',',':') otherwise.For the most compact JSON,specify(',',':') to eliminate whitespace.

• default (callable | None) – A function that is called for objects that can’t otherwise be serialized.It should return a JSON encodable version of the objector raise aTypeError.IfNone (the default),TypeError is raised.

• sort_keys (bool) – IfTrue, dictionaries will be outputted sorted by key.DefaultFalse.

Changed in version 3.2:Allow strings forindent in addition to integers.

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

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

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 to a Python objectusing theJSON-to-Python conversion table.

Parameters:

• fp (file-like object) – A.read()-supportingtext file orbinary filecontaining the JSON document to be deserialized.

• cls (aJSONDecoder subclass) – If set, a custom JSON decoder.Additional keyword arguments toload()will be passed to the constructor ofcls.IfNone (the default),JSONDecoder is used.

• object_hook (callable | None) – If set, a function that is called with the result ofany JSON object literal decoded (adict).The return value of this function will be usedinstead of thedict.This feature can be used to implement custom decoders,for exampleJSON-RPC class hinting.DefaultNone.

• object_pairs_hook (callable | None) – If set, a function that is called with the result ofany JSON object literal decoded with an ordered list of pairs.The return value of this function will be usedinstead of thedict.This feature can be used to implement custom decoders.Ifobject_hook is also set,object_pairs_hook takes priority.DefaultNone.

• parse_float (callable | None) – If set, a function that is called withthe string of every JSON float to be decoded.IfNone (the default), it is equivalent tofloat(num_str).This can be used to parse JSON floats into custom datatypes,for exampledecimal.Decimal.

• parse_int (callable | None) – If set, a function that is called withthe string of every JSON int to be decoded.IfNone (the default), it is equivalent toint(num_str).This can be used to parse JSON integers into custom datatypes,for examplefloat.

• parse_constant (callable | None) – If set, a function that is called with one of the following strings:'-Infinity','Infinity', or'NaN'.This can be used to raise an exceptionif invalid JSON numbers are encountered.DefaultNone.

Raises:

• JSONDecodeError – When the data being deserialized is not a valid JSON document.

• UnicodeDecodeError – When the data being deserialized does not containUTF-8, UTF-16 or UTF-32 encoded data.

Changed in version 3.1:

• Added the optionalobject_pairs_hook parameter.

• parse_constant doesn’t get called on ‘null’, ‘true’, ‘false’ anymore.

Changed in version 3.6:

• All optional parameters are nowkeyword-only.

• fp can now be abinary file.The input encoding should be UTF-8, UTF-16 or UTF-32.

Changed in version 3.11: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.

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

Identical toload(), but instead of a file-like object,deserializes (astr,bytes orbytearrayinstance containing a JSON document) to a Python object using thisconversion table.

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 is an optional function that will be called with the result ofevery JSON object decoded and its return value will be used in place of thegivendict. This can be used to provide custom deserializations(e.g. to supportJSON-RPC class hinting).

object_pairs_hook is an optional function that will be called with theresult of every JSON object 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 is an optional function that will be called with the string ofevery JSON float to be decoded. By default, this is equivalent tofloat(num_str). This can be used to use another datatype or parser forJSON floats (e.g.decimal.Decimal).

parse_int is an optional function that will be called with the string ofevery JSON int to be decoded. By default, this is equivalent toint(num_str). This can be used to use another datatype or parser forJSON integers (e.g.float).

parse_constant is an optional function that will be called with one of thefollowing strings:'-Infinity','Infinity','NaN'. This can beused to raise an exception if invalid JSON numbers are 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,float,bool orNone. 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 aRecursionError).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 TypeErrorreturnsuper().default(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.

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