From d31d7c18676b6292e8dc688b61913d572eccde91 Mon Sep 17 00:00:00 2001
From: Tom Christie
Date: Sat, 29 Jun 2013 22:53:27 +0100
Subject: First pass at testing docs

---
 docs/api-guide/testing.md | 97 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 97 insertions(+)
 create mode 100644 docs/api-guide/testing.md

(limited to 'docs/api-guide')

diff --git a/docs/api-guide/testing.md b/docs/api-guide/testing.md
new file mode 100644
index 00000000..f3a092a9
--- /dev/null
+++ b/docs/api-guide/testing.md
@@ -0,0 +1,97 @@
+<a class="github" href="test.py"></a>
+
+# Testing
+
+> Code without tests is broken as designed
+>
+> &mdash; [Jacob Kaplan-Moss][cite]
+
+REST framework includes a few helper classes that extend Django's existing test framework, and improve support for making API requests.
+
+# APIRequestFactory
+
+Extends Django's existing `RequestFactory`.
+
+**TODO**: Document making requests.  Note difference on form PUT requests.  Document configuration.
+
+# APIClient
+
+Extends Django's existing `Client`.
+
+### .login(**kwargs)
+
+The `login` method functions exactly as it does with Django's regular `Client` class.  This allows you to authenticate requests against any views which include `SessionAuthentication`.
+
+    # Make all requests in the context of a logged in session.
+    >>> client = APIClient()
+    >>> client.login(username='lauren', password='secret')
+
+To logout, call the `logout` method as usual.
+
+    # Log out
+    >>> client.logout()
+
+The `login` method is appropriate for testing APIs that use session authentication, for example web sites which include AJAX interaction with the API.
+
+### .credentials(**kwargs)
+
+The `credentials` method can be used to set headers that will then be included on all subsequent requests by the test client.
+
+    # Include an appropriate `Authorization:` header on all requests.
+    >>> token = Token.objects.get(username='lauren')
+    >>> client = APIClient()
+    >>> client.credentials(HTTP_AUTHORIZATION='Token ' + token.key)
+
+Note that calling `credentials` a second time overwrites any existing credentials.  You can unset any existing credentials by calling the method with no arguments.
+
+    # Stop including any credentials
+    >>> client.credentials()
+
+The `credentials` method is appropriate for testing APIs that require authentication headers, such as basic authentication, OAuth1a and OAuth2 authentication, and simple token authentication schemes.
+
+### .force_authenticate(user=None, token=None)
+
+Sometimes you may want to bypass authentication, and simple force all requests by the test client to be automatically treated as authenticated.
+
+This can be a useful shortcut if you're testing the API but don't want to have to construct valid authentication credentials in order to make test requests.
+
+    >>> user = User.objects.get(username='lauren')
+    >>> client = APIClient()
+    >>> client.force_authenticate(user=user)
+
+To unauthenticate subsequant requests, call `force_authenticate` setting the user and/or token to `None`.
+
+    >>> client.force_authenticate(user=None) 
+
+### Making requests
+
+**TODO**: Document requests similarly to `APIRequestFactory`
+
+# Testing responses
+
+### Using request.data
+
+When checking the validity of test responses it's often more convenient to inspect the data that the response was created with, rather than inspecting the fully rendered response.
+
+For example, it's easier to inspect `request.data`:
+
+    response = self.client.get('/users/4/')
+    self.assertEqual(response.data, {'id': 4, 'username': 'lauren'})
+
+Instead of inspecting the result of parsing `request.content`:
+
+    response = self.client.get('/users/4/')
+    self.assertEqual(json.loads(response.content), {'id': 4, 'username': 'lauren'})
+
+### Rendering responses
+
+If you're testing views directly using `APIRequestFactory`, the responses that are returned will not yet be rendered, as rendering of template responses is performed by Django's internal request-response cycle.  In order to access `response.content`, you'll first need to render the response.
+
+    view = UserDetail.as_view()
+    request = factory.get('/users/4')
+    response = view(request, pk='4')
+    response.render()  # Cannot access `response.content` without this.
+    self.assertEqual(response.content, '{"username": "lauren", "id": 4}')
+    
+
+[cite]: http://jacobian.org/writing/django-apps-with-buildout/#s-create-a-test-wrapper
\ No newline at end of file
-- 
cgit v1.2.3


From 0a722de171b0e80ac26d8c77b8051a4170bdb4c6 Mon Sep 17 00:00:00 2001
From: Tom Christie
Date: Mon, 1 Jul 2013 13:59:05 +0100
Subject: Complete testing docs

---
 docs/api-guide/renderers.md |  11 ++++
 docs/api-guide/settings.md  |  27 +++++++++
 docs/api-guide/testing.md   | 143 ++++++++++++++++++++++++++++++++++++++++----
 3 files changed, 171 insertions(+), 10 deletions(-)

