codec_options – Tools for specifying BSON codec options

Tools for specifying BSON codec options.

class bson.codec_options.CodecOptions(document_class: Optional[Type[Mapping[str, Any]]] = None, tz_aware: bool = False, uuid_representation: Optional[int] = 0, unicode_decode_error_handler: str = 'strict', tzinfo: Optional[datetime.tzinfo] = None, type_registry: Optional[bson.codec_options.TypeRegistry] = None, datetime_conversion: Optional[bson.codec_options.DatetimeConversion] = 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) → bson.codec_options.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: Optional[Iterable[Union[bson.codec_options.TypeEncoder, bson.codec_options.TypeDecoder, bson.codec_options.TypeCodec]]] = None, fallback_encoder: Optional[Callable[[Any], Any]] = 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.