Class Binary

bson/binary.py:273–665

Representation of BSON binary data. We want to represent Python strings as the BSON string type. We need to wrap binary data so that we can tell the difference between what should be considered binary data and what should be considered a string when we encode to BSON. Subtype 9

class Binary(bytes):
    """Representation of BSON binary data.

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

    Subtype 9 provides a space-efficient representation of 1-dimensional vector data.
    Its data is prepended with two bytes of metadata.
    The first (dtype) describes its data type, such as float32 or int8.
    The second (padding) prescribes the number of bits to ignore in the final byte.
    This is relevant when the element size of the dtype is not a multiple of 8.

    Raises TypeError if `subtype` is not an instance of :class:`int`.
    Raises ValueError if `subtype` is not in [0, 256).

    .. note::
      Instances of Binary with subtype 0 will be decoded directly to :class:`bytes`.

    :param data: the binary data to represent. Can be any bytes-like type
        that implements the buffer protocol.
    :param subtype: the `binary subtype
        <https://bsonspec.org/spec.html>`_
        to use

    .. versionchanged:: 3.9
       Support any bytes-like type that implements the buffer protocol.

    .. versionchanged:: 4.10
       Addition of vector subtype.
    """

    _type_marker = 5
    __subtype: int

    def __new__(
        cls: Type[Binary],
        data: Union[memoryview, bytes, bytearray, _mmap, _array[Any]],
        subtype: int = BINARY_SUBTYPE,
    ) -> Binary:
        if not isinstance(subtype, int):
            raise TypeError(f"subtype must be an instance of int, not {type(subtype)}")
        if subtype >= 256 or subtype < 0:
            raise ValueError("subtype must be contained in [0, 256)")
        # Support any type that implements the buffer protocol.
        self = bytes.__new__(cls, memoryview(data).tobytes())
        self.__subtype = subtype
        return self

    @classmethod
    def from_uuid(
        cls: Type[Binary], uuid: UUID, uuid_representation: int = UuidRepresentation.STANDARD
    ) -> Binary:
        """Create a BSON Binary object from a Python UUID.

        Creates a :class:`~bson.binary.Binary` object from a
        :class:`uuid.UUID` instance. Assumes that the native