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 the
native json
methods and provide explicit BSON conversion to and from
json. This allows for specialized encoding and decoding of BSON documents
into MongoDB Extended JSON’s Strict
mode. This lets you encode / decode BSON documents to JSON even when
they use special BSON types.
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 (deserialization):
>>> from bson.json_util import loads
>>> loads('[{"foo": [1, 2]}, {"bar": {"hello": "world"}}, {"code": {"$scope": {}, "$code": "function x() { return 1; }"}}, {"bin": {"$type": "00", "$binary": "AQIDBA=="}}]')
[{u'foo': [1, 2]}, {u'bar': {u'hello': u'world'}}, {u'code': Code('function x() { return 1; }', {})}, {u'bin': Binary('...', 0)}]
Alternatively, you can manually pass the default to json.dumps()
.
It won’t handle Binary
and Code
instances (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 by
JSONOptions
and spends a large amount of time in the json_util
module, look to
python-bsonjs for a nice
performance improvement. python-bsonjs is a fast BSON to MongoDB
Extended JSON converter for Python built on top of
libbson. python-bsonjs works best
with 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 of
Timestamp
. The old format will continue to be
decoded to a python dict as before. Encoding to the old format is no longer
supported as it was never correct and loses type information.
Added support for $numberLong and $undefined - new in MongoDB 2.6 - and
parsing $date in ISO-8601 format.
Changed in version 2.7: Preserves order when rendering SON, Timestamp, Code, Binary, and DBRef instances.
Changed in version 2.3: Added dumps and loads helpers to automatically handle conversion to and
from json and supports Binary
and
Code
-
class
bson.json_util.
DatetimeRepresentation
¶ -
LEGACY
= 0¶ Legacy MongoDB Extended JSON datetime representation.
datetime.datetime
instances will be encoded to JSON in the format {“$date”: <dateAsMilliseconds>}, where dateAsMilliseconds is a 64-bit signed integer giving the number of milliseconds since the Unix epoch 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 the format {“$date”: {“$numberLong”: “<dateAsMilliseconds>”}}, where dateAsMilliseconds is the string representation of a 64-bit signed integer 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 Unix epoch UTC will be encoded to JSON in the format {“$date”: “<ISO-8601>”}.datetime.datetime
instances before the Unix epoch UTC will be encoded as if the datetime representation isNUMBERLONG
.New in version 3.4.
-
-
class
bson.json_util.
JSONOptions
¶ Encapsulates JSON options for
dumps()
andloads()
.Raises
ConfigurationError
on Python 2.6 if simplejson is not installed and document_class is not the default (dict
).Parameters: - 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 toFalse
. - datetime_representation: The representation to use when encoding
instances of
datetime.datetime
. Defaults toLEGACY
. - 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 toFalse
. - document_class: BSON documents returned by
loads()
will be decoded to an instance of this class. Must be a subclass ofcollections.MutableMapping
. Defaults todict
. - uuid_representation: The BSON representation to use when encoding
and decoding instances of
uuid.UUID
. Defaults toPYTHON_LEGACY
. - tz_aware: If
True
, MongoDB Extended JSON’s Strict mode type Date will be decoded to timezone aware instances ofdatetime.datetime
. Otherwise they will be naive. Defaults toTrue
. - tzinfo: A
datetime.tzinfo
subclass that specifies the timezone from whichdatetime
objects should be decoded. Defaults toutc
. - args: arguments to
CodecOptions
- kwargs: arguments to
CodecOptions
See also
The documentation for MongoDB Extended JSON.
New in version 3.4.
- strict_number_long: If
-
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>)¶ The default
JSONOptions
for JSON encoding/decoding.New in version 3.4.
-
bson.json_util.
STRICT_JSON_OPTIONS
= JSONOptions(strict_number_long=True, datetime_representation=2, strict_uuid=True, document_class=dict, tz_aware=True, uuid_representation=PYTHON_LEGACY, unicode_decode_error_handler='strict', tzinfo=<bson.tz_util.FixedOffset object>)¶ JSONOptions
for MongoDB Extended JSON’s Strict mode encoding.New in version 3.4.
-
bson.json_util.
dumps
(obj, *args, **kwargs)¶ Helper function that wraps
json.dumps()
.Recursive function that handles all BSON types including
Binary
andCode
.Parameters: - json_options: A
JSONOptions
instance used to modify the encoding 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 DBRef instances.
- json_options: A
-
bson.json_util.
loads
(s, *args, **kwargs)¶ Helper function that wraps
json.loads()
.Automatically passes the object_hook for BSON type conversion.
Parameters: - json_options: A
JSONOptions
instance used to modify the decoding of MongoDB Extended JSON types. Defaults toDEFAULT_JSON_OPTIONS
.
Changed in version 3.4: Accepts optional parameter json_options. See
JSONOptions
.- json_options: A
-
bson.json_util.
object_pairs_hook
(pairs, 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>))¶
-
bson.json_util.
object_hook
(dct, 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>))¶
-
bson.json_util.
default
(obj, 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>))¶