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. JSONOptions
provides a way to control how JSON
is emitted and parsed, with the default being the legacy PyMongo format.
json_util
can also generate Canonical or Relaxed Extended JSON
when CANONICAL_JSON_OPTIONS
or RELAXED_JSON_OPTIONS
is
provided, 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 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.
JSONMode
¶ -
LEGACY
= 0¶ Legacy Extended JSON representation.
In this mode,
dumps()
produces PyMongo’s legacy non-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 only uses ordinary JSON type primitives. In particular, theint
,Int64
, andfloat
numeric types are represented in the native JSON number format. This output is also the most human readable and 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 Extended JSON, a type preserving format. Consider using this for things like testing, where one has to precisely specify expected types in JSON. In particular, theint
,Int64
, andfloat
numeric types 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()
andloads()
.Raises
ConfigurationError
on Python 2.6 if simplejson >= 2.1.0 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
. - json_mode: The
JSONMode
to use when encoding BSON types to Extended JSON. Defaults toLEGACY
. - 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 specification for Relaxed and Canonical Extended JSON.
New in version 3.4.
Changed in version 3.5: Accepts the optional parameter json_mode.
- strict_number_long: If
-
bson.json_util.
LEGACY_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=<bson.tz_util.FixedOffset object>)¶ 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.json_util.
DEFAULT_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=<bson.tz_util.FixedOffset object>)¶ 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.json_util.
CANONICAL_JSON_OPTIONS
= JSONOptions(strict_number_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=<bson.tz_util.FixedOffset object>)¶ JSONOptions
for Canonical Extended JSON.See also
The documentation for
bson.json_util.JSONMode.CANONICAL
.New in version 3.5.
-
bson.json_util.
RELAXED_JSON_OPTIONS
= JSONOptions(strict_number_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=<bson.tz_util.FixedOffset object>)¶ JSONOptions
for Relaxed Extended JSON.See also
The documentation for
bson.json_util.JSONMode.RELAXED
.New in version 3.5.
-
bson.json_util.
STRICT_JSON_OPTIONS
= JSONOptions(strict_number_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=<bson.tz_util.FixedOffset object>)¶ DEPRECATED -
JSONOptions
for MongoDB Extended JSON’s Strict mode encoding.New in version 3.4.
Changed in version 3.5: Deprecated. Use
RELAXED_JSON_OPTIONS
orCANONICAL_JSON_OPTIONS
instead.
-
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.
Raises
TypeError
,ValueError
,KeyError
, orInvalidId
on invalid MongoDB Extended JSON.Parameters: - json_options: A
JSONOptions
instance used to modify the decoding 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 legacy format. Now raises
TypeError
orValueError
when parsing JSON type wrappers with values of the wrong type or any extra keys.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, json_mode=0, 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, json_mode=0, 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, json_mode=0, document_class=dict, tz_aware=True, uuid_representation=PYTHON_LEGACY, unicode_decode_error_handler=’strict’, tzinfo=<bson.tz_util.FixedOffset object>))¶