bson – BSON (Binary JSON) Encoding and Decoding

BSON (Binary JSON) encoding and decoding.

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

Note that, when using Python 2.x, to save binary data it must be wrapped as an instance of bson.binary.Binary. Otherwise it will be saved as a BSON string and retrieved as unicode. Users of Python 3.x can use the Python bytes type.

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(document_class=dict, tz_aware=False, uuid_representation=UuidRepresentation.PYTHON_LEGACY, unicode_decode_error_handler=’strict’, tzinfo=None, type_registry=TypeRegistry(type_codecs=[], fallback_encoder=None)))

  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:	codec_options (optional): An instance of CodecOptions.

  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.

  Changed in version 2.7: Added compile_re option. If set to False, PyMongo represented BSON regular expressions as Regex objects instead of attempting to compile BSON regular expressions as Python native regular expressions, thus preventing errors for some incompatible patterns, see PYTHON-500.

• classmethod encode(document, check_keys=False, codec_options=CodecOptions(document_class=dict, tz_aware=False, uuid_representation=UuidRepresentation.PYTHON_LEGACY, unicode_decode_error_handler=’strict’, tzinfo=None, type_registry=TypeRegistry(type_codecs=[], fallback_encoder=None)))

  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, codec_options=CodecOptions(document_class=dict, tz_aware=False, uuid_representation=UuidRepresentation.PYTHON_LEGACY, unicode_decode_error_handler=’strict’, tzinfo=None, type_registry=TypeRegistry(type_codecs=[], fallback_encoder=None)))

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

New in version 3.9.

bson.decode_all(data, codec_options=CodecOptions(document_class=dict, tz_aware=False, uuid_representation=UuidRepresentation.PYTHON_LEGACY, unicode_decode_error_handler=’strict’, tzinfo=None, type_registry=TypeRegistry(type_codecs=[], fallback_encoder=None)))

Decode BSON data to multiple documents.

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

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.

Changed in version 2.7: Added compile_re option. If set to False, PyMongo represented BSON regular expressions as Regex objects instead of attempting to compile BSON regular expressions as Python native regular expressions, thus preventing errors for some incompatible patterns, see PYTHON-500.

bson.decode_file_iter(file_obj, codec_options=CodecOptions(document_class=dict, tz_aware=False, uuid_representation=UuidRepresentation.PYTHON_LEGACY, unicode_decode_error_handler=’strict’, tzinfo=None, type_registry=TypeRegistry(type_codecs=[], fallback_encoder=None)))

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.

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, codec_options=CodecOptions(document_class=dict, tz_aware=False, uuid_representation=UuidRepresentation.PYTHON_LEGACY, unicode_decode_error_handler=’strict’, tzinfo=None, type_registry=TypeRegistry(type_codecs=[], fallback_encoder=None)))

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.

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, check_keys=False, codec_options=CodecOptions(document_class=dict, tz_aware=False, uuid_representation=UuidRepresentation.PYTHON_LEGACY, unicode_decode_error_handler=’strict’, tzinfo=None, type_registry=TypeRegistry(type_codecs=[], fallback_encoder=None)))

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.

New in version 3.9.

bson.gen_list_name()

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()

Is the C extension installed?

bson.is_valid(bson)

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.

Sub-modules:

• binary – Tools for representing binary data to be stored in MongoDB
• code – Tools for representing JavaScript code
• codec_options – Tools for specifying BSON codec options
• dbref – Tools for manipulating DBRefs (references to documents stored in MongoDB)
• decimal128 – Support for BSON Decimal128
• errors – Exceptions raised by the bson package
• int64 – Tools for representing BSON int64
• json_util – Tools for using Python’s json module with BSON documents
• max_key – Representation for the MongoDB internal MaxKey type
• min_key – Representation for the MongoDB internal MinKey type
• objectid – Tools for working with MongoDB ObjectIds
• raw_bson – Tools for representing raw BSON documents.
  • Inserting and Retrieving RawBSONDocuments
• regex – Tools for representing MongoDB regular expressions
• son – Tools for working with SON, an ordered mapping
• timestamp – Tools for representing MongoDB internal Timestamps
• tz_util – Utilities for dealing with timezones in Python