Merge branch 'master' of github.com:tomchristie/django-rest-framework

12 files changed, 135 insertions, 43 deletions

diff --git a/docs/api-guide/fields.md b/docs/api-guide/fields.md
index 391a52e5..aa5cc84e 100644
--- a/docs/api-guide/fields.md
+++ b/docs/api-guide/fields.md
@@ -453,7 +453,7 @@ If you want to create a custom field, you'll need to subclass `Field` and then o
 
 The `.to_representation()` method is called to convert the initial datatype into a primitive, serializable datatype.
 
-The `to_internal_value()` method is called to restore a primitive datatype into its internal python representation.
+The `to_internal_value()` method is called to restore a primitive datatype into its internal python representation. This method should raise a `serializer.ValidationError` if the data is invalid.
 
 Note that the `WritableField` class that was present in version 2.x no longer exists. You should subclass `Field` and override `to_internal_value()` if the field supports data input.
 
@@ -498,6 +498,53 @@ As an example, let's create a field that can be used represent the class name of
             """
             return obj.__class__.__name__
 
+#### Raising validation errors
+
+Our `ColorField` class above currently does not perform any data validation.
+To indicate invalid data, we should raise a `serializers.ValidationError`, like so:
+
+    def to_internal_value(self, data):
+        if not isinstance(data, six.text_type):
+            msg = 'Incorrect type. Expected a string, but got %s'
+            raise ValidationError(msg % type(data).__name__)
+
+        if not re.match(r'^rgb\([0-9]+,[0-9]+,[0-9]+\)$', data):
+            raise ValidationError('Incorrect format. Expected `rgb(#,#,#)`.')
+
+        data = data.strip('rgb(').rstrip(')')
+        red, green, blue = [int(col) for col in data.split(',')]
+
+        if any([col > 255 or col < 0 for col in (red, green, blue)]):
+            raise ValidationError('Value out of range. Must be between 0 and 255.')
+
+        return Color(red, green, blue)
+
+The `.fail()` method is a shortcut for raising `ValidationError` that takes a message string from the `error_messages` dictionary. For example:
+
+    default_error_messages = {
+        'incorrect_type': 'Incorrect type. Expected a string, but got {input_type}',
+        'incorrect_format': 'Incorrect format. Expected `rgb(#,#,#)`.',
+        'out_of_range': 'Value out of range. Must be between 0 and 255.'
+    }
+
+    def to_internal_value(self, data):
+        if not isinstance(data, six.text_type):
+            msg = 'Incorrect type. Expected a string, but got %s'
+            self.fail('incorrect_type', input_type=type(data).__name__)
+
+        if not re.match(r'^rgb\([0-9]+,[0-9]+,[0-9]+\)$', data):
+            self.fail('incorrect_format')
+
+        data = data.strip('rgb(').rstrip(')')
+        red, green, blue = [int(col) for col in data.split(',')]
+
+        if any([col > 255 or col < 0 for col in (red, green, blue)]):
+            self.fail('out_of_range')
+
+        return Color(red, green, blue)
+
+This style keeps you error messages more cleanly separated from your code, and should be preferred.
+
 # Third party packages
 
 The following third party packages are also available.
diff --git a/docs/api-guide/serializers.md b/docs/api-guide/serializers.md
index 0ee80d53..1779c863 100644
--- a/docs/api-guide/serializers.md
+++ b/docs/api-guide/serializers.md
@@ -96,7 +96,7 @@ If we want to be able to return complete object instances based on the validated
 If your object instances correspond to Django models you'll also want to ensure that these methods save the object to the database. For example, if `Comment` was a Django model, the methods might look like this:
 
         def create(self, validated_data):
-            return Comment.objcts.create(**validated_data)
+            return Comment.objects.create(**validated_data)
 
         def update(self, instance, validated_data):
             instance.email = validated_data.get('email', instance.email)
@@ -567,13 +567,13 @@ There needs to be a way of determining which views should be used for hyperlinki
 
 By default hyperlinks are expected to correspond to a view name that matches the style `'{model_name}-detail'`, and looks up the instance by a `pk` keyword argument.
 
-You can override a URL field view name and lookup field by using either, or both of, the `view_name` and `lookup_field` options in the `extra_field_kwargs` setting, like so:
+You can override a URL field view name and lookup field by using either, or both of, the `view_name` and `lookup_field` options in the `extra_kwargs` setting, like so:
 
     class AccountSerializer(serializers.HyperlinkedModelSerializer):
         class Meta:
             model = Account
             fields = ('account_url', 'account_name', 'users', 'created')
-            extra_field_kwargs = {
+            extra_kwargs = {
                 'url': {'view_name': 'accounts', 'lookup_field': 'account_name'}
                 'users': {'lookup_field': 'username'}
             }
@@ -689,6 +689,21 @@ Here's an example of how you might choose to implement multiple updates:
 
 It is possible that a third party package may be included alongside the 3.1 release that provides some automatic support for multiple update operations, similar to the `allow_add_remove` behavior that was present in REST framework 2.
 
+#### Customizing ListSerializer initialization
+
+When a serializer with `many=True` is instantiated, we need to determine which arguments and keyword arguments should be passed to the `.__init__()` method for both the child `Serializer` class, and for the parent `ListSerializer` class.
+
+The default implementation is to pass all arguments to both classes, except for `validators`, and any custom keyword arguments, both of which are assumed to be intended for the child serializer class.
+
+Occasionally you might need to explicitly specify how the child and parent classes should be instantiated when `many=True` is passed. You can do so by using the `many_init` class method.
+
+        @classmethod
+        def many_init(cls, *args, **kwargs):
+            # Instantiate the child serializer.
+            kwargs['child'] = cls()
+            # Instantiate the parent list serializer.
+            return CustomListSerializer(*args, **kwargs)
+
 ---
 
 # BaseSerializer
diff --git a/docs/api-guide/validators.md b/docs/api-guide/validators.md
index f087e191..8f5a8929 100644
--- a/docs/api-guide/validators.md
+++ b/docs/api-guide/validators.md
@@ -1,4 +1,4 @@
-<a class="github" href="validators.py"></a>
+source: validators.py
 
 ---
 
diff --git a/docs/index.md b/docs/index.md
index 10b45584..52e42fc9 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -4,14 +4,14 @@
 <a href="https://twitter.com/share" class="twitter-share-button" data-url="django-rest-framework.org" data-text="Checking out the totally awesome Django REST framework! http://www.django-rest-framework.org" data-count="none"></a>
 <script>!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0];if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src="http://platform.twitter.com/widgets.js";fjs.parentNode.insertBefore(js,fjs);}}(document,"script","twitter-wjs");</script>
 
-<img src="https://secure.travis-ci.org/tomchristie/django-rest-framework.png?branch=master" class="travis-build-image">
+<img src="https://secure.travis-ci.org/tomchristie/django-rest-framework.svg?branch=master" class="travis-build-image">
 </p>
 
 ---
 
 **Note**: This is the documentation for the **version 3.0** of REST framework. Documentation for [version 2.4](http://tomchristie.github.io/rest-framework-2-docs/) is also available.
 
-For more details see the [3.0 release notes](3.0-announcement).
+For more details see the [3.0 release notes][3.0-announcement].
 
 ---
 
@@ -33,7 +33,7 @@ Django REST framework is a powerful and flexible toolkit that makes it easy to b
 
 Some reasons you might want to use REST framework:
 
-* The [Web browseable API][sandbox] is a huge usability win for your developers.
+* The [Web browsable API][sandbox] is a huge usability win for your developers.
 * [Authentication policies][authentication] including [OAuth1a][oauth1-section] and [OAuth2][oauth2-section] out of the box.
 * [Serialization][serializers] that supports both [ORM][modelserializer-section] and [non-ORM][serializer-section] data sources.
 * Customizable all the way down - just use [regular function-based views][functionview-section] if you don't need the [more][generic-views] [powerful][viewsets] [features][routers].
@@ -134,7 +134,7 @@ Here's our project's root `urls.py` module:
     router.register(r'users', UserViewSet)
 
     # Wire up our API using automatic URL routing.
-    # Additionally, we include login URLs for the browseable API.
+    # Additionally, we include login URLs for the browsable API.
     urlpatterns = [
         url(r'^', include(router.urls)),
         url(r'^api-auth/', include('rest_framework.urls', namespace='rest_framework'))
diff --git a/docs/topics/2.3-announcement.md b/docs/topics/2.3-announcement.md
index 9c9f3e9f..66e46865 100644
--- a/docs/topics/2.3-announcement.md
+++ b/docs/topics/2.3-announcement.md
@@ -35,7 +35,7 @@ As an example of just how simple REST framework APIs can now be, here's an API w
 
 
     # Wire up our API using automatic URL routing.
-    # Additionally, we include login URLs for the browseable API.
+    # Additionally, we include login URLs for the browsable API.
     urlpatterns = [
         url(r'^', include(router.urls)),
         url(r'^api-auth/', include('rest_framework.urls', namespace='rest_framework'))
@@ -207,9 +207,9 @@ The old-style signature will continue to function but will raise a `PendingDepre
 
 ## View names and descriptions
 
-The mechanics of how the names and descriptions used in the browseable API are generated has been modified and cleaned up somewhat.
+The mechanics of how the names and descriptions used in the browsable API are generated has been modified and cleaned up somewhat.
 
-If you've been customizing this behavior, for example perhaps to use `rst` markup for the browseable API, then you'll need to take a look at the implementation to see what updates you need to make.
+If you've been customizing this behavior, for example perhaps to use `rst` markup for the browsable API, then you'll need to take a look at the implementation to see what updates you need to make.
 
 Note that the relevant methods have always been private APIs, and the docstrings called them out as intended to be deprecated.
 
diff --git a/docs/topics/3.0-announcement.md b/docs/topics/3.0-announcement.md
index b32fe510..8791ad08 100644
--- a/docs/topics/3.0-announcement.md
+++ b/docs/topics/3.0-announcement.md
@@ -1,14 +1,16 @@
-# REST framework 3.0
+# Django REST framework 3.0
 
 The 3.0 release of Django REST framework is the result of almost four years of iteration and refinement. It comprehensively addresses some of the previous remaining design issues in serializers, fields and the generic views.
 
-This release is incremental in nature. There *are* some breaking API changes, and upgrading *will* require you to read the release notes carefully, but the migration path should otherwise be relatively straightforward.
+**This release is incremental in nature. There *are* some breaking API changes, and upgrading *will* require you to read the release notes carefully, but the migration path should otherwise be relatively straightforward.**
 
 The difference in quality of the REST framework API and implementation should make writing, maintaining and debugging your application far easier.
 
-3.0 is the first of three releases that have been funded by our recent [Kickstarter campaign](kickstarter.com/projects/tomchristie/django-rest-framework-3).
+3.0 is the first of three releases that have been funded by our recent [Kickstarter campaign][kickstarter].
 
-As ever, a huge thank you to our many [wonderful sponsors](sponsors). If you're looking for a Django gig, and want to work with smart community-minded folks, you should probably check out that list and see who's hiring.
+As ever, a huge thank you to our many [wonderful sponsors][sponsors]. If you're looking for a Django gig, and want to work with smart community-minded folks, you should probably check out that list and see who's hiring.
+
+---
 
 ## New features
 
@@ -51,6 +53,8 @@ Instead of passing the files argument separately:
 
 The usage of `request.QUERY_PARAMS` is now pending deprecation in favor of the lowercased `request.query_params`.
 
+---
+
 ## Serializers
 
 #### Single-step object creation.
@@ -149,7 +153,7 @@ Previously `serializers.ValidationError` error was simply a synonym for `django.
 
 The reason behind this is that Django's `ValidationError` class is intended for use with HTML forms and its API makes using it slightly awkward with nested validation errors that can occur in serializers.
 
-For most users this change shouldn't require any updates to your codebase, but it is worth ensuring that whenever raising validation errors you are always using the `serializers.ValidationError` exception class, and not Django's built-in exception.
+For most users this change shouldn't require any updates to your codebase, but it is worth ensuring that whenever raising validation errors you should prefer using the `serializers.ValidationError` exception class, and not Django's built-in exception.
 
 We strongly recommend that you use the namespaced import style of `import serializers` and not `from serializers import ValidationError` in order to avoid any potential confusion.
 
@@ -218,7 +222,18 @@ If you absolutely need to preserve `transform_<field_name>` behavior, for exampl
 
 This change also means that we no longer use the `.full_clean()` method on model instances, but instead perform all validation explicitly on the serializer. This gives a cleaner separation, and ensures that there's no automatic validation behavior on `ModelSerializer` classes that can't also be easily replicated on regular `Serializer` classes.
 
-It's important to note that this change also means that the model `.clean()` method will not be called as part of serializer validation, as it would be if using a `ModelForm`. Use the serializer `.validate()` method to perform a final validation step on incoming data where required.
+For the most part this change should be transparent. Field validation and uniqueness checks will still be run as normal, but the implementation is a little different.
+
+The one difference that you do need to note is that the `.clean()` method will not be called as part of serializer validation, as it would be if using a `ModelForm`. Use the serializer `.validate()` method to perform a final validation step on incoming data where required.
+
+There may be some cases where you really do need to keep validation logic in the model `.clean()` method, and cannot instead separate it into the serializer `.validate()`. You can do so by explicitly instantiating a model instance in the `.validate()` method.
+
+    def validate(self, attrs):
+        instance = ExampleModel(**attrs)
+        instance.clean()
+        return attrs
+
+Again, you really should look at properly separating the validation logic out of the model method if possible, but the above might be useful in some backwards compatibility cases, or for an easy migration path.
 
 #### Writable nested serialization.
 
@@ -524,6 +539,8 @@ The following class is an example of a generic serializer that can handle coerci
                     # Force anything else to its string representation.
                     output[attribute_name] = str(attribute)
 
+---
+
 ## Serializer fields
 
 #### The `Field` and `ReadOnly` field classes.
@@ -540,22 +557,22 @@ We now use the following:
 * `Field` is the base class for all fields. It does not include any default implementation for either serializing or deserializing data.
 * `ReadOnlyField` is a concrete implementation for read-only fields that simply returns the attribute value without modification.
 
-#### The `required`, `allow_none`, `allow_blank` and `default` arguments.
+#### The `required`, `allow_null`, `allow_blank` and `default` arguments.
 
 REST framework now has more explicit and clear control over validating empty values for fields.
 
 Previously the meaning of the `required=False` keyword argument was underspecified. In practice its use meant that a field could either be not included in the input, or it could be included, but be `None` or the empty string.
 
-We now have a better separation, with separate `required`, `allow_none` and `allow_blank` arguments.
+We now have a better separation, with separate `required`, `allow_null` and `allow_blank` arguments.
 
 The following set of arguments are used to control validation of empty values:
 
 * `required=False`: The value does not need to be present in the input, and will not be passed to `.create()` or `.update()` if it is not seen.
 * `default=<value>`: The value does not need to be present in the input, and a default value will be passed to `.create()` or `.update()` if it is not seen.
-* `allow_none=True`: `None` is a valid input.
+* `allow_null=True`: `None` is a valid input.
 * `allow_blank=True`: `''` is valid input. For `CharField` and subclasses only.
 
-Typically you'll want to use `required=False` if the corresponding model field has a default value, and additionally set either `allow_none=True` or `allow_blank=True` if required.
+Typically you'll want to use `required=False` if the corresponding model field has a default value, and additionally set either `allow_null=True` or `allow_blank=True` if required.
 
 The `default` argument is also available and always implies that the field is not required to be in the input. It is unnecessary to use the `required` argument when a default is specified, and doing so will result in an error.
 
@@ -710,10 +727,11 @@ The `UniqueTogetherValidator` should be applied to a serializer, and takes a `qu
         position = serializers.IntegerField()
         name = serializers.CharField(max_length=100)
 
-        default_validators = [UniqueTogetherValidator(
-            queryset=RaceResult.objects.all(),
-            fields=('category', 'position')
-        )]
+        class Meta:
+            validators = [UniqueTogetherValidator(
+                queryset=RaceResult.objects.all(),
+                fields=('category', 'position')
+            )]
 
 #### The `UniqueForDateValidator` classes.
 
@@ -721,6 +739,8 @@ REST framework also now includes explicit validator classes for validating the `
 
 These classes are documented in the [Validators](../api-guide/validators.md) section of the documentation.
 
+---
+
 ## Generic views
 
 #### Simplification of view logic.
@@ -769,12 +789,16 @@ The generic views now raise `ValidationFailed` exception for invalid data. This
 
 This change means that you can now easily customize the style of error responses across your entire API, without having to modify any of the generic views.
 
+---
+
 ## The metadata API
 
 Behavior for dealing with `OPTIONS` requests was previously built directly into the class based views. This has now been properly separated out into a Metadata API that allows the same pluggable style as other API policies in REST framework.
 
 This makes it far easier to use a different style for `OPTIONS` responses throughout your API, and makes it possible to create third-party metadata policies.
 
+---
+
 ## Serializers as HTML forms
 
 REST framework 3.0 includes templated HTML form rendering for serializers.
@@ -806,6 +830,8 @@ Similarly, to use a radio button control instead of the default `select` control
 
 This API should be considered provisional, and there may be minor alterations with the incoming 3.1 release.
 
+---
+
 ## API style
 
 There are some improvements in the default style we use in our API responses.
@@ -899,12 +925,16 @@ Or modify it on an individual serializer field, using the `coerce_to_string` key
 
 The default JSON renderer will return float objects for un-coerced `Decimal` instances. This allows you to easily switch between string or float representations for decimals depending on your API design needs.
 
-## Miscellaneous notes.
+---
+
+## Miscellaneous notes
 
 * The serializer `ChoiceField` does not currently display nested choices, as was the case in 2.4. This will be address as part of 3.1.
 * Due to the new templated form rendering, the 'widget' option is no longer valid. This means there's no easy way of using third party "autocomplete" widgets for rendering select inputs that contain a large number of choices. You'll either need to use a regular select or a plain text input. We may consider addressing this in 3.1 or 3.2 if there's sufficient demand.
 
-## What's coming next.
+---
+
+## What's coming next
 
 3.0 is an incremental release, and there are several upcoming features that will build on the baseline improvements that it makes.
 
@@ -919,5 +949,6 @@ The 3.2 release is planned to introduce an alternative admin-style interface to
 
 You can follow development on the GitHub site, where we use [milestones to indicate planning timescales](https://github.com/tomchristie/django-rest-framework/milestones).
 
+[kickstarter]: http://kickstarter.com/projects/tomchristie/django-rest-framework-3
 [sponsors]: http://www.django-rest-framework.org/topics/kickstarter-announcement/#sponsors
 [mixins.py]: https://github.com/tomchristie/django-rest-framework/blob/master/rest_framework/mixins.py
diff --git a/docs/topics/contributing.md b/docs/topics/contributing.md
index 99f4fc3c..c9626ebf 100644
--- a/docs/topics/contributing.md
+++ b/docs/topics/contributing.md
@@ -62,7 +62,6 @@ To run the tests, clone the repository, and then:
     virtualenv env
     source env/bin/activate
     pip install -r requirements.txt
-    pip install -r requirements-test.txt
 
     # Run the tests
     ./runtests.py
diff --git a/docs/topics/release-notes.md b/docs/topics/release-notes.md
index 53187589..19dfbb98 100644
--- a/docs/topics/release-notes.md
+++ b/docs/topics/release-notes.md
@@ -121,7 +121,7 @@ You can determine your currently installed version using `pip freeze`:
 * Add `UnicodeYAMLRenderer` that extends `YAMLRenderer` with unicode.
 * Fix `parse_header` argument convertion.
 * Fix mediatype detection under Python 3.
-* Web browseable API now offers blank option on dropdown when the field is not required.
+* Web browsable API now offers blank option on dropdown when the field is not required.
 * `APIException` representation improved for logging purposes.
 * Allow source="*" within nested serializers.
 * Better support for custom oauth2 provider backends.
@@ -200,7 +200,7 @@ You can determine your currently installed version using `pip freeze`:
 * Added `MAX_PAGINATE_BY` setting and `max_paginate_by` generic view attribute.
 * Added `cache` attribute to throttles to allow overriding of default cache.
 * 'Raw data' tab in browsable API now contains pre-populated data.
-* 'Raw data' and 'HTML form' tab preference in browseable API now saved between page views.
+* 'Raw data' and 'HTML form' tab preference in browsable API now saved between page views.
 * Bugfix: `required=True` argument fixed for boolean serializer fields.
 * Bugfix: `client.force_authenticate(None)` should also clear session info if it exists.
 * Bugfix: Client sending empty string instead of file now clears `FileField`.
diff --git a/docs/topics/third-party-resources.md b/docs/topics/third-party-resources.md
index efa0b91f..0358d614 100644
--- a/docs/topics/third-party-resources.md
+++ b/docs/topics/third-party-resources.md
@@ -93,7 +93,7 @@ The cookiecutter template includes a `runtests.py` which uses the `pytest` packa
 
 Before running, you'll need to install a couple test requirements.
 
-    $ pip install -r requirements-test.txt
+    $ pip install -r requirements.txt
 
 Once requirements installed, you can run `runtests.py`.
 
diff --git a/docs/tutorial/1-serialization.md b/docs/tutorial/1-serialization.md
index a3c19858..52c75d2c 100644
--- a/docs/tutorial/1-serialization.md
+++ b/docs/tutorial/1-serialization.md
@@ -110,21 +110,21 @@ The first thing we need to get started on our Web API is to provide a way of ser
         style = serializers.ChoiceField(choices=STYLE_CHOICES,
                                         default='friendly')
 
-        def create(self, validated_attrs):
+        def create(self, validated_data):
             """
             Create and return a new `Snippet` instance, given the validated data.
             """
-            return Snippet.objects.create(**validated_attrs)
+            return Snippet.objects.create(**validated_data)
 
-        def update(self, instance, validated_attrs):
+        def update(self, instance, validated_data):
             """
             Update and return an existing `Snippet` instance, given the validated data.
             """
-            instance.title = validated_attrs.get('title', instance.title)
-            instance.code = validated_attrs.get('code', instance.code)
-            instance.linenos = validated_attrs.get('linenos', instance.linenos)
-            instance.language = validated_attrs.get('language', instance.language)
-            instance.style = validated_attrs.get('style', instance.style)
+            instance.title = validated_data.get('title', instance.title)
+            instance.code = validated_data.get('code', instance.code)
+            instance.linenos = validated_data.get('linenos', instance.linenos)
+            instance.language = validated_data.get('language', instance.language)
+            instance.style = validated_data.get('style', instance.style)
             instance.save()
             return instance
 
diff --git a/docs/tutorial/6-viewsets-and-routers.md b/docs/tutorial/6-viewsets-and-routers.md
index 3fad509a..816e9da6 100644
--- a/docs/tutorial/6-viewsets-and-routers.md
+++ b/docs/tutorial/6-viewsets-and-routers.md
@@ -112,7 +112,7 @@ Here's our re-wired `urls.py` file.
     router.register(r'users', views.UserViewSet)
 
     # The API URLs are now determined automatically by the router.
-    # Additionally, we include the login URLs for the browseable API.
+    # Additionally, we include the login URLs for the browsable API.
     urlpatterns = [
         url(r'^', include(router.urls)),
         url(r'^api-auth/', include('rest_framework.urls', namespace='rest_framework'))
@@ -130,7 +130,7 @@ That doesn't mean it's always the right approach to take.  There's a similar set
 
 ## Reviewing our work
 
-With an incredibly small amount of code, we've now got a complete pastebin Web API, which is fully web browseable, and comes complete with authentication, per-object permissions, and multiple renderer formats.
+With an incredibly small amount of code, we've now got a complete pastebin Web API, which is fully web browsable, and comes complete with authentication, per-object permissions, and multiple renderer formats.
 
 We've walked through each step of the design process, and seen how if we need to customize anything we can gradually work our way down to simply using regular Django views.
 
diff --git a/docs/tutorial/quickstart.md b/docs/tutorial/quickstart.md
index 1c398c1f..3e1ce0a9 100644
--- a/docs/tutorial/quickstart.md
+++ b/docs/tutorial/quickstart.md
@@ -100,7 +100,7 @@ Okay, now let's wire up the API URLs.  On to `tutorial/urls.py`...
     router.register(r'groups', views.GroupViewSet)
 
     # Wire up our API using automatic URL routing.
-    # Additionally, we include login URLs for the browseable API.
+    # Additionally, we include login URLs for the browsable API.
     urlpatterns = [
         url(r'^', include(router.urls)),
         url(r'^api-auth/', include('rest_framework.urls', namespace='rest_framework'))