codec_options
– Tools for specifying BSON codec options¶
Tools for specifying BSON codec options.
-
class
bson.codec_options.
CodecOptions
¶ 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
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
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 Datetimes and Timezones for examples using the tz_aware and tzinfo options.
See
UUIDLegacy
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
MutableMapping
. Defaults todict
. - tz_aware: If
True
, BSON datetimes will be decoded to timezone aware instances ofdatetime
. Otherwise they will be naive. Defaults toFalse
. - uuid_representation: The BSON representation to use when encoding
and decoding instances of
UUID
. Defaults toPYTHON_LEGACY
. - unicode_decode_error_handler: The error handler to apply when
a Unicode-related error occurs during BSON decoding that would
otherwise raise
UnicodeDecodeError
. Valid options include ‘strict’, ‘replace’, and ‘ignore’. Defaults to ‘strict’. - tzinfo: A
tzinfo
subclass that specifies the timezone to/from whichdatetime
objects should be encoded/decoded. - type_registry: Instance of
TypeRegistry
used to customize encoding and decoding behavior.
New in version 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.
-
with_options
(**kwargs)¶ Make a copy of this CodecOptions, overriding some options:
>>> from bson.codec_options import DEFAULT_CODEC_OPTIONS >>> DEFAULT_CODEC_OPTIONS.tz_aware False >>> options = DEFAULT_CODEC_OPTIONS.with_options(tz_aware=True) >>> options.tz_aware True
New in version 3.5.
- document_class: BSON documents returned in queries will be decoded
to an instance of this class. Must be a subclass of
-
class
bson.codec_options.
TypeCodec
¶ Base class for defining type codec classes which describe how a custom type can be transformed to/from one of the types
bson
can already encode/decode.Codec classes must implement the
python_type
attribute, and thetransform_python
method to support encoding, as well as thebson_type
attribute, and thetransform_bson
method to support decoding.See The TypeCodec Class documentation for an example.
-
class
bson.codec_options.
TypeDecoder
¶ Base class for defining type codec classes which describe how a BSON type can be transformed to a custom type.
Codec classes must implement the
bson_type
attribute, and thetransform_bson
method to support decoding.See The TypeCodec Class documentation for an example.
-
bson_type
¶ The BSON type to be converted into our own type.
-
transform_bson
(value)¶ Convert the given BSON value into our own type.
-
-
class
bson.codec_options.
TypeEncoder
¶ Base class for defining type codec classes which describe how a custom type can be transformed to one of the types BSON understands.
Codec classes must implement the
python_type
attribute, and thetransform_python
method to support encoding.See The TypeCodec Class documentation for an example.
-
python_type
¶ The Python type to be converted into something serializable.
-
transform_python
(value)¶ Convert the given Python object into something serializable.
-
-
class
bson.codec_options.
TypeRegistry
(type_codecs=None, fallback_encoder=None)¶ Encapsulates type codecs used in encoding and / or decoding BSON, as well as the fallback encoder. Type registries cannot be modified after instantiation.
TypeRegistry
can be initialized with an iterable of type codecs, and a callable for the fallback encoder:>>> from bson.codec_options import TypeRegistry >>> type_registry = TypeRegistry([Codec1, Codec2, Codec3, ...], ... fallback_encoder)
See The TypeRegistry Class documentation for an example.
Parameters: - type_codecs (optional): iterable of type codec instances. If
type_codecs
contains multiple codecs that transform a single python or BSON type, the transformation specified by the type codec occurring last prevails. A TypeError will be raised if one or more type codecs modify the encoding behavior of a built-inbson
type. - fallback_encoder (optional): callable that accepts a single,
unencodable python value and transforms it into a type that
bson
can encode. See The fallback_encoder Callable documentation for an example.
- type_codecs (optional): iterable of type codec instances. If