Merge branch 'version-3.1' of github.com:tomchristie/django-rest-framework into oauth_as_package

Conflicts:
	.travis.yml

1 files changed, 508 insertions, 721 deletions

diff --git a/rest_framework/fields.py b/rest_framework/fields.py
index 8e15345d..0c78b3fb 100644
--- a/rest_framework/fields.py
+++ b/rest_framework/fields.py
@@ -1,34 +1,28 @@
-"""
-Serializer fields perform validation on incoming data.
-
-They are very similar to Django's form fields.
-"""
-from __future__ import unicode_literals
-
-import copy
-import datetime
-import inspect
-import re
-import warnings
-from decimal import Decimal, DecimalException
-from django import forms
+from django.conf import settings
 from django.core import validators
 from django.core.exceptions import ValidationError
-from django.conf import settings
-from django.db.models.fields import BLANK_CHOICE_DASH
-from django.http import QueryDict
-from django.forms import widgets
-from django.utils import six, timezone
+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 django.utils.translation import ugettext_lazy as _
-from django.utils.datastructures import SortedDict
-from django.utils.dateparse import parse_date, parse_datetime, parse_time
 from rest_framework import ISO_8601
-from rest_framework.compat import (
-    BytesIO, smart_text,
-    force_text, is_non_str_iterable
-)
+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:
+    """
+    This class is used to represent no data being provided for a given input
+    or output value.
+
+    It is required because `None` may be a valid input or output value.
+    """
+    pass
 
 
 def is_simple_callable(obj):
@@ -47,597 +41,487 @@ def is_simple_callable(obj):
     return len_args <= len_defaults
 
 
-def get_component(obj, attr_name):
+def get_attribute(instance, attrs):
     """
-    Given an object, and an attribute name,
-    return that attribute on the object.
+    Similar to Python's built in `getattr(instance, attr)`,
+    but takes a list of nested attributes, instead of a single attribute.
+
+    Also accepts either attribute lookup on objects or dictionary lookups.
     """
-    if isinstance(obj, dict):
-        val = obj.get(attr_name)
-    else:
-        val = getattr(obj, attr_name)
-
-    if is_simple_callable(val):
-        return val()
-    return val
-
-
-def readable_datetime_formats(formats):
-    format = ', '.join(formats).replace(
-        ISO_8601,
-        'YYYY-MM-DDThh:mm[:ss[.uuuuuu]][+HH:MM|-HH:MM|Z]'
-    )
-    return humanize_strptime(format)
-
-
-def readable_date_formats(formats):
-    format = ', '.join(formats).replace(ISO_8601, 'YYYY[-MM[-DD]]')
-    return humanize_strptime(format)
-
-
-def readable_time_formats(formats):
-    format = ', '.join(formats).replace(ISO_8601, 'hh:mm[:ss[.uuuuuu]]')
-    return humanize_strptime(format)
-
-
-def humanize_strptime(format_string):
-    # Note that we're missing some of the locale specific mappings that
-    # don't really make sense.
-    mapping = {
-        "%Y": "YYYY",
-        "%y": "YY",
-        "%m": "MM",
-        "%b": "[Jan-Dec]",
-        "%B": "[January-December]",
-        "%d": "DD",
-        "%H": "hh",
-        "%I": "hh",  # Requires '%p' to differentiate from '%H'.
-        "%M": "mm",
-        "%S": "ss",
-        "%f": "uuuuuu",
-        "%a": "[Mon-Sun]",
-        "%A": "[Monday-Sunday]",
-        "%p": "[AM|PM]",
-        "%z": "[+HHMM|-HHMM]"
-    }
-    for key, val in mapping.items():
-        format_string = format_string.replace(key, val)
-    return format_string
+    for attr in attrs:
+        try:
+            instance = getattr(instance, attr)
+        except AttributeError as exc:
+            try:
+                return instance[attr]
+            except (KeyError, TypeError):
+                raise exc
+    return instance
 
 
-def strip_multiple_choice_msg(help_text):
+def set_value(dictionary, keys, value):
     """
-    Remove the 'Hold down "control" ...' message that is Django enforces in
-    select multiple fields on ModelForms.  (Required for 1.5 and earlier)
+    Similar to Python's built in `dictionary[key] = value`,
+    but takes a list of nested keys instead of a single key.
 
-    See https://code.djangoproject.com/ticket/9321
+    set_value({'a': 1}, [], {'b': 2}) -> {'a': 1, 'b': 2}
+    set_value({'a': 1}, ['x'], 2) -> {'a': 1, 'x': 2}
+    set_value({'a': 1}, ['x', 'y'], 2) -> {'a': 1, 'x': {'y': 2}}
     """
-    multiple_choice_msg = _(' Hold down "Control", or "Command" on a Mac, to select more than one.')
-    multiple_choice_msg = force_text(multiple_choice_msg)
+    if not keys:
+        dictionary.update(value)
+        return
 
-    return help_text.replace(multiple_choice_msg, '')
+    for key in keys[:-1]:
+        if key not in dictionary:
+            dictionary[key] = {}
+        dictionary = dictionary[key]
 
+    dictionary[keys[-1]] = value
 
-class Field(object):
-    read_only = True
-    creation_counter = 0
-    empty = ''
-    type_name = None
-    partial = False
-    use_files = False
-    form_field_class = forms.CharField
-    type_label = 'field'
-    widget = None
-
-    def __init__(self, source=None, label=None, help_text=None):
-        self.parent = None
-
-        self.creation_counter = Field.creation_counter
-        Field.creation_counter += 1
 
