From 657008ea0336ff4f275ed3f0c2b6dd2e52de2bba Mon Sep 17 00:00:00 2001 From: Raymond Hettinger Date: Thu, 22 Aug 2019 15:14:42 -0700 Subject: [PATCH] bpo-30550: Clarify JSON ordering guarantees (GH-15397) --- Doc/library/json.rst | 12 ++++++++++++ 1 file changed, 12 insertions(+) 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 ----------- -- 2.40.0