bson – BSON (Binary JSON) Encoding and Decoding

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
long	int64	py -> bson
bson.int64.Int64	int64	both
float	number (real)	both
string	string	py -> bson
unicode	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
unicode	code	bson -> py
bson.code.Code	code	py -> bson
unicode	symbol	bson -> py
bytes (Python 3) [5]	binary	both

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

[1]	A Python int will be saved as a BSON int32 or BSON int64 dependingon its size. A BSON int32 will always decode to a Python int. A BSONint64 will always decode to a `Int64`.

[2]	datetime.datetime instances will be rounded to the nearestmillisecond when saved

[3]	all datetime.datetime instances are treated as naive. clientsshould always use UTC.

[4]	`Regex` instances and regular expressionobjects from `re.compile()` are both saved as BSON regular expressions.BSON regular expressions are decoded as `Regex`instances.

[5]	The bytes type from Python 3.x is encoded as BSON binary withsubtype 0. In Python 3.x it will be decoded back to bytes. In Python 2.xit will be decoded to an instance of `Binary` withsubtype 0.

class bson.BSON
BSON (Binary JSON) data.

Warning

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

decode(codec_options=CodecOptions(document_class=dict, tz_aware=False, uuid_representation=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 Pythondict. 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[<code>CodecOptions</code>]($f5dfe349e82ce60f.md#bson.codec_options.CodecOptions).

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

Replaced as_class, tz_aware, and uuid_subtype options withcodec_options.

Changed in version 2.7: Added compile_re option. If set to False, PyMongo represented BSONregular expressions as Regex objects instead ofattempting to compile BSON regular expressions as Python nativeregular expressions, thus preventing errors for some incompatiblepatterns, see PYTHON-500.

classmethod encode(document, check_keys=False, codec_options=CodecOptions(document_class=dict, tz_aware=False, uuid_representation=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 ofbasestring (str in python 3). RaisesInvalidDocument if document cannot beconverted to BSON.

Parameters:

- _document_: mapping type representing a document
- _check_keys_ (optional): check if keys start with ‘$’ orcontain ‘.’, raising [<code>InvalidDocument</code>]($9ad445b3e7ad20f7.md#bson.errors.InvalidDocument) ineither case
- _codec_options_ (optional): An instance of[<code>CodecOptions</code>]($f5dfe349e82ce60f.md#bson.codec_options.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=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 Pythondict. 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 implementsthe buffer protocol.
codec_options (optional): An instance ofCodecOptions.

New in version 3.9.

bson.decodeall(_data, codec_options=CodecOptions(document_class=dict, tz_aware=False, uuid_representation=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 thatprovides concatenated, valid, BSON-encoded documents.

Parameters:

data: BSON data
codec_options (optional): An instance ofCodecOptions.

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 regularexpressions as Regex objects. Usetry_compile() to attempt to convert from aBSON regular expression to a Python regular expression object.

Replaced as_class, tz_aware, and uuid_subtype options withcodec_options.

bson.decodefile_iter(_file_obj, codec_options=CodecOptions(document_class=dict, tz_aware=False, uuid_representation=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 objectin 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 ofCodecOptions.

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

New in version 2.8.

bson.decodeiter(_data, codec_options=CodecOptions(document_class=dict, tz_aware=False, uuid_representation=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 atime.

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

Parameters:

data: BSON data
codec_options (optional): An instance ofCodecOptions.

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

New in version 2.8.

bson.encode(document, check_keys=False, codec_options=CodecOptions(document_class=dict, tz_aware=False, uuid_representation=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 ofbasestring (str in python 3). RaisesInvalidDocument if document cannot beconverted to BSON.

Parameters:

document: mapping type representing a document
check_keys (optional): check if keys start with ‘$’ orcontain ‘.’, raising InvalidDocument ineither case
codec_options (optional): An instance ofCodecOptions.

New in version 3.9.

bson.gen_list_name()
Generate “keys” for encoded lists in the sequenceb”0”, b”1”, b”2”, …

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

bson.has_c()
Is the C extension installed?

bson.isvalid(_bson)
Check that the given string represents valid BSON data.

Raises TypeError if bson is not an instance ofstr (bytes in python 3). Returns Trueif bson is valid BSON, False otherwise.

Parameters:

bson: the data to be validated

Sub-modules: