binary – Tools for representing binary data to be stored in MongoDB — PyMongo 2.7.2 documentation

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

`bson.binary.` `BINARY_SUBTYPE` = 0

  BSON binary subtype for binary data.

  This is the default subtype for binary data.

  New in version 1.5.

`bson.binary.` `FUNCTION_SUBTYPE` = 1

  BSON binary subtype for functions.

  New in version 1.5.

`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`.

  New in version 1.7.

`bson.binary.` `OLD_UUID_SUBTYPE` = 3

  Old BSON binary subtype for a UUID.

  `uuid.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 `OLD_UUID_SUBTYPE` but will change to this in a future release.

  Changed in version 2.1: Changed to subtype 4.

  New in version 1.5.

`bson.binary.` `JAVA_LEGACY` = 5

  Used with `pymongo.collection.Collection.uuid_subtype` to specify that UUIDs should be stored in the legacy byte order used by the Java driver.

  `uuid.UUID` instances will automatically be encoded by `bson` using `OLD_UUID_SUBTYPE`.

  New in version 2.3.

`bson.binary.` `CSHARP_LEGACY` = 6

  Used with `pymongo.collection.Collection.uuid_subtype` to specify that UUIDs should be stored in the legacy byte order used by the C# driver.

  `uuid.UUID` instances will automatically be encoded by `bson` using `OLD_UUID_SUBTYPE`.

  New in version 2.3.

`bson.binary.` `MD5_SUBTYPE` = 5

  BSON binary subtype for an MD5 hash.

  New in version 1.5.

`bson.binary.` `USER_DEFINED_SUBTYPE` = 128

  BSON binary subtype for any user defined structure.

  New in version 1.5.

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 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` (`bytes` in python 3) or subtype is not an instance of `int`. 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`.

  Parameters: | data: the binary data to represent subtype (optional): the binary subtype to use

  `subtype`

    Subtype of this binary data.

class `bson.binary.` `UUIDLegacy`(obj)

  Bases: `bson.binary.Binary`

  UUID wrapper to support working with UUIDs stored as legacy BSON binary subtype 3.

      >>> import uuid
      >>> from bson.binary import Binary, UUIDLegacy, UUID_SUBTYPE
      >>> my_uuid = uuid.uuid4()
      >>> coll = db.test
      >>> coll.uuid_subtype = UUID_SUBTYPE
      >>> coll.insert({'uuid': Binary(my_uuid.bytes, 3)})
      ObjectId('...')
      >>> coll.find({'uuid': my_uuid}).count()
      0
      >>> coll.find({'uuid': UUIDLegacy(my_uuid)}).count()
      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.save(doc)
      ObjectId('...')
      >>> coll.find({'uuid': UUIDLegacy(my_uuid)}).count()
      0
      >>> coll.find({'uuid': {'$in': [UUIDLegacy(my_uuid), my_uuid]}}).count()
      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`.

  `uuid`

    UUID instance wrapped by this UUIDLegacy instance.