xtquant.xtbson.bson36.binary

  1# Copyright 2009-present MongoDB, Inc.
  2#
  3# Licensed under the Apache License, Version 2.0 (the "License");
  4# you may not use this file except in compliance with the License.
  5# You may obtain a copy of the License at
  6#
  7# http://www.apache.org/licenses/LICENSE-2.0
  8#
  9# Unless required by applicable law or agreed to in writing, software
 10# distributed under the License is distributed on an "AS IS" BASIS,
 11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 12# See the License for the specific language governing permissions and
 13# limitations under the License.
 14
 15from uuid import UUID
 16from warnings import warn
 17
 18"""Tools for representing BSON binary data.
 19"""
 20
 21BINARY_SUBTYPE = 0
 22"""BSON binary subtype for binary data.
 23
 24This is the default subtype for binary data.
 25"""
 26
 27FUNCTION_SUBTYPE = 1
 28"""BSON binary subtype for functions.
 29"""
 30
 31OLD_BINARY_SUBTYPE = 2
 32"""Old BSON binary subtype for binary data.
 33
 34This is the old default subtype, the current
 35default is :data:`BINARY_SUBTYPE`.
 36"""
 37
 38OLD_UUID_SUBTYPE = 3
 39"""Old BSON binary subtype for a UUID.
 40
 41:class:`uuid.UUID` instances will automatically be encoded
 42by :mod:`bson` using this subtype when using
 43:data:`UuidRepresentation.PYTHON_LEGACY`,
 44:data:`UuidRepresentation.JAVA_LEGACY`, or
 45:data:`UuidRepresentation.CSHARP_LEGACY`.
 46
 47.. versionadded:: 2.1
 48"""
 49
 50UUID_SUBTYPE = 4
 51"""BSON binary subtype for a UUID.
 52
 53This is the standard BSON binary subtype for UUIDs.
 54:class:`uuid.UUID` instances will automatically be encoded
 55by :mod:`bson` using this subtype when using
 56:data:`UuidRepresentation.STANDARD`.
 57"""
 58
 59
 60class UuidRepresentation:
 61    UNSPECIFIED = 0
 62    """An unspecified UUID representation.
 63
 64    When configured, :class:`uuid.UUID` instances will **not** be
 65    automatically encoded to or decoded from :class:`~bson.binary.Binary`.
 66    When encoding a :class:`uuid.UUID` instance, an error will be raised.
 67    To encode a :class:`uuid.UUID` instance with this configuration, it must
 68    be wrapped in the :class:`~bson.binary.Binary` class by the application
 69    code. When decoding a BSON binary field with a UUID subtype, a
 70    :class:`~bson.binary.Binary` instance will be returned instead of a
 71    :class:`uuid.UUID` instance.
 72
 73    See :ref:`unspecified-representation-details` for details.
 74
 75    .. versionadded:: 3.11
 76    """
 77
 78    STANDARD = UUID_SUBTYPE
 79    """The standard UUID representation.
 80
 81    :class:`uuid.UUID` instances will automatically be encoded to
 82    and decoded from . binary, using RFC-4122 byte order with
 83    binary subtype :data:`UUID_SUBTYPE`.
 84
 85    See :ref:`standard-representation-details` for details.
 86
 87    .. versionadded:: 3.11
 88    """
 89
 90    PYTHON_LEGACY = OLD_UUID_SUBTYPE
 91    """The Python legacy UUID representation.
 92
 93    :class:`uuid.UUID` instances will automatically be encoded to
 94    and decoded from . binary, using RFC-4122 byte order with
 95    binary subtype :data:`OLD_UUID_SUBTYPE`.
 96
 97    See :ref:`python-legacy-representation-details` for details.
 98
 99    .. versionadded:: 3.11
100    """
101
102    JAVA_LEGACY = 5
103    """The Java legacy UUID representation.
104
105    :class:`uuid.UUID` instances will automatically be encoded to
106    and decoded from . binary subtype :data:`OLD_UUID_SUBTYPE`,
107    using the Java driver's legacy byte order.
108
109    See :ref:`java-legacy-representation-details` for details.
110
111    .. versionadded:: 3.11
112    """
113
114    CSHARP_LEGACY = 6
115    """The C#/.net legacy UUID representation.
116
117    :class:`uuid.UUID` instances will automatically be encoded to
118    and decoded from . binary subtype :data:`OLD_UUID_SUBTYPE`,
119    using the C# driver's legacy byte order.
120
121    See :ref:`csharp-legacy-representation-details` for details.
122
123    .. versionadded:: 3.11
124    """
125
126
127STANDARD = UuidRepresentation.STANDARD
128"""An alias for :data:`UuidRepresentation.STANDARD`.
129
130.. versionadded:: 3.0
131"""
132
133PYTHON_LEGACY = UuidRepresentation.PYTHON_LEGACY
134"""An alias for :data:`UuidRepresentation.PYTHON_LEGACY`.
135
136.. versionadded:: 3.0
137"""
138
139JAVA_LEGACY = UuidRepresentation.JAVA_LEGACY
140"""An alias for :data:`UuidRepresentation.JAVA_LEGACY`.
141
142.. versionchanged:: 3.6
143   BSON binary subtype 4 is decoded using RFC-4122 byte order.
144.. versionadded:: 2.3
145"""
146
147CSHARP_LEGACY = UuidRepresentation.CSHARP_LEGACY
148"""An alias for :data:`UuidRepresentation.CSHARP_LEGACY`.
149
150.. versionchanged:: 3.6
151   BSON binary subtype 4 is decoded using RFC-4122 byte order.
152.. versionadded:: 2.3
153"""
154
155ALL_UUID_SUBTYPES = (OLD_UUID_SUBTYPE, UUID_SUBTYPE)
156ALL_UUID_REPRESENTATIONS = (
157    UuidRepresentation.UNSPECIFIED,
158    UuidRepresentation.STANDARD,
159    UuidRepresentation.PYTHON_LEGACY,
160    UuidRepresentation.JAVA_LEGACY,
161    UuidRepresentation.CSHARP_LEGACY,
162)
163UUID_REPRESENTATION_NAMES = {
164    UuidRepresentation.UNSPECIFIED: "UuidRepresentation.UNSPECIFIED",
165    UuidRepresentation.STANDARD: "UuidRepresentation.STANDARD",
166    UuidRepresentation.PYTHON_LEGACY: "UuidRepresentation.PYTHON_LEGACY",
167    UuidRepresentation.JAVA_LEGACY: "UuidRepresentation.JAVA_LEGACY",
168    UuidRepresentation.CSHARP_LEGACY: "UuidRepresentation.CSHARP_LEGACY",
169}
170
171MD5_SUBTYPE = 5
172"""BSON binary subtype for an MD5 hash.
173"""
174
175COLUMN_SUBTYPE = 7
176"""BSON binary subtype for columns.
177
178.. versionadded:: 4.0
179"""
180
181USER_DEFINED_SUBTYPE = 128
182"""BSON binary subtype for any user defined structure.
183"""
184
185
186class Binary(bytes):
187    """Representation of BSON binary data.
188
189    This is necessary because we want to represent Python strings as
190    the BSON string type. We need to wrap binary data so we can tell
191    the difference between what should be considered binary data and
192    what should be considered a string when we encode to BSON.
193
194    Raises TypeError if `data` is not an instance of :class:`bytes`
195    (:class:`str` in python 2) or `subtype` is not an instance of
196    :class:`int`. Raises ValueError if `subtype` is not in [0, 256).
197
198    .. note::
199      In python 3 instances of Binary with subtype 0 will be decoded
200      directly to :class:`bytes`.
201
202    :Parameters:
203      - `data`: the binary data to represent. Can be any bytes-like type
204        that implements the buffer protocol.
205      - `subtype` (optional): the `binary subtype
206        <http://bsonspec.org/#/specification>`_
207        to use
208
209    .. versionchanged:: 3.9
210      Support any bytes-like type that implements the buffer protocol.
211    """
212
213    _type_marker = 5
214
215    def __new__(cls, data, subtype=BINARY_SUBTYPE):
216        if not isinstance(subtype, int):
217            raise TypeError("subtype must be an instance of int")
218        if subtype >= 256 or subtype < 0:
219            raise ValueError("subtype must be contained in [0, 256)")
220        # Support any type that implements the buffer protocol.
221        self = bytes.__new__(cls, memoryview(data).tobytes())
222        self.__subtype = subtype
223        return self
224
225    @classmethod
226    def from_uuid(cls, uuid, uuid_representation=UuidRepresentation.STANDARD):
227        """Create a BSON Binary object from a Python UUID.
228
229        Creates a :class:`~bson.binary.Binary` object from a
230        :class:`uuid.UUID` instance. Assumes that the native
231        :class:`uuid.UUID` instance uses the byte-order implied by the
232        provided ``uuid_representation``.
233
234        Raises :exc:`TypeError` if `uuid` is not an instance of
235        :class:`~uuid.UUID`.
236
237        :Parameters:
238          - `uuid`: A :class:`uuid.UUID` instance.
239          - `uuid_representation`: A member of
240            :class:`~bson.binary.UuidRepresentation`. Default:
241            :const:`~bson.binary.UuidRepresentation.STANDARD`.
242            See :ref:`handling-uuid-data-example` for details.
243
244        .. versionadded:: 3.11
245        """
246        if not isinstance(uuid, UUID):
247            raise TypeError("uuid must be an instance of uuid.UUID")
248
249        if uuid_representation not in ALL_UUID_REPRESENTATIONS:
250            raise ValueError(
251                "uuid_representation must be a value " "from .binary.UuidRepresentation"
252            )
253
254        if uuid_representation == UuidRepresentation.UNSPECIFIED:
255            raise ValueError(
256                "cannot encode native uuid.UUID with "
257                "UuidRepresentation.UNSPECIFIED. UUIDs can be manually "
258                "converted to bson.Binary instances using "
259                "bson.Binary.from_uuid() or a different UuidRepresentation "
260                "can be configured. See the documentation for "
261                "UuidRepresentation for more information."
262            )
263
264        subtype = OLD_UUID_SUBTYPE
265        if uuid_representation == UuidRepresentation.PYTHON_LEGACY:
266            payload = uuid.bytes
267        elif uuid_representation == UuidRepresentation.JAVA_LEGACY:
268            from_uuid = uuid.bytes
269            payload = from_uuid[0:8][::-1] + from_uuid[8:16][::-1]
270        elif uuid_representation == UuidRepresentation.CSHARP_LEGACY:
271            payload = uuid.bytes_le
272        else:
273            # uuid_representation == UuidRepresentation.STANDARD
274            subtype = UUID_SUBTYPE
275            payload = uuid.bytes
276
277        return cls(payload, subtype)
278
279    def as_uuid(self, uuid_representation=UuidRepresentation.STANDARD):
280        """Create a Python UUID from this BSON Binary object.
281
282        Decodes this binary object as a native :class:`uuid.UUID` instance
283        with the provided ``uuid_representation``.
284
285        Raises :exc:`ValueError` if this :class:`~bson.binary.Binary` instance
286        does not contain a UUID.
287
288        :Parameters:
289          - `uuid_representation`: A member of
290            :class:`~bson.binary.UuidRepresentation`. Default:
291            :const:`~bson.binary.UuidRepresentation.STANDARD`.
292            See :ref:`handling-uuid-data-example` for details.
293
294        .. versionadded:: 3.11
295        """
296        if self.subtype not in ALL_UUID_SUBTYPES:
297            raise ValueError("cannot decode subtype %s as a uuid" % (self.subtype,))
298
299        if uuid_representation not in ALL_UUID_REPRESENTATIONS:
300            raise ValueError(
301                "uuid_representation must be a value from " "bson.binary.UuidRepresentation"
302            )
303
304        if uuid_representation == UuidRepresentation.UNSPECIFIED:
305            raise ValueError("uuid_representation cannot be UNSPECIFIED")
306        elif uuid_representation == UuidRepresentation.PYTHON_LEGACY:
307            if self.subtype == OLD_UUID_SUBTYPE:
308                return UUID(bytes=self)
309        elif uuid_representation == UuidRepresentation.JAVA_LEGACY:
310            if self.subtype == OLD_UUID_SUBTYPE:
311                return UUID(bytes=self[0:8][::-1] + self[8:16][::-1])
312        elif uuid_representation == UuidRepresentation.CSHARP_LEGACY:
313            if self.subtype == OLD_UUID_SUBTYPE:
314                return UUID(bytes_le=self)
315        else:
316            # uuid_representation == UuidRepresentation.STANDARD
317            if self.subtype == UUID_SUBTYPE:
318                return UUID(bytes=self)
319
320        raise ValueError(
321            "cannot decode subtype %s to %s"
322            % (self.subtype, UUID_REPRESENTATION_NAMES[uuid_representation])
323        )
324
325    @property
326    def subtype(self):
327        """Subtype of this binary data."""
328        return self.__subtype
329
330    def __getnewargs__(self):
331        # Work around http://bugs.python.org/issue7382
332        data = super(Binary, self).__getnewargs__()[0]
333        if not isinstance(data, bytes):
334            data = data.encode("latin-1")
335        return data, self.__subtype
336
337    def __eq__(self, other):
338        if isinstance(other, Binary):
339            return (self.__subtype, bytes(self)) == (other.subtype, bytes(other))
340        # We don't return NotImplemented here because if we did then
341        # Binary("foo") == "foo" would return True, since Binary is a
342        # subclass of str...
343        return False
344
345    def __hash__(self):
346        return super(Binary, self).__hash__() ^ hash(self.__subtype)
347
348    def __ne__(self, other):
349        return not self == other
350
351    def __repr__(self):
352        return "Binary(%s, %s)" % (bytes.__repr__(self), self.__subtype)