-        self.source = source
+class SkipField(Exception):
+    pass
 
-        if label is not None:
-            self.label = smart_text(label)
-        else:
-            self.label = None
 
-        if help_text is not None:
-            self.help_text = strip_multiple_choice_msg(smart_text(help_text))
-        else:
-            self.help_text = None
+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.'
+)
 
-        self._errors = []
-        self._value = None
-        self._name = None
 
-    @property
-    def errors(self):
-        return self._errors
+class Field(object):
+    _creation_counter = 0
 
-    def widget_html(self):
-        if not self.widget:
-            return ''
+    default_error_messages = {
+        'required': _('This field is required.')
+    }
+    default_validators = []
 
-        attrs = {}
-        if 'id' not in self.widget.attrs:
-            attrs['id'] = self._name
+    def __init__(self, read_only=False, write_only=False,
+                 required=None, default=empty, initial=None, source=None,
+                 label=None, help_text=None, style=None,
+                 error_messages=None, validators=[]):
+        self._creation_counter = Field._creation_counter
+        Field._creation_counter += 1
 
-        return self.widget.render(self._name, self._value, attrs=attrs)
+        # If `required` is unset, then use `True` unless a default is provided.
+        if required is None:
+            required = default is empty and not read_only
 
-    def label_tag(self):
-        return '<label for="%s">%s:</label>' % (self._name, self.label)
+        # Some combinations of keyword arguments do not make sense.
+        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
 
-    def initialize(self, parent, field_name):
-        """
-        Called to set up a field prior to field_to_native or field_from_native.
+        self.read_only = read_only
+        self.write_only = write_only
+        self.required = required
+        self.default = default
+        self.source = source
+        self.initial = initial
+        self.label = label
+        self.help_text = help_text
+        self.style = {} if style is None else style
+        self.validators = validators or self.default_validators[:]
 
-        parent - The parent serializer.
-        field_name - The name of the field being initialized.
-        """
-        self.parent = parent
-        self.root = parent.root or parent
-        self.context = self.root.context
-        self.partial = self.root.partial
-        if self.partial:
-            self.required = False
+        # 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 field_from_native(self, data, files, field_name, into):
+    def __new__(cls, *args, **kwargs):
         """
-        Given a dictionary and a field name, updates the dictionary `into`,
-        with the field and it's deserialized value.
+        When a field is instantiated, we store the arguments that were used,
+        so that we can present a helpful representation of the object.
         """
-        return
+        instance = super(Field, cls).__new__(cls)
+        instance._args = args
+        instance._kwargs = kwargs
+        return instance
 
-    def field_to_native(self, obj, field_name):
+    def bind(self, field_name, parent, root):
         """
-        Given an object and a field name, returns the value that should be
-        serialized for that field.
+        Setup the context for the field instance.
         """
-        if obj is None:
-            return self.empty
-
-        if self.source == '*':
-            return self.to_native(obj)
+        self.field_name = field_name
+        self.parent = parent
+        self.root = root
+        self.context = parent.context
 
-        source = self.source or field_name
-        value = obj
+        # `self.label` should deafult to being based on the field name.
+        if self.label is None:
+            self.label = field_name.replace('_', ' ').capitalize()
 
-        for component in source.split('.'):
-            value = get_component(value, component)
-            if value is None:
-                break
+        # self.source should default to being the same as the field name.
+        if self.source is None:
+            self.source = field_name
 
-        return self.to_native(value)
+        # self.source_attrs is a list of attributes that need to be looked up
+        # when serializing the instance, or populating the validated data.
+        if self.source == '*':
+            self.source_attrs = []
+        else:
+            self.source_attrs = self.source.split('.')
 
-    def to_native(self, value):
+    def get_initial(self):
         """
-        Converts the field's value into it's simple representation.
+        Return a value to use when the field is being returned as a primative
+        value, without any object instance.
         """
-        if is_simple_callable(value):
-            value = value()
-
-        if is_protected_type(value):
-            return value
-        elif (is_non_str_iterable(value) and
-              not isinstance(value, (dict, six.string_types))):
-            return [self.to_native(item) for item in value]
-        elif isinstance(value, dict):
-            # Make sure we preserve field ordering, if it exists
-            ret = SortedDict()
-            for key, val in value.items():
-                ret[key] = self.to_native(val)
-            return ret
-        return force_text(value)
+        return self.initial
 
-    def attributes(self):
+    def get_value(self, dictionary):
         """
-        Returns a dictionary of attributes to be used when serializing to xml.
+        Given the *incoming* primative data, return the value for this field
+        that should be validated and transformed to a native value.
         """
