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

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

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

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)
 
 

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

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