Version 3.5 (#4525)

* Start test case

* Added 'requests' test client

* Address typos

* Graceful fallback if requests is not installed.

* Add cookie support

* Tests for auth and CSRF

* Py3 compat

* py3 compat

* py3 compat

* Add get_requests_client

* Added SchemaGenerator.should_include_link

* add settings for html cutoff on related fields

* Router doesn't work if prefix is blank, though project urls.py handles prefix

* Fix Django 1.10 to-many deprecation

* Add django.core.urlresolvers compatibility

* Update django-filter & django-guardian

* Check for empty router prefix; adjust URL accordingly

It's easiest to fix this issue after we have made the regex.  To try
to fix it before would require doing something different for List vs
Detail, which means we'd have to know which type of url we're
constructing before acting accordingly.

* Fix misc django deprecations

* Use TOC extension instead of header

* Fix deprecations for py3k

* Add py3k compatibility to is_simple_callable

* Add is_simple_callable tests

* Drop python 3.2 support (EOL, Dropped by Django)

* schema_renderers= should *set* the renderers, not append to them.

* API client (#4424)

* Fix release notes

* Add note about 'User account is disabled.' vs 'Unable to log in'

* Clean up schema generation (#4527)

* Handle multiple methods on custom action (#4529)

* RequestsClient, CoreAPIClient

* exclude_from_schema

* Added 'get_schema_view()' shortcut

* Added schema descriptions

* Better descriptions for schemas

* Add type annotation to schema generation

* Coerce schema 'pk' in path to actual field name

* Deprecations move into assertion errors

* Use get_schema_view in tests

* Updte CoreJSON media type

* Handle schema structure correctly when path prefixs exist. Closes #4401

* Add PendingDeprecation to Router schema generation.

* Added SCHEMA_COERCE_PATH_PK and SCHEMA_COERCE_METHOD_NAMES

* Renamed and documented 'get_schema_fields' interface.

Author: lovelydinosaur

.travis.yml

@@ -14,7 +14,6 @@ env:
     - TOX_ENV=py35-django18
     - TOX_ENV=py34-django18
     - TOX_ENV=py33-django18
-    - TOX_ENV=py32-django18
     - TOX_ENV=py27-django18
     - TOX_ENV=py27-django110
     - TOX_ENV=py35-django110

docs/api-guide/filtering.md

@@ -416,6 +416,12 @@ Generic filters may also present an interface in the browsable API. To do so you
 
 The method should return a rendered HTML string.
 
+## Pagination & schemas
+
+You can also make the filter controls available to the schema autogeneration
+that REST framework provides, by implementing a `get_schema_fields()` method,
+which should return a list of `coreapi.Field` instances.
+
 # Third party packages
 
 The following third party packages provide additional filter implementations.

docs/api-guide/pagination.md

@@ -276,6 +276,12 @@ To have your custom pagination class be used by default, use the `DEFAULT_PAGINA
 
 API responses for list endpoints will now include a `Link` header, instead of including the pagination links as part of the body of the response, for example:
 
+## Pagination & schemas
+
+You can also make the pagination controls available to the schema autogeneration
+that REST framework provides, by implementing a `get_schema_fields()` method,
+which should return a list of `coreapi.Field` instances.
+
 ---
 
 ![Link Header][link-header]

docs/api-guide/relations.md

@@ -463,6 +463,8 @@ There are two keyword arguments you can use to control this behavior:
 - `html_cutoff` - If set this will be the maximum number of choices that will be displayed by a HTML select drop down. Set to `None` to disable any limiting. Defaults to `1000`.
 - `html_cutoff_text` - If set this will display a textual indicator if the maximum number of items have been cutoff in an HTML select drop down. Defaults to `"More than {count} items…"`
 
+You can also control these globally using the settings `HTML_SELECT_CUTOFF` and `HTML_SELECT_CUTOFF_TEXT`.
+
 In cases where the cutoff is being enforced you may want to instead use a plain input field in the HTML form. You can do so using the `style` keyword argument. For example:
 
     assigned_to = serializers.SlugRelatedField(

docs/api-guide/reverse.md

@@ -23,7 +23,7 @@ There's no requirement for you to use them, but if you do then the self-describi
 
 **Signature:** `reverse(viewname, *args, **kwargs)`
 
-Has the same behavior as [`django.core.urlresolvers.reverse`][reverse], except that it returns a fully qualified URL, using the request to determine the host and port.
+Has the same behavior as [`django.urls.reverse`][reverse], except that it returns a fully qualified URL, using the request to determine the host and port.
 
 You should **include the request as a keyword argument** to the function, for example:
 
@@ -44,7 +44,7 @@ You should **include the request as a keyword argument** to the function, for ex
 
 **Signature:** `reverse_lazy(viewname, *args, **kwargs)`
 
-Has the same behavior as [`django.core.urlresolvers.reverse_lazy`][reverse-lazy], except that it returns a fully qualified URL, using the request to determine the host and port.
+Has the same behavior as [`django.urls.reverse_lazy`][reverse-lazy], except that it returns a fully qualified URL, using the request to determine the host and port.
 
 As with the `reverse` function, you should **include the request as a keyword argument** to the function, for example:
 

docs/api-guide/schemas.md

@@ -102,15 +102,20 @@ REST framework includes functionality for auto-generating a schema,
 or allows you to specify one explicitly. There are a few different ways to
 add a schema to your API, depending on exactly what you need.
 
-## Using DefaultRouter
+## The get_schema_view shortcut
 
-If you're using `DefaultRouter` then you can include an auto-generated schema,
-simply by adding a `schema_title` argument to the router.
+The simplest way to include a schema in your project is to use the
+`get_schema_view()` function.
 
-    router = DefaultRouter(schema_title='Server Monitoring API')
+    schema_view = get_schema_view(title="Server Monitoring API")
 
-The schema will be included at the root URL, `/`, and presented to clients
-that include the Core JSON media type in their `Accept` header.
+    urlpatterns = [
+        url('^$', schema_view),
+        ...
+    ]
+
+Once the view has been added, you'll be able to make API requests to retrieve
+the auto-generated schema definition.
 
     $ http http://127.0.0.1:8000/ Accept:application/vnd.coreapi+json
     HTTP/1.0 200 OK
@@ -125,48 +130,43 @@ that include the Core JSON media type in their `Accept` header.
         ...
     }
 
-This is a great zero-configuration option for when you want to get up and
-running really quickly.
-
-The other available options to `DefaultRouter` are:
+The arguments to `get_schema_view()` are:
 
-#### schema_renderers
-
-May be used to pass the set of renderer classes that can be used to render schema output.
-
-    from rest_framework.renderers import CoreJSONRenderer
-    from my_custom_package import APIBlueprintRenderer
+#### `title`
 
-    router = DefaultRouter(schema_title='Server Monitoring API', schema_renderers=[
-        CoreJSONRenderer, APIBlueprintRenderer
-    ])
+May be used to provide a descriptive title for the schema definition.
 
-#### schema_url
+#### `url`
 
-May be used to pass the root URL for the schema. This can either be used to ensure that
-the schema URLs include a canonical hostname and schema, or to ensure that all the
-schema URLs include a path prefix.
+May be used to pass a canonical URL for the schema.
 
-    router = DefaultRouter(
-        schema_title='Server Monitoring API',
-        schema_url='https://www.example.org/api/'
+    schema_view = get_schema_view(
+        title='Server Monitoring API',
+        url='https://www.example.org/api/'
     )
 
-If you want more flexibility over the schema output then you'll need to consider
-using `SchemaGenerator` instead.
-
-#### root_renderers
+#### `renderer_classes`
 
 May be used to pass the set of renderer classes that can be used to render the API root endpoint.
 
-## Using SchemaGenerator
+    from rest_framework.renderers import CoreJSONRenderer
+    from my_custom_package import APIBlueprintRenderer
 
-The most common way to add a schema to your API is to use the `SchemaGenerator`
-class to auto-generate the `Document` instance, and to return that from a view.
+    schema_view = get_schema_view(
+        title='Server Monitoring API',
+        url='https://www.example.org/api/',
+        renderer_classes=[CoreJSONRenderer, APIBlueprintRenderer]
+    )
+
+## Using an explicit schema view
+
+If you need a little more control than the `get_schema_view()` shortcut gives you,
+then you can use the `SchemaGenerator` class directly to auto-generate the
+`Document` instance, and to return that from a view.
 
 This option gives you the flexibility of setting up the schema endpoint
-with whatever behavior you want. For example, you can apply different
-permission, throttling or authentication policies to the schema endpoint.
+with whatever behaviour you want. For example, you can apply different
+permission, throttling, or authentication policies to the schema endpoint.
 
 Here's an example of using `SchemaGenerator` together with a view to
 return the schema.
@@ -176,12 +176,13 @@ return the schema.
     from rest_framework.decorators import api_view, renderer_classes
     from rest_framework import renderers, response, schemas
 
+    generator = schemas.SchemaGenerator(title='Bookings API')
 
     @api_view()
     @renderer_classes([renderers.CoreJSONRenderer])
     def schema_view(request):
-        generator = schemas.SchemaGenerator(title='Bookings API')
-        return response.Response(generator.get_schema())
+        schema = generator.get_schema(request)
+        return response.Response(schema)
 
 **urls.py:**
 
@@ -241,6 +242,69 @@ You could then either:
 
 ---
 
+# Schemas as documentation
+
+One common usage of API schemas is to use them to build documentation pages.
+
+The schema generation in REST framework uses docstrings to automatically
+populate descriptions in the schema document.
+
+These descriptions will be based on:
+
+* The corresponding method docstring if one exists.
+* A named section within the class docstring, which can be either single line or multi-line.
+* The class docstring.
+
+## Examples
+
+An `APIView`, with an explicit method docstring.
+
+    class ListUsernames(APIView):
+        def get(self, request):
+            """
+            Return a list of all user names in the system.
+            """
+            usernames = [user.username for user in User.objects.all()]
+            return Response(usernames)
+
+A `ViewSet`, with an explict action docstring.
+
+    class ListUsernames(ViewSet):
+        def list(self, request):
+            """
+            Return a list of all user names in the system.
+            """
+            usernames = [user.username for user in User.objects.all()]
+            return Response(usernames)
+
+A generic view with sections in the class docstring, using single-line style.
+
+    class UserList(generics.ListCreateAPIView):
+        """
+        get: Create a new user.
+        post: List all the users.
+        """
+        queryset = User.objects.all()
+        serializer_class = UserSerializer
+        permission_classes = (IsAdminUser,)
+
+A generic viewset with sections in the class docstring, using multi-line style.
+
+    class UserViewSet(viewsets.ModelViewSet):
+        """
+        API endpoint that allows users to be viewed or edited.
+
+        retrieve:
+        Return a user instance.
+
+        list:
+        Return all users, ordered by most recently joined.
+        """
+        queryset = User.objects.all().order_by('-date_joined')
+        serializer_class = UserSerializer
+
+---
+
 # Alternate schema formats
 
 In order to support an alternate schema format, you need to implement a custom renderer

docs/api-guide/settings.md

@@ -234,6 +234,28 @@ Default:
 
 ---
 
+## Schema generation controls
+
+#### SCHEMA_COERCE_PATH_PK
+
+If set, this maps the `'pk'` identifier in the URL conf onto the actual field
+name when generating a schema path parameter. Typically this will be `'id'`.
+This gives a more suitable representation as "primary key" is an implementation
+detail, wheras "identifier" is a more general concept.
+
+Default: `True`
+
+#### SCHEMA_COERCE_METHOD_NAMES
+
+If set, this is used to map internal viewset method names onto external action
+names used in the schema generation. This allows us to generate names that
+are more suitable for an external representation than those that are used
+internally in the codebase.
+
+Default: `{'retrieve': 'read', 'destroy': 'delete'}`
+
+---
+
 ## Content type controls
 
 #### URL_FORMAT_OVERRIDE
@@ -382,6 +404,22 @@ This should be a function with the following signature:
 
 Default: `'rest_framework.views.get_view_description'`
 
+## HTML Select Field cutoffs
+
+Global settings for [select field cutoffs for rendering relational fields](relations.md#select-field-cutoffs) in the browsable API.
+
+#### HTML_SELECT_CUTOFF
+
+Global setting for the `html_cutoff` value.  Must be an integer.
+
+Default: 1000
+
+#### HTML_SELECT_CUTOFF_TEXT
+
+A string representing a global setting for `html_cutoff_text`.
+
+Default: `"More than {count} items..."`
+
 ---
 
 ## Miscellaneous settings