-        if self.type_name:
-            return {'type': self.type_name}
-        return {}
-
-    def metadata(self):
-        metadata = SortedDict()
-        metadata['type'] = self.type_label
-        metadata['required'] = getattr(self, 'required', False)
-        optional_attrs = ['read_only', 'label', 'help_text',
-                          'min_length', 'max_length']
-        for attr in optional_attrs:
-            value = getattr(self, attr, None)
-            if value is not None and value != '':
-                metadata[attr] = force_text(value, strings_only=True)
-        return metadata
-
-
-class WritableField(Field):
-    """
-    Base for read/write fields.
-    """
-    write_only = False
-    default_validators = []
-    default_error_messages = {
-        'required': _('This field is required.'),
-        'invalid': _('Invalid value.'),
-    }
-    widget = widgets.TextInput
-    default = None
-
-    def __init__(self, source=None, label=None, help_text=None,
-                 read_only=False, write_only=False, required=None,
-                 validators=[], error_messages=None, widget=None,
-                 default=None, blank=None):
-
-        super(WritableField, self).__init__(source=source, label=label, help_text=help_text)
-
-        self.read_only = read_only
-        self.write_only = write_only
-
-        assert not (read_only and write_only), "Cannot set read_only=True and write_only=True"
-
-        if required is None:
-            self.required = not(read_only)
-        else:
-            assert not (read_only and required), "Cannot set required=True and read_only=True"
-            self.required = required
+        return dictionary.get(self.field_name, empty)
 
-        messages = {}
-        for c in reversed(self.__class__.__mro__):
-            messages.update(getattr(c, 'default_error_messages', {}))
-        messages.update(error_messages or {})
-        self.error_messages = messages
+    def get_attribute(self, instance):
+        """
+        Given the *outgoing* object instance, return the value for this field
+        that should be returned as a primative value.
+        """
+        return get_attribute(instance, self.source_attrs)
 
-        self.validators = self.default_validators + validators
-        self.default = default if default is not None else self.default
+    def get_default(self):
+        """
+        Return the default value to use when validating data if no input
+        is provided for this field.
 
-        # Widgets are only used for HTML forms.
-        widget = widget or self.widget
-        if isinstance(widget, type):
-            widget = widget()
-        self.widget = widget
+        If a default has not been set for this field then this will simply
+        return `empty`, indicating that no value should be set in the
+        validated data for this field.
+        """
+        if self.default is empty:
+            raise SkipField()
+        return self.default
 
-    def __deepcopy__(self, memo):
-        result = copy.copy(self)
-        memo[id(self)] = result
-        result.validators = self.validators[:]
-        return result
+    def run_validation(self, data=empty):
+        """
+        Validate a simple representation and return the internal value.
 
-    def get_default_value(self):
-        if is_simple_callable(self.default):
-            return self.default()
-        return self.default
+        The provided data may be `empty` if no representation was included.
+        May return `empty` if the field should not be included in the
+        validated data.
+        """
+        if data is empty:
+            if self.required:
+                self.fail('required')
+            return self.get_default()
 
-    def validate(self, value):
-        if value in validators.EMPTY_VALUES and self.required:
-            raise ValidationError(self.error_messages['required'])
+        value = self.to_internal_value(data)
+        self.run_validators(value)
+        return value
 
     def run_validators(self, value):
-        if value in validators.EMPTY_VALUES:
+        if value in (None, '', [], (), {}):
             return
+
         errors = []
-        for v in self.validators:
+        for validator in self.validators:
             try:
-                v(value)
-            except ValidationError as e:
-                if hasattr(e, 'code') and e.code in self.error_messages:
-                    message = self.error_messages[e.code]
-                    if e.params:
-                        message = message % e.params
-                    errors.append(message)
-                else:
-                    errors.extend(e.messages)
+                validator(value)
+            except ValidationError as exc:
+                errors.extend(exc.messages)
         if errors:
             raise ValidationError(errors)
 
-    def field_to_native(self, obj, field_name):
-        if self.write_only:
-            return None
-        return super(WritableField, self).field_to_native(obj, field_name)
-
-    def field_from_native(self, data, files, field_name, into):
+    def to_internal_value(self, data):
         """
-        Given a dictionary and a field name, updates the dictionary `into`,
-        with the field and it's deserialized value.
+        Transform the *incoming* primative data into a native value.
         """
-        if self.read_only:
-            return
-
-        try:
-            data = data or {}
-            if self.use_files:
-                files = files or {}
-                try:
-                    native = files[field_name]
-                except KeyError:
-                    native = data[field_name]
-            else:
-                native = data[field_name]
-        except KeyError:
-            if self.default is not None and not self.partial:
-                # Note: partial updates shouldn't set defaults
-                native = self.get_default_value()
-            else:
-                if self.required:
-                    raise ValidationError(self.error_messages['required'])
-                return
-
-        value = self.from_native(native)
-        if self.source == '*':
-            if value:
-                into.update(value)
-        else:
-            self.validate(value)
-            self.run_validators(value)
-            into[self.source or field_name] = value
+        raise NotImplementedError('to_internal_value() must be implemented.')
 
-    def from_native(self, value):
+    def to_representation(self, value):
         """
-        Reverts a simple representation back to the field's value.
+        Transform the *outgoing* native value into primative data.
         """
-        return value
-
+        raise NotImplementedError('to_representation() must be implemented.')
 
-class ModelField(WritableField):
-    """
-    A generic field that can be used against an arbitrary model field.
-    """
-    def __init__(self, *args, **kwargs):
+    def fail(self, key, **kwargs):
+        """
+        A helper method that simply raises a validation error.
+        """
         try:
-            self.model_field = kwargs.pop('model_field')
+            msg = self.error_messages[key]
         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))
+            class_name = self.__class__.__name__
+            msg = MISSING_ERROR_MESSAGE.format(class_name=class_name, key=key)
+            raise AssertionError(msg)
+        raise ValidationError(msg.format(**kwargs))
 
-    def from_native(self, value):
-        rel = getattr(self.model_field, "rel", None)
-        if rel is not None:
-            return rel.to._meta.get_field(rel.field_name).to_python(value)
-        else:
-            return self.model_field.to_python(value)
-
-    def field_to_native(self, obj, field_name):
-        value = self.model_field._get_val_from_obj(obj)
-        if is_protected_type(value):
-            return value
-        return self.model_field.value_to_string(obj)
+    def __repr__(self):
+        return representation.field_repr(self)
 
-    def attributes(self):
-        return {
-            "type": self.model_field.get_internal_type()
-        }
 
+# Boolean types...
 
-# Typed Fields
-
-class BooleanField(WritableField):
-    type_name = 'BooleanField'
-    type_label = 'boolean'
-    form_field_class = forms.BooleanField
-    widget = widgets.CheckboxInput
+class BooleanField(Field):
     default_error_messages = {
-        'invalid': _("'%s' value must be either True or False."),
+        'invalid': _('`{input}` is not a valid boolean.')
     }
-    empty = False
-
-    def field_from_native(self, data, files, field_name, into):
-        # HTML checkboxes do not explicitly represent unchecked as `False`
-        # we deal with that here...
-        if isinstance(data, QueryDict) and self.default is None:
-            self.default = False
-
-        return super(BooleanField, self).field_from_native(
-            data, files, field_name, into
-        )
+    TRUE_VALUES = set(('t', 'T', 'true', 'True', 'TRUE', '1', 1, True))
+    FALSE_VALUES = set(('f', 'F', 'false', 'False', 'FALSE', '0', 0, 0.0, False))
+
+    def get_value(self, dictionary):
+        if html.is_html_input(dictionary):
+            # HTML forms do not send a `False` value on an empty checkbox,
+            # so we override the default empty value to be False.
+            return dictionary.get(self.field_name, False)
+        return dictionary.get(self.field_name, empty)
+
+    def to_internal_value(self, data):
+        if data in self.TRUE_VALUES:
+            return True
+        elif data in self.FALSE_VALUES:
+            return False
+        self.fail('invalid', input=data)
 
-    def from_native(self, value):
-        if value in ('true', 't', 'True', '1'):
+    def to_representation(self, value):
+        if value is None:
+            return None
+        if value in self.TRUE_VALUES:
             return True
-        if value in ('false', 'f', 'False', '0'):
+        elif value in self.FALSE_VALUES:
             return False
         return bool(value)
 
 
-class CharField(WritableField):
-    type_name = 'CharField'
-    type_label = 'string'
-    form_field_class = forms.CharField
+# String types...
 
-    def __init__(self, max_length=None, min_length=None, allow_none=False, *args, **kwargs):
-        self.max_length, self.min_length = max_length, min_length
-        self.allow_none = allow_none
-        super(CharField, self).__init__(*args, **kwargs)
-        if min_length is not None:
-            self.validators.append(validators.MinLengthValidator(min_length))
-        if max_length is not None:
-            self.validators.append(validators.MaxLengthValidator(max_length))
+class CharField(Field):
+    default_error_messages = {
+        'blank': _('This field may not be blank.')
+    }
 
-    def from_native(self, value):
-        if isinstance(value, six.string_types):
-            return value
+    def __init__(self, **kwargs):
+        self.allow_blank = kwargs.pop('allow_blank', False)
+        self.max_length = kwargs.pop('max_length', None)
+        self.min_length = kwargs.pop('min_length', None)
+        super(CharField, self).__init__(**kwargs)
+
+    def to_internal_value(self, data):
+        if data == '' and not self.allow_blank:
+            self.fail('blank')
+        if data is None:
+            return None
+        return str(data)
 
+    def to_representation(self, value):
         if value is None:
-            if not self.allow_none:
-                return ''
-            else:
-                # Return None explicitly because smart_text(None) == 'None'. See #1834 for details
-                return None
+            return None
+        return str(value)
+
 
-        return smart_text(value)
+class EmailField(CharField):
+    default_error_messages = {
+        'invalid': _('Enter a valid email address.')
+    }
+    default_validators = [validators.validate_email]
 
+    def to_internal_value(self, data):
+        if data == '' and not self.allow_blank:
+            self.fail('blank')
+        if data is None:
+            return None
+        return str(data).strip()
 
-class URLField(CharField):
-    type_name = 'URLField'
-    type_label = 'url'
+    def to_representation(self, value):
+        if value is None:
+            return None
+        return str(value).strip()
 
-    def __init__(self, **kwargs):
-        if 'validators' not in kwargs:
-            kwargs['validators'] = [validators.URLValidator()]
-        super(URLField, self).__init__(**kwargs)
 
+class RegexField(CharField):
+    def __init__(self, regex, **kwargs):
+        kwargs['validators'] = (
+            [validators.RegexValidator(regex)] +
+            kwargs.get('validators', [])
+        )
+        super(RegexField, self).__init__(**kwargs)
 
-class SlugField(CharField):
-    type_name = 'SlugField'
-    type_label = 'slug'
-    form_field_class = forms.SlugField
 
+class SlugField(CharField):
     default_error_messages = {
-        'invalid': _("Enter a valid 'slug' consisting of letters, numbers,"
-                     " underscores or hyphens."),
+        'invalid': _("Enter a valid 'slug' consisting of letters, numbers, underscores or hyphens.")
     }
     default_validators = [validators.validate_slug]
 
