Merge branch 'master' into version-3.1

9 files changed, 67 insertions, 15 deletions

diff --git a/docs/api-guide/fields.md b/docs/api-guide/fields.md
index e4ef1d4a..f06db56c 100644
--- a/docs/api-guide/fields.md
+++ b/docs/api-guide/fields.md
@@ -112,6 +112,8 @@ Two options are currently used in HTML form generation, `'input_type'` and `'bas
 
 A boolean representation.
 
+When using HTML encoded form input be aware that omitting a value will always be treated as setting a field to `False`, even if it has a `default=True` option specified. This is because HTML checkbox inputs represent the unchecked state by omitting the value, so REST framework treats omission as if it is an empty checkbox input.
+
 Corresponds to `django.db.models.fields.BooleanField`.
 
 **Signature:** `BooleanField()`
diff --git a/docs/api-guide/permissions.md b/docs/api-guide/permissions.md
index 6d86b72c..8731cab0 100644
--- a/docs/api-guide/permissions.md
+++ b/docs/api-guide/permissions.md
@@ -10,12 +10,24 @@ Together with [authentication] and [throttling], permissions determine whether a
 
 Permission checks are always run at the very start of the view, before any other code is allowed to proceed.  Permission checks will typically use the authentication information in the `request.user` and `request.auth` properties to determine if the incoming request should be permitted.
 
+Permissions are used to grant or deny access different classes of users to different parts of the API.
+
+The simplest style of permission would be to allow access to any authenticated user, and deny access to any unauthenticated user. This corresponds the `IsAuthenticated` class in REST framework.
+
+A slightly less strict style of permission would be to allow full access to authenticated users, but allow read-only access to unauthenticated users. This corresponds to the `IsAuthenticatedOrReadOnly` class in REST framework.
+
 ## How permissions are determined
 
 Permissions in REST framework are always defined as a list of permission classes.
 
 Before running the main body of the view each permission in the list is checked.
-If any permission check fails an `exceptions.PermissionDenied` exception will be raised, and the main body of the view will not run.
+If any permission check fails an `exceptions.PermissionDenied` or `exceptions.NotAuthenticated` exception will be raised, and the main body of the view will not run.
+
+When the permissions checks fail either a "403 Forbidden" or a "401 Unauthorized" response will be returned, according to the following rules:
+
+* The request was successfully authenticated, but permission was denied. *— An HTTP 403 Forbidden response will be returned.*
+* The request was not successfully authenticated, and the highest priority authentication class *does not* use `WWW-Authenticate` headers. *— An HTTP 403 Forbidden response will be returned.*
+* The request was not successfully authenticated, and the highest priority authentication class *does* use `WWW-Authenticate` headers. *— An HTTP 401 Unauthorized response, with an appropriate `WWW-Authenticate` header will be returned.*
 
 ## Object level permissions
 
diff --git a/docs/api-guide/relations.md b/docs/api-guide/relations.md
index a79b6ea5..e56db229 100644
--- a/docs/api-guide/relations.md
+++ b/docs/api-guide/relations.md
@@ -397,7 +397,7 @@ We could define a custom field that could be used to serialize tagged instances,
                 return 'Note: ' + value.text
             raise Exception('Unexpected type of tagged object')
 
-If you need the target of the relationship to have a nested representation, you can use the required serializers inside the `.to_native()` method:
+If you need the target of the relationship to have a nested representation, you can use the required serializers inside the `.to_representation()` method:
 
         def to_representation(self, value):
             """
diff --git a/docs/api-guide/serializers.md b/docs/api-guide/serializers.md
index 5fe6b4c2..b9f0e7bc 100644
--- a/docs/api-guide/serializers.md
+++ b/docs/api-guide/serializers.md
@@ -22,11 +22,13 @@ The serializers in REST framework work very similarly to Django's `Form` and `Mo
 
 Let's start by creating a simple object we can use for example purposes:
 
+    from datetime import datetime
+    
     class Comment(object):
         def __init__(self, email, content, created=None):
             self.email = email
             self.content = content
-            self.created = created or datetime.datetime.now()
+            self.created = created or datetime.now()
 
     comment = Comment(email='leila@example.com', content='foo bar')
 
@@ -61,10 +63,10 @@ At this point we've translated the model instance into Python native datatypes.
 
 Deserialization is similar. First we parse a stream into Python native datatypes...
 
-    from StringIO import StringIO
+    from django.utils.six import BytesIO
     from rest_framework.parsers import JSONParser
 
