diff --git a/api-guide/authentication.html b/api-guide/authentication.html
index 09d6a22b0..d04b3f1ba 100644
--- a/api-guide/authentication.html
+++ b/api-guide/authentication.html
@@ -73,7 +73,7 @@
Topics
from django.utils.encoding import smart_unicode
from rest_framework import renderers
@@ -234,11 +234,19 @@ class PlainText(renderers.BaseRenderer):
media_type = 'text/plain'
format = 'txt'
- def render(self, data, media_type):
+ def render(self, data, media_type=None, renderer_context=None):
if isinstance(data, basestring):
return data
return smart_unicode(data)
+The arguments passed to the .render() method are:
+data
+The request data, as set by the Response() instantiation.
+
+Optional. If provided, this is the accepted media type, as determined by the content negotiation stage. Depending on the client's Accept: header, this may be more specific than the renderer's media_type attribute, and may include media type parameters. For example "application/json; nested=true".
+renderer_context=None
+Optional. If provided, this is a dictionary of contextual information provided by the view.
+By default this will include the following keys: view, request, response, args, kwargs.
Advanced renderer usage
You can do some pretty flexible things using REST framework's renderers. Some examples...
diff --git a/api-guide/requests.html b/api-guide/requests.html
index c96a9107a..62adc621d 100644
--- a/api-guide/requests.html
+++ b/api-guide/requests.html
@@ -73,7 +73,7 @@
Topics
+For more details see the parsers documentation.
.FILES
request.FILES returns any uploaded files that may be present in the content of the request body. This is the same as the standard HttpRequest behavior, except that the same flexible request parsing that is used for request.DATA.
-This allows you to support file uploads from multiple content-types. For example you can write a parser that supports POSTing the raw content of a file, instead of using form-encoded file uploads.
-.user
-request.user returns a django.contrib.auth.models.User instance.
-.auth
-request.auth returns any additional authentication context that may not be contained in request.user. The exact behavior of request.auth depends on what authentication has been set in request.authentication. For many types of authentication this will simply be None, but it may also be an object representing a permission scope, an expiry time, or any other information that might be contained in a token-based authentication scheme.
+For more details see the parsers documentation.
+.QUERY_PARAMS
+request.QUERY_PARAMS is a more correcly named synonym for request.GET.
+For clarity inside your code, we recommend using request.QUERY_PARAMS instead of the usual request.GET, as any HTTP method type may include query parameters.
.parsers
-request.parsers should be set to a list of Parser instances that can be used to parse the content of the request body.
-request.parsers may no longer be altered once request.DATA, request.FILES or request.POST have been accessed.
-If you're using the rest_framework.views.View class... [TODO]
+The APIView class or @api_view decorator will ensure that this property is automatically to a list of Parser instances, based on the parser_classes set on the view or based on the DEFAULT_PARSERS setting.
+You won't typically need to access this property.
+
+Note: If a client sends malformed content, then accessing request.DATA or request.FILES may raise a ParseError. By default REST framework's APIView class or @api_view decorator will catch the error and return a 400 Bad Request response.
+
+Authentication
+REST framework provides flexbile, per-request authentication, that gives you the abilty to:
+
+- Use different authentication policies for different parts of your API.
+- Support the use of multiple authentication policies.
+- Provide both user and token information associated with the incoming request.
+
+.user
+request.user typically returns an instance of django.contrib.auth.models.User, although the behavior depends on the authentication policy being used.
+If the request is unauthenticated the default value of request.user is an instance of django.contrib.auth.models.AnonymousUser.
+For more details see the authentication documentation.
+.auth
+request.auth returns any additional authentication context. The exact behavior of request.auth depends on the authentication policy being used, but it may typically be an instance of the token that the request was authenticated against.
+If the request is unauthenticated, or if no additional context is present, the default value of request.auth is None.
+For more details see the authentication documentation.
+.authenticators
+The APIView class or @api_view decorator will ensure that this property is automatically to a list of Authentication instances, based on the authentication_classes set on the view or based on the DEFAULT_AUTHENTICATORS setting.
+You won't typically need to access this property.
+
+Browser enhancments
+REST framework supports a few browser enhancments such as broser-based PUT and DELETE forms.
+.method
+request.method returns the uppercased string representation of the request's HTTP method.
+Browser-based PUT and DELETE forms are transparently supported.
+For more information see the browser enhancements documentation.
+
+.content_type
+request.content_type, returns a string object representing the media type of the HTTP request's body, or an empty string if no media type was provided.
+You won't typically need to directly access the request's content type, as you'll normally rely on REST framework's default request parsing behavior.
+If you do need to access the content type of the request you should use the .content_type property in preference to using request.META.get('HTTP_CONTENT_TYPE'), as it provides transparent support for browser-based non-form content.
+For more information see the browser enhancements documentation.
+
.stream
request.stream returns a stream representing the content of the request body.
-You will not typically need to access request.stream, unless you're writing a Parser class.
-.authentication
-request.authentication should be set to a list of Authentication instances that can be used to authenticate the request.
-request.authentication may no longer be altered once request.user or request.auth have been accessed.
-If you're using the rest_framework.views.View class... [TODO]
+You won't typically need to directly access the request's content, as you'll normally rely on REST framework's default request parsing behavior.
+If you do need to access the raw content directly, you should use the .stream property in preference to using request.content, as it provides transparent support for browser-based non-form content.
+For more information see the browser enhancements documentation.
+
diff --git a/api-guide/responses.html b/api-guide/responses.html
index 23d03afd8..a0ea0d7e7 100644
--- a/api-guide/responses.html
+++ b/api-guide/responses.html
@@ -73,7 +73,7 @@
Topics
@@ -178,6 +179,9 @@ response['Cache-Control'] = 'no-cache'
Set automatically by the APIView or @api_view immediately before the response is returned from the view.
The media type that was selected by the content negotiation stage.
+Set automatically by the APIView or @api_view immediately before the response is returned from the view.
+.renderer_context
+A dictionary of additional context information that will be passed to the renderer's .render() method.
Set automatically by the APIView or @api_view immediately before the response is returned from the view.
diff --git a/api-guide/reverse.html b/api-guide/reverse.html
index 30cb1903d..9f3e7ce63 100644
--- a/api-guide/reverse.html
+++ b/api-guide/reverse.html
@@ -73,7 +73,7 @@
Topics