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

1

A Python int will be saved as a BSON int32 or BSON int64 depending on its size. A BSON int32 will always decode to a Python int. A BSON int64 will always decode to a Int64.

2

datetime.datetime instances will be rounded to the nearest millisecond when saved

3

all datetime.datetime instances are treated as naive. clients should always use UTC.

4

Regex instances and regular expression objects from re.compile() are both saved as BSON regular expressions. BSON regular expressions are decoded as Regex instances.

5

The bytes type is encoded as BSON binary with subtype 0. It will be decoded back to bytes.

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: bson.codec_options.CodecOptions = 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))) bson.codec_options._DocumentType

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: bson.codec_options.CodecOptions = 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))) bson.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 basestring (str in python 3). 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.

Changed in version 3.0: Replaced uuid_subtype option with codec_options.

bson.decode(data: Union[bytes, memoryview, mmap, array], codec_options: Optional[CodecOptions[_DocumentType]] = None) bson.codec_options._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: Union[bytes, memoryview, mmap, array], codec_options: Optional[CodecOptions[_DocumentType]] = None) List[bson.codec_options._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: Union[BinaryIO, IO], codec_options: Optional[CodecOptions[_DocumentType]] = None) Iterator[bson.codec_options._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: Optional[CodecOptions[_DocumentType]] = None) Iterator[bson.codec_options._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: bson.codec_options.CodecOptions = 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))) 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 basestring (str in python 3). 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 str (bytes in python 3). Returns True if bson is valid BSON, False otherwise.

Parameters
  • bson: the data to be validated

Sub-modules: