codec_options – Tools for specifying BSON codec options

Tools for specifying BSON codec options.

class bson.codec_options.CodecOptions(document_class: Type[Mapping[str, Any]] | None = None, tz_aware: bool = False, uuid_representation: int | None = 0, unicode_decode_error_handler: str = 'strict', tzinfo: tzinfo | None = None, type_registry: TypeRegistry | None = None, datetime_conversion: DatetimeConversion | None = DatetimeConversion.DATETIME)

Create new instance of _BaseCodecOptions(document_class, tz_aware, uuid_representation, unicode_decode_error_handler, tzinfo, type_registry, datetime_conversion)

with_options(**kwargs: Any) CodecOptions

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.

class bson.codec_options.DatetimeConversion(value)

Options for decoding BSON datetimes.

DATETIME = 1

Decode a BSON UTC datetime as a datetime.datetime.

BSON UTC datetimes that cannot be represented as a datetime will raise an OverflowError or a ValueError.

DATETIME_AUTO = 4

Decode a BSON UTC datetime as a datetime.datetime if possible, and a DatetimeMS if not.

DATETIME_CLAMP = 2

Decode a BSON UTC datetime as a datetime.datetime, clamping to min and max.

DATETIME_MS = 3

Decode a BSON UTC datetime as a DatetimeMS object.

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 the transform_python method to support encoding, as well as the bson_type attribute, and the transform_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 the transform_bson method to support decoding.

See The TypeCodec Class documentation for an example.

abstract property bson_type: Any

The BSON type to be converted into our own type.

abstract transform_bson(value: Any) Any

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 the transform_python method to support encoding.

See The TypeCodec Class documentation for an example.

abstract property python_type: Any

The Python type to be converted into something serializable.

abstract transform_python(value: Any) Any

Convert the given Python object into something serializable.

class bson.codec_options.TypeRegistry(type_codecs: Iterable[TypeEncoder | TypeDecoder | TypeCodec] | None = None, fallback_encoder: Callable[[Any], Any] | None = 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-in bson 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.