PYTHON-2046 Cleanup docs

Author: ShaneHarvey

bson/json_util.py

@@ -17,9 +17,9 @@
 This module provides two helper methods `dumps` and `loads` that wrap the
 native :mod:`json` methods and provide explicit BSON conversion to and from
 JSON. :class:`~bson.json_util.JSONOptions` provides a way to control how JSON
-is emitted and parsed, with the default being the legacy PyMongo format.
-:mod:`~bson.json_util` can also generate Canonical or Relaxed `Extended JSON`_
-when :const:`CANONICAL_JSON_OPTIONS` or :const:`RELAXED_JSON_OPTIONS` is
+is emitted and parsed, with the default being the Relaxed Extended JSON format.
+:mod:`~bson.json_util` can also generate Canonical or legacy `Extended JSON`_
+when :const:`CANONICAL_JSON_OPTIONS` or :const:`LEGACY_JSON_OPTIONS` is
 provided, respectively.
 
 .. _Extended JSON: https://github.com/mongodb/specifications/blob/master/source/extended-json.rst
@@ -32,17 +32,17 @@
    >>> loads('[{"foo": [1, 2]}, {"bar": {"hello": "world"}}, {"code": {"$scope": {}, "$code": "function x() { return 1; }"}}, {"bin": {"$type": "80", "$binary": "AQIDBA=="}}]')
    [{'foo': [1, 2]}, {'bar': {'hello': 'world'}}, {'code': Code('function x() { return 1; }', {})}, {'bin': Binary(b'...', 128)}]
 
-Example usage (serialization):
+Example usage with :const:`RELAXED_JSON_OPTIONS` (the default):
 
 .. doctest::
 
    >>> from bson import Binary, Code
    >>> from bson.json_util import dumps
    >>> dumps([{'foo': [1, 2]},
    ...        {'bar': {'hello': 'world'}},
-   ...        {'code': Code("function x() { return 1; }", {})},
+   ...        {'code': Code("function x() { return 1; }")},
    ...        {'bin': Binary(b"\x01\x02\x03\x04")}])
-   '[{"foo": [1, 2]}, {"bar": {"hello": "world"}}, {"code": {"$code": "function x() { return 1; }", "$scope": {}}}, {"bin": {"$binary": "AQIDBA==", "$type": "00"}}]'
+   '[{"foo": [1, 2]}, {"bar": {"hello": "world"}}, {"code": {"$code": "function x() { return 1; }"}}, {"bin": {"$binary": {"base64": "AQIDBA==", "subType": "00"}}}]'
 
 Example usage (with :const:`CANONICAL_JSON_OPTIONS`):
 
@@ -57,18 +57,18 @@
    ...       json_options=CANONICAL_JSON_OPTIONS)
    '[{"foo": [{"$numberInt": "1"}, {"$numberInt": "2"}]}, {"bar": {"hello": "world"}}, {"code": {"$code": "function x() { return 1; }"}}, {"bin": {"$binary": {"base64": "AQIDBA==", "subType": "00"}}}]'
 
-Example usage (with :const:`RELAXED_JSON_OPTIONS`):
+Example usage (with :const:`LEGACY_JSON_OPTIONS`):
 
 .. doctest::
 
    >>> from bson import Binary, Code
-   >>> from bson.json_util import dumps, RELAXED_JSON_OPTIONS
+   >>> from bson.json_util import dumps, LEGACY_JSON_OPTIONS
    >>> dumps([{'foo': [1, 2]},
    ...        {'bar': {'hello': 'world'}},
-   ...        {'code': Code("function x() { return 1; }")},
+   ...        {'code': Code("function x() { return 1; }", {})},
    ...        {'bin': Binary(b"\x01\x02\x03\x04")}],
-   ...       json_options=RELAXED_JSON_OPTIONS)
-   '[{"foo": [1, 2]}, {"bar": {"hello": "world"}}, {"code": {"$code": "function x() { return 1; }"}}, {"bin": {"$binary": {"base64": "AQIDBA==", "subType": "00"}}}]'
+   ...       json_options=LEGACY_JSON_OPTIONS)
+   '[{"foo": [1, 2]}, {"bar": {"hello": "world"}}, {"code": {"$code": "function x() { return 1; }", "$scope": {}}}, {"bin": {"$binary": "AQIDBA==", "$type": "00"}}]'
 
 Alternatively, you can manually pass the `default` to :func:`json.dumps`.
 It won't handle :class:`~bson.binary.Binary` and :class:`~bson.code.Code`

doc/changelog.rst

@@ -101,6 +101,9 @@ Breaking Changes in 4.0
 - Removed :const:`bson.json_util.STRICT_JSON_OPTIONS`. Use
   :const:`~bson.json_util.RELAXED_JSON_OPTIONS` or
   :const:`~bson.json_util.CANONICAL_JSON_OPTIONS` instead.
+- Changed the default JSON encoding representation from legacy to relaxed.
+  The json_mode parameter for :const:`bson.json_util.dumps` now defaults to
+  :const:`~bson.json_util.RELAXED_JSON_OPTIONS`.
 - The "tls" install extra is no longer necessary or supported and will be
   ignored by pip.
 

doc/migrate-to-pymongo3.rst

@@ -124,9 +124,7 @@ modifier. Code like this::
   # Set a 5 second select() timeout.
   >>> cursor = collection.find({"a": 1}, network_timeout=5)
 
-can be changed to this with PyMongo 2.9 or later:
-
-.. doctest::
+can be changed to this with PyMongo 2.9 or later::
 
   # Set a 5 second (5000 millisecond) server side query timeout.
   >>> cursor = collection.find({"a": 1}, modifiers={"$maxTimeMS": 5000})

doc/migrate-to-pymongo4.rst

@@ -662,6 +662,13 @@ can be changed to this::
   uu = uuid.uuid4()
   uuid_legacy = Binary.from_uuid(uu, PYTHON_LEGACY)
 
+Default JSONMode changed from LEGACY to RELAXED
+-----------------------------------------------
+
+Changed the default JSON encoding representation from legacy to relaxed.
+The json_mode parameter for :const:`bson.json_util.dumps` now defaults to
+:const:`~bson.json_util.RELAXED_JSON_OPTIONS`.
+
 Removed features with no migration path
 ---------------------------------------
 

gridfs/grid_file.py

@@ -658,7 +658,7 @@ def seekable(self):
     def __iter__(self):
         """Return an iterator over all of this file's data.
 
-        The iterator will return lines (delimited by b'\n') of
+        The iterator will return lines (delimited by ``b'\\n'``) of
         :class:`bytes`. This can be useful when serving files
         using a webserver that handles such an iterator efficiently.