From: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com>
Date: Thu, 22 Aug 2019 22:50:32 +0000 (-0700)
Subject: bpo-30550: Clarify JSON ordering guarantees (GH-15397) (GH-15403)
X-Git-Tag: v3.8.0b4~70
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=4a40498ea96a3c606952712c7951b2ea4ab258e4;p=python

bpo-30550: Clarify JSON ordering guarantees (GH-15397) (GH-15403)

(cherry picked from commit 657008ea0336ff4f275ed3f0c2b6dd2e52de2bba)

Co-authored-by: Raymond Hettinger <rhettinger@users.noreply.github.com>
---

diff --git a/Doc/library/json.rst b/Doc/library/json.rst
index b476c37237..56c16f5d29 100644
--- a/Doc/library/json.rst
+++ b/Doc/library/json.rst
@@ -120,6 +120,18 @@ See :ref:`json-commandline` for detailed documentation.
    value) is also a subset of YAML 1.0 and 1.1.  This module can thus also be
    used as a YAML serializer.
 
+.. note::
+
+   This module's encoders and decoders preserve input and output order by
+   default.  Order is only lost if the underlying containers are unordered.
+
+   Prior to Python 3.7, :class:`dict` was not guaranteed to be ordered, so
+   inputs and outputs were typically scrambled unless
+   :class:`collections.OrderedDict` was specifically requested.  Starting
+   with Python 3.7, the regular :class:`dict` became order preserving, so
+   it is no longer necessary specify :class:`collections.OrderedDict` for
+   JSON generation and parsing.
+
 
 Basic Usage
 -----------