Merge branch 'master' into version-3.1

4 files changed, 27 insertions, 5 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.