-    def __init__(self, *args, **kwargs):
-        super(SlugField, self).__init__(*args, **kwargs)
-
 
-class ChoiceField(WritableField):
-    type_name = 'ChoiceField'
-    type_label = 'choice'
-    form_field_class = forms.ChoiceField
-    widget = widgets.Select
+class URLField(CharField):
     default_error_messages = {
-        'invalid_choice': _('Select a valid choice. %(value)s is not one of '
-                            'the available choices.'),
+        'invalid': _("Enter a valid URL.")
     }
+    default_validators = [validators.URLValidator()]
 
-    def __init__(self, choices=(), blank_display_value=None, *args, **kwargs):
-        self.empty = kwargs.pop('empty', '')
-        super(ChoiceField, self).__init__(*args, **kwargs)
-        self.choices = choices
-        if not self.required:
-            if blank_display_value is None:
-                blank_choice = BLANK_CHOICE_DASH
-            else:
-                blank_choice = [('', blank_display_value)]
-            self.choices = blank_choice + self.choices
 
-    def _get_choices(self):
-        return self._choices
+# Number types...
 
-    def _set_choices(self, value):
-        # Setting choices also sets the choices on the widget.
-        # choices can be any iterable, but we call list() on it because
-        # it will be consumed more than once.
-        self._choices = self.widget.choices = list(value)
+class IntegerField(Field):
+    default_error_messages = {
+        'invalid': _('A valid integer is required.')
+    }
 
-    choices = property(_get_choices, _set_choices)
+    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 metadata(self):
-        data = super(ChoiceField, self).metadata()
-        data['choices'] = [{'value': v, 'display_name': n} for v, n in self.choices]
+    def to_internal_value(self, data):
+        try:
+            data = int(str(data))
+        except (ValueError, TypeError):
+            self.fail('invalid')
         return data
 
-    def validate(self, value):
-        """
-        Validates that the input is in self.choices.
-        """
-        super(ChoiceField, self).validate(value)
-        if value and not self.valid_value(value):
-            raise ValidationError(self.error_messages['invalid_choice'] % {'value': value})
+    def to_representation(self, value):
+        if value is None:
+            return None
+        return int(value)
 
-    def valid_value(self, value):
-        """
-        Check to see if the provided value is a valid choice.
-        """
-        for k, v in self.choices:
-            if isinstance(v, (list, tuple)):
-                # This is an optgroup, so look inside the group for options
-                for k2, v2 in v:
-                    if value == smart_text(k2):
-                        return True
-            else:
-                if value == smart_text(k) or value == k:
-                    return True
-        return False
 
-    def from_native(self, value):
-        value = super(ChoiceField, self).from_native(value)
-        if value == self.empty or value in validators.EMPTY_VALUES:
-            return self.empty
-        return value
+class FloatField(Field):
+    default_error_messages = {
+        'invalid': _("'%s' value must be a float."),
+    }
+
+    def __init__(self, **kwargs):
+        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_internal_value(self, value):
+        if value is None:
+            return None
+        return float(value)
 
-class EmailField(CharField):
-    type_name = 'EmailField'
-    type_label = 'email'
-    form_field_class = forms.EmailField
+    def to_representation(self, value):
+        if value is None:
+            return None
+        try:
+            return float(value)
+        except (TypeError, ValueError):
+            self.fail('invalid', value=value)
 
+
+class DecimalField(Field):
     default_error_messages = {
-        'invalid': _('Enter a valid email address.'),
+        '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.')
     }
-    default_validators = [validators.validate_email]
 
-    def from_native(self, value):
-        ret = super(EmailField, self).from_native(value)
-        if ret is None:
+    coerce_to_string = api_settings.COERCE_DECIMAL_TO_STRING
+
+    def __init__(self, max_digits, decimal_places, coerce_to_string=None, max_value=None, min_value=None, **kwargs):
+        self.max_digits = max_digits
+        self.decimal_places = decimal_places
+        self.coerce_to_string = coerce_to_string if (coerce_to_string is not None) else self.coerce_to_string
+        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 to_internal_value(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 (None, ''):
             return None
-        return ret.strip()
 
+        value = smart_text(value).strip()
+        try:
+            value = decimal.Decimal(value)
+        except decimal.DecimalException:
+            self.fail('invalid')
 
-class RegexField(CharField):
-    type_name = 'RegexField'
-    type_label = 'regex'
-    form_field_class = forms.RegexField
+        # 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')
 
-    def __init__(self, regex, max_length=None, min_length=None, *args, **kwargs):
-        super(RegexField, self).__init__(max_length, min_length, *args, **kwargs)
-        self.regex = regex
+        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
 
-    def _get_regex(self):
-        return self._regex
+        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.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)
 
-    def _set_regex(self, regex):
-        if isinstance(regex, six.string_types):
-            regex = re.compile(regex)
-        self._regex = regex
-        if hasattr(self, '_regex_validator') and self._regex_validator in self.validators:
-            self.validators.remove(self._regex_validator)
-        self._regex_validator = validators.RegexValidator(regex=regex)
-        self.validators.append(self._regex_validator)
+        return value
 