(limited to 'docs/api-guide')

diff --git a/docs/api-guide/renderers.md b/docs/api-guide/renderers.md
index b627c930..869bdc16 100644
--- a/docs/api-guide/renderers.md
+++ b/docs/api-guide/renderers.md
@@ -217,6 +217,16 @@ Renders data into HTML for the Browsable API.  This renderer will determine whic
 
 **.charset**: `utf-8`
 
+## 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 +383,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/
diff --git a/docs/api-guide/settings.md b/docs/api-guide/settings.md
index 4a5164c9..7b114983 100644
--- a/docs/api-guide/settings.md
+++ b/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.*
diff --git a/docs/api-guide/testing.md b/docs/api-guide/testing.md
index f3a092a9..293ee701 100644
--- a/docs/api-guide/testing.md
+++ b/docs/api-guide/testing.md
@@ -10,13 +10,100 @@ REST framework includes a few helper classes that extend Django's existing test
 
 # APIRequestFactory
 
-Extends Django's existing `RequestFactory`.
+Extends [Django's existing `RequestFactory` class][requestfactory].
 
-**TODO**: Document making requests.  Note difference on form PUT requests.  Document configuration.
+## Creating test requests
+
+The `APIRequestFactory` class supports an almost identical API to Django's standard `RequestFactory` class.  This means the that standard `.get()`, `.post()`, `.put()`, `.patch()`, `.delete()`, `.head()` and `.options()` methods are all available.
+
+### Using the format arguments
+
+Methods which create a request body, such as `post`, `put` and `patch`, include a `format` argument, which make it easy to generate requests using a content type other than multipart form data.  For example:
+
+    factory = APIRequestFactory()
+    request = factory.post('/notes/', {'title': 'new idea'}, format='json')
+
+By default the available formats are `'multipart'` and `'json'`.  For compatibility with Django's existing `RequestFactory` the default format is `'multipart'`.
+
+To support a wider set of request formats, or change the default format, [see the configuration section][configuration].
+
+If you need to explictly encode the request body, you can do so by explicitly setting the `content_type` flag.  For example:
+
+    request = factory.post('/notes/', json.dumps({'title': 'new idea'}), content_type='application/json')
+
+### PUT and PATCH with form data
+
+One difference worth noting between Django's `RequestFactory` and REST framework's `APIRequestFactory` is that multipart form data will be encoded for methods other than just `.post()`.
+
+For example, using `APIRequestFactory`, you can make a form PUT request like so:
+
+    factory = APIRequestFactory()
+    request = factory.put('/notes/547/', {'title': 'remember to email dave'})
+
+Using Django's `Factory`, you'd need to explicitly encode the data yourself:
+
+    factory = RequestFactory()
+    data = {'title': 'remember to email dave'}
+    content = encode_multipart('BoUnDaRyStRiNg', data)
+    content_type = 'multipart/form-data; boundary=BoUnDaRyStRiNg'
+    request = factory.put('/notes/547/', content, content_type=content_type)
+
+## Forcing authentication
+
+When testing views directly using a request factory, it's often convenient to be able to directly authenticate the request, rather than having to construct the correct authentication credentials.
+
+To forcibly authenticate a request, use the `force_authenticate()` method.
+
+    factory = APIRequestFactory()
+    user = User.objects.get(username='olivia')
+    view = AccountDetail.as_view()
+
+    # Make an authenticated request to the view...
+    request = factory.get('/accounts/django-superstars/')
+    force_authenticate(request, user=user)
+    response = view(request)
+
+The signature for the method is `force_authenticate(request, user=None, token=None)`.  When making the call, either or both of the user and token may be set.
+
+---
+
+**Note**: When using `APIRequestFactory`, the object that is returned is Django's standard `HttpRequest`, and not REST framework's `Request` object, which is only generated once the view is called.
+
+This means that setting attributes directly on the request object may not always have the effect you expect.  For example, setting `.token` directly will have no effect, and setting `.user` directly will only work if session authentication is being used.
+
+    # Request will only authenticate if `SessionAuthentication` is in use.
+    request = factory.get('/accounts/django-superstars/')
+    request.user = user
+    response = view(request)
+
+---
+
+## Forcing CSRF validation
+
+By default, requests created with `APIRequestFactory` will not have CSRF validation applied when passed to a REST framework view.  If you need to explicitly turn CSRF validation on, you can do so by setting the `enforce_csrf_checks` flag when instantiating the factory.
+
+    factory = APIRequestFactory(enforce_csrf_checks=True)
+
+---
+
+**Note**: It's worth noting that Django's standard `RequestFactory` doesn't need to include this option, because when using regular Django the CSRF validation takes place in middleware, which is not run when testing views directly.  When using REST framework, CSRF validation takes place inside the view, so the request factory needs to disable view-level CSRF checks.
+
+---
 
 # APIClient
 
-Extends Django's existing `Client`.
+Extends [Django's existing `Client` class][client].
+
+## Making requests
+
+The `APIClient` class supports the same request interface as `APIRequestFactory`.  This means the that standard `.get()`, `.post()`, `.put()`, `.patch()`, `.delete()`, `.head()` and `.options()` methods are all available.  For example:
+
+    client = APIClient()
+    client.post('/notes/', {'title': 'new idea'}, format='json')
+
+To support a wider set of request formats, or change the default format, [see the configuration section][configuration].
+
+## Authenticating
 
 ### .login(**kwargs)
 
@@ -59,17 +146,23 @@ This can be a useful shortcut if you're testing the API but don't want to have t
     >>> client = APIClient()
     >>> client.force_authenticate(user=user)
 
-To unauthenticate subsequant requests, call `force_authenticate` setting the user and/or token to `None`.
+To unauthenticate subsequent requests, call `force_authenticate` setting the user and/or token to `None`.
 
     >>> client.force_authenticate(user=None) 
 
-### Making requests
+## CSRF validation
 
-**TODO**: Document requests similarly to `APIRequestFactory`
+By default CSRF validation is not applied when using `APIClient`.  If you need to explicitly enable CSRF validation, you can do so by setting the `enforce_csrf_checks` flag when instantiating the client.
+
+    client = APIClient(enforce_csrf_checks=True)
+
+As usual CSRF validation will only apply to any session authenticated views.  This means CSRF validation will only occur if the client has been logged in by calling `login()`.
+
+---
 
 # Testing responses
 
-### Using request.data
+## Checking the response data
 
 When checking the validity of test responses it's often more convenient to inspect the data that the response was created with, rather than inspecting the fully rendered response.
 
@@ -83,7 +176,7 @@ Instead of inspecting the result of parsing `request.content`:
     response = self.client.get('/users/4/')
     self.assertEqual(json.loads(response.content), {'id': 4, 'username': 'lauren'})
 
-### Rendering responses
+## Rendering responses
 
 If you're testing views directly using `APIRequestFactory`, the responses that are returned will not yet be rendered, as rendering of template responses is performed by Django's internal request-response cycle.  In order to access `response.content`, you'll first need to render the response.
 
@@ -92,6 +185,36 @@ If you're testing views directly using `APIRequestFactory`, the responses that a
     response = view(request, pk='4')
     response.render()  # Cannot access `response.content` without this.
     self.assertEqual(response.content, '{"username": "lauren", "id": 4}')
-    
 
-[cite]: http://jacobian.org/writing/django-apps-with-buildout/#s-create-a-test-wrapper
\ No newline at end of file
+---
+
+# Configuration
+
+## Setting the default format
+
+The default format used to make test requests may be set using the `TEST_REQUEST_DEFAULT_FORMAT` setting key.  For example, to always use JSON for test requests by default instead of standard multipart form requests, set the following in your `settings.py` file:
+
+    REST_FRAMEWORK = {
+        ...
+        'TEST_REQUEST_DEFAULT_FORMAT': 'json'
+    }
+
+## Setting the available formats
+
+If you need to test requests using something other than multipart or json requests, you can do so by setting the `TEST_REQUEST_RENDERER_CLASSES` setting.
+
+For example, to add support for using `format='yaml'` in test requests, you might have something like this in your `settings.py` file.
+
+    REST_FRAMEWORK = {
+        ...
+        'TEST_REQUEST_RENDERER_CLASSES': (
+            'rest_framework.renderers.MultiPartRenderer',
+            'rest_framework.renderers.JSONRenderer',
+            'rest_framework.renderers.YAMLRenderer'
+        )
+    }
+
+[cite]: http://jacobian.org/writing/django-apps-with-buildout/#s-create-a-test-wrapper
+[client]: https://docs.djangoproject.com/en/dev/topics/testing/overview/#module-django.test.client
+[requestfactory]: https://docs.djangoproject.com/en/dev/topics/testing/advanced/#django.test.client.RequestFactory
+[configuration]: #configuration
-- 
cgit v1.2.3


From 5427d90fa48398684948067530cd8083f785c248 Mon Sep 17 00:00:00 2001
From: Tom Christie
Date: Mon, 1 Jul 2013 17:22:11 +0100
Subject: Remove console style from code blocks

---
 docs/api-guide/testing.md | 32 ++++++++++++++++----------------
 1 file changed, 16 insertions(+), 16 deletions(-)

(limited to 'docs/api-guide')

diff --git a/docs/api-guide/testing.md b/docs/api-guide/testing.md
index 293ee701..a48aff00 100644
--- a/docs/api-guide/testing.md
+++ b/docs/api-guide/testing.md
@@ -16,7 +16,7 @@ Extends [Django's existing `RequestFactory` class][requestfactory].
 
 The `APIRequestFactory` class supports an almost identical API to Django's standard `RequestFactory` class.  This means the that standard `.get()`, `.post()`, `.put()`, `.patch()`, `.delete()`, `.head()` and `.options()` methods are all available.
 
-### Using the format arguments
+#### Using the format arguments
 
 Methods which create a request body, such as `post`, `put` and `patch`, include a `format` argument, which make it easy to generate requests using a content type other than multipart form data.  For example:
 
@@ -31,7 +31,7 @@ If you need to explictly encode the request body, you can do so by explicitly se
 
     request = factory.post('/notes/', json.dumps({'title': 'new idea'}), content_type='application/json')
 
-### PUT and PATCH with form data
+#### PUT and PATCH with form data
 
 One difference worth noting between Django's `RequestFactory` and REST framework's `APIRequestFactory` is that multipart form data will be encoded for methods other than just `.post()`.
 
@@ -105,50 +105,50 @@ To support a wider set of request formats, or change the default format, [see th
 
 ## Authenticating
 
-### .login(**kwargs)
+#### .login(**kwargs)
 
 The `login` method functions exactly as it does with Django's regular `Client` class.  This allows you to authenticate requests against any views which include `SessionAuthentication`.
 
     # Make all requests in the context of a logged in session.
-    >>> client = APIClient()
-    >>> client.login(username='lauren', password='secret')
+    client = APIClient()
+    client.login(username='lauren', password='secret')
 
 To logout, call the `logout` method as usual.
 
     # Log out
-    >>> client.logout()
+    client.logout()
 
 The `login` method is appropriate for testing APIs that use session authentication, for example web sites which include AJAX interaction with the API.
 
-### .credentials(**kwargs)
+#### .credentials(**kwargs)
 
 The `credentials` method can be used to set headers that will then be included on all subsequent requests by the test client.
 
     # Include an appropriate `Authorization:` header on all requests.
-    >>> token = Token.objects.get(username='lauren')
-    >>> client = APIClient()
-    >>> client.credentials(HTTP_AUTHORIZATION='Token ' + token.key)
+    token = Token.objects.get(username='lauren')
+    client = APIClient()
+    client.credentials(HTTP_AUTHORIZATION='Token ' + token.key)
 
 Note that calling `credentials` a second time overwrites any existing credentials.  You can unset any existing credentials by calling the method with no arguments.
 
     # Stop including any credentials
-    >>> client.credentials()
+    client.credentials()
 
 The `credentials` method is appropriate for testing APIs that require authentication headers, such as basic authentication, OAuth1a and OAuth2 authentication, and simple token authentication schemes.
 
-### .force_authenticate(user=None, token=None)
+#### .force_authenticate(user=None, token=None)
 
 Sometimes you may want to bypass authentication, and simple force all requests by the test client to be automatically treated as authenticated.
 
 This can be a useful shortcut if you're testing the API but don't want to have to construct valid authentication credentials in order to make test requests.
 
-    >>> user = User.objects.get(username='lauren')
-    >>> client = APIClient()
-    >>> client.force_authenticate(user=user)
+    user = User.objects.get(username='lauren')
+    client = APIClient()
+    client.force_authenticate(user=user)
 
 To unauthenticate subsequent requests, call `force_authenticate` setting the user and/or token to `None`.
 
-    >>> client.force_authenticate(user=None) 
+    client.force_authenticate(user=None) 
 
 ## CSRF validation
 
-- 
cgit v1.2.3


From 7398464b397d37dbcfda13eb6142039fed3e9a19 Mon Sep 17 00:00:00 2001
From: Tom Christie
Date: Wed, 3 Jul 2013 13:08:43 +0100
Subject: Tweak docs

---
 docs/api-guide/testing.md | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

(limited to 'docs/api-guide')

diff --git a/docs/api-guide/testing.md b/docs/api-guide/testing.md
index a48aff00..aba9283e 100644
--- a/docs/api-guide/testing.md
+++ b/docs/api-guide/testing.md
@@ -16,10 +16,15 @@ Extends [Django's existing `RequestFactory` class][requestfactory].
 
 The `APIRequestFactory` class supports an almost identical API to Django's standard `RequestFactory` class.  This means the that standard `.get()`, `.post()`, `.put()`, `.patch()`, `.delete()`, `.head()` and `.options()` methods are all available.
 
-#### Using the format arguments
+    # Using the standard RequestFactory API to create a form POST request
+    factory = APIRequestFactory()
+    request = factory.post('/notes/', {'title': 'new idea'})
+
+#### Using the `format` argument
 
 Methods which create a request body, such as `post`, `put` and `patch`, include a `format` argument, which make it easy to generate requests using a content type other than multipart form data.  For example:
 
+    # Create a JSON POST request
     factory = APIRequestFactory()
     request = factory.post('/notes/', {'title': 'new idea'}, format='json')
 
@@ -27,7 +32,9 @@ By default the available formats are `'multipart'` and `'json'`.  For compatibil
 
 To support a wider set of request formats, or change the default format, [see the configuration section][configuration].
 
-If you need to explictly encode the request body, you can do so by explicitly setting the `content_type` flag.  For example:
+#### Explicitly encoding the request body
+
+If you need to explictly encode the request body, you can do so by setting the `content_type` flag.  For example:
 
     request = factory.post('/notes/', json.dumps({'title': 'new idea'}), content_type='application/json')
 
@@ -40,7 +47,7 @@ For example, using `APIRequestFactory`, you can make a form PUT request like so:
     factory = APIRequestFactory()
     request = factory.put('/notes/547/', {'title': 'remember to email dave'})
 
-Using Django's `Factory`, you'd need to explicitly encode the data yourself:
+Using Django's `RequestFactory`, you'd need to explicitly encode the data yourself:
 
     factory = RequestFactory()
     data = {'title': 'remember to email dave'}
-- 
cgit v1.2.3


From b88bdfb9a5b82fce89a0e8f263e92e0817c9241d Mon Sep 17 00:00:00 2001
From: Tom Christie
Date: Thu, 4 Jul 2013 13:30:56 +0100
Subject: Add section on dynamically modifying fields.  Refs #958

---
 docs/api-guide/serializers.md | 43 ++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 42 insertions(+), 1 deletion(-)

(limited to 'docs/api-guide')

diff --git a/docs/api-guide/serializers.md b/docs/api-guide/serializers.md
index f8761cb2..dc16ba83 100644
--- a/docs/api-guide/serializers.md
+++ b/docs/api-guide/serializers.md
@@ -423,6 +423,47 @@ 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.
+
+### 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': 'jon@example.com'}
+    >>>
+    >>> print UserSerializer(user, fields=('id', 'email'))
+    {'id': 2, 'email': 'jon@example.com'}
+
 ## 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 +498,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.
 
-- 
cgit v1.2.3


From a890116ab31e57af3bd1382c1f17259fa368f988 Mon Sep 17 00:00:00 2001
From: Tom Christie
Date: Thu, 4 Jul 2013 13:49:28 +0100
Subject: Minor docs addition

---
 docs/api-guide/serializers.md | 2 ++
 1 file changed, 2 insertions(+)

(limited to 'docs/api-guide')

diff --git a/docs/api-guide/serializers.md b/docs/api-guide/serializers.md
index dc16ba83..8e9de10e 100644
--- a/docs/api-guide/serializers.md
+++ b/docs/api-guide/serializers.md
@@ -427,6 +427,8 @@ Doing so should be considered advanced usage, and will only be needed if you hav
 
 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:
-- 
cgit v1.2.3


From 045ad73f69388decff4c26a79ce191bc825672fd Mon Sep 17 00:00:00 2001
From: Tom Christie
Date: Wed, 10 Jul 2013 14:32:10 +0100
Subject: Fixing up content negotiation docs

---
 docs/api-guide/content-negotiation.md | 29 +++++++++++++++++++++++++++--
 1 file changed, 27 insertions(+), 2 deletions(-)

(limited to 'docs/api-guide')

diff --git a/docs/api-guide/content-negotiation.md b/docs/api-guide/content-negotiation.md
index 10288c94..2a774278 100644
--- a/docs/api-guide/content-negotiation.md
+++ b/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
-- 
cgit v1.2.3


From 453b7b03dd5ee43cd4e63d05258116fd9f005fb3 Mon Sep 17 00:00:00 2001
From: Matthias Jacob
Date: Wed, 10 Jul 2013 19:02:38 +0200
Subject: Fix broken links in views doc

---
 docs/api-guide/views.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

(limited to 'docs/api-guide')

diff --git a/docs/api-guide/views.md b/docs/api-guide/views.md
index 37ebd55f..683222d1 100644
--- a/docs/api-guide/views.md
+++ b/docs/api-guide/views.md
@@ -137,11 +137,11 @@ The core of this functionality is the `api_view` decorator, which takes a list o
         return Response({"message": "Hello, world!"})
 
 
-This view will use the default renderers, parsers, authentication classes etc specified in the [settings](settings).
+This view will use the default renderers, parsers, authentication classes etc specified in the [settings].
 
 ## API policy decorators
 
-To override the default settings, REST framework provides a set of additional decorators which can be added to your views.  These must come *after* (below) the `@api_view` decorator.  For example, to create a view that uses a [throttle](throttling) to ensure it can only be called once per day by a particular user, use the `@throttle_classes` decorator, passing a list of throttle classes:
+To override the default settings, REST framework provides a set of additional decorators which can be added to your views.  These must come *after* (below) the `@api_view` decorator.  For example, to create a view that uses a [throttle][throttling] to ensure it can only be called once per day by a particular user, use the `@throttle_classes` decorator, passing a list of throttle classes:
 
     from rest_framework.decorators import api_view, throttle_classes
     from rest_framework.throttling import UserRateThrottle
-- 
cgit v1.2.3


From 6de9b7c8caaea00df2b1399ecd7b815ac556a70e Mon Sep 17 00:00:00 2001
From: Tom Christie
Date: Thu, 11 Jul 2013 21:02:47 +0100
Subject: Add note on ModelSerializer validation of both model fields and
 serializer fields. Refs #949

---
 docs/api-guide/serializers.md | 6 ++++++
 1 file changed, 6 insertions(+)

(limited to 'docs/api-guide')

diff --git a/docs/api-guide/serializers.md b/docs/api-guide/serializers.md
index 8e9de10e..a1f0853e 100644
--- a/docs/api-guide/serializers.md
+++ b/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`.
-- 
cgit v1.2.3


From 77dd334026cb2f8a45b817c4577f5d5ea6a2671a Mon Sep 17 00:00:00 2001
From: Yuri Prezument
Date: Sun, 14 Jul 2013 19:16:56 +0300
Subject: Fix Mixin class name in viewsets docs example

---
 docs/api-guide/viewsets.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

(limited to 'docs/api-guide')

diff --git a/docs/api-guide/viewsets.md b/docs/api-guide/viewsets.md
index 25d11bfb..17c528b3 100644
--- a/docs/api-guide/viewsets.md
+++ b/docs/api-guide/viewsets.md
@@ -205,9 +205,9 @@ You may need to provide custom `ViewSet` classes that do not have the full set o
 
 To create a base viewset class that provides `create`, `list` and `retrieve` operations, inherit from `GenericViewSet`, and mixin the required actions:
 
-    class CreateListRetrieveViewSet(mixins.CreateMixin,
-                                    mixins.ListMixin,
-                                    mixins.RetrieveMixin,
+    class CreateListRetrieveViewSet(mixins.CreateModelMixin,
+                                    mixins.ListModelMixin,
+                                    mixins.RetrieveModelMixin,
                                     viewsets.GenericViewSet):
         """
         A viewset that provides `retrieve`, `update`, and `list` actions.
-- 
cgit v1.2.3


From ae63c49777f4d5b766b85a4b28f6328bd6f9516a Mon Sep 17 00:00:00 2001
From: Tom Christie
Date: Mon, 15 Jul 2013 11:38:38 +0100
Subject: Added test case classes

---
 docs/api-guide/testing.md | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

(limited to 'docs/api-guide')

diff --git a/docs/api-guide/testing.md b/docs/api-guide/testing.md
index aba9283e..40b07763 100644
--- a/docs/api-guide/testing.md
+++ b/docs/api-guide/testing.md
@@ -167,6 +167,36 @@ As usual CSRF validation will only apply to any session authenticated views.  Th
 
 ---
 
+# Test cases
+
+REST framework includes the following test case classes, that mirror the existing Django test case classes, but use `APIClient` instead of Django's default `Client`.
+
+* `APISimpleTestCase`
+* `APITransactionTestCase`
+* `APITestCase`
+* `APILiveServerTestCase`
+
+## Example
+
+You can use any of REST framework's test case classes as you would for the regular Django test case classes.  The `self.client` attribute will be an `APIClient` instance.
+
+    from django.core.urlresolvers import reverse
+    from rest_framework import status
+    from rest_framework.test import APITestCase 
+
+    class AccountTests(APITestCase):
+        def test_create_account(self):
+            """
+            Ensure we can create a new account object.
+            """
+            url = reverse('account-list')
+            data = {'name': 'DabApps'}
+            response = self.client.post(url, data, format='json')
+            self.assertEqual(response.status_code, status.HTTP_201_CREATED)
+            self.assertEqual(response.data, data)
+
+---
+
 # Testing responses
 
 ## Checking the response data
-- 
cgit v1.2.3


From 3eaad89c160c478e3706206535929ad0658ae8c5 Mon Sep 17 00:00:00 2001
From: Tom Christie
Date: Mon, 15 Jul 2013 21:23:34 +0100
Subject: Docs fix

---
 docs/api-guide/viewsets.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

(limited to 'docs/api-guide')

diff --git a/docs/api-guide/viewsets.md b/docs/api-guide/viewsets.md
index 17c528b3..47e59e2b 100644
--- a/docs/api-guide/viewsets.md
+++ b/docs/api-guide/viewsets.md
@@ -99,7 +99,8 @@ For example:
     from django.contrib.auth.models import User
     from rest_framework import viewsets
     from rest_framework.decorators import action
-    from myapp.serializers import UserSerializer
+    from rest_framework.response import Response
+    from myapp.serializers import UserSerializer, PasswordSerializer
 
     class UserViewSet(viewsets.ModelViewSet):
         """
@@ -176,7 +177,7 @@ Note that you can use any of the standard attributes or method overrides provide
         permission_classes = [IsAccountAdminOrReadOnly]
 
         def get_queryset(self):
-            return request.user.accounts.all()
+            return self.request.user.accounts.all()
 
 Also note that although this class provides the complete set of create/list/retrieve/update/destroy actions by default, you can restrict the available operations by using the standard permission classes.
 
-- 
cgit v1.2.3


From b676cce61f364095caa0bdbc46c22cdc87b98646 Mon Sep 17 00:00:00 2001
From: Eric Buehl
Date: Thu, 18 Jul 2013 19:03:38 -0700
Subject: pedantic doc updates

---
 docs/api-guide/viewsets.md | 1 +
 1 file changed, 1 insertion(+)

(limited to 'docs/api-guide')

diff --git a/docs/api-guide/viewsets.md b/docs/api-guide/viewsets.md
index 47e59e2b..0c68afb0 100644
--- a/docs/api-guide/viewsets.md
+++ b/docs/api-guide/viewsets.md
@@ -98,6 +98,7 @@ For example:
 
     from django.contrib.auth.models import User
     from rest_framework import viewsets
+    from rest_framework import status
     from rest_framework.decorators import action
     from rest_framework.response import Response
     from myapp.serializers import UserSerializer, PasswordSerializer
-- 
cgit v1.2.3


From 3fbb4097e64592cd02924302fcb4e63dc1b6062d Mon Sep 17 00:00:00 2001
From: Will Kahn-Greene
Date: Thu, 25 Jul 2013 12:55:03 -0400
Subject: Fix *Throttle class names in the docs

* AnonThrottle -> AnonRateThrottle
* UserThrottle -> UserRateThrottle
* ScopedThrottle -> ScopedRateThrottle
* (cosmetic) removed one errant whitespace character

Fixes #1006.
---
 docs/api-guide/throttling.md | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

(limited to 'docs/api-guide')

diff --git a/docs/api-guide/throttling.md b/docs/api-guide/throttling.md
index d6de85ba..56f32f58 100644
--- a/docs/api-guide/throttling.md
+++ b/docs/api-guide/throttling.md
@@ -12,7 +12,7 @@ As with permissions, multiple throttles may be used.  Your API might have a rest
 
 Another scenario where you might want to use multiple throttles would be if you need to impose different constraints on different parts of the API, due to some services being particularly resource-intensive.
 
-Multiple throttles can also be used if you want to impose both burst throttling  rates, and sustained throttling rates.  For example, you might want to limit a user to a maximum of 60 requests per minute, and 1000 requests per day.
+Multiple throttles can also be used if you want to impose both burst throttling rates, and sustained throttling rates.  For example, you might want to limit a user to a maximum of 60 requests per minute, and 1000 requests per day.
 
 Throttles do not necessarily only refer to rate-limiting requests.  For example a storage service might also need to throttle against bandwidth, and a paid data service might want to throttle against a certain number of a records being accessed.
 
@@ -44,7 +44,7 @@ You can also set the throttling policy on a per-view or per-viewset basis,
 using the `APIView` class based views.
 
     class ExampleView(APIView):
-        throttle_classes = (UserThrottle,)
+        throttle_classes = (UserRateThrottle,)
 
         def get(self, request, format=None):
             content = {
@@ -55,7 +55,7 @@ using the `APIView` class based views.
 Or, if you're using the `@api_view` decorator with function based views.
 
     @api_view('GET')
-    @throttle_classes(UserThrottle)
+    @throttle_classes(UserRateThrottle)
     def example_view(request, format=None):
         content = {
             'status': 'request was permitted'
@@ -72,22 +72,22 @@ The throttle classes provided by REST framework use Django's cache backend.  You
 
 ## AnonRateThrottle
 
-The `AnonThrottle` will only ever throttle unauthenticated users.  The IP address of the incoming request is used to generate a unique key to throttle against.
+The `AnonRateThrottle` will only ever throttle unauthenticated users.  The IP address of the incoming request is used to generate a unique key to throttle against.
 
 The allowed request rate is determined from one of the following (in order of preference).
 
-* The `rate` property on the class, which may be provided by overriding `AnonThrottle` and setting the property.
+* The `rate` property on the class, which may be provided by overriding `AnonRateThrottle` and setting the property.
 * The `DEFAULT_THROTTLE_RATES['anon']` setting.
 
-`AnonThrottle` is suitable if you want to restrict the rate of requests from unknown sources.
+`AnonRateThrottle` is suitable if you want to restrict the rate of requests from unknown sources.
 
 ## UserRateThrottle
 
-The `UserThrottle` will throttle users to a given rate of requests across the API.  The user id is used to generate a unique key to throttle against.  Unauthenticated requests will fall back to using the IP address of the incoming request to generate a unique key to throttle against.
+The `UserRateThrottle` will throttle users to a given rate of requests across the API.  The user id is used to generate a unique key to throttle against.  Unauthenticated requests will fall back to using the IP address of the incoming request to generate a unique key to throttle against.
 
 The allowed request rate is determined from one of the following (in order of preference).
 
-* The `rate` property on the class, which may be provided by overriding `UserThrottle` and setting the property.
+* The `rate` property on the class, which may be provided by overriding `UserRateThrottle` and setting the property.
 * The `DEFAULT_THROTTLE_RATES['user']` setting.
 
 An API may have multiple `UserRateThrottles` in place at the same time.  To do so, override `UserRateThrottle` and set a unique "scope" for each class.
@@ -113,11 +113,11 @@ For example, multiple user throttle rates could be implemented by using the foll
         }
     }
 
-`UserThrottle` is suitable if you want simple global rate restrictions per-user.
+`UserRateThrottle` is suitable if you want simple global rate restrictions per-user.
 
 ## ScopedRateThrottle
 
-The `ScopedThrottle` class can be used to restrict access to specific parts of the API.  This throttle will only be applied if the view that is being accessed includes a `.throttle_scope` property.  The unique throttle key will then be formed by concatenating the "scope" of the request with the unique user id or IP address.
+The `ScopedRateThrottle` class can be used to restrict access to specific parts of the API.  This throttle will only be applied if the view that is being accessed includes a `.throttle_scope` property.  The unique throttle key will then be formed by concatenating the "scope" of the request with the unique user id or IP address.
 
 The allowed request rate is determined by the `DEFAULT_THROTTLE_RATES` setting using a key from the request "scope".
 
-- 
cgit v1.2.3


From 5c4bf5309d2e952fb33c27778ff1f1213ebfd5e0 Mon Sep 17 00:00:00 2001
From: Tom Christie
Date: Mon, 29 Jul 2013 09:08:35 +0100
Subject: Docs about migrations and `post_save`.

Documentation detailing requirement to migrate prior to running `createsuperuser` if using an authtoken `post_save` signal.
Closes #987.  Thanks to @yprez.
---
 docs/api-guide/authentication.md | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

(limited to 'docs/api-guide')

diff --git a/docs/api-guide/authentication.md b/docs/api-guide/authentication.md
index 5d6e0d91..ee1282b5 100755
--- a/docs/api-guide/authentication.md
+++ b/docs/api-guide/authentication.md
@@ -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 not 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.
-- 
cgit v1.2.3


From 856dc855c952746f566a6a8de263afe951362dfb Mon Sep 17 00:00:00 2001
From: Tom Christie
Date: Mon, 29 Jul 2013 09:21:20 +0100
Subject: Notes on customizing BrowsableAPIRenderer.  Refs #1001

---
 docs/api-guide/renderers.md | 8 ++++++++
 1 file changed, 8 insertions(+)

(limited to 'docs/api-guide')

diff --git a/docs/api-guide/renderers.md b/docs/api-guide/renderers.md
index 869bdc16..b434efe9 100644
--- a/docs/api-guide/renderers.md
+++ b/docs/api-guide/renderers.md
@@ -217,6 +217,14 @@ 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].
-- 
cgit v1.2.3


From 1a4ff1567ea4231cde9a2f23725550a754f3f54c Mon Sep 17 00:00:00 2001
From: James Rutherford
Date: Mon, 29 Jul 2013 10:16:15 +0100
Subject: Updated authtoken docs to mention south migrations

---
 docs/api-guide/authentication.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'docs/api-guide')

diff --git a/docs/api-guide/authentication.md b/docs/api-guide/authentication.md
index ee1282b5..fd6bfb56 100755
--- a/docs/api-guide/authentication.md
+++ b/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.
 
-- 
cgit v1.2.3


From 195b1af7ba34b833fc17f5693d7fbd9c8e7cce78 Mon Sep 17 00:00:00 2001
From: James Rutherford
Date: Mon, 29 Jul 2013 10:16:51 +0100
Subject: Minor typo fix

---
 docs/api-guide/authentication.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'docs/api-guide')

diff --git a/docs/api-guide/authentication.md b/docs/api-guide/authentication.md
index fd6bfb56..b1ab4622 100755
--- a/docs/api-guide/authentication.md
+++ b/docs/api-guide/authentication.md
@@ -203,7 +203,7 @@ 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 not 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:
+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
-- 
cgit v1.2.3