bson – BSON (Binary JSON) Encoding and Decoding#

BSON (Binary JSON) encoding and decoding.

The mapping from Python types to BSON types is as follows:

Python Type

BSON Type

Supported Direction

None

null

both

bool

boolean

both

int [1]

int32 / int64

py -> bson

bson.int64.Int64

int64

both

float

number (real)

both

str

string

both

list

array

both

dict / SON

object

both

datetime.datetime [2] [3]

date

both

bson.regex.Regex

regex

both

compiled re [4]

regex

py -> bson

bson.binary.Binary

binary

both

bson.objectid.ObjectId

oid

both

bson.dbref.DBRef

dbref

both

None

undefined

bson -> py

bson.code.Code

code

both

str

symbol

bson -> py

bytes [5]

binary

both

class bson.BSON#

BSON (Binary JSON) data.

Warning

Using this class to encode and decode BSON adds a performance cost. For better performance use the module level functions encode() and decode() instead.

decode(codec_options: CodecOptions[Any] = CodecOptions(document_class=dict, tz_aware=False, uuid_representation=UuidRepresentation.UNSPECIFIED, unicode_decode_error_handler='strict', tzinfo=None, type_registry=TypeRegistry(type_codecs=[], fallback_encoder=None), datetime_conversion=DatetimeConversion.DATETIME)) dict[str, Any]#

Decode this BSON data.

By default, returns a BSON document represented as a Python dict. To use a different MutableMapping class, configure a CodecOptions:

>>> import collections  # From Python standard library.
>>> import bson
>>> from bson.codec_options import CodecOptions
>>> data = bson.BSON.encode({'a': 1})
>>> decoded_doc = bson.BSON(data).decode()
<type 'dict'>
>>> options = CodecOptions(document_class=collections.OrderedDict)
>>> decoded_doc = bson.BSON(data).decode(codec_options=options)
>>> type(decoded_doc)
<class 'collections.OrderedDict'>
Parameters:

Changed in version 3.0: Removed compile_re option: PyMongo now always represents BSON regular expressions as Regex objects. Use try_compile() to attempt to convert from a BSON regular expression to a Python regular expression object.

Replaced as_class, tz_aware, and uuid_subtype options with codec_options.

classmethod encode(document: Mapping[str, Any], check_keys: bool = False, codec_options: CodecOptions[Any] = CodecOptions(document_class=dict, tz_aware=False, uuid_representation=UuidRepresentation.UNSPECIFIED, unicode_decode_error_handler='strict', tzinfo=None, type_registry=TypeRegistry(type_codecs=[], fallback_encoder=None), datetime_conversion=DatetimeConversion.DATETIME)) BSON#

Encode a document to a new BSON instance.

A document can be any mapping type (like dict).

Raises TypeError if document is not a mapping type, or contains keys that are not instances of str'. Raises :class:`~bson.errors.InvalidDocument if document cannot be converted to BSON.

Parameters:
  • document: mapping type representing a document

  • check_keys (optional): check if keys start with ‘$’ or contain ‘.’, raising InvalidDocument in either case

  • codec_options (optional): An instance of CodecOptions.

Changed in version 3.0: Replaced uuid_subtype option with codec_options.

bson.decode(data: _ReadableBuffer, codec_options: None = None) dict[str, Any]#
bson.decode(data: _ReadableBuffer, codec_options: CodecOptions[_DocumentType]) _DocumentType

Decode BSON to a document.

By default, returns a BSON document represented as a Python dict. To use a different MutableMapping class, configure a CodecOptions:

>>> import collections  # From Python standard library.
>>> import bson
>>> from bson.codec_options import CodecOptions
>>> data = bson.encode({'a': 1})
>>> decoded_doc = bson.decode(data)
<type 'dict'>
>>> options = CodecOptions(document_class=collections.OrderedDict)
>>> decoded_doc = bson.decode(data, codec_options=options)
>>> type(decoded_doc)
<class 'collections.OrderedDict'>
Parameters:
  • data: the BSON to decode. Any bytes-like object that implements the buffer protocol.

  • codec_options (optional): An instance of CodecOptions.

New in version 3.9.

bson.decode_all(data: _ReadableBuffer, codec_options: None = None) list[dict[str, Any]]#
bson.decode_all(data: _ReadableBuffer, codec_options: CodecOptions[_DocumentType]) list[_DocumentType]

Decode BSON data to multiple documents.

data must be a bytes-like object implementing the buffer protocol that provides concatenated, valid, BSON-encoded documents.

Parameters:
  • data: BSON data

  • codec_options (optional): An instance of CodecOptions.

Changed in version 3.9: Supports bytes-like objects that implement the buffer protocol.

Changed in version 3.0: Removed compile_re option: PyMongo now always represents BSON regular expressions as Regex objects. Use try_compile() to attempt to convert from a BSON regular expression to a Python regular expression object.

Replaced as_class, tz_aware, and uuid_subtype options with codec_options.

bson.decode_file_iter(file_obj: BinaryIO | IO[bytes], codec_options: None = None) Iterator[dict[str, Any]]#
bson.decode_file_iter(file_obj: BinaryIO | IO[bytes], codec_options: CodecOptions[_DocumentType]) Iterator[_DocumentType]

Decode bson data from a file to multiple documents as a generator.

Works similarly to the decode_all function, but reads from the file object in chunks and parses bson in chunks, yielding one document at a time.

Parameters:
  • file_obj: A file object containing BSON data.

  • codec_options (optional): An instance of CodecOptions.

Changed in version 3.0: Replaced as_class, tz_aware, and uuid_subtype options with codec_options.

New in version 2.8.

bson.decode_iter(data: bytes, codec_options: None = None) Iterator[dict[str, Any]]#
bson.decode_iter(data: bytes, codec_options: CodecOptions[_DocumentType]) Iterator[_DocumentType]

Decode BSON data to multiple documents as a generator.

Works similarly to the decode_all function, but yields one document at a time.

data must be a string of concatenated, valid, BSON-encoded documents.

Parameters:
  • data: BSON data

  • codec_options (optional): An instance of CodecOptions.

Changed in version 3.0: Replaced as_class, tz_aware, and uuid_subtype options with codec_options.

New in version 2.8.

bson.encode(document: Mapping[str, Any], check_keys: bool = False, codec_options: CodecOptions[Any] = CodecOptions(document_class=dict, tz_aware=False, uuid_representation=UuidRepresentation.UNSPECIFIED, unicode_decode_error_handler='strict', tzinfo=None, type_registry=TypeRegistry(type_codecs=[], fallback_encoder=None), datetime_conversion=DatetimeConversion.DATETIME)) bytes#

Encode a document to BSON.

A document can be any mapping type (like dict).

Raises TypeError if document is not a mapping type, or contains keys that are not instances of str. Raises InvalidDocument if document cannot be converted to BSON.

Parameters:
  • document: mapping type representing a document

  • check_keys (optional): check if keys start with ‘$’ or contain ‘.’, raising InvalidDocument in either case

  • codec_options (optional): An instance of CodecOptions.

New in version 3.9.

bson.gen_list_name() Generator[bytes, None, None]#

Generate “keys” for encoded lists in the sequence b”0", b”1", b”2", …

The first 1000 keys are returned from a pre-built cache. All subsequent keys are generated on the fly.

bson.has_c() bool#

Is the C extension installed?

bson.is_valid(bson: bytes) bool#

Check that the given string represents valid BSON data.

Raises TypeError if bson is not an instance of bytes. Returns True if bson is valid BSON, False otherwise.

Parameters:
  • bson: the data to be validated

Sub-modules: