Merge pull request #2 from tomchristie/master

Update to latest

Author: philipdouglas

docs/api-guide/authentication.md

@@ -121,7 +121,7 @@ To use the `TokenAuthentication` scheme, include `rest_framework.authtoken` in y
         'rest_framework.authtoken'
     )
 
-Make sure to run `manage.py syncdb` after changing your settings.
+Make sure to run `manage.py syncdb` after changing your settings. The `authtoken` database tables are managed by south (see [Schema migrations](#schema-migrations) below).
 
 You'll also need to create tokens for your users.
 
@@ -184,9 +184,11 @@ The `obtain_auth_token` view will return a JSON response when valid `username` a
 
 Note that the default `obtain_auth_token` view explicitly uses JSON requests and responses, rather than using default renderer and parser classes in your settings.  If you need a customized version of the `obtain_auth_token` view, you can do so by overriding the `ObtainAuthToken` view class, and using that in your url conf instead.
 
-#### Custom user models
+#### Schema migrations
 
-The `rest_framework.authtoken` app includes a south migration that will create the authtoken table.   If you're using a [custom user model][custom-user-model] you'll need to make sure that any initial migration that creates the user table runs before the authtoken table is created.
+The `rest_framework.authtoken` app includes a south migration that will create the authtoken table.
+
+If you're using a [custom user model][custom-user-model] you'll need to make sure that any initial migration that creates the user table runs before the authtoken table is created.
 
 You can do so by inserting a `needed_by` attribute in your user migration:
 
@@ -201,6 +203,12 @@ You can do so by inserting a `needed_by` attribute in your user migration:
 
 For more details, see the [south documentation on dependencies][south-dependencies].
 
+Also note that if you're using a `post_save` signal to create tokens, then the first time you create the database tables, you'll need to ensure any migrations are run prior to creating any superusers.  For example:
+
+    python manage.py syncdb --noinput  # Won't create a superuser just yet, due to `--noinput`.
+    python manage.py migrate
+    python manage.py createsuperuser
+
 ## SessionAuthentication
 
 This authentication scheme uses Django's default session backend for authentication.  Session authentication is appropriate for AJAX clients that are running in the same session context as your website.

docs/api-guide/content-negotiation.md

@@ -43,7 +43,11 @@ This is a valid approach as the HTTP spec deliberately underspecifies how a serv
 
 It's unlikely that you'll want to provide a custom content negotiation scheme for REST framework, but you can do so if needed.  To implement a custom content negotiation scheme override `BaseContentNegotiation`.
 
-REST framework's content negotiation classes handle selection of both the appropriate parser for the request, and the appropriate renderer for the response,  so you should implement both the `.select_parser(request, parsers)` and `.select_renderer(request, renderers, format_suffix)` methods.
+REST framework's content negotiation classes handle selection of both the appropriate parser for the request, and the appropriate renderer for the response, so you should implement both the `.select_parser(request, parsers)` and `.select_renderer(request, renderers, format_suffix)` methods.
+
+The `select_parser()` method should return one of the parser instances from the list of available parsers, or `None` if none of the parsers can handle the incoming request.
+
+The `select_renderer()` method should return a two-tuple of (renderer instance, media type), or raise a `NotAcceptable` exception.
 
 ## Example
 
@@ -61,6 +65,27 @@ request when selecting the appropriate parser or renderer.
             """
             Select the first renderer in the `.renderer_classes` list.
             """
-            return renderers[0]
+            return (renderers[0], renderers[0].media_type)
+
+## Setting the content negotiation
+
+The default content negotiation class may be set globally, using the `DEFAULT_CONTENT_NEGOTIATION_CLASS` setting.  For example, the following settings would use our example `IgnoreClientContentNegotiation` class.
+
+    REST_FRAMEWORK = {
+        'DEFAULT_CONTENT_NEGOTIATION_CLASS': 'myapp.negotiation.IgnoreClientContentNegotiation',
+    }
+
+You can also set the content negotiation used for an individual view, or viewset, using the `APIView` class based views.
+
+    class NoNegotiationView(APIView):
+        """
+        An example view that does not perform content negotiation.
+        """
+        content_negotiation_class = IgnoreClientContentNegotiation
+
+        def get(self, request, format=None):
+            return Response({
+                'accepted media type': request.accepted_renderer.media_type
+            })
 
 [accept-header]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html

docs/api-guide/renderers.md

@@ -217,6 +217,24 @@ Renders data into HTML for the Browsable API.  This renderer will determine whic
 
 **.charset**: `utf-8`
 
+#### Customizing BrowsableAPIRenderer
+
+By default the response content will be rendered with the highest priority renderer apart from `BrowseableAPIRenderer`.  If you need to customize this behavior, for example to use HTML as the default return format, but use JSON in the browsable API, you can do so by overriding the `get_default_renderer()` method.  For example:
+
+    class CustomBrowsableAPIRenderer(BrowsableAPIRenderer):
+        def get_default_renderer(self, view):
+            return JSONRenderer()
+
+## MultiPartRenderer
+
+This renderer is used for rendering HTML multipart form data.  **It is not suitable as a response renderer**, but is instead used for creating test requests, using REST framework's [test client and test request factory][testing].
+
+**.media_type**: `multipart/form-data; boundary=BoUnDaRyStRiNg`
+
+**.format**: `'.multipart'`
+
+**.charset**: `utf-8`
+
 ---
 
 # Custom renderers
@@ -373,6 +391,7 @@ Comma-separated values are a plain-text tabular data format, that can be easily
 [rfc4627]: http://www.ietf.org/rfc/rfc4627.txt
 [cors]: http://www.w3.org/TR/cors/
 [cors-docs]: ../topics/ajax-csrf-cors.md
+[testing]: testing.md
 [HATEOAS]: http://timelessrepo.com/haters-gonna-hateoas
 [quote]: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
 [application/vnd.github+json]: http://developer.github.com/v3/media/

docs/api-guide/serializers.md

@@ -308,6 +308,12 @@ By default, all the model fields on the class will be mapped to corresponding se
 
 Any relationships such as foreign keys on the model will be mapped to `PrimaryKeyRelatedField`.  Other models fields will be mapped to a corresponding serializer field.
 
+---
+
+**Note**: When validation is applied to a `ModelSerializer`, both the serializer fields, and their corresponding model fields must correctly validate.  If you have optional fields on your model, make sure to correctly set `blank=True` on the model field, as well as setting `required=False` on the serializer field.
+
+---
+
 ## Specifying which fields should be included
 
 If you only want a subset of the default fields to be used in a model serializer, you can do so using `fields` or `exclude` options, just as you would with a `ModelForm`.
@@ -423,6 +429,49 @@ You can create customized subclasses of `ModelSerializer` or `HyperlinkedModelSe
 
 Doing so should be considered advanced usage, and will only be needed if you have some particular serializer requirements that you often need to repeat.
 
+## Dynamically modifiying fields
+
+Once a serializer has been initialized, the dictionary of fields that are set on the serializer may be accessed using the `.fields` attribute.  Accessing and modifying this attribute allows you to dynamically modify the serializer.
+
+Modifying the `fields` argument directly allows you to do interesting things such as changing the arguments on serializer fields at runtime, rather than at the point of declaring the serializer.
+
+### Example
+
+For example, if you wanted to be able to set which fields should be used by a serializer at the point of initializing it, you could create a serializer class like so:
+
+    class DynamicFieldsModelSerializer(serializers.ModelSerializer):
+        """
+        A ModelSerializer that takes an additional `fields` argument that
+        controls which fields should be displayed.
+        """
+
+        def __init__(self, *args, **kwargs):
+            # Don't pass the 'fields' arg up to the superclass
+            fields = kwargs.pop('fields', None)
+            
+            # Instatiate the superclass normally
+            super(DynamicFieldsModelSerializer, self).__init__(*args, **kwargs)
+    
+            if fields:
+                # Drop any fields that are not specified in the `fields` argument.
+                allowed = set(fields)
+                existing = set(self.fields.keys())
+                for field_name in existing - allowed:
+                    self.fields.pop(field_name)
+
+This would then allow you to do the following:
+
+    >>> class UserSerializer(DynamicFieldsModelSerializer):
+    >>>     class Meta:
+    >>>         model = User
+    >>>         fields = ('id', 'username', 'email')
+    >>>
+    >>> print UserSerializer(user)
+    {'id': 2, 'username': 'jonwatts', 'email': '[email protected]'}
+    >>>
+    >>> print UserSerializer(user, fields=('id', 'email'))
+    {'id': 2, 'email': '[email protected]'}
+
 ## Customising the default fields
 
 The `field_mapping` attribute is a dictionary that maps model classes to serializer classes.  Overriding the attribute will let you set a different set of default serializer classes. 
@@ -457,7 +506,7 @@ Note that the `model_field` argument will be `None` for reverse relationships.
 
 Returns the field instance that should be used for non-relational, non-pk fields.
 
-## Example
+### Example
 
 The following custom model serializer could be used as a base class for model serializers that should always exclude the pk by default.
 

docs/api-guide/settings.md

@@ -149,6 +149,33 @@ Default: `None`
 
 ---
 
+## Test settings
+
+*The following settings control the behavior of APIRequestFactory and APIClient*
+
+#### TEST_REQUEST_DEFAULT_FORMAT
+
+The default format that should be used when making test requests.
+
+This should match up with the format of one of the renderer classes in the `TEST_REQUEST_RENDERER_CLASSES` setting.
+
+Default: `'multipart'`
+
+#### TEST_REQUEST_RENDERER_CLASSES
+
+The renderer classes that are supported when building test requests.
+
+The format of any of these renderer classes may be used when contructing a test request, for example: `client.post('/users', {'username': 'jamie'}, format='json')`
+
+Default:
+
+    (
+        'rest_framework.renderers.MultiPartRenderer',
+        'rest_framework.renderers.JSONRenderer'
+    )
+
+---
+
 ## Browser overrides
 
 *The following settings provide URL or form-based overrides of the default browser behavior.*