Merge branch 'master' of github.com:mongodb/mongo-python-driver

Author: blink1073

README.md

@@ -16,6 +16,13 @@ implementation on top of `pymongo`.
 
 PyMongo supports MongoDB 4.0, 4.2, 4.4, 5.0, 6.0, 7.0, and 8.0. PyMongo follows [semantic versioning](https://semver.org/spec/v2.0.0.html) for its releases.
 
+## Documentation
+
+Documentation is available at
+[mongodb.com](https://www.mongodb.com/docs/languages/python/pymongo-driver/current/).
+
+[API documentation](https://pymongo.readthedocs.io/en/stable/api/) and the [full changelog](https://pymongo.readthedocs.io/en/stable/changelog.html) for each release is available at [readthedocs.io](https://pymongo.readthedocs.io/en/stable/index.html).
+
 ## Support / Feedback
 
 For issues with, questions about, or feedback for PyMongo, please look
@@ -191,13 +198,6 @@ ObjectId('4aba160ee23f6b543e000002')
 [8, 11]
 ```
 
-## Documentation
-
-Documentation is available at
-[pymongo.readthedocs.io](https://pymongo.readthedocs.io/en/stable/).
-
-See the [contributing guide](./CONTRIBUTING.md#documentation) for how to build the documentation.
-
 ## Learning Resources
 
 - MongoDB Learn - [Python

bson/__init__.py

@@ -58,10 +58,10 @@
    the microsecond field is truncated.
 .. [#dt2] all datetime.datetime instances are encoded as UTC. By default, they
    are decoded as *naive* but timezone aware datetimes are also supported.
-   See :doc:`/examples/datetimes` for examples.
+   See `Dates and Times <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/data-formats/dates-and-times/#dates-and-times>`_ for examples.
 .. [#dt3] To enable decoding a bson UTC datetime to a :class:`~bson.datetime_ms.DatetimeMS`
-   instance see :ref:`handling-out-of-range-datetimes`.
-.. [#uuid] For :py:class:`uuid.UUID` encoding and decoding behavior see :doc:`/examples/uuid`.
+   instance see `handling out of range datetimes <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/data-formats/dates-and-times/#handling-out-of-range-datetimes>`_.
+.. [#uuid] For :py:class:`uuid.UUID` encoding and decoding behavior see `<https://www.mongodb.com/docs/languages/python/pymongo-driver/current/data-formats/uuid/#universally-unique-ids--uuids->`_.
 .. [#re] :class:`~bson.regex.Regex` instances and regular expression
    objects from ``re.compile()`` are both saved as BSON regular expressions.
    BSON regular expressions are decoded as :class:`~bson.regex.Regex`

bson/binary.py

@@ -79,7 +79,7 @@ class UuidRepresentation:
     :class:`~bson.binary.Binary` instance will be returned instead of a
     :class:`uuid.UUID` instance.
 
-    See :ref:`unspecified-representation-details` for details.
+    See `unspecified representation details <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/data-formats/uuid/#unspecified>`_ for details.
 
     .. versionadded:: 3.11
     """
@@ -91,7 +91,7 @@ class UuidRepresentation:
     and decoded from BSON binary, using RFC-4122 byte order with
     binary subtype :data:`UUID_SUBTYPE`.
 
-    See :ref:`standard-representation-details` for details.
+    See `standard representation details <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/data-formats/uuid/#standard>`_ for details.
 
     .. versionadded:: 3.11
     """
@@ -103,7 +103,7 @@ class UuidRepresentation:
     and decoded from BSON binary, using RFC-4122 byte order with
     binary subtype :data:`OLD_UUID_SUBTYPE`.
 
-    See :ref:`python-legacy-representation-details` for details.
+    See `python legacy representation details <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/data-formats/uuid/#python_legacy>`_ for details.
 
     .. versionadded:: 3.11
     """
@@ -115,7 +115,7 @@ class UuidRepresentation:
     and decoded from BSON binary subtype :data:`OLD_UUID_SUBTYPE`,
     using the Java driver's legacy byte order.
 
-    See :ref:`java-legacy-representation-details` for details.
+    See `Java Legacy UUID <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/data-formats/uuid/#java_legacy>`_ for details.
 
     .. versionadded:: 3.11
     """
@@ -127,7 +127,7 @@ class UuidRepresentation:
     and decoded from BSON binary subtype :data:`OLD_UUID_SUBTYPE`,
     using the C# driver's legacy byte order.
 
-    See :ref:`csharp-legacy-representation-details` for details.
+    See `C# Legacy UUID <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/data-formats/uuid/#csharp_legacy>`_ for details.
 
     .. versionadded:: 3.11
     """
@@ -328,7 +328,7 @@ def from_uuid(
         :param uuid_representation: A member of
             :class:`~bson.binary.UuidRepresentation`. Default:
             :const:`~bson.binary.UuidRepresentation.STANDARD`.
-            See :ref:`handling-uuid-data-example` for details.
+            See `UUID representations <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/data-formats/uuid/#universally-unique-ids--uuids->`_ for details.
 
         .. versionadded:: 3.11
         """
@@ -377,7 +377,7 @@ def as_uuid(self, uuid_representation: int = UuidRepresentation.STANDARD) -> UUI
         :param uuid_representation: A member of
             :class:`~bson.binary.UuidRepresentation`. Default:
             :const:`~bson.binary.UuidRepresentation.STANDARD`.
-            See :ref:`handling-uuid-data-example` for details.
+            See `UUID representations <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/data-formats/uuid/#universally-unique-ids--uuids->`_ for details.
 
         .. versionadded:: 3.11
         """

bson/codec_options.py

@@ -57,7 +57,7 @@ class TypeEncoder(abc.ABC):
     Codec classes must implement the ``python_type`` attribute, and the
     ``transform_python`` method to support encoding.
 
-    See :ref:`custom-type-type-codec` documentation for an example.
+    See `encode data with type codecs <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/data-formats/custom-types/type-codecs/#encode-data-with-type-codecs>`_ documentation for an example.
     """
 
     @abc.abstractproperty
@@ -76,7 +76,7 @@ class TypeDecoder(abc.ABC):
     Codec classes must implement the ``bson_type`` attribute, and the
     ``transform_bson`` method to support decoding.
 
-    See :ref:`custom-type-type-codec` documentation for an example.
+    See `encode data with type codecs <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/data-formats/custom-types/type-codecs/#encode-data-with-type-codecs>`_ documentation for an example.
     """
 
     @abc.abstractproperty
@@ -98,7 +98,7 @@ class TypeCodec(TypeEncoder, TypeDecoder):
     ``bson_type`` attribute, and the ``transform_bson`` method to support
     decoding.
 
-    See :ref:`custom-type-type-codec` documentation for an example.
+    See `encode data with type codecs <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/data-formats/custom-types/type-codecs/#encode-data-with-type-codecs>`_ documentation for an example.
     """
 
 
@@ -118,7 +118,7 @@ class TypeRegistry:
       >>> type_registry = TypeRegistry([Codec1, Codec2, Codec3, ...],
       ...                              fallback_encoder)
 
-    See :ref:`custom-type-type-registry` documentation for an example.
+    See `add codec to the type registry <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/data-formats/custom-types/type-codecs/#add-codec-to-the-type-registry>`_ documentation for an example.
 
     :param type_codecs: iterable of type codec instances. If
         ``type_codecs`` contains multiple codecs that transform a single
@@ -128,7 +128,7 @@ class TypeRegistry:
         type.
     :param fallback_encoder: callable that accepts a single,
         unencodable python value and transforms it into a type that
-        :mod:`bson` can encode. See :ref:`fallback-encoder-callable`
+        :mod:`bson` can encode. See `define a fallback encoder <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/data-formats/custom-types/type-codecs/#define-a-fallback-encoder>`_
         documentation for an example.
     """
 
@@ -327,10 +327,10 @@ def __init__(self, *args, **kwargs):
               >>> doc._id
               ObjectId('5b3016359110ea14e8c58b93')
 
-            See :doc:`/examples/datetimes` for examples using the `tz_aware` and
+            See `Dates and Times <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/data-formats/dates-and-times/#dates-and-times>`_ for examples using the `tz_aware` and
             `tzinfo` options.
 
-            See :doc:`/examples/uuid` for examples using the `uuid_representation`
+            See `UUID <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/data-formats/uuid/#universally-unique-ids--uuids->`_ for examples using the `uuid_representation`
             option.
 
             :param document_class: BSON documents returned in queries will be decoded
@@ -344,7 +344,7 @@ def __init__(self, *args, **kwargs):
                 :data:`~bson.binary.UuidRepresentation.UNSPECIFIED`. New
                 applications should consider setting this to
                 :data:`~bson.binary.UuidRepresentation.STANDARD` for cross language
-                compatibility. See :ref:`handling-uuid-data-example` for details.
+                compatibility. See `UUID representations <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/data-formats/uuid/#universally-unique-ids--uuids->`_ for details.
             :param unicode_decode_error_handler: The error handler to apply when
                 a Unicode-related error occurs during BSON decoding that would
                 otherwise raise :exc:`UnicodeDecodeError`. Valid options include

bson/datetime_ms.py

@@ -51,7 +51,7 @@ def __init__(self, value: Union[int, datetime.datetime]):
 
         To decode UTC datetimes as a ``DatetimeMS``, `datetime_conversion` in
         :class:`~bson.codec_options.CodecOptions` must be set to 'datetime_ms' or
-        'datetime_auto'. See :ref:`handling-out-of-range-datetimes` for
+        'datetime_auto'. See `handling out of range datetimes <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/data-formats/dates-and-times/#handling-out-of-range-datetimes>`_ for
         details.
 
         :param value: An instance of :class:`datetime.datetime` to be

bson/json_util.py

@@ -281,7 +281,7 @@ def __init__(self, *args: Any, **kwargs: Any):
             return DatetimeMS objects when the underlying datetime is
             out-of-range and 'datetime_clamp' to clamp to the minimum and
             maximum possible datetimes. Defaults to 'datetime'. See
-            :ref:`handling-out-of-range-datetimes` for details.
+            `handling out of range datetimes <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/data-formats/dates-and-times/#handling-out-of-range-datetimes>`_ for details.
         :param args: arguments to :class:`~bson.codec_options.CodecOptions`
         :param kwargs: arguments to :class:`~bson.codec_options.CodecOptions`
 
@@ -844,7 +844,7 @@ def _encode_binary(data: bytes, subtype: int, json_options: JSONOptions) -> Any:
     return {"$binary": {"base64": base64.b64encode(data).decode(), "subType": "%02x" % subtype}}
 
 
-def _encode_datetimems(obj: Any, json_options: JSONOptions) -> dict:
+def _encode_datetimems(obj: Any, json_options: JSONOptions) -> dict:  # type: ignore[type-arg]
     if (
         json_options.datetime_representation == DatetimeRepresentation.ISO8601
         and 0 <= int(obj) <= _MAX_UTC_MS
@@ -855,7 +855,7 @@ def _encode_datetimems(obj: Any, json_options: JSONOptions) -> dict:
     return {"$date": {"$numberLong": str(int(obj))}}
 
 
-def _encode_code(obj: Code, json_options: JSONOptions) -> dict:
+def _encode_code(obj: Code, json_options: JSONOptions) -> dict:  # type: ignore[type-arg]
     if obj.scope is None:
         return {"$code": str(obj)}
     else:
@@ -873,7 +873,7 @@ def _encode_noop(obj: Any, dummy0: Any) -> Any:
     return obj
 
 
-def _encode_regex(obj: Any, json_options: JSONOptions) -> dict:
+def _encode_regex(obj: Any, json_options: JSONOptions) -> dict:  # type: ignore[type-arg]
     flags = ""
     if obj.flags & re.IGNORECASE:
         flags += "i"
@@ -918,7 +918,7 @@ def _encode_float(obj: float, json_options: JSONOptions) -> Any:
     return obj
 
 
-def _encode_datetime(obj: datetime.datetime, json_options: JSONOptions) -> dict:
+def _encode_datetime(obj: datetime.datetime, json_options: JSONOptions) -> dict:  # type: ignore[type-arg]
     if json_options.datetime_representation == DatetimeRepresentation.ISO8601:
         if not obj.tzinfo:
             obj = obj.replace(tzinfo=utc)
@@ -941,51 +941,51 @@ def _encode_datetime(obj: datetime.datetime, json_options: JSONOptions) -> dict:
     return {"$date": {"$numberLong": str(millis)}}
 
 
-def _encode_bytes(obj: bytes, json_options: JSONOptions) -> dict:
+def _encode_bytes(obj: bytes, json_options: JSONOptions) -> dict:  # type: ignore[type-arg]
     return _encode_binary(obj, 0, json_options)
 
 
-def _encode_binary_obj(obj: Binary, json_options: JSONOptions) -> dict:
+def _encode_binary_obj(obj: Binary, json_options: JSONOptions) -> dict:  # type: ignore[type-arg]
     return _encode_binary(obj, obj.subtype, json_options)
 
 
-def _encode_uuid(obj: uuid.UUID, json_options: JSONOptions) -> dict:
+def _encode_uuid(obj: uuid.UUID, json_options: JSONOptions) -> dict:  # type: ignore[type-arg]
     if json_options.strict_uuid:
         binval = Binary.from_uuid(obj, uuid_representation=json_options.uuid_representation)
         return _encode_binary(binval, binval.subtype, json_options)
     else:
         return {"$uuid": obj.hex}
 
 
-def _encode_objectid(obj: ObjectId, dummy0: Any) -> dict:
+def _encode_objectid(obj: ObjectId, dummy0: Any) -> dict:  # type: ignore[type-arg]
     return {"$oid": str(obj)}
 
 
-def _encode_timestamp(obj: Timestamp, dummy0: Any) -> dict:
+def _encode_timestamp(obj: Timestamp, dummy0: Any) -> dict:  # type: ignore[type-arg]
     return {"$timestamp": {"t": obj.time, "i": obj.inc}}
 
 
-def _encode_decimal128(obj: Timestamp, dummy0: Any) -> dict:
+def _encode_decimal128(obj: Timestamp, dummy0: Any) -> dict:  # type: ignore[type-arg]
     return {"$numberDecimal": str(obj)}
 
 
-def _encode_dbref(obj: DBRef, json_options: JSONOptions) -> dict:
+def _encode_dbref(obj: DBRef, json_options: JSONOptions) -> dict:  # type: ignore[type-arg]
     return _json_convert(obj.as_doc(), json_options=json_options)
 
 
-def _encode_minkey(dummy0: Any, dummy1: Any) -> dict:
+def _encode_minkey(dummy0: Any, dummy1: Any) -> dict:  # type: ignore[type-arg]
     return {"$minKey": 1}
 
 
-def _encode_maxkey(dummy0: Any, dummy1: Any) -> dict:
+def _encode_maxkey(dummy0: Any, dummy1: Any) -> dict:  # type: ignore[type-arg]
     return {"$maxKey": 1}
 
 
 # Encoders for BSON types
 # Each encoder function's signature is:
 #   - obj: a Python data type, e.g. a Python int for _encode_int
 #   - json_options: a JSONOptions
-_ENCODERS: dict[Type, Callable[[Any, JSONOptions], Any]] = {
+_ENCODERS: dict[Type, Callable[[Any, JSONOptions], Any]] = {  # type: ignore[type-arg]
     bool: _encode_noop,
     bytes: _encode_bytes,
     datetime.datetime: _encode_datetime,
@@ -1056,7 +1056,7 @@ def _get_datetime_size(obj: datetime.datetime) -> int:
     return 5 + len(str(obj.time()))
 
 
-def _get_regex_size(obj: Regex) -> int:
+def _get_regex_size(obj: Regex) -> int:  # type: ignore[type-arg]
     return 18 + len(obj.pattern)
 
 

bson/typings.py

@@ -28,4 +28,4 @@
 _DocumentOut = Union[MutableMapping[str, Any], "RawBSONDocument"]
 _DocumentType = TypeVar("_DocumentType", bound=Mapping[str, Any])
 _DocumentTypeArg = TypeVar("_DocumentTypeArg", bound=Mapping[str, Any])
-_ReadableBuffer = Union[bytes, memoryview, "mmap", "array"]
+_ReadableBuffer = Union[bytes, memoryview, "mmap", "array"]  # type: ignore[type-arg]