json_util – Tools for using Python’s json module with BSON documents

json_util – Tools for using Python’s json module with BSON documents

Tools for using Python’s json module with BSON documents.

This module provides two helper methods dumps and loads that wrap thenative json methods and provide explicit BSON conversion to and fromJSON. JSONOptions provides a way to control how JSONis emitted and parsed, with the default being the legacy PyMongo format.json_util can also generate Canonical or Relaxed Extended JSONwhen CANONICAL_JSON_OPTIONS or RELAXED_JSON_OPTIONS isprovided, respectively.

Example usage (deserialization):

>>> from bson.json_util import loads
>>> loads('[{"foo": [1, 2]}, {"bar": {"hello": "world"}}, {"code": {"$scope": {}, "$code": "function x() { return 1; }"}}, {"bin": {"$type": "80", "$binary": "AQIDBA=="}}]')
[{u'foo': [1, 2]}, {u'bar': {u'hello': u'world'}}, {u'code': Code('function x() { return 1; }', {})}, {u'bin': Binary('...', 128)}]

Example usage (serialization):

>>> from bson import Binary, Code
>>> from bson.json_util import dumps
>>> dumps([{'foo': [1, 2]},
...        {'bar': {'hello': 'world'}},
...        {'code': Code("function x() { return 1; }", {})},
...        {'bin': Binary(b"")}])
'[{"foo": [1, 2]}, {"bar": {"hello": "world"}}, {"code": {"$code": "function x() { return 1; }", "$scope": {}}}, {"bin": {"$binary": "AQIDBA==", "$type": "00"}}]'

Example usage (with CANONICAL_JSON_OPTIONS):

>>> from bson import Binary, Code
>>> from bson.json_util import dumps, CANONICAL_JSON_OPTIONS
>>> dumps([{'foo': [1, 2]},
...        {'bar': {'hello': 'world'}},
...        {'code': Code("function x() { return 1; }")},
...        {'bin': Binary(b"")}],
...       json_options=CANONICAL_JSON_OPTIONS)
'[{"foo": [{"$numberInt": "1"}, {"$numberInt": "2"}]}, {"bar": {"hello": "world"}}, {"code": {"$code": "function x() { return 1; }"}}, {"bin": {"$binary": {"base64": "AQIDBA==", "subType": "00"}}}]'

Example usage (with RELAXED_JSON_OPTIONS):

>>> from bson import Binary, Code
>>> from bson.json_util import dumps, RELAXED_JSON_OPTIONS
>>> dumps([{'foo': [1, 2]},
...        {'bar': {'hello': 'world'}},
...        {'code': Code("function x() { return 1; }")},
...        {'bin': Binary(b"")}],
...       json_options=RELAXED_JSON_OPTIONS)
'[{"foo": [1, 2]}, {"bar": {"hello": "world"}}, {"code": {"$code": "function x() { return 1; }"}}, {"bin": {"$binary": {"base64": "AQIDBA==", "subType": "00"}}}]'

Alternatively, you can manually pass the default to json.dumps().It won’t handle Binary and Codeinstances (as they are extended strings you can’t provide custom defaults),but it will be faster as there is less recursion.

Note

If your application does not need the flexibility offered byJSONOptions and spends a large amount of time in the json_util_module, look topython-bsonjs for a niceperformance improvement. _python-bsonjs is a fast BSON to MongoDBExtended JSON converter for Python built on top oflibbson. python-bsonjs works bestwith PyMongo when using RawBSONDocument.

Changed in version 2.8: The output format for Timestamp has changed from‘{“t”: <int>, “i”: <int>}’ to ‘{“$timestamp”: {“t”: <int>, “i”: <int>}}’.This new format will be decoded to an instance ofTimestamp. The old format will continue to bedecoded to a python dict as before. Encoding to the old format is no longersupported as it was never correct and loses type information.Added support for $numberLong and $undefined - new in MongoDB 2.6 - andparsing $date in ISO-8601 format.

Changed in version 2.7: Preserves order when rendering SON, Timestamp, Code, Binary, and DBRefinstances.

Changed in version 2.3: Added dumps and loads helpers to automatically handle conversion to andfrom json and supports Binary andCode

class bson.json_util.DatetimeRepresentation
- LEGACY = 0
- Legacy MongoDB Extended JSON datetime representation.