-    stream = StringIO(json)
+    stream = BytesIO(json)
     data = JSONParser().parse(stream)
 
 ...then we restore those native datatypes into a dictionary of validated data.
@@ -240,6 +242,12 @@ Serializer classes can also include reusable validators that are applied to the
 
 For more information see the [validators documentation](validators.md).
 
+## Accessing the initial data and instance
+
+When passing an initial object or queryset to a serializer instance, the object will be made available as `.instance`. If no initial object is passed then the `.instance` attribute will be `None`.
+
+When passing data to a serializer instance, the unmodified data will be made available as `.initial_data`. If the data keyword argument is not passed then the `.initial_data` attribute will not exist.
+
 ## Partial updates
 
 By default, serializers must be passed values for all required fields or they will raise validation errors. You can use the `partial` argument in order to allow partial updates.
diff --git a/docs/topics/release-notes.md b/docs/topics/release-notes.md
index f00d3c54..b9216e36 100644
--- a/docs/topics/release-notes.md
+++ b/docs/topics/release-notes.md
@@ -40,9 +40,21 @@ You can determine your currently installed version using `pip freeze`:
 
 ## 3.0.x series
 
+### 3.0.2
+
+**Date**: [17th December 2014][3.0.2-milestone].
+
+* Ensure `request.user` is made available to response middleware. ([#2155][gh2155])
+* `Client.logout()` also cancels any existing `force_authenticate`. ([#2218][gh2218], [#2259][gh2259])
+* Extra assertions and better checks to preventing incorrect serializer API use. ([#2228][gh2228], [#2234][gh2234], [#2262][gh2262], [#2263][gh2263], [#2266][gh2266], [#2267][gh2267], [#2289][gh2289], [#2291][gh2291])
+* Fixed `min_length` message for `CharField`. ([#2255][gh2255])
+* Fix `UnicodeDecodeError`, which can occur on serializer `repr`.  ([#2270][gh2270], [#2279][gh2279])
+* Fix empty HTML values when a default is provided. ([#2280][gh2280], [#2294][gh2294])
+* Fix `SlugRelatedField` raising `UnicodeEncodeError` when used as a multiple choice input. ([#2290][gh2290])
+
 ### 3.0.1
 
-**Date**: [December 2014][3.0.1-milestone].
+**Date**: [11th December 2014][3.0.1-milestone].
 
 * More helpful error message when the default Serializer `create()` fails. ([#2013][gh2013])
 * Raise error when attempting to save serializer if data is not valid. ([#2098][gh2098])
@@ -665,9 +677,11 @@ For older release notes, [please see the GitHub repo](old-release-notes).
 [ticket-582]: https://github.com/tomchristie/django-rest-framework/issues/582
 [rfc-6266]: http://tools.ietf.org/html/rfc6266#section-4.3
 [old-release-notes]: https://github.com/tomchristie/django-rest-framework/blob/2.4.4/docs/topics/release-notes.md#04x-series
-[3.0.1-milestone]: https://github.com/tomchristie/django-rest-framework/issues?q=milestone%3A%223.0.1+Release%22
 
+[3.0.1-milestone]: https://github.com/tomchristie/django-rest-framework/issues?q=milestone%3A%223.0.1+Release%22
+[3.0.2-milestone]: https://github.com/tomchristie/django-rest-framework/issues?q=milestone%3A%223.0.2+Release%22
 
+<!-- 3.0.1 -->
 [gh2013]: https://github.com/tomchristie/django-rest-framework/issues/2013
 [gh2098]: https://github.com/tomchristie/django-rest-framework/issues/2098
 [gh2109]: https://github.com/tomchristie/django-rest-framework/issues/2109
@@ -697,3 +711,21 @@ For older release notes, [please see the GitHub repo](old-release-notes).
 [gh2242]: https://github.com/tomchristie/django-rest-framework/issues/2242
 [gh2243]: https://github.com/tomchristie/django-rest-framework/issues/2243
 [gh2244]: https://github.com/tomchristie/django-rest-framework/issues/2244
+<!-- 3.0.2 -->
+[gh2155]: https://github.com/tomchristie/django-rest-framework/issues/2155
+[gh2218]: https://github.com/tomchristie/django-rest-framework/issues/2218
+[gh2228]: https://github.com/tomchristie/django-rest-framework/issues/2228
+[gh2234]: https://github.com/tomchristie/django-rest-framework/issues/2234
+[gh2255]: https://github.com/tomchristie/django-rest-framework/issues/2255
+[gh2259]: https://github.com/tomchristie/django-rest-framework/issues/2259
+[gh2262]: https://github.com/tomchristie/django-rest-framework/issues/2262
+[gh2263]: https://github.com/tomchristie/django-rest-framework/issues/2263
+[gh2266]: https://github.com/tomchristie/django-rest-framework/issues/2266
+[gh2267]: https://github.com/tomchristie/django-rest-framework/issues/2267
+[gh2270]: https://github.com/tomchristie/django-rest-framework/issues/2270
+[gh2279]: https://github.com/tomchristie/django-rest-framework/issues/2279
+[gh2280]: https://github.com/tomchristie/django-rest-framework/issues/2280
+[gh2289]: https://github.com/tomchristie/django-rest-framework/issues/2289
+[gh2290]: https://github.com/tomchristie/django-rest-framework/issues/2290
+[gh2291]: https://github.com/tomchristie/django-rest-framework/issues/2291
+[gh2294]: https://github.com/tomchristie/django-rest-framework/issues/2294
diff --git a/docs/tutorial/1-serialization.md b/docs/tutorial/1-serialization.md
index dea43cc0..ff507a2b 100644
--- a/docs/tutorial/1-serialization.md
+++ b/docs/tutorial/1-serialization.md
@@ -161,9 +161,7 @@ At this point we've translated the model instance into Python native datatypes.
 
 Deserialization is similar.  First we parse a stream into Python native datatypes...
 
-    # This import will use either `StringIO.StringIO` or `io.BytesIO`
-    # as appropriate, depending on if we're running Python 2 or Python 3.
-    from rest_framework.compat import BytesIO
+    from django.utils.six import BytesIO
 
     stream = BytesIO(content)
     data = JSONParser().parse(stream)
@@ -200,7 +198,7 @@ Open the file `snippets/serializers.py` again, and edit the `SnippetSerializer`
             model = Snippet
             fields = ('id', 'title', 'code', 'linenos', 'language', 'style')
 
-One nice property that serializers have is that you can inspect all the fields in a serializer instance, by printing it's representation. Open the Django shell with `python manange.py shell`, then try the following:
+One nice property that serializers have is that you can inspect all the fields in a serializer instance, by printing it's representation. Open the Django shell with `python manage.py shell`, then try the following:
 
     >>> from snippets.serializers import SnippetSerializer
     >>> serializer = SnippetSerializer()
diff --git a/docs/tutorial/4-authentication-and-permissions.md b/docs/tutorial/4-authentication-and-permissions.md
index a6d27bf7..592c77e8 100644
--- a/docs/tutorial/4-authentication-and-permissions.md
+++ b/docs/tutorial/4-authentication-and-permissions.md
@@ -206,7 +206,7 @@ If we try to create a snippet without authenticating, we'll get an error:
 
 We can make a successful request by including the username and password of one of the users we created earlier.
 
-    http POST -a tom:password http://127.0.0.1:8000/snippets/ code="print 789"
+    http -a tom:password POST http://127.0.0.1:8000/snippets/ code="print 789"
 
     {
         "id": 5,
diff --git a/docs/tutorial/6-viewsets-and-routers.md b/docs/tutorial/6-viewsets-and-routers.md
index 816e9da6..d55a60de 100644
--- a/docs/tutorial/6-viewsets-and-routers.md
+++ b/docs/tutorial/6-viewsets-and-routers.md
@@ -44,8 +44,8 @@ Next we're going to replace the `SnippetList`, `SnippetDetail` and `SnippetHighl
             snippet = self.get_object()
             return Response(snippet.highlighted)
 
-        def pre_save(self, obj):
-            obj.owner = self.request.user
+        def perform_create(self, serializer):
+                serializer.save(owner=self.request.user)
 
 This time we've used the `ModelViewSet` class in order to get the complete set of default read and write operations.
 
diff --git a/docs/tutorial/quickstart.md b/docs/tutorial/quickstart.md
index c3f95994..a4474c34 100644
--- a/docs/tutorial/quickstart.md
+++ b/docs/tutorial/quickstart.md
@@ -19,7 +19,7 @@ Create a new Django project named `tutorial`, then start a new app called `quick
     pip install djangorestframework
 
     # Set up a new project with a single application
-    django-admin.py startproject tutorial .
+    django-admin.py startproject tutorial .  # Note the trailing '.' character
     cd tutorial
     django-admin.py startapp quickstart
     cd ..