-    regex = property(_get_regex, _set_regex)
+    def to_representation(self, value):
+        if isinstance(value, decimal.Decimal):
+            context = decimal.getcontext().copy()
+            context.prec = self.max_digits
+            quantized = value.quantize(
+                decimal.Decimal('.1') ** self.decimal_places,
+                context=context
+            )
+            if not self.coerce_to_string:
+                return quantized
+            return '{0:f}'.format(quantized)
+
+        if not self.coerce_to_string:
+            return value
+        return '%.*f' % (self.max_decimal_places, value)
 
 
-class DateField(WritableField):
-    type_name = 'DateField'
-    type_label = 'date'
-    widget = widgets.DateInput
-    form_field_class = forms.DateField
+# Date & time fields...
 
+class DateField(Field):
     default_error_messages = {
-        'invalid': _("Date has wrong format. Use one of these formats instead: %s"),
+        'invalid': _('Date has wrong format. Use one of these formats instead: {format}'),
     }
-    empty = None
-    input_formats = api_settings.DATE_INPUT_FORMATS
     format = api_settings.DATE_FORMAT
+    input_formats = api_settings.DATE_INPUT_FORMATS
 
-    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
+    def __init__(self, format=None, input_formats=None, *args, **kwargs):
         self.format = format if format is not None else self.format
+        self.input_formats = input_formats if input_formats is not None else self.input_formats
         super(DateField, self).__init__(*args, **kwargs)
 
-    def from_native(self, value):
-        if value in validators.EMPTY_VALUES:
+    def to_internal_value(self, value):
+        if value in (None, ''):
             return None
 
         if isinstance(value, datetime.datetime):
@@ -647,6 +531,7 @@ class DateField(WritableField):
                 default_timezone = timezone.get_default_timezone()
                 value = timezone.make_naive(value, default_timezone)
             return value.date()
+
         if isinstance(value, datetime.date):
             return value
 
@@ -667,10 +552,10 @@ class DateField(WritableField):
                 else:
                     return parsed.date()
 
-        msg = self.error_messages['invalid'] % readable_date_formats(self.input_formats)
-        raise ValidationError(msg)
+        humanized_format = humanize_datetime.date_formats(self.input_formats)
+        self.fail('invalid', format=humanized_format)
 
-    def to_native(self, value):
+    def to_representation(self, value):
         if value is None or self.format is None:
             return value
 
@@ -682,30 +567,25 @@ class DateField(WritableField):
         return value.strftime(self.format)
 
 
-class DateTimeField(WritableField):
-    type_name = 'DateTimeField'
-    type_label = 'datetime'
-    widget = widgets.DateTimeInput
-    form_field_class = forms.DateTimeField
-
+class DateTimeField(Field):
     default_error_messages = {
-        'invalid': _("Datetime has wrong format. Use one of these formats instead: %s"),
+        'invalid': _('Datetime has wrong format. Use one of these formats instead: {format}'),
     }
-    empty = None
-    input_formats = api_settings.DATETIME_INPUT_FORMATS
     format = api_settings.DATETIME_FORMAT
+    input_formats = api_settings.DATETIME_INPUT_FORMATS
 
-    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
+    def __init__(self, format=None, input_formats=None, *args, **kwargs):
         self.format = format if format is not None else self.format
+        self.input_formats = input_formats if input_formats is not None else self.input_formats
         super(DateTimeField, self).__init__(*args, **kwargs)
 
-    def from_native(self, value):
-        if value in validators.EMPTY_VALUES:
+    def to_internal_value(self, value):
+        if value in (None, ''):
             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:
@@ -737,10 +617,10 @@ class DateTimeField(WritableField):
                 else:
                     return parsed
 
-        msg = self.error_messages['invalid'] % readable_datetime_formats(self.input_formats)
-        raise ValidationError(msg)
+        humanized_format = humanize_datetime.datetime_formats(self.input_formats)
+        self.fail('invalid', format=humanized_format)
 
-    def to_native(self, value):
+    def to_representation(self, value):
         if value is None or self.format is None:
             return value
 
@@ -752,26 +632,20 @@ class DateTimeField(WritableField):
         return value.strftime(self.format)
 
 
-class TimeField(WritableField):
-    type_name = 'TimeField'
-    type_label = 'time'
-    widget = widgets.TimeInput
-    form_field_class = forms.TimeField
-
+class TimeField(Field):
     default_error_messages = {
-        'invalid': _("Time has wrong format. Use one of these formats instead: %s"),
+        'invalid': _('Time has wrong format. Use one of these formats instead: {format}'),
     }
-    empty = None
-    input_formats = api_settings.TIME_INPUT_FORMATS
     format = api_settings.TIME_FORMAT
+    input_formats = api_settings.TIME_INPUT_FORMATS
 
-    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
+    def __init__(self, format=None, input_formats=None, *args, **kwargs):
         self.format = format if format is not None else self.format
+        self.input_formats = input_formats if input_formats is not None else self.input_formats
         super(TimeField, self).__init__(*args, **kwargs)
 
     def from_native(self, value):
-        if value in validators.EMPTY_VALUES:
+        if value in (None, ''):
             return None
 
         if isinstance(value, datetime.time):
@@ -794,10 +668,10 @@ class TimeField(WritableField):
                 else:
                     return parsed.time()
 
-        msg = self.error_messages['invalid'] % readable_time_formats(self.input_formats)
-        raise ValidationError(msg)
+        humanized_format = humanize_datetime.time_formats(self.input_formats)
+        self.fail('invalid', format=humanized_format)
 
-    def to_native(self, value):
+    def to_representation(self, value):
         if value is None or self.format is None:
             return value
 
@@ -809,234 +683,147 @@ class TimeField(WritableField):
         return value.strftime(self.format)
 
 