datetime.datetime instances will be encoded to JSON in theformat {“$date”: }, where dateAsMilliseconds isa 64-bit signed integer giving the number of milliseconds since the Unixepoch UTC. This was the default encoding before PyMongo version 3.4.

New in version 3.4.

NUMBERLONG = 1
NumberLong datetime representation.

datetime.datetime instances will be encoded to JSON in theformat {“$date”: {“$numberLong”: “”}},where dateAsMilliseconds is the string representation of a 64-bit signedinteger giving the number of milliseconds since the Unix epoch UTC.

New in version 3.4.

ISO8601 = 2
ISO-8601 datetime representation.

datetime.datetime instances greater than or equal to the Unixepoch UTC will be encoded to JSON in the format {“$date”: “”}.datetime.datetime instances before the Unix epoch UTC will beencoded as if the datetime representation isNUMBERLONG.

New in version 3.4.

class bson.json_util.JSONMode
- LEGACY = 0
- Legacy Extended JSON representation.

In this mode, dumps() produces PyMongo’s legacynon-standard JSON output. Consider usingRELAXED orCANONICAL instead.

New in version 3.5.

RELAXED = 1
Relaxed Extended JSON representation.

In this mode, dumps() produces Relaxed Extended JSON,a mostly JSON-like format. Consider using this for things like a web API,where one is sending a document (or a projection of a document) that onlyuses ordinary JSON type primitives. In particular, the int,Int64, and float numeric types are represented inthe native JSON number format. This output is also the most human readableand is useful for debugging and documentation.

See also

The specification for Relaxed Extended JSON.

New in version 3.5.

CANONICAL = 2
Canonical Extended JSON representation.

In this mode, dumps() produces Canonical ExtendedJSON, a type preserving format. Consider using this for things liketesting, where one has to precisely specify expected types in JSON. Inparticular, the int, Int64, and float numerictypes are encoded with type wrappers.

See also

The specification for Canonical Extended JSON.

New in version 3.5.

class bson.json_util.JSONOptions
Encapsulates JSON options for dumps() and loads().

Parameters:

strict_number_long: If True, Int64 objectsare encoded to MongoDB Extended JSON’s Strict mode typeNumberLong, ie '{"$numberLong": "<number>" }'. Otherwise theywill be encoded as an int. Defaults to False.
datetime_representation: The representation to use when encodinginstances of datetime.datetime. Defaults toLEGACY.
strict_uuid: If True, uuid.UUID object are encoded toMongoDB Extended JSON’s Strict mode type Binary. Otherwise itwill be encoded as '{"$uuid": "<hex>" }'. Defaults to False.
json_mode: The JSONMode to use when encoding BSON types toExtended JSON. Defaults to LEGACY.
document_class: BSON documents returned by loads() will bedecoded to an instance of this class. Must be a subclass ofcollections.MutableMapping. Defaults to dict.
uuid_representation: The BSON representation to use when encodingand decoding instances of uuid.UUID. Defaults toPYTHON_LEGACY.
tz_aware: If True, MongoDB Extended JSON’s Strict mode typeDate will be decoded to timezone aware instances ofdatetime.datetime. Otherwise they will be naive. Defaultsto True.
tzinfo: A datetime.tzinfo subclass that specifies thetimezone from which datetime objects should bedecoded. Defaults to utc.
args: arguments to CodecOptions
kwargs: arguments to CodecOptions

See also

The specification for Relaxed and Canonical Extended JSON.

New in version 3.4.

Changed in version 3.5: Accepts the optional parameter json_mode.

bson.jsonutil.LEGACY_JSON_OPTIONS = JSONOptions(strictnumber_long=False, datetime_representation=0, strict_uuid=False, json_mode=0, document_class=dict, tz_aware=True, uuid_representation=PYTHON_LEGACY, unicode_decode_error_handler='strict', tzinfo=, type_registry=TypeRegistry(type_codecs=[], fallback_encoder=None))
JSONOptions for encoding to PyMongo’s legacy JSON format.

See also

The documentation for bson.json_util.JSONMode.LEGACY.

New in version 3.5.

bson.jsonutil.DEFAULT_JSON_OPTIONS = JSONOptions(strictnumber_long=False, datetime_representation=0, strict_uuid=False, json_mode=0, document_class=dict, tz_aware=True, uuid_representation=PYTHON_LEGACY, unicode_decode_error_handler='strict', tzinfo=, type_registry=TypeRegistry(type_codecs=[], fallback_encoder=None))
The default JSONOptions for JSON encoding/decoding.

The same as LEGACY_JSON_OPTIONS. This will change toRELAXED_JSON_OPTIONS in a future release.

New in version 3.4.

bson.jsonutil.CANONICAL_JSON_OPTIONS = JSONOptions(strictnumber_long=True, datetime_representation=1, strict_uuid=True, json_mode=2, document_class=dict, tz_aware=True, uuid_representation=PYTHON_LEGACY, unicode_decode_error_handler='strict', tzinfo=, type_registry=TypeRegistry(type_codecs=[], fallback_encoder=None))
JSONOptions for Canonical Extended JSON.

See also

The documentation for bson.json_util.JSONMode.CANONICAL.

New in version 3.5.

bson.jsonutil.RELAXED_JSON_OPTIONS = JSONOptions(strictnumber_long=False, datetime_representation=2, strict_uuid=True, json_mode=1, document_class=dict, tz_aware=True, uuid_representation=PYTHON_LEGACY, unicode_decode_error_handler='strict', tzinfo=, type_registry=TypeRegistry(type_codecs=[], fallback_encoder=None))
JSONOptions for Relaxed Extended JSON.

See also

The documentation for bson.json_util.JSONMode.RELAXED.

New in version 3.5.

bson.jsonutil.STRICT_JSON_OPTIONS = JSONOptions(strictnumber_long=True, datetime_representation=2, strict_uuid=True, json_mode=0, document_class=dict, tz_aware=True, uuid_representation=PYTHON_LEGACY, unicode_decode_error_handler='strict', tzinfo=, type_registry=TypeRegistry(type_codecs=[], fallback_encoder=None))
DEPRECATED - JSONOptions for MongoDB Extended JSON’s Strictmode encoding.

New in version 3.4.

Changed in version 3.5: Deprecated. Use RELAXED_JSON_OPTIONS orCANONICAL_JSON_OPTIONS instead.

bson.jsonutil.dumps(_obj, *args, **kwargs)
Helper function that wraps json.dumps().

Recursive function that handles all BSON types includingBinary and Code.

Parameters:

json_options: A JSONOptions instance used to modify theencoding of MongoDB Extended JSON types. Defaults toDEFAULT_JSON_OPTIONS.

Changed in version 3.4: Accepts optional parameter json_options. See JSONOptions.

Changed in version 2.7: Preserves order when rendering SON, Timestamp, Code, Binary, and DBRefinstances.

bson.jsonutil.loads(_s, *args, **kwargs)
Helper function that wraps json.loads().

Automatically passes the object_hook for BSON type conversion.

Raises TypeError, ValueError, KeyError, orInvalidId on invalid MongoDB Extended JSON.

Parameters:

json_options: A JSONOptions instance used to modify thedecoding of MongoDB Extended JSON types. Defaults toDEFAULT_JSON_OPTIONS.

Changed in version 3.5: Parses Relaxed and Canonical Extended JSON as well as PyMongo’s legacyformat. Now raises TypeError or ValueError when parsing JSONtype wrappers with values of the wrong type or any extra keys.

Changed in version 3.4: Accepts optional parameter json_options. See JSONOptions.

bson.jsonutil.object_pairs_hook(_pairs, json_options=JSONOptions(strict_number_long=False, datetime_representation=0, strict_uuid=False, json_mode=0, document_class=dict, tz_aware=True, uuid_representation=PYTHON_LEGACY, unicode_decode_error_handler='strict', tzinfo=, type_registry=TypeRegistry(type_codecs=[], fallback_encoder=None)))
bson.jsonutil.object_hook(_dct, json_options=JSONOptions(strict_number_long=False, datetime_representation=0, strict_uuid=False, json_mode=0, document_class=dict, tz_aware=True, uuid_representation=PYTHON_LEGACY, unicode_decode_error_handler='strict', tzinfo=, type_registry=TypeRegistry(type_codecs=[], fallback_encoder=None)))
bson.jsonutil.default(_obj, json_options=JSONOptions(strict_number_long=False, datetime_representation=0, strict_uuid=False, json_mode=0, document_class=dict, tz_aware=True, uuid_representation=PYTHON_LEGACY, unicode_decode_error_handler='strict', tzinfo=, type_registry=TypeRegistry(type_codecs=[], fallback_encoder=None)))