PYTHON-3259 Improve migration guide for loads/JSONOptions/tz_aware

bson/json_util.py

@@ -438,6 +438,11 @@ def loads(s: str, *args: Any, **kwargs: Any) -> Any:
         decoding of MongoDB Extended JSON types. Defaults to
         :const:`DEFAULT_JSON_OPTIONS`.
 
+    .. versionchanged:: 4.0
+       Now loads :class:`datetime.datetime` instances as naive by default. To
+       load timezone aware instances utilize the `json_options` parameter.
+       See :ref:`tz_aware_default_change` for an example.
+
     .. versionchanged:: 3.5
        Parses Relaxed and Canonical Extended JSON as well as PyMongo's legacy
        format. Now raises ``TypeError`` or ``ValueError`` when parsing JSON

doc/changelog.rst

@@ -256,9 +256,9 @@ Breaking Changes in 4.0
   :class:`~bson.dbref.DBRef`.
 - The "tls" install extra is no longer necessary or supported and will be
   ignored by pip.
-- ``tz_aware``, an argument for :class:`~bson.json_util.JSONOptions`,
-  now defaults to ``False`` instead of ``True``. ``json_util.loads`` now
-  decodes datetime as naive by default.
+- The ``tz_aware`` argument to :class:`~bson.json_util.JSONOptions`
+  now defaults to ``False`` instead of ``True``. :meth:`bson.json_util.loads` now
+  decodes datetime as naive by default. See :ref:`tz_aware_default_change` for more info.
 - ``directConnection`` URI option and keyword argument to :class:`~pymongo.mongo_client.MongoClient`
   defaults to ``False`` instead of ``None``, allowing for the automatic
   discovery of replica sets. This means that if you

doc/migrate-to-pymongo4.rst

@@ -253,12 +253,30 @@ can be changed to this::
     client.options.pool_options.min_pool_size
     client.options.pool_options.max_idle_time_seconds
 
+.. _tz_aware_default_change:
+
 ``tz_aware`` defaults to ``False``
 ..................................
 
-``tz_aware``, an argument for :class:`~bson.json_util.JSONOptions`,
-now defaults to ``False`` instead of ``True``. ``json_util.loads`` now
-decodes datetime as naive by default.
+The ``tz_aware`` argument to :class:`~bson.json_util.JSONOptions`
+now defaults to ``False`` instead of ``True``. :meth:`bson.json_util.loads`
+now decodes datetime as naive by default::
+
+    >>> from bson import json_util
+    >>> s = '{"dt": {"$date": "2022-05-09T17:54:00Z"}}'
+    >>> json_util.loads(s)
+    {'dt': datetime.datetime(2022, 5, 9, 17, 54)}
+
+To retain the PyMongo 3 behavior set ``tz_aware=True``, for example::
+
+    >>> from bson import json_util
+    >>> opts = json_util.JSONOptions(tz_aware=True)
+    >>> s = '{"dt": {"$date": "2022-05-09T17:54:00Z"}}'
+    >>> json_util.loads(s, json_options=opts)
+    {'dt': datetime.datetime(2022, 5, 9, 17, 54, tzinfo=<bson.tz_util.FixedOffset object at 0x7fd1ebc1add0>)}
+
+This change was made to match the default behavior of
+:class:`~bson.codec_options.CodecOptions` and :class:`bson.decode`.
 
 MongoClient cannot execute operations after ``close()``
 .......................................................