-class IntegerField(WritableField):
-    type_name = 'IntegerField'
-    type_label = 'integer'
-    form_field_class = forms.IntegerField
-    empty = 0
+# Choice types...
 
+class ChoiceField(Field):
     default_error_messages = {
-        'invalid': _('Enter a whole number.'),
-        'max_value': _('Ensure this value is less than or equal to %(limit_value)s.'),
-        'min_value': _('Ensure this value is greater than or equal to %(limit_value)s.'),
+        'invalid_choice': _('`{input}` is not a valid choice.')
     }
 
-    def __init__(self, max_value=None, min_value=None, *args, **kwargs):
-        self.max_value, self.min_value = max_value, min_value
-        super(IntegerField, self).__init__(*args, **kwargs)
+    def __init__(self, choices, **kwargs):
+        # Allow either single or paired choices style:
+        # choices = [1, 2, 3]
+        # choices = [(1, 'First'), (2, 'Second'), (3, 'Third')]
+        pairs = [
+            isinstance(item, (list, tuple)) and len(item) == 2
+            for item in choices
+        ]
+        if all(pairs):
+            self.choices = dict([(key, display_value) for key, display_value in choices])
+        else:
+            self.choices = dict([(item, item) for item in choices])
 
-        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))
+        # Map the string representation of choices to the underlying value.
+        # Allows us to deal with eg. integer choices while supporting either
+        # integer or string input, but still get the correct datatype out.
+        self.choice_strings_to_values = dict([
+            (str(key), key) for key in self.choices.keys()
+        ])
 
-    def from_native(self, value):
-        if value in validators.EMPTY_VALUES:
-            return None
+        super(ChoiceField, self).__init__(**kwargs)
 
+    def to_internal_value(self, data):
         try:
-            value = int(str(value))
-        except (ValueError, TypeError):
-            raise ValidationError(self.error_messages['invalid'])
-        return value
+            return self.choice_strings_to_values[str(data)]
+        except KeyError:
+            self.fail('invalid_choice', input=data)
 
+    def to_representation(self, value):
+        return value
 
-class FloatField(WritableField):
-    type_name = 'FloatField'
-    type_label = 'float'
-    form_field_class = forms.FloatField
-    empty = 0
 
+class MultipleChoiceField(ChoiceField):
     default_error_messages = {
-        'invalid': _("'%s' value must be a float."),
+        'invalid_choice': _('`{input}` is not a valid choice.'),
+        'not_a_list': _('Expected a list of items but got type `{input_type}`')
     }
 
-    def from_native(self, value):
-        if value in validators.EMPTY_VALUES:
-            return None
-
-        try:
-            return float(value)
-        except (TypeError, ValueError):
-            msg = self.error_messages['invalid'] % value
-            raise ValidationError(msg)
-
-
-class DecimalField(WritableField):
-    type_name = 'DecimalField'
-    type_label = 'decimal'
-    form_field_class = forms.DecimalField
-    empty = Decimal('0')
-
-    default_error_messages = {
-        'invalid': _('Enter a number.'),
-        'max_value': _('Ensure this value is less than or equal to %(limit_value)s.'),
-        'min_value': _('Ensure this value is greater than or equal to %(limit_value)s.'),
-        'max_digits': _('Ensure that there are no more than %s digits in total.'),
-        'max_decimal_places': _('Ensure that there are no more than %s decimal places.'),
-        'max_whole_digits': _('Ensure that there are no more than %s digits before the decimal point.')
-    }
+    def to_internal_value(self, data):
+        if not hasattr(data, '__iter__'):
+            self.fail('not_a_list', input_type=type(data).__name__)
+        return set([
+            super(MultipleChoiceField, self).to_internal_value(item)
+            for item in data
+        ])
 
-    def __init__(self, max_value=None, min_value=None, max_digits=None, decimal_places=None, *args, **kwargs):
-        self.max_value, self.min_value = max_value, min_value
-        self.max_digits, self.decimal_places = max_digits, decimal_places
-        super(DecimalField, self).__init__(*args, **kwargs)
+    def to_representation(self, value):
+        return value
 
-        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(value)
-        except DecimalException:
-            raise ValidationError(self.error_messages['invalid'])
-        return value
+# File types...
 
