PyMongo Converting between BSON and JSON Using json_util

Example

json_util provides two helper methods, dumps and loads, that wrap the native json methods and provide explicit BSON conversion to and from json.

Simple usage

from bson.json_util import loads, dumps
record = db.movies.find_one()
json_str = dumps(record)
record2 = loads(json_str)

if record is:

{ 
    "_id" : ObjectId("5692a15524de1e0ce2dfcfa3"), 
    "title" : "Toy Story 4", 
    "released" : ISODate("2010-06-18T04:00:00Z") 
}

then json_str becomes:

{
    "_id": {"$oid": "5692a15524de1e0ce2dfcfa3"},
    "title" : "Toy Story 4", 
    "released": {"$date": 1276833600000}
}

JSONOptions

It is possible to customize the behavior of dumps via a JSONOptions object. Two sets of options are already available: DEFAULT_JSON_OPTIONS and STRICT_JSON_OPTIONS.

>>> bson.json_util.DEFAULT_JSON_OPTIONS
    JSONOptions(strict_number_long=False, datetime_representation=0,
     strict_uuid=False, document_class=dict, tz_aware=True, 
     uuid_representation=PYTHON_LEGACY, unicode_decode_error_handler='strict',
     tzinfo=<bson.tz_util.FixedOffset object at 0x7fc168a773d0>) 

To use different options, you can:

1. modify the DEFAULT_JSON_OPTIONS object. In this case, the options will be used for all subsequent call to dumps:

    from bson.json_util import DEFAULT_JSON_OPTIONS
    DEFAULT_JSON_OPTIONS.datetime_representation = 2
    dumps(record)
   

2. specify a JSONOptions in a call to dumps using the json_options parameter:

    # using strict
    dumps(record, json_options=bson.json_util.STRICT_JSON_OPTIONS)
   
    # using a custom set of options
    from bson.json_util import JSONOptions
    options = JSONOptions() # options is a copy of DEFAULT_JSON_OPTIONS
    options.datetime_representation=2
    dumps(record, json_options=options)
   

The parameters of JSONOptions are:

• strict_number_long: If true, Int64 objects are encoded to MongoDB Extended JSON’s Strict mode type NumberLong, ie {"$numberLong": "<number>" }. Otherwise they will be encoded as an int. Defaults to False.
• datetime_representation: The representation to use when encoding instances of datetime.datetime. 0 => {"$date": <dateAsMilliseconds>}, 1 => {"$date": {"$numberLong": "<dateAsMilliseconds>"}}, 2 => {"$date": "<ISO-8601>"}
• strict_uuid: If true, uuid.UUID object are encoded to MongoDB Extended JSON’s Strict mode type Binary. Otherwise it will be encoded as {"$uuid": "<hex>" }. Defaults to False.
• document_class: BSON documents returned by loads() will be decoded to an instance of this class. Must be a subclass of collections.MutableMapping. Defaults to dict.
• uuid_representation: The BSON representation to use when encoding and decoding instances of uuid.UUID. Defaults to PYTHON_LEGACY.
• tz_aware: If true, MongoDB Extended JSON’s Strict mode type Date will be decoded to timezone aware instances of datetime.datetime. Otherwise they will be naive. Defaults to True.
• tzinfo: A datetime.tzinfo subclass that specifies the timezone from which datetime objects should be decoded. Defaults to utc.