PYTHON-3546 bson.CodecOptions docs missing unicode_decode_error_handler=ignore option in newer documentation (#1131)

Author: blink1073

bson/codec_options.py

@@ -245,87 +245,92 @@ class _BaseCodecOptions(NamedTuple):
 
 
 class CodecOptions(_BaseCodecOptions):
-    """Encapsulates options used encoding and / or decoding BSON.
-
-    The `document_class` option is used to define a custom type for use
-    decoding BSON documents. Access to the underlying raw BSON bytes for
-    a document is available using the :class:`~bson.raw_bson.RawBSONDocument`
-    type::
-
-      >>> from bson.raw_bson import RawBSONDocument
-      >>> from bson.codec_options import CodecOptions
-      >>> codec_options = CodecOptions(document_class=RawBSONDocument)
-      >>> coll = db.get_collection('test', codec_options=codec_options)
-      >>> doc = coll.find_one()
-      >>> doc.raw
-      '\\x16\\x00\\x00\\x00\\x07_id\\x00[0\\x165\\x91\\x10\\xea\\x14\\xe8\\xc5\\x8b\\x93\\x00'
-
-    The document class can be any type that inherits from
-    :class:`~collections.abc.MutableMapping`::
-
-      >>> class AttributeDict(dict):
-      ...     # A dict that supports attribute access.
-      ...     def __getattr__(self, key):
-      ...         return self[key]
-      ...     def __setattr__(self, key, value):
-      ...         self[key] = value
-      ...
-      >>> codec_options = CodecOptions(document_class=AttributeDict)
-      >>> coll = db.get_collection('test', codec_options=codec_options)
-      >>> doc = coll.find_one()
-      >>> doc._id
-      ObjectId('5b3016359110ea14e8c58b93')
-
-    See :doc:`/examples/datetimes` for examples using the `tz_aware` and
-    `tzinfo` options.
-
-    See :doc:`/examples/uuid` for examples using the `uuid_representation`
-    option.
-
-    :Parameters:
-      - `document_class`: BSON documents returned in queries will be decoded
-        to an instance of this class. Must be a subclass of
-        :class:`~collections.abc.MutableMapping`. Defaults to :class:`dict`.
-      - `tz_aware`: If ``True``, BSON datetimes will be decoded to timezone
-        aware instances of :class:`~datetime.datetime`. Otherwise they will be
-        naive. Defaults to ``False``.
-      - `uuid_representation`: The BSON representation to use when encoding
-        and decoding instances of :class:`~uuid.UUID`. Defaults to
-        :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.
-      - `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
-        'strict', 'replace', 'backslashreplace', 'surrogateescape', and
-        'ignore'. Defaults to 'strict'.
-      - `tzinfo`: A :class:`~datetime.tzinfo` subclass that specifies the
-        timezone to/from which :class:`~datetime.datetime` objects should be
-        encoded/decoded.
-      - `type_registry`: Instance of :class:`TypeRegistry` used to customize
-        encoding and decoding behavior.
-      - `datetime_conversion`: Specifies how UTC datetimes should be decoded
-        within BSON. Valid options include 'datetime_ms' to return as a
-        DatetimeMS, 'datetime' to return as a datetime.datetime and
-        raising a ValueError for out-of-range values, 'datetime_auto' to
-        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'.
-    .. versionchanged:: 4.0
-       The default for `uuid_representation` was changed from
-       :const:`~bson.binary.UuidRepresentation.PYTHON_LEGACY` to
-       :const:`~bson.binary.UuidRepresentation.UNSPECIFIED`.
-
-    .. versionadded:: 3.8
-       `type_registry` attribute.
-
-    .. warning:: Care must be taken when changing
-       `unicode_decode_error_handler` from its default value ('strict').
-       The 'replace' and 'ignore' modes should not be used when documents
-       retrieved from the server will be modified in the client application
-       and stored back to the server.
-    """
+    """Encapsulates options used encoding and / or decoding BSON."""
+
+    def __init__(self, *args, **kwargs):
+        """Encapsulates options used encoding and / or decoding BSON.
+
+        The `document_class` option is used to define a custom type for use
+        decoding BSON documents. Access to the underlying raw BSON bytes for
+        a document is available using the :class:`~bson.raw_bson.RawBSONDocument`
+        type::
+
+          >>> from bson.raw_bson import RawBSONDocument
+          >>> from bson.codec_options import CodecOptions
+          >>> codec_options = CodecOptions(document_class=RawBSONDocument)
+          >>> coll = db.get_collection('test', codec_options=codec_options)
+          >>> doc = coll.find_one()
+          >>> doc.raw
+          '\\x16\\x00\\x00\\x00\\x07_id\\x00[0\\x165\\x91\\x10\\xea\\x14\\xe8\\xc5\\x8b\\x93\\x00'
+
+        The document class can be any type that inherits from
+        :class:`~collections.abc.MutableMapping`::
+
+          >>> class AttributeDict(dict):
+          ...     # A dict that supports attribute access.
+          ...     def __getattr__(self, key):
+          ...         return self[key]
+          ...     def __setattr__(self, key, value):
+          ...         self[key] = value
+          ...
+          >>> codec_options = CodecOptions(document_class=AttributeDict)
+          >>> coll = db.get_collection('test', codec_options=codec_options)
+          >>> doc = coll.find_one()
+          >>> doc._id
+          ObjectId('5b3016359110ea14e8c58b93')
+
+        See :doc:`/examples/datetimes` for examples using the `tz_aware` and
+        `tzinfo` options.
+
+        See :doc:`/examples/uuid` for examples using the `uuid_representation`
+        option.
+
+        :Parameters:
+          - `document_class`: BSON documents returned in queries will be decoded
+            to an instance of this class. Must be a subclass of
+            :class:`~collections.abc.MutableMapping`. Defaults to :class:`dict`.
+          - `tz_aware`: If ``True``, BSON datetimes will be decoded to timezone
+            aware instances of :class:`~datetime.datetime`. Otherwise they will be
+            naive. Defaults to ``False``.
+          - `uuid_representation`: The BSON representation to use when encoding
+            and decoding instances of :class:`~uuid.UUID`. Defaults to
+            :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.
+          - `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
+            'strict', 'replace', 'backslashreplace', 'surrogateescape', and
+            'ignore'. Defaults to 'strict'.
+          - `tzinfo`: A :class:`~datetime.tzinfo` subclass that specifies the
+            timezone to/from which :class:`~datetime.datetime` objects should be
+            encoded/decoded.
+          - `type_registry`: Instance of :class:`TypeRegistry` used to customize
+            encoding and decoding behavior.
+          - `datetime_conversion`: Specifies how UTC datetimes should be decoded
+            within BSON. Valid options include 'datetime_ms' to return as a
+            DatetimeMS, 'datetime' to return as a datetime.datetime and
+            raising a ValueError for out-of-range values, 'datetime_auto' to
+            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'.
+
+        .. versionchanged:: 4.0
+           The default for `uuid_representation` was changed from
+           :const:`~bson.binary.UuidRepresentation.PYTHON_LEGACY` to
+           :const:`~bson.binary.UuidRepresentation.UNSPECIFIED`.
+
+        .. versionadded:: 3.8
+           `type_registry` attribute.
+
+        .. warning:: Care must be taken when changing
+           `unicode_decode_error_handler` from its default value ('strict').
+           The 'replace' and 'ignore' modes should not be used when documents
+           retrieved from the server will be modified in the client application
+           and stored back to the server.
+        """
+        return super().__init__()
 
     def __new__(
         cls: Type["CodecOptions"],