Add 'format' argument to UUIDField

To allow serializations to control the representation format of a
UUID value

Author: ovangle

docs/api-guide/fields.md

@@ -183,6 +183,15 @@ A field that ensures the input is a valid UUID string. The `to_internal_value` m
 
     "de305d54-75b4-431b-adb2-eb6b9e546013"
 
+**Signature:** `UUIDField(format='hex_verbose')`
+
+- `format`: Determines the representation format of the uuid value
+    - `'hex_verbose'` - The cannoncical hex representation, including hyphens
+    - `'hex'` - The compact hex representation of the UUID, not including hyphens
+    - `'int'` - A 128 bit integer representation of the UUID.
+    - `'urn'` - RFC 4122 URN representation of the UUID
+  The `to_internal_value` will accept any of the string formats of a UUID unless the `format` is `'int'`, when it will accept a
+
 ---
 
 # Numeric fields

rest_framework/fields.py

@@ -639,20 +639,37 @@ def __init__(self, **kwargs):
 
 
 class UUIDField(Field):
+    valid_formats = ('hex_verbose', 'hex', 'int', 'urn')
+
     default_error_messages = {
         'invalid': _('"{value}" is not a valid UUID.'),
     }
 
+    def __init__(self, **kwargs):
+        self.uuid_format = kwargs.pop('format', 'hex_verbose')
+        if self.uuid_format not in self.valid_formats:
+            raise ValueError(
+                'Invalid format for uuid representation. '
+                'Must be one of "{0}"'.format('", "'.join(self.valid_formats))
+            )
+        super(UUIDField, self).__init__(**kwargs)
+
     def to_internal_value(self, data):
         if not isinstance(data, uuid.UUID):
             try:
-                return uuid.UUID(data)
+                if isinstance(data, six.integer_types):
+                    return uuid.UUID(int=data)
+                else:
+                    return uuid.UUID(hex=data)
             except (ValueError, TypeError):
                 self.fail('invalid', value=data)
         return data
 
     def to_representation(self, value):
-        return str(value)
+        if self.uuid_format == 'hex_verbose':
+            return str(value)
+        else:
+            return getattr(value, self.uuid_format)
 
 
 # Number types...

tests/test_fields.py

@@ -526,7 +526,9 @@ class TestUUIDField(FieldValues):
     """
     valid_inputs = {
         '825d7aeb-05a9-45b5-a5b7-05df87923cda': uuid.UUID('825d7aeb-05a9-45b5-a5b7-05df87923cda'),
-        '825d7aeb05a945b5a5b705df87923cda': uuid.UUID('825d7aeb-05a9-45b5-a5b7-05df87923cda')
+        '825d7aeb05a945b5a5b705df87923cda': uuid.UUID('825d7aeb-05a9-45b5-a5b7-05df87923cda'),
+        'urn:uuid:213b7d9b-244f-410d-828c-dabce7a2615d': uuid.UUID('213b7d9b-244f-410d-828c-dabce7a2615d'),
+        284758210125106368185219588917561929842: uuid.UUID('d63a6fb6-88d5-40c7-a91c-9edf73283072')
     }
     invalid_inputs = {
         '825d7aeb-05a9-45b5-a5b7': ['"825d7aeb-05a9-45b5-a5b7" is not a valid UUID.']
@@ -536,6 +538,17 @@ class TestUUIDField(FieldValues):
     }
     field = serializers.UUIDField()
 
+    def _test_format(self, uuid_format, formatted_uuid_0):
+        field = serializers.UUIDField(format=uuid_format)
+        assert field.to_representation(uuid.UUID(int=0)) == formatted_uuid_0
+        assert field.to_internal_value(formatted_uuid_0) == uuid.UUID(int=0)
+
+    def test_formats(self):
+        self._test_format('int', 0)
+        self._test_format('hex_verbose', '00000000-0000-0000-0000-000000000000')
+        self._test_format('urn', 'urn:uuid:00000000-0000-0000-0000-000000000000')
+        self._test_format('hex', '0' * 32)
+
 
 # Number types...