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.
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