Fleshing out serializer fields

1 files changed, 466 insertions, 125 deletions

diff --git a/rest_framework/fields.py b/rest_framework/fields.py
index 250c0579..043a44ed 100644
--- a/rest_framework/fields.py
+++ b/rest_framework/fields.py
@@ -1,8 +1,18 @@
+from django.conf import settings
 from django.core import validators
 from django.core.exceptions import ValidationError
+from django.utils import timezone
+from django.utils.dateparse import parse_date, parse_datetime, parse_time
 from django.utils.encoding import is_protected_type
-from rest_framework.utils import html
+from django.utils.translation import ugettext_lazy as _
+from rest_framework import ISO_8601
+from rest_framework.compat import smart_text
+from rest_framework.settings import api_settings
+from rest_framework.utils import html, representation, humanize_datetime
+import datetime
+import decimal
 import inspect
+import warnings
 
 
 class empty:
@@ -71,22 +81,22 @@ class SkipField(Exception):
     pass
 
 
+NOT_READ_ONLY_WRITE_ONLY = 'May not set both `read_only` and `write_only`'
+NOT_READ_ONLY_REQUIRED = 'May not set both `read_only` and `required`'
+NOT_READ_ONLY_DEFAULT = 'May not set both `read_only` and `default`'
+NOT_REQUIRED_DEFAULT = 'May not set both `required` and `default`'
+MISSING_ERROR_MESSAGE = (
+    'ValidationError raised by `{class_name}`, but error key `{key}` does '
+    'not exist in the `error_messages` dictionary.'
+)
+
+
 class Field(object):
     _creation_counter = 0
 
