diff -r d1c0b57aeb1b Doc/library/json.rst --- a/Doc/library/json.rst Mon May 14 19:45:27 2012 +0200 +++ b/Doc/library/json.rst Mon May 14 19:30:46 2012 -0700 @@ -6,8 +6,10 @@ .. moduleauthor:: Bob Ippolito .. sectionauthor:: Bob Ippolito -`JSON (JavaScript Object Notation) `_ is a subset of JavaScript -syntax (ECMA-262 3rd edition) used as a lightweight data interchange format. +`JSON (JavaScript Object Notation) `_, specified by +:rfc:`4627`, is a a lightweight data interchange format based on a subset of +`JavaScript `_ syntax (`ECMA-262 3rd +edition `_). :mod:`json` exposes an API familiar to users of the standard library :mod:`marshal` and :mod:`pickle` modules. @@ -106,10 +108,11 @@ .. note:: The JSON produced by this module's default settings is a subset of - YAML, so it may be used as a serializer for that as well. + `YAML `_, so it may be used as a serializer for format + that as well. -Basic Usage +Basic usage ----------- .. function:: dump(obj, fp, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, cls=None, indent=None, separators=None, default=None, **kw) @@ -412,3 +415,85 @@ for chunk in json.JSONEncoder().iterencode(bigobject): mysocket.write(chunk) + + +Standard compliance +------------------- + +The JSON format is specified by :rfc:`4627`. This module does not comply with +the RFC in a strict fashion, implementing some extensions that are valid +JavaScript but not valid JSON. In particular, it allows infinite and NaN +floating point number values, and treats individual scalar values as valid +top-level JSON values. + +The following sections detail this module's level of compliance with the RFC. +For simplicity, :class:`JSONEncoder` and :class:`JSONDecoder` subclasses, and +parameters other than those explicitly mentioned, are not considered. + +The RFC recommends that JSON be represented using either UTF-8, UTF-16, or +UTF-32, with UTF-8 being the default. This module is defined strictly in terms +of conversion between Python objects and :class:`Unicode strings `, and +thus does not itself address the issue of character encodings. + +Parser +^^^^^^^^^^^ + +This module's JSON parser is RFC-compliant by default and accepts all valid +JSON texts, subject to memory restrictions. As permitted by the RFC, it also +accepts certain input texts that are not compliant with the RFC. + +The parser accepts input texts consisting solely of a JSON scalar value:: + + >>> import json + >>> invalid_json_text = '"spam and eggs"' # valid as part of a JSON text, but not itself valid as an entire JSON text + >>> json.loads(invalid_json_text) # does not raise an exception + 'spam and eggs' + +The RFC only requires that JSON objects or arrays need be accepted as top-level +values. The module itself does not include a way to request that such input +texts be regarded as illegal. + +Copying JavaScript syntax, the parser accepts ``Infinity``, ``-Infinity``, and +``NaN`` as valid JSON number values; the RFC does not permit the representation +of infinite or NaN values. The *parse_constant* parameter can be used to alter +this behavior. + +The RFC specifies that the names within a JSON object should be unique, but +does not specify how repeated names in JSON objects should be handled. By +default, this module does not raise an exception; instead, it ignores all but +the last name/value pair for a given name:: + + >>> import json + >>> weird_json = '{"x": 1, "x": 2, "x": 3}' # multiple values for the same name in an object + >>> json.loads(weird_json) # does not raise an exception; last value silently wins + {'x': 3} + +The *object_pairs_hook* parameter can be used to alter this behavior. + +Generator +^^^^^^^^^^^^^^ + +This module's JSON generator accepts scalar values as input and will generate +output texts consisting solely of a top-level JSON scalar value without +raising an exception:: + + >>> import json + >>> top_level = "spam and eggs" # a string is a scalar value in JSON + >>> json.dumps(top_level) # does not raise an exception + '"spam and eggs"' + +This behavior is not compliant with RFC, which only permits JSON objects or +arrays (Python :class:`dicts ` or :class:`lists `) as top-level +values. This module itself does not include a way to enforce this +constraint. To be RFC-compliant, this module's JSON generator must only be +directly called with Python :class:`list` or :class:`dict` values. + +By default, this module sets ``allow_nan=True``, which makes its JSON +generator non-compliant with the RFC when the input contains infinite or NaN +floating point values:: + + >>> import json + >>> json.dumps(float('-inf')) # does not throw an exception; result is not valid JSON + '-Infinity' + >>> json.dumps(float('nan')) # does not throw an exception; result is not valid JSON + 'NaN'