7 files changed, 48 insertions, 9 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 ddcefadb..743ca435 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. *&mdash; 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. *&mdash; 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. *&mdash; An HTTP 401 Unauthorized response, with an appropriate `WWW-Authenticate` header will be returned.*
 
 ## Object level permissions
 
diff --git a/docs/api-guide/serializers.md b/docs/api-guide/serializers.md
index 137cc9d5..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.
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/rest_framework/fields.py b/rest_framework/fields.py
index f3e17b18..5be2a21b 100644
--- a/rest_framework/fields.py
+++ b/rest_framework/fields.py
@@ -185,8 +185,13 @@ class Field(object):
         self.allow_null = allow_null
 
         if allow_null and self.default_empty_html is empty:
+            # HTML input cannot represent `None` values, so we need to
+            # forcibly coerce empty HTML values to `None` if `allow_null=True`.
             self.default_empty_html = None
 
+        if default is not empty:
+            self.default_empty_html = default
+
         if validators is not None:
             self.validators = validators[:]
 
diff --git a/tests/test_fields.py b/tests/test_fields.py
index c20bdd8c..7f7af5cc 100644
--- a/tests/test_fields.py
+++ b/tests/test_fields.py
@@ -215,6 +215,26 @@ class TestBooleanHTMLInput:
         assert serializer.validated_data == {'archived': False}
 
 
+class TestCharHTMLInput:
+    def setup(self):
+        class TestSerializer(serializers.Serializer):
+            message = serializers.CharField(default='happy')
+        self.Serializer = TestSerializer
+
+    def test_empty_html_checkbox(self):
+        """
+        HTML checkboxes do not send any value, but should be treated
+        as `False` by BooleanField.
+        """
+        # This class mocks up a dictionary like object, that behaves
+        # as if it was returned for multipart or urlencoded data.
+        class MockHTMLDict(dict):
+            getlist = None
+        serializer = self.Serializer(data=MockHTMLDict())
+        assert serializer.is_valid()
+        assert serializer.validated_data == {'message': 'happy'}
+
+
 class TestCreateOnlyDefault:
     def setup(self):
         default = serializers.CreateOnlyDefault('2001-01-01')