-    MESSAGES = {
-        'required': 'This field is required.'
+    default_error_messages = {
+        'required': _('This field is required.')
     }
-
-    _NOT_READ_ONLY_WRITE_ONLY = 'May not set both `read_only` and `write_only`'
-    _NOT_READ_ONLY_REQUIRED = 'May not set both `read_only` and `required`'
-    _NOT_READ_ONLY_DEFAULT = 'May not set both `read_only` and `default`'
-    _NOT_REQUIRED_DEFAULT = 'May not set both `required` and `default`'
-    _MISSING_ERROR_MESSAGE = (
-        'ValidationError raised by `{class_name}`, but error key `{key}` does '
-        'not exist in the `MESSAGES` dictionary.'
-    )
-
     default_validators = []
 
     def __init__(self, read_only=False, write_only=False,
@@ -100,10 +110,10 @@ class Field(object):
             required = default is empty and not read_only
 
         # Some combinations of keyword arguments do not make sense.
-        assert not (read_only and write_only), self._NOT_READ_ONLY_WRITE_ONLY
-        assert not (read_only and required), self._NOT_READ_ONLY_REQUIRED
-        assert not (read_only and default is not empty), self._NOT_READ_ONLY_DEFAULT
-        assert not (required and default is not empty), self._NOT_REQUIRED_DEFAULT
+        assert not (read_only and write_only), NOT_READ_ONLY_WRITE_ONLY
+        assert not (read_only and required), NOT_READ_ONLY_REQUIRED
+        assert not (read_only and default is not empty), NOT_READ_ONLY_DEFAULT
+        assert not (required and default is not empty), NOT_REQUIRED_DEFAULT
 
         self.read_only = read_only
         self.write_only = write_only
@@ -113,7 +123,14 @@ class Field(object):
         self.initial = initial
         self.label = label
         self.style = {} if style is None else style
-        self.validators = self.default_validators + validators
+        self.validators = validators or self.default_validators[:]
+
+        # Collect default error message from self and parent classes
+        messages = {}
+        for cls in reversed(self.__class__.__mro__):
+            messages.update(getattr(cls, 'default_error_messages', {}))
+        messages.update(error_messages or {})
+        self.error_messages = messages
 
     def bind(self, field_name, parent, root):
         """
@@ -186,12 +203,14 @@ class Field(object):
                 self.fail('required')
             return self.get_default()
 
-        self.run_validators(data)
-        return self.to_native(data)
+        value = self.to_native(data)
+        self.run_validators(value)
+        return value
 
     def run_validators(self, value):
         if value in validators.EMPTY_VALUES:
             return
+
         errors = []
         for validator in self.validators:
             try:
@@ -218,33 +237,32 @@ class Field(object):
         A helper method that simply raises a validation error.
         """
         try:
-            raise ValidationError(self.MESSAGES[key].format(**kwargs))
+            msg = self.error_messages[key]
         except KeyError:
             class_name = self.__class__.__name__
-            msg = self._MISSING_ERROR_MESSAGE.format(class_name=class_name, key=key)
+            msg = MISSING_ERROR_MESSAGE.format(class_name=class_name, key=key)
             raise AssertionError(msg)
+        raise ValidationError(msg.format(**kwargs))
 
     def __new__(cls, *args, **kwargs):
+        """
+        When a field is instantiated, we store the arguments that were used,
+        so that we can present a helpful representation of the object.
+        """
         instance = super(Field, cls).__new__(cls)
         instance._args = args
         instance._kwargs = kwargs
         return instance
 
     def __repr__(self):
-        arg_string = ', '.join([repr(val) for val in self._args])
-        kwarg_string = ', '.join([
-            '%s=%s' % (key, repr(val)) for key, val in self._kwargs.items()
-        ])
-        if arg_string and kwarg_string:
-            arg_string += ', '
-        class_name = self.__class__.__name__
-        return "%s(%s%s)" % (class_name, arg_string, kwarg_string)
+        return representation.field_repr(self)
 
 
+# Boolean types...
+
 class BooleanField(Field):
-    MESSAGES = {
-        'required': 'This field is required.',
-        'invalid_value': '`{input}` is not a valid boolean.'
+    default_error_messages = {
+        'invalid': _('`{input}` is not a valid boolean.')
     }
     TRUE_VALUES = {'t', 'T', 'true', 'True', 'TRUE', '1', 1, True}
     FALSE_VALUES = {'f', 'F', 'false', 'False', 'FALSE', '0', 0, 0.0, False}
@@ -261,13 +279,23 @@ class BooleanField(Field):
             return True
         elif data in self.FALSE_VALUES:
             return False
-        self.fail('invalid_value', input=data)
+        self.fail('invalid', input=data)
+
+    def to_primative(self, value):
+        if value is None:
+            return None
+        if value in self.TRUE_VALUES:
+            return True
+        elif value in self.FALSE_VALUES:
+            return False
+        return bool(value)
 
 
+# String types...
+
 class CharField(Field):
-    MESSAGES = {
-        'required': 'This field is required.',
-        'blank': 'This field may not be blank.'
+    default_error_messages = {
+        'blank': _('This field may not be blank.')
     }
 
     def __init__(self, **kwargs):
@@ -281,19 +309,364 @@ class CharField(Field):
             self.fail('blank')
         return str(data)
 
+    def to_primative(self, value):
+        if value is None:
+            return None
+        return str(value)
 
-class ChoiceField(Field):
-    MESSAGES = {
-        'required': 'This field is required.',
-        'invalid_choice': '`{input}` is not a valid choice.'
+
+class EmailField(CharField):
+    default_error_messages = {
+        'invalid': _('Enter a valid email address.')
+    }
+    default_validators = [validators.validate_email]
+
+    def to_native(self, data):
+        ret = super(EmailField, self).to_native(data)
+        if ret is None:
+            return None
+        return ret.strip()
+
+    def to_primative(self, value):
+        ret = super(EmailField, self).to_primative(value)
+        if ret is None:
+            return None
+        return ret.strip()
+
+
+class RegexField(CharField):
+    def __init__(self, regex, **kwargs):
+        kwargs['validators'] = (
+            [validators.RegexValidator(regex)] +
+            kwargs.get('validators', [])
+        )
+        super(RegexField, self).__init__(**kwargs)
+
+
+class SlugField(CharField):
+    default_error_messages = {
+        'invalid': _("Enter a valid 'slug' consisting of letters, numbers, underscores or hyphens.")
+    }
+    default_validators = [validators.validate_slug]
+
+
+class URLField(CharField):
+    default_error_messages = {
+        'invalid': _("Enter a valid URL.")
+    }
+    default_validators = [validators.URLValidator()]
+
+
+# Number types...
+
+class IntegerField(Field):
+    default_error_messages = {
+        'invalid': _('A valid integer is required.')
+    }
+
+    def __init__(self, **kwargs):
+        max_value = kwargs.pop('max_value', None)
+        min_value = kwargs.pop('min_value', None)
+        super(IntegerField, self).__init__(**kwargs)
+        if max_value is not None:
+            self.validators.append(validators.MaxValueValidator(max_value))
+        if min_value is not None:
+            self.validators.append(validators.MinValueValidator(min_value))
+        print self.__class__.__name__, self.validators
+
+    def to_native(self, data):
+        try:
+            data = int(str(data))
+        except (ValueError, TypeError):
+            self.fail('invalid')
+        return data
+
+    def to_primative(self, value):
+        if value is None:
+            return None
+        return int(value)
+
+
+class FloatField(Field):
+    default_error_messages = {
+        'invalid': _("'%s' value must be a float."),
     }
-    coerce_to_type = str
 
     def __init__(self, **kwargs):
-        choices = kwargs.pop('choices')
+        max_value = kwargs.pop('max_value', None)
+        min_value = kwargs.pop('min_value', None)
+        super(FloatField, self).__init__(**kwargs)
+        if max_value is not None:
+            self.validators.append(validators.MaxValueValidator(max_value))
+        if min_value is not None:
+            self.validators.append(validators.MinValueValidator(min_value))
+
+    def to_primative(self, value):
+        if value is None:
+            return None
+        try:
+            return float(value)
+        except (TypeError, ValueError):
+            self.fail('invalid', value=value)
+
+    def to_native(self, value):
+        if value is None:
+            return None
+        return float(value)
+
+
+class DecimalField(Field):
+    default_error_messages = {
+        'invalid': _('Enter a number.'),
+        'max_value': _('Ensure this value is less than or equal to {max_value}.'),
+        'min_value': _('Ensure this value is greater than or equal to {min_value}.'),
+        'max_digits': _('Ensure that there are no more than {max_digits} digits in total.'),
+        'max_decimal_places': _('Ensure that there are no more than {max_decimal_places} decimal places.'),
+        'max_whole_digits': _('Ensure that there are no more than {max_whole_digits} digits before the decimal point.')
+    }
+
+    def __init__(self, max_value=None, min_value=None, max_digits=None, decimal_places=None, **kwargs):
+        self.max_value, self.min_value = max_value, min_value
+        self.max_digits, self.max_decimal_places = max_digits, decimal_places
+        super(DecimalField, self).__init__(**kwargs)
+        if max_value is not None:
+            self.validators.append(validators.MaxValueValidator(max_value))
+        if min_value is not None:
+            self.validators.append(validators.MinValueValidator(min_value))
+
+    def from_native(self, value):
+        """
+        Validates that the input is a decimal number. Returns a Decimal
+        instance. Returns None for empty values. Ensures that there are no more
+        than max_digits in the number, and no more than decimal_places digits
+        after the decimal point.
+        """
+        if value in validators.EMPTY_VALUES:
+            return None
+
+        value = smart_text(value).strip()
+        try:
+            value = decimal.Decimal(value)
+        except decimal.DecimalException:
+            self.fail('invalid')
+
+        # Check for NaN. It is the only value that isn't equal to itself,
+        # so we can use this to identify NaN values.
+        if value != value:
+            self.fail('invalid')
+
+        # Check for infinity and negative infinity.
+        if value in (decimal.Decimal('Inf'), decimal.Decimal('-Inf')):
+            self.fail('invalid')
+
+        sign, digittuple, exponent = value.as_tuple()
+        decimals = abs(exponent)
+        # digittuple doesn't include any leading zeros.
+        digits = len(digittuple)
+        if decimals > digits:
+            # We have leading zeros up to or past the decimal point.  Count
+            # everything past the decimal point as a digit.  We do not count
+            # 0 before the decimal point as a digit since that would mean
+            # we would not allow max_digits = decimal_places.
+            digits = decimals
+        whole_digits = digits - decimals
+
+        if self.max_digits is not None and digits > self.max_digits:
+            self.fail('max_digits', max_digits=self.max_digits)
+        if self.decimal_places is not None and decimals > self.decimal_places:
+            self.fail('max_decimal_places', max_decimal_places=self.max_decimal_places)
+        if self.max_digits is not None and self.decimal_places is not None and whole_digits > (self.max_digits - self.decimal_places):
+            self.fail('max_whole_digits', max_while_digits=self.max_digits - self.decimal_places)
+
+        return value
+
+
+# Date & time fields...
+
+class DateField(Field):
+    default_error_messages = {
+        'invalid': _("Date has wrong format. Use one of these formats instead: %s"),
+    }
+    input_formats = api_settings.DATE_INPUT_FORMATS
+    format = api_settings.DATE_FORMAT
+
+    def __init__(self, input_formats=None, format=None, *args, **kwargs):
+        self.input_formats = input_formats if input_formats is not None else self.input_formats
+        self.format = format if format is not None else self.format
+        super(DateField, self).__init__(*args, **kwargs)
+
+    def from_native(self, value):
+        if value in validators.EMPTY_VALUES:
+            return None
+
+        if isinstance(value, datetime.datetime):
+            if timezone and settings.USE_TZ and timezone.is_aware(value):
+                # Convert aware datetimes to the default time zone
+                # before casting them to dates (#17742).
+                default_timezone = timezone.get_default_timezone()
+                value = timezone.make_naive(value, default_timezone)
+            return value.date()
+        if isinstance(value, datetime.date):
+            return value
+
+        for format in self.input_formats:
+            if format.lower() == ISO_8601:
+                try:
+                    parsed = parse_date(value)
+                except (ValueError, TypeError):
+                    pass
+                else:
+                    if parsed is not None:
+                        return parsed
+            else:
+                try:
+                    parsed = datetime.datetime.strptime(value, format)
+                except (ValueError, TypeError):
+                    pass
+                else:
+                    return parsed.date()
+
+        humanized_format = humanize_datetime.date_formats(self.input_formats)
+        msg = self.error_messages['invalid'] % humanized_format
+        raise ValidationError(msg)
+
+    def to_primative(self, value):
+        if value is None or self.format is None:
+            return value
+
+        if isinstance(value, datetime.datetime):
+            value = value.date()
+
+        if self.format.lower() == ISO_8601:
+            return value.isoformat()
+        return value.strftime(self.format)
+
+
+class DateTimeField(Field):
+    default_error_messages = {
+        'invalid': _("Datetime has wrong format. Use one of these formats instead: %s"),
+    }
+    input_formats = api_settings.DATETIME_INPUT_FORMATS
+    format = api_settings.DATETIME_FORMAT
+
+    def __init__(self, input_formats=None, format=None, *args, **kwargs):
+        self.input_formats = input_formats if input_formats is not None else self.input_formats
+        self.format = format if format is not None else self.format
+        super(DateTimeField, self).__init__(*args, **kwargs)
+
+    def from_native(self, value):
+        if value in validators.EMPTY_VALUES:
+            return None
+
+        if isinstance(value, datetime.datetime):
+            return value
+        if isinstance(value, datetime.date):
+            value = datetime.datetime(value.year, value.month, value.day)
+            if settings.USE_TZ:
+                # For backwards compatibility, interpret naive datetimes in
+                # local time. This won't work during DST change, but we can't
+                # do much about it, so we let the exceptions percolate up the
+                # call stack.
+                warnings.warn("DateTimeField received a naive datetime (%s)"
+                              " while time zone support is active." % value,
+                              RuntimeWarning)
+                default_timezone = timezone.get_default_timezone()
+                value = timezone.make_aware(value, default_timezone)
+            return value
+
+        for format in self.input_formats:
+            if format.lower() == ISO_8601:
+                try:
+                    parsed = parse_datetime(value)
+                except (ValueError, TypeError):
+                    pass
+                else:
+                    if parsed is not None:
+                        return parsed
+            else:
+                try:
+                    parsed = datetime.datetime.strptime(value, format)
+                except (ValueError, TypeError):
+                    pass
+                else:
+                    return parsed
+
+        humanized_format = humanize_datetime.datetime_formats(self.input_formats)
+        msg = self.error_messages['invalid'] % humanized_format
+        raise ValidationError(msg)
+
+    def to_primative(self, value):
+        if value is None or self.format is None:
+            return value
+
+        if self.format.lower() == ISO_8601:
+            ret = value.isoformat()
+            if ret.endswith('+00:00'):
+                ret = ret[:-6] + 'Z'
+            return ret
+        return value.strftime(self.format)
 
-        assert choices, '`choices` argument is required and may not be empty'
 
+class TimeField(Field):
+    default_error_messages = {
+        'invalid': _("Time has wrong format. Use one of these formats instead: %s"),
+    }
+    input_formats = api_settings.TIME_INPUT_FORMATS
+    format = api_settings.TIME_FORMAT
+
+    def __init__(self, input_formats=None, format=None, *args, **kwargs):
+        self.input_formats = input_formats if input_formats is not None else self.input_formats
+        self.format = format if format is not None else self.format
+        super(TimeField, self).__init__(*args, **kwargs)
+
+    def from_native(self, value):
+        if value in validators.EMPTY_VALUES:
+            return None
+
+        if isinstance(value, datetime.time):
+            return value
+
+        for format in self.input_formats:
+            if format.lower() == ISO_8601:
+                try:
+                    parsed = parse_time(value)
+                except (ValueError, TypeError):
+                    pass
+                else:
+                    if parsed is not None:
+                        return parsed
+            else:
+                try:
+                    parsed = datetime.datetime.strptime(value, format)
+                except (ValueError, TypeError):
+                    pass
+                else:
+                    return parsed.time()
+
+        humanized_format = humanize_datetime.time_formats(self.input_formats)
+        msg = self.error_messages['invalid'] % humanized_format
+        raise ValidationError(msg)
+
+    def to_primative(self, value):
+        if value is None or self.format is None:
+            return value
+
+        if isinstance(value, datetime.datetime):
+            value = value.time()
+
+        if self.format.lower() == ISO_8601:
+            return value.isoformat()
+        return value.strftime(self.format)
+
+
+# Choice types...
+
+class ChoiceField(Field):
+    default_error_messages = {
+        'invalid_choice': _('`{input}` is not a valid choice.')
+    }
+
+    def __init__(self, choices, **kwargs):
         # Allow either single or paired choices style:
         # choices = [1, 2, 3]
         # choices = [(1, 'First'), (2, 'Second'), (3, 'Third')]
@@ -321,12 +694,14 @@ class ChoiceField(Field):
         except KeyError:
             self.fail('invalid_choice', input=data)
 
+    def to_primative(self, value):
+        return value
+
 
 class MultipleChoiceField(ChoiceField):
-    MESSAGES = {
-        'required': 'This field is required.',
-        'invalid_choice': '`{input}` is not a valid choice.',
-        'not_a_list': 'Expected a list of items but got type `{input_type}`'
+    default_error_messages = {
+        'invalid_choice': _('`{input}` is not a valid choice.'),
+        'not_a_list': _('Expected a list of items but got type `{input_type}`')
     }
 
     def to_native(self, data):
@@ -337,72 +712,42 @@ class MultipleChoiceField(ChoiceField):
             for item in data
         ])
 
-
-class IntegerField(Field):
-    MESSAGES = {
-        'required': 'This field is required.',
-        'invalid_integer': 'A valid integer is required.'
-    }
-
-    def __init__(self, **kwargs):
-        max_value = kwargs.pop('max_value', None)
-        min_value = kwargs.pop('min_value', None)
-        super(IntegerField, self).__init__(**kwargs)
-        if max_value is not None:
-            self.validators.append(validators.MaxValueValidator(max_value))
-        if min_value is not None:
-            self.validators.append(validators.MinValueValidator(min_value))
-
-    def to_native(self, data):
-        try:
-            data = int(str(data))
-        except (ValueError, TypeError):
-            self.fail('invalid_integer')
-        return data
-
     def to_primative(self, value):
-        if value is None:
-            return None
-        return int(value)
+        return value
 
 
-class EmailField(CharField):
+# File types...
+
+class FileField(Field):
     pass  # TODO
 
 
-class URLField(CharField):
+class ImageField(Field):
     pass  # TODO
 
 
-class RegexField(CharField):
-    def __init__(self, **kwargs):
-        self.regex = kwargs.pop('regex')
-        super(CharField, self).__init__(**kwargs)
-
+# Advanced field types...
 
-class DateField(CharField):
-    def __init__(self, **kwargs):
-        self.input_formats = kwargs.pop('input_formats', None)
-        super(DateField, self).__init__(**kwargs)
+class ReadOnlyField(Field):
+    """
+    A read-only field that simply returns the field value.
 
+    If the field is a method with no parameters, the method will be called
+    and it's return value used as the representation.
 
-class TimeField(CharField):
-    def __init__(self, **kwargs):
-        self.input_formats = kwargs.pop('input_formats', None)
-        super(TimeField, self).__init__(**kwargs)
+    For example, the following would call `get_expiry_date()` on the object:
 
+    class ExampleSerializer(self):
+        expiry_date = ReadOnlyField(source='get_expiry_date')
+    """
 
-class DateTimeField(CharField):
     def __init__(self, **kwargs):
-        self.input_formats = kwargs.pop('input_formats', None)
-        super(DateTimeField, self).__init__(**kwargs)
-
-
-class FileField(Field):
-    pass  # TODO
+        kwargs['read_only'] = True
+        super(ReadOnlyField, self).__init__(**kwargs)
 
+    def to_native(self, data):
+        raise NotImplemented('.to_native() not supported.')
 
-class ReadOnlyField(Field):
     def to_primative(self, value):
         if is_simple_callable(value):
             return value()
@@ -410,11 +755,28 @@ class ReadOnlyField(Field):
 
 
 class MethodField(Field):
+    """
+    A read-only field that get its representation from calling a method on the
+    parent serializer class. The method called will be of the form
+    "get_{field_name}", and should take a single argument, which is the
+    object being serialized.
+
+    For example:
+
+    class ExampleSerializer(self):
+        extra_info = MethodField()
+
+        def get_extra_info(self, obj):
+            return ...  # Calculate some data to return.
+    """
     def __init__(self, **kwargs):
         kwargs['source'] = '*'
         kwargs['read_only'] = True
         super(MethodField, self).__init__(**kwargs)
 
+    def to_native(self, data):
+        raise NotImplemented('.to_native() not supported.')
+
     def to_primative(self, value):
         attr = 'get_{field_name}'.format(field_name=self.field_name)
         method = getattr(self.parent, attr)
@@ -424,35 +786,14 @@ class MethodField(Field):
 class ModelField(Field):
     """
     A generic field that can be used against an arbitrary model field.
-    """
-    def __init__(self, *args, **kwargs):
-        try:
-            self.model_field = kwargs.pop('model_field')
-        except KeyError:
-            raise ValueError("ModelField requires 'model_field' kwarg")
-
-        self.min_length = kwargs.pop('min_length',
-                                     getattr(self.model_field, 'min_length', None))
-        self.max_length = kwargs.pop('max_length',
-                                     getattr(self.model_field, 'max_length', None))
-        self.min_value = kwargs.pop('min_value',
-                                    getattr(self.model_field, 'min_value', None))
-        self.max_value = kwargs.pop('max_value',
-                                    getattr(self.model_field, 'max_value', None))
-
-        super(ModelField, self).__init__(*args, **kwargs)
-
-        if self.min_length is not None:
-            self.validators.append(validators.MinLengthValidator(self.min_length))
-        if self.max_length is not None:
-            self.validators.append(validators.MaxLengthValidator(self.max_length))
-        if self.min_value is not None:
-            self.validators.append(validators.MinValueValidator(self.min_value))
-        if self.max_value is not None:
-            self.validators.append(validators.MaxValueValidator(self.max_value))
 
-    def get_attribute(self, instance):
-        return get_attribute(instance, self.source_attrs[:-1])
+    This is used by `ModelSerializer` when dealing with custom model fields,
+    that do not have a serializer field to be mapped to.
+    """
+    def __init__(self, model_field, **kwargs):
+        self.model_field = model_field
+        kwargs['source'] = '*'
+        super(ModelField, self).__init__(**kwargs)
 
     def to_native(self, data):
         rel = getattr(self.model_field, 'rel', None)