bson – BSON (Binary JSON) Encoding and Decoding

BSON (Binary JSON) encoding and decoding.

class bson.BSON

BSON (Binary JSON) data.

decode(as_class=<type 'dict'>, tz_aware=False, uuid_subtype=3, compile_re=True, codec_options=None)

Decode this BSON data.

The default type to use for the resultant document is dict. Any other class that supports __setitem__() can be used instead by passing it as the as_class parameter.

If tz_aware is True (recommended), any datetime instances returned will be timezone-aware, with their timezone set to bson.tz_util.utc. Otherwise (default), all datetime instances will be naive (but contain UTC).

Parameters:
  • as_class (optional): the class to use for the resulting document
  • tz_aware (optional): if True, return timezone-aware datetime instances
  • uuid_subtype (optional): The BSON representation to use for UUIDs. See the bson.binary module for all options.
  • compile_re (optional): if False, don’t attempt to compile BSON regular expressions into Python regular expressions. Return instances of Regex instead. Can avoid InvalidBSON errors when receiving Python-incompatible regular expressions, for example from currentOp

Changed in version 2.7: Added compile_re option.

New in version 1.9.

classmethod encode(document, check_keys=False, uuid_subtype=3, codec_options=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
  • uuid_subtype (optional): The BSON representation to use for UUIDs. See the bson.binary module for all options.

New in version 1.9.

bson.decode_all(data, as_class=<type 'dict'>, tz_aware=True, uuid_subtype=3, compile_re=True, codec_options=None)

Decode BSON data to multiple documents.

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

Parameters:
  • data: BSON data
  • as_class (optional): the class to use for the resulting documents
  • tz_aware (optional): if True, return timezone-aware datetime instances
  • uuid_subtype (optional): The BSON representation to use for UUIDs. See the bson.binary module for all options.
  • compile_re (optional): if False, don’t attempt to compile BSON regular expressions into Python regular expressions. Return instances of Regex instead. Can avoid InvalidBSON errors when receiving Python-incompatible regular expressions, for example from currentOp

Changed in version 2.7: Added compile_re option.

New in version 1.9.

bson.decode_file_iter(file_obj, as_class=<type 'dict'>, tz_aware=True, uuid_subtype=3, compile_re=True, codec_options=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.

Parameters:
  • file_obj: A file object containing BSON data.
  • as_class (optional): the class to use for the resulting documents
  • tz_aware (optional): if True, return timezone-aware datetime instances
  • uuid_subtype (optional): The BSON representation to use for UUIDs. See the bson.binary module for all options.
  • compile_re (optional): if False, don’t attempt to compile BSON regular expressions into Python regular expressions. Return instances of Regex instead. Can avoid InvalidBSON errors when receiving Python-incompatible regular expressions, for example from currentOp

New in version 2.8.

bson.decode_iter(data, as_class=<type 'dict'>, tz_aware=True, uuid_subtype=3, compile_re=True, codec_options=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.

Parameters:
  • data: BSON data
  • as_class (optional): the class to use for the resulting documents
  • tz_aware (optional): if True, return timezone-aware datetime instances
  • uuid_subtype (optional): The BSON representation to use for UUIDs. See the bson.binary module for all options.
  • compile_re (optional): if False, don’t attempt to compile BSON regular expressions into Python regular expressions. Return instances of Regex instead. Can avoid InvalidBSON errors when receiving Python-incompatible regular expressions, for example from currentOp

New in version 2.8.

bson.has_c()

Is the C extension installed?

New in version 1.9.

bson.has_uuid()

Is the uuid module available?

New in version 2.3.

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.

Parameters:
  • bson: the data to be validated

Sub-modules:

Previous topic

API Documentation

Next topic

binary – Tools for representing binary data to be stored in MongoDB

This Page