-    def validate(self, value):
-        super(DecimalField, self).validate(value)
-        if value in validators.EMPTY_VALUES:
-            return
-        # Check for NaN, Inf and -Inf values. We can't compare directly for NaN,
-        # since it is never equal to itself. However, NaN is the only value that
-        # isn't equal to itself, so we can use this to identify NaN
-        if value != value or value == Decimal("Inf") or value == Decimal("-Inf"):
-            raise ValidationError(self.error_messages['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
+class FileField(Field):
+    pass  # TODO
 
-        if self.max_digits is not None and digits > self.max_digits:
-            raise ValidationError(self.error_messages['max_digits'] % self.max_digits)
-        if self.decimal_places is not None and decimals > self.decimal_places:
-            raise ValidationError(self.error_messages['max_decimal_places'] % self.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):
-            raise ValidationError(self.error_messages['max_whole_digits'] % (self.max_digits - self.decimal_places))
-        return value
 
+class ImageField(Field):
+    pass  # TODO
 
-class FileField(WritableField):
-    use_files = True
-    type_name = 'FileField'
-    type_label = 'file upload'
-    form_field_class = forms.FileField
-    widget = widgets.FileInput
 
-    default_error_messages = {
-        'invalid': _("No file was submitted. Check the encoding type on the form."),
-        'missing': _("No file was submitted."),
-        'empty': _("The submitted file is empty."),
-        'max_length': _('Ensure this filename has at most %(max)d characters (it has %(length)d).'),
-        'contradiction': _('Please either submit a file or check the clear checkbox, not both.')
-    }
+# Advanced field types...
 
-    def __init__(self, *args, **kwargs):
-        self.max_length = kwargs.pop('max_length', None)
-        self.allow_empty_file = kwargs.pop('allow_empty_file', False)
-        super(FileField, self).__init__(*args, **kwargs)
+class ReadOnlyField(Field):
+    """
+    A read-only field that simply returns the field value.
 
-    def from_native(self, data):
-        if data in validators.EMPTY_VALUES:
-            return None
+    If the field is a method with no parameters, the method will be called
+    and it's return value used as the representation.
 
-        # UploadedFile objects should have name and size attributes.
-        try:
-            file_name = data.name
-            file_size = data.size
-        except AttributeError:
-            raise ValidationError(self.error_messages['invalid'])
-
-        if self.max_length is not None and len(file_name) > self.max_length:
-            error_values = {'max': self.max_length, 'length': len(file_name)}
-            raise ValidationError(self.error_messages['max_length'] % error_values)
-        if not file_name:
-            raise ValidationError(self.error_messages['invalid'])
-        if not self.allow_empty_file and not file_size:
-            raise ValidationError(self.error_messages['empty'])
+    For example, the following would call `get_expiry_date()` on the object:
 
-        return data
+    class ExampleSerializer(self):
+        expiry_date = ReadOnlyField(source='get_expiry_date')
+    """
 
-    def to_native(self, value):
-        return value.name
+    def __init__(self, **kwargs):
+        kwargs['read_only'] = True
+        super(ReadOnlyField, self).__init__(**kwargs)
 
+    def to_representation(self, value):
+        if is_simple_callable(value):
+            return value()
+        return value
 
-class ImageField(FileField):
-    use_files = True
-    type_name = 'ImageField'
-    type_label = 'image upload'
-    form_field_class = forms.ImageField
 
-    default_error_messages = {
-        'invalid_image': _("Upload a valid image. The file you uploaded was "
-                           "either not an image or a corrupted image."),
-    }
+class SerializerMethodField(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.
 
-    def from_native(self, data):
-        """
-        Checks that the file-upload field data contains a valid image (GIF, JPG,
-        PNG, possibly others -- whatever the Python Imaging Library supports).
-        """
-        f = super(ImageField, self).from_native(data)
-        if f is None:
-            return None
+    For example:
 
-        from rest_framework.compat import Image
-        assert Image is not None, 'Either Pillow or PIL must be installed for ImageField support.'
+    class ExampleSerializer(self):
+        extra_info = SerializerMethodField()
 
-        # We need to get a file object for PIL. We might have a path or we might
-        # have to read the data into memory.
-        if hasattr(data, 'temporary_file_path'):
-            file = data.temporary_file_path()
-        else:
-            if hasattr(data, 'read'):
-                file = BytesIO(data.read())
-            else:
-                file = BytesIO(data['content'])
+        def get_extra_info(self, obj):
+            return ...  # Calculate some data to return.
+    """
+    def __init__(self, method_attr=None, **kwargs):
+        self.method_attr = method_attr
+        kwargs['source'] = '*'
+        kwargs['read_only'] = True
+        super(SerializerMethodField, self).__init__(**kwargs)
 
-        try:
-            # load() could spot a truncated JPEG, but it loads the entire
-            # image in memory, which is a DoS vector. See #3848 and #18520.
-            # verify() must be called immediately after the constructor.
-            Image.open(file).verify()
-        except ImportError:
-            # Under PyPy, it is possible to import PIL. However, the underlying
-            # _imaging C module isn't available, so an ImportError will be
-            # raised. Catch and re-raise.
-            raise
-        except Exception:  # Python Imaging Library doesn't recognize it as an image
-            raise ValidationError(self.error_messages['invalid_image'])
-        if hasattr(f, 'seek') and callable(f.seek):
-            f.seek(0)
-        return f
+    def to_representation(self, value):
+        method_attr = self.method_attr
+        if method_attr is None:
+            method_attr = 'get_{field_name}'.format(field_name=self.field_name)
+        method = getattr(self.parent, method_attr)
+        return method(value)
 
 
-class SerializerMethodField(Field):
+class ModelField(Field):
     """
-    A field that gets its value by calling a method on the serializer it's attached to.
+    A generic field that can be used against an arbitrary model field.
+
+    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 __init__(self, method_name, *args, **kwargs):
-        self.method_name = method_name
-        super(SerializerMethodField, self).__init__(*args, **kwargs)
+    def to_internal_value(self, data):
+        rel = getattr(self.model_field, 'rel', None)
+        if rel is not None:
+            return rel.to._meta.get_field(rel.field_name).to_python(data)
+        return self.model_field.to_python(data)
 
-    def field_to_native(self, obj, field_name):
-        value = getattr(self.parent, self.method_name)(obj)
-        return self.to_native(value)
+    def to_representation(self, obj):
+        value = self.model_field._get_val_from_obj(obj)
+        if is_protected_type(value):
+            return value
+        return self.model_field.value_to_string(obj)