From: Serhiy Storchaka <storchaka@gmail.com>
Date: Thu, 27 Nov 2014 17:45:31 +0000 (+0200)
Subject: Issue #21514: The documentation of the json module now refers to new JSON RFC
X-Git-Tag: v3.5.0a1~426
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=715f01b56581b58af34e3dd703bf05fc54510628;p=thirdparty%2FPython%2Fcpython.git

Issue #21514: The documentation of the json module now refers to new JSON RFC
7159 instead of obsoleted RFC 4627.
---

715f01b56581b58af34e3dd703bf05fc54510628
diff --cc Doc/library/json.rst
index edbc5e0bd5a8,33ad102e6f4b..c77b89ed6b52
--- a/Doc/library/json.rst
+++ b/Doc/library/json.rst
@@@ -566,64 -552,47 +554,109 @@@ the last name-value pair for a given na
  
  The *object_pairs_hook* parameter can be used to alter this behavior.
  
+ 
+ Top-level Non-Object, Non-Array Values
+ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ 
+ The old version of JSON specified by the obsolete :rfc:`4627` required that
+ the top-level value of a JSON text must be either a JSON object or array
+ (Python :class:`dict` or :class:`list`), and could not be a JSON null,
+ boolean, number, or string value.  :rfc:`7159` removed that restriction, and
+ this module does not and has never implemented that restriction in either its
+ serializer or its deserializer.
+ 
+ Regardless, for maximum interoperability, you may wish to voluntarily adhere
+ to the restriction yourself.
+ 
+ 
+ Implementation Limitations
+ ^^^^^^^^^^^^^^^^^^^^^^^^^^
+ 
+ Some JSON deserializer implementations may set limits on:
+ 
+ * the size of accepted JSON texts
+ * the maximum level of nesting of JSON objects and arrays
+ * the range and precision of JSON numbers
+ * the content and maximum length of JSON strings
+ 
+ This module does not impose any such limits beyond those of the relevant
+ Python datatypes themselves or the Python interpreter itself.
+ 
+ When serializing to JSON, beware any such limitations in applications that may
+ consume your JSON.  In particular, it is common for JSON numbers to be
+ deserialized into IEEE 754 double precision numbers and thus subject to that
+ representation's range and precision limitations.  This is especially relevant
+ when serializing Python :class:`int` values of extremely large magnitude, or
+ when serializing instances of "exotic" numerical types such as
+ :class:`decimal.Decimal`.
+ 
 +.. highlight:: bash
 +.. module:: json.tool
 +
 +.. _json-commandline:
 +
 +Command Line Interface
 +----------------------
 +
 +The :mod:`json.tool` module provides a simple command line interface to validate
 +and pretty-print JSON objects.
 +
 +If the optional ``infile`` and ``outfile`` arguments are not
 +specified, :attr:`sys.stdin` and :attr:`sys.stdout` will be used respectively::
 +
 +    $ 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)
 +
 +.. versionchanged:: 3.5
 +   The output is now in the same order as the input. Use the
 +   :option:`--sort-keys` option to sort the output of dictionaries
 +   alphabetically by key.
 +
 +Command line options
 +^^^^^^^^^^^^^^^^^^^^
 +
 +.. cmdoption:: infile
 +
 +   The JSON file to be validated or pretty-printed::
 +
 +      $ 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
 +          }
 +      ]
 +
 +   If *infile* is not specified, read from :attr:`sys.stdin`.
 +
 +.. cmdoption:: outfile
 +
 +   Write the output of the *infile* to the given *outfile*. Otherwise, write it
 +   to :attr:`sys.stdout`.
 +
 +.. cmdoption:: --sort-keys
 +
 +   Sort the output of dictionaries alphabetically by key.
 +
 +   .. versionadded:: 3.5
 +
 +.. cmdoption:: -h, --help
 +
 +   Show the help message.
++
+ 
+ .. rubric:: Footnotes
+ 
+ .. [#rfc-errata] As noted in `the errata for RFC 7159
+    <http://www.rfc-editor.org/errata_search.php?rfc=7159>`_,
+    JSON permits literal U+2028 (LINE SEPARATOR) and
+    U+2029 (PARAGRAPH SEPARATOR) characters in strings, whereas JavaScript
+    (as of ECMAScript Edition 5.1) does not.
diff --cc Misc/NEWS
index db6daed62bf5,c1abebed3114..c005a6f310fa
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@@ -1300,12 -974,6 +1300,15 @@@ C AP
  Documentation
  -------------
  
++- Issue #21514: The documentation of the json module now refers to new JSON RFC
++  7159 instead of obsoleted RFC 4627.
++
 +- Issue #21777: The binary sequence methods on bytes and bytearray are now
 +  documented explicitly, rather than assuming users will be able to derive
 +  the expected behaviour from the behaviour of the corresponding str methods.
 +
 +- Issue #6916: undocument deprecated asynchat.fifo class.
 +
  - Issue #17386: Expanded functionality of the ``Doc/make.bat`` script to make
    it much more comparable to ``Doc/Makefile``.