binary – Tools for representing binary data to be stored in MongoDB

BSON binary subtype for binary data.

This is the default subtype for binary data.

bson.binary.``FUNCTION_SUBTYPE = 1

BSON binary subtype for functions.

bson.binary.``OLD_BINARY_SUBTYPE = 2

Old BSON binary subtype for binary data.

This is the old default subtype, the current default is BINARY_SUBTYPE.

bson.binary.``OLD_UUID_SUBTYPE = 3

Old BSON binary subtype for a UUID.

instances will automatically be encoded by bson using this subtype.

New in version 2.1.

bson.binary.``UUID_SUBTYPE = 4

BSON binary subtype for a UUID.

This is the new BSON binary subtype for UUIDs. The current default is .

Changed in version 2.1: Changed to subtype 4.

bson.binary.``STANDARD = 4

An alias for UuidRepresentation.STANDARD.

New in version 3.0.

bson.binary.``PYTHON_LEGACY = 3

An alias for .

New in version 3.0.

bson.binary.``JAVA_LEGACY = 5

An alias for UuidRepresentation.JAVA_LEGACY.

Changed in version 3.6: BSON binary subtype 4 is decoded using RFC-4122 byte order.

New in version 2.3.

bson.binary.``CSHARP_LEGACY = 6

An alias for .

Changed in version 3.6: BSON binary subtype 4 is decoded using RFC-4122 byte order.

New in version 2.3.

BSON binary subtype for an MD5 hash.

bson.binary.``USER_DEFINED_SUBTYPE = 128

BSON binary subtype for any user defined structure.

class bson.binary.``UuidRepresentation

• CSHARP_LEGACY = 6

  The C#/.net legacy UUID representation.

  uuid.UUID instances will automatically be encoded to and decoded from BSON binary subtype , using the C# driver’s legacy byte order.

  See CSHARP_LEGACY for details.

  New in version 3.11.

• JAVA_LEGACY = 5

  The Java legacy UUID representation.

  instances will automatically be encoded to and decoded from BSON binary subtype OLD_UUID_SUBTYPE, using the Java driver’s legacy byte order.

  See for details.

  New in version 3.11.

• PYTHON_LEGACY = 3

  The Python legacy UUID representation.

  uuid.UUID instances will automatically be encoded to and decoded from BSON binary, using RFC-4122 byte order with binary subtype .

  See PYTHON_LEGACY for details.

  New in version 3.11.

• STANDARD = 4

  The standard UUID representation.

  instances will automatically be encoded to and decoded from BSON binary, using RFC-4122 byte order with binary subtype UUID_SUBTYPE.

  See for details.

  New in version 3.11.

• UNSPECIFIED = 0

  An unspecified UUID representation.

  When configured, instances will not be automatically encoded to or decoded from . When encoding a uuid.UUID instance, an error will be raised. To encode a instance with this configuration, it must be wrapped in the Binary class by the application code. When decoding a BSON binary field with a UUID subtype, a instance will be returned instead of a uuid.UUID instance.

  See for details.

  New in version 3.11.

Bases: bytes

Representation of BSON binary data.

This is necessary because we want to represent Python strings as the BSON string type. We need to wrap binary data so we can tell the difference between what should be considered binary data and what should be considered a string when we encode to BSON.

Raises TypeError if data is not an instance of (str in python 2) or subtype is not an instance of . Raises ValueError if subtype is not in [0, 256).

Note

In python 3 instances of Binary with subtype 0 will be decoded directly to bytes.

Changed in version 3.9: Support any bytes-like type that implements the buffer protocol.

• as_uuid(uuid_representation=4)

  Create a Python UUID from this BSON Binary object.

  Decodes this binary object as a native instance with the provided uuid_representation.

  Raises ValueError if this instance does not contain a UUID.

  New in version 3.11.

• classmethod from_uuid(uuid, uuid_representation=4)

  Create a BSON Binary object from a Python UUID.

  Creates a Binary object from a instance. Assumes that the native uuid.UUID instance uses the byte-order implied by the provided uuid_representation.

  Raises if uuid is not an instance of UUID.

  New in version 3.11.

• subtype

  Subtype of this binary data.

class bson.binary.``UUIDLegacy(obj)

Bases:

DEPRECATED - UUID wrapper to support working with UUIDs stored as PYTHON_LEGACY.

Note

This class has been deprecated and will be removed in PyMongo 4.0. Use from_uuid() and with the appropriate to handle legacy-formatted UUIDs instead.:

>>> 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
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 if obj is not an instance of UUID.

Changed in version 3.11: Deprecated. The same functionality can be replicated using the and to_uuid() methods with PYTHON_LEGACY.

New in version 2.1.

• uuid

  UUID instance wrapped by this UUIDLegacy instance.

Previous topic

Next topic

Quick search