From 7e4ebde1473df54bdd46d9911d133722232d779a Mon Sep 17 00:00:00 2001 From: Bernie Hackett Date: Wed, 24 Dec 2014 09:52:58 -0800 Subject: [PATCH] PYTHON-801 - Add STANDARD and PYTHON_LEGACY to bson.binary And use them in place of UUID_SUBTYPE and OLD_UUID_SUBTYPE. This change also cleans up and clarifies the documentation for JAVA_LEGACY and CSHARP_LEGACY. None of these are binary subtypes, but instead UUID representations in the Python, C#, and Java drivers. --- bson/binary.py | 43 ++++++++++++++++++++++++++++----------- doc/api/bson/binary.rst | 2 ++ pymongo/client_options.py | 4 ++-- pymongo/codec_options.py | 11 +++++----- pymongo/common.py | 20 ++++++++++-------- 5 files changed, 52 insertions(+), 28 deletions(-) diff --git a/bson/binary.py b/bson/binary.py index 925588877..49d9fdb6d 100644 --- a/bson/binary.py +++ b/bson/binary.py @@ -56,29 +56,48 @@ change to this in a future release. Changed to subtype 4. """ -JAVA_LEGACY = 5 -"""Used with :attr:`pymongo.collection.Collection.uuid_subtype` -to specify that UUIDs should be stored in the legacy byte order -used by the Java driver. +STANDARD = UUID_SUBTYPE +"""The standard UUID representation. -:class:`uuid.UUID` instances will automatically be encoded -by :mod:`bson` using :data:`OLD_UUID_SUBTYPE`. +:class:`uuid.UUID` instances will automatically be encoded to +and decoded from BSON binary, using RFC-4122 byte order with +binary subtype :data:`UUID_SUBTYPE`. + +.. versionadded:: 3.0 +""" + +PYTHON_LEGACY = OLD_UUID_SUBTYPE +"""The Python legacy UUID representation. + +:class:`uuid.UUID` instances will automatically be encoded to +and decoded from BSON binary, using RFC-4122 byte order with +binary subtype :data:`OLD_UUID_SUBTYPE`. + +.. versionadded:: 3.0 +""" + +JAVA_LEGACY = 5 +"""The Java legacy UUID representation. + +:class:`uuid.UUID` instances will automatically be encoded to +and decoded from BSON binary, using the Java driver's legacy +byte order with binary subtype :data:`OLD_UUID_SUBTYPE`. .. versionadded:: 2.3 """ CSHARP_LEGACY = 6 -"""Used with :attr:`pymongo.collection.Collection.uuid_subtype` -to specify that UUIDs should be stored in the legacy byte order -used by the C# driver. +"""The C#/.net legacy UUID representation. -:class:`uuid.UUID` instances will automatically be encoded -by :mod:`bson` using :data:`OLD_UUID_SUBTYPE`. +:class:`uuid.UUID` instances will automatically be encoded to +and decoded from BSON binary, using the C# driver's legacy +byte order and binary subtype :data:`OLD_UUID_SUBTYPE`. .. versionadded:: 2.3 """ -ALL_UUID_SUBTYPES = (OLD_UUID_SUBTYPE, UUID_SUBTYPE, JAVA_LEGACY, CSHARP_LEGACY) +ALL_UUID_SUBTYPES = (OLD_UUID_SUBTYPE, UUID_SUBTYPE) +ALL_UUID_REPRESENTATIONS = (STANDARD, PYTHON_LEGACY, JAVA_LEGACY, CSHARP_LEGACY) MD5_SUBTYPE = 5 """BSON binary subtype for an MD5 hash. diff --git a/doc/api/bson/binary.rst b/doc/api/bson/binary.rst index 57b87255f..65d24fec3 100644 --- a/doc/api/bson/binary.rst +++ b/doc/api/bson/binary.rst @@ -9,6 +9,8 @@ .. autodata:: OLD_BINARY_SUBTYPE .. autodata:: OLD_UUID_SUBTYPE .. autodata:: UUID_SUBTYPE + .. autodata:: STANDARD + .. autodata:: PYTHON_LEGACY .. autodata:: JAVA_LEGACY .. autodata:: CSHARP_LEGACY .. autodata:: MD5_SUBTYPE diff --git a/pymongo/client_options.py b/pymongo/client_options.py index cab4eef35..33980bb93 100644 --- a/pymongo/client_options.py +++ b/pymongo/client_options.py @@ -14,7 +14,7 @@ """Tools to parse mongo client options.""" -from bson.binary import OLD_UUID_SUBTYPE +from bson.binary import PYTHON_LEGACY from bson.py3compat import iteritems from pymongo.auth import _build_credentials_tuple from pymongo.codec_options import CodecOptions @@ -40,7 +40,7 @@ def _parse_codec_options(options): """Parse BSON codec options.""" as_class = options.get('document_class', dict) tz_aware = options.get('tz_aware', False) - uuid_rep = options.get('uuidrepresentation', OLD_UUID_SUBTYPE) + uuid_rep = options.get('uuidrepresentation', PYTHON_LEGACY) return CodecOptions(as_class, tz_aware, uuid_rep) diff --git a/pymongo/codec_options.py b/pymongo/codec_options.py index f6b83367d..75dda8fb7 100644 --- a/pymongo/codec_options.py +++ b/pymongo/codec_options.py @@ -16,7 +16,7 @@ from collections import MutableMapping -from bson.binary import OLD_UUID_SUBTYPE +from bson.binary import ALL_UUID_REPRESENTATIONS, PYTHON_LEGACY class CodecOptions(object): @@ -31,20 +31,21 @@ class CodecOptions(object): naive. Defaults to ``False``. - `uuid_representation`: The BSON representation to use when encoding and decoding instances of :class:`~uuid.UUID`. Defaults to - :data:`~bson.binary.OLD_UUID_SUBTYPE`. + :data:`~bson.binary.PYTHON_LEGACY`. """ __slots__ = ("__as_class", "__tz_aware", "__uuid_rep") def __init__(self, as_class=dict, - tz_aware=False, uuid_representation=OLD_UUID_SUBTYPE): + tz_aware=False, uuid_representation=PYTHON_LEGACY): if not issubclass(as_class, MutableMapping): raise TypeError("document_class must be a " "subclass of MutableMapping") if not isinstance(tz_aware, bool): raise TypeError("tz_aware must be a boolean") - if not isinstance(uuid_representation, int): - raise TypeError("uuid_representation must be an integer") + if uuid_representation not in ALL_UUID_REPRESENTATIONS: + raise ValueError("uuid_representation must be a value " + "from bson.binary.ALL_UUID_REPRESENTATIONS") self.__as_class = as_class self.__tz_aware = tz_aware diff --git a/pymongo/common.py b/pymongo/common.py index 5beea8ac1..68f0ff8c3 100644 --- a/pymongo/common.py +++ b/pymongo/common.py @@ -26,8 +26,9 @@ from pymongo.read_preferences import (make_read_preference, ServerMode) from pymongo.ssl_support import validate_cert_reqs from pymongo.write_concern import WriteConcern -from bson.binary import (OLD_UUID_SUBTYPE, UUID_SUBTYPE, - JAVA_LEGACY, CSHARP_LEGACY) +from bson.binary import (STANDARD, PYTHON_LEGACY, + JAVA_LEGACY, CSHARP_LEGACY, + ALL_UUID_REPRESENTATIONS) from bson.py3compat import string_type, integer_types # Defaults until we connect to a server and get updated limits. @@ -91,9 +92,9 @@ def raise_config_error(key, dummy): # Mapping of URI uuid representation options to valid subtypes. -_UUID_SUBTYPES = { - 'standard': UUID_SUBTYPE, - 'pythonLegacy': OLD_UUID_SUBTYPE, +_UUID_REPRESENTATIONS = { + 'standard': STANDARD, + 'pythonLegacy': PYTHON_LEGACY, 'javaLegacy': JAVA_LEGACY, 'csharpLegacy': CSHARP_LEGACY } @@ -246,17 +247,18 @@ def validate_auth_mechanism(option, value): def validate_uuid_representation(dummy, value): """Validate the uuid representation option selected in the URI. """ - if value not in _UUID_SUBTYPES: + try: + return _UUID_REPRESENTATIONS[value] + except KeyError: raise ConfigurationError("%s is an invalid UUID representation. " "Must be one of " - "%s" % (value, list(_UUID_SUBTYPES))) - return _UUID_SUBTYPES[value] + "%s" % (value, tuple(_UUID_REPRESENTATIONS))) def validate_uuid_subtype(dummy, value): """Validate the uuid subtype option, a numerical value whose acceptable values are defined in bson.binary.""" - if value not in _UUID_SUBTYPES.values(): + if value not in ALL_UUID_REPRESENTATIONS: raise ConfigurationError("Not a valid setting for uuid_subtype.") return value