binary – Tools for representing binary data to be stored in MongoDB
This is the default subtype for binary data.
This is the old default subtype, the currentdefault is BINARY_SUBTYPE
.
uuid.UUID
instances will automatically be encodedby bson
using this subtype.
New in version 2.1.
This is the new BSON binary subtype for UUIDs. Thecurrent default is OLD_UUID_SUBTYPE
.
Changed in version 2.1: Changed to subtype 4.
uuid.UUID
instances will automatically be encoded toand decoded from BSON binary, using RFC-4122 byte order withbinary subtype UUID_SUBTYPE
.
New in version 3.0.
uuid.UUID
instances will automatically be encoded toand decoded from BSON binary, using RFC-4122 byte order withbinary subtype OLD_UUID_SUBTYPE
.
New in version 3.0.
uuid.UUID
instances will automatically be encoded toand decoded from BSON binary subtype OLD_UUID_SUBTYPE
,using the Java driver’s legacy byte order.
Changed in version 3.6: BSON binary subtype 4 is decoded using RFC-4122 byte order.
New in version 2.3.
uuid.UUID
instances will automatically be encoded toand decoded from BSON binary subtype OLD_UUID_SUBTYPE
,using the C# driver’s legacy byte order.
Changed in version 3.6: BSON binary subtype 4 is decoded using RFC-4122 byte order.
New in version 2.3.
- class
bson.binary.
Binary
(data, subtype=BINARY_SUBTYPE) - Bases:
str
Representation of BSON binary data.
This is necessary because we want to represent Python strings asthe BSON string type. We need to wrap binary data so we can tellthe difference between what should be considered binary data andwhat should be considered a string when we encode to BSON.
Raises TypeError if data is not an instance of bytes
(str
in python 2) or subtype is not an instance ofint
. Raises ValueError if subtype is not in [0, 256).
Note
In python 3 instances of Binary with subtype 0 will be decodeddirectly to bytes
.
Parameters:
- data: the binary data to represent. Can be any bytes-like typethat implements the buffer protocol.
- subtype (optional): the binary subtypeto use
Changed in version 3.9: Support any bytes-like type that implements the buffer protocol.
- class
bson.binary.
UUIDLegacy
(obj) - Bases:
bson.binary.Binary
UUID wrapper to support working with UUIDs stored as PYTHON_LEGACY.
- >>> import uuid
- >>> from bson.binary import Binary, UUIDLegacy, STANDARD
- >>> from bson.codec_options import CodecOptions
- >>> my_uuid = uuid.uuid4()
- >>> coll = db.get_collection('test',
- ... CodecOptions(uuid_representation=STANDARD))
- >>> coll.insert_one({'uuid': Binary(my_uuid.bytes, 3)}).inserted_id
- ObjectId('...')
- >>> coll.count_documents({'uuid': my_uuid})
- 0
- >>> coll.count_documents({'uuid': UUIDLegacy(my_uuid)})
- 1
- >>> coll.find({'uuid': UUIDLegacy(my_uuid)})[0]['uuid']
- UUID('...')
- >>>
- >>> # Convert from subtype 3 to subtype 4
- >>> doc = coll.find_one({'uuid': UUIDLegacy(my_uuid)})
- >>> coll.replace_one({"_id": doc["_id"]}, doc).matched_count
- 1
- >>> coll.count_documents({'uuid': UUIDLegacy(my_uuid)})
- 0
- >>> coll.count_documents({'uuid': {'$in': [UUIDLegacy(my_uuid), my_uuid]}})
- 1
- >>> coll.find_one({'uuid': my_uuid})['uuid']
- UUID('...')
Raises TypeError if obj is not an instance of UUID
.
Parameters:
- obj: An instance of
UUID
.