Merge branch 'master' of https://github.com/encode/django-rest-framework

.github/FUNDING.yml

@@ -0,0 +1 @@
+custom: https://fund.django-rest-framework.org/topics/funding/

.travis.yml

@@ -5,9 +5,6 @@ matrix:
     fast_finish: true
     include:
 
-      - { python: "3.4", env: DJANGO=1.11 }
-      - { python: "3.4", env: DJANGO=2.0 }
-
       - { python: "3.5", env: DJANGO=1.11 }
       - { python: "3.5", env: DJANGO=2.0 }
       - { python: "3.5", env: DJANGO=2.1 }

README.md

@@ -24,10 +24,10 @@ The initial aim is to provide a single full-time position on REST framework.
 [![][rollbar-img]][rollbar-url]
 [![][cadre-img]][cadre-url]
 [![][kloudless-img]][kloudless-url]
-[![][release-history-img]][release-history-url]
+[![][esg-img]][esg-url]
 [![][lightson-img]][lightson-url]
 
-Many thanks to all our [wonderful sponsors][sponsors], and in particular to our premium backers, [Sentry][sentry-url], [Stream][stream-url], [Rollbar][rollbar-url], [Cadre][cadre-url], [Kloudless][kloudless-url], [Release History][release-history-url], and [Lights On Software][lightson-url].
+Many thanks to all our [wonderful sponsors][sponsors], and in particular to our premium backers, [Sentry][sentry-url], [Stream][stream-url], [Rollbar][rollbar-url], [Cadre][cadre-url], [Kloudless][kloudless-url], [ESG][esg-url], and [Lights On Software][lightson-url].
 
 ---
 
@@ -53,7 +53,7 @@ There is a live example API for testing purposes, [available here][sandbox].
 
 # Requirements
 
-* Python (3.4, 3.5, 3.6, 3.7)
+* Python (3.5, 3.6, 3.7)
 * Django (1.11, 2.0, 2.1, 2.2)
 
 We **highly recommend** and only officially support the latest patch release of
@@ -67,10 +67,10 @@ Install using `pip`...
 
 Add `'rest_framework'` to your `INSTALLED_APPS` setting.
 
-    INSTALLED_APPS = (
+    INSTALLED_APPS = [
         ...
         'rest_framework',
-    )
+    ]
 
 # Example
 
@@ -96,7 +96,7 @@ from rest_framework import serializers, viewsets, routers
 class UserSerializer(serializers.HyperlinkedModelSerializer):
     class Meta:
         model = User
-        fields = ('url', 'username', 'email', 'is_staff')
+        fields = ['url', 'username', 'email', 'is_staff']
 
 
 # ViewSets define the view behavior.
@@ -123,10 +123,10 @@ We'd also like to configure a couple of settings for our API.
 Add the following to your `settings.py` module:
 
 ```python
-INSTALLED_APPS = (
+INSTALLED_APPS = [
     ...  # Make sure to include the default installed apps here.
     'rest_framework',
-)
+]
 
 REST_FRAMEWORK = {
     # Use Django's standard `django.contrib.auth` permissions,
@@ -175,9 +175,7 @@ You may also want to [follow the author on Twitter][twitter].
 
 # Security
 
-If you believe you've found something in Django REST framework which has security implications, please **do not raise the issue in a public forum**.
+Please see the [security policy][security-policy].
-
-Send a description of the issue via email to [rest-framework-security@googlegroups.com][security-mail].  The project maintainers will then work with you to resolve any issues where required, prior to any public disclosure.
 
 [build-status-image]: https://secure.travis-ci.org/encode/django-rest-framework.svg?branch=master
 [travis]: https://travis-ci.org/encode/django-rest-framework?branch=master
@@ -199,17 +197,15 @@ Send a description of the issue via email to [rest-framework-security@googlegrou
 [cadre-img]: https://raw.githubusercontent.com/encode/django-rest-framework/master/docs/img/premium/cadre-readme.png
 [load-impact-img]: https://raw.githubusercontent.com/encode/django-rest-framework/master/docs/img/premium/load-impact-readme.png
 [kloudless-img]: https://raw.githubusercontent.com/encode/django-rest-framework/master/docs/img/premium/kloudless-readme.png
-[release-history-img]: https://raw.githubusercontent.com/encode/django-rest-framework/master/docs/img/premium/release-history.png
+[esg-img]: https://raw.githubusercontent.com/encode/django-rest-framework/master/docs/img/premium/esg-readme.png
 [lightson-img]: https://raw.githubusercontent.com/encode/django-rest-framework/master/docs/img/premium/lightson-readme.png
 
-[rover-url]: http://jobs.rover.com/
 [sentry-url]: https://getsentry.com/welcome/
 [stream-url]: https://getstream.io/try-the-api/?utm_source=drf&utm_medium=banner&utm_campaign=drf
-[rollbar-url]: https://rollbar.com/
+[rollbar-url]: https://rollbar.com/?utm_source=django&utm_medium=sponsorship&utm_campaign=freetrial
 [cadre-url]: https://cadre.com/
-[load-impact-url]: https://loadimpact.com/?utm_campaign=Sponsorship%20links&utm_source=drf&utm_medium=drf
 [kloudless-url]: https://hubs.ly/H0f30Lf0
-[release-history-url]: https://releasehistory.io
+[esg-url]: https://software.esg-usa.com/
 [lightson-url]: https://lightsonsoftware.com
 
 [oauth1-section]: https://www.django-rest-framework.org/api-guide/authentication/#django-rest-framework-oauth
@@ -225,4 +221,4 @@ Send a description of the issue via email to [rest-framework-security@googlegrou
 [image]: https://www.django-rest-framework.org/img/quickstart.png
 
 [docs]: https://www.django-rest-framework.org/
-[security-mail]: mailto:rest-framework-security@googlegroups.com
+[security-policy]: https://github.com/encode/django-rest-framework/security/policy

SECURITY.md

@@ -0,0 +1,9 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+If you believe you've found something in Django REST framework which has security implications, please **do not raise the issue in a public forum**.
+
+Send a description of the issue via email to [rest-framework-security@googlegroups.com][security-mail].  The project maintainers will then work with you to resolve any issues where required, prior to any public disclosure.
+
+[security-mail]: mailto:rest-framework-security@googlegroups.com

docs/api-guide/authentication.md

@@ -1,4 +1,7 @@
-source: authentication.py
+---
+source:
+    - authentication.py
+---
 
 # Authentication
 
@@ -37,10 +40,10 @@ The value of `request.user` and `request.auth` for unauthenticated requests can
 The default authentication schemes may be set globally, using the `DEFAULT_AUTHENTICATION_CLASSES` setting.  For example.
 
     REST_FRAMEWORK = {
-        'DEFAULT_AUTHENTICATION_CLASSES': (
+        'DEFAULT_AUTHENTICATION_CLASSES': [
             'rest_framework.authentication.BasicAuthentication',
             'rest_framework.authentication.SessionAuthentication',
-        )
+        ]
     }
 
 You can also set the authentication scheme on a per-view or per-viewset basis,
@@ -52,8 +55,8 @@ using the `APIView` class-based views.
     from rest_framework.views import APIView
 
     class ExampleView(APIView):
-        authentication_classes = (SessionAuthentication, BasicAuthentication)
+        authentication_classes = [SessionAuthentication, BasicAuthentication]
-        permission_classes = (IsAuthenticated,)
+        permission_classes = [IsAuthenticated]
 
         def get(self, request, format=None):
             content = {
@@ -65,8 +68,8 @@ using the `APIView` class-based views.
 Or, if you're using the `@api_view` decorator with function based views.
 
     @api_view(['GET'])
-    @authentication_classes((SessionAuthentication, BasicAuthentication))
+    @authentication_classes([SessionAuthentication, BasicAuthentication])
-    @permission_classes((IsAuthenticated,))
+    @permission_classes([IsAuthenticated])
     def example_view(request, format=None):
         content = {
             'user': unicode(request.user),  # `django.contrib.auth.User` instance.
@@ -121,10 +124,10 @@ This authentication scheme uses a simple token-based HTTP Authentication scheme.
 
 To use the `TokenAuthentication` scheme you'll need to [configure the authentication classes](#setting-the-authentication-scheme) to include `TokenAuthentication`, and additionally include `rest_framework.authtoken` in your `INSTALLED_APPS` setting:
 
-    INSTALLED_APPS = (
+    INSTALLED_APPS = [
         ...
         'rest_framework.authtoken'
-    )
+    ]
 
 ---
 
@@ -247,7 +250,7 @@ It is also possible to create Tokens manually through admin interface. In case y
 
     from rest_framework.authtoken.admin import TokenAdmin
 
-    TokenAdmin.raw_id_fields = ('user',)
+    TokenAdmin.raw_id_fields = ['user']
 
 
 #### Using Django manage.py command
@@ -321,13 +324,13 @@ If the `.authenticate_header()` method is not overridden, the authentication sch
 
 ---
 
-**Note:** When your custom authenticator is invoked by the request object's `.user` or `.auth` properties, you may see an `AttributeError` re-raised as a `WrappedAttributeError`. This is necessary to prevent the original exception from being suppressed by the outer property access. Python will not recognize that the `AttributeError` orginates from your custom authenticator and will instead assume that the request object does not have a `.user` or `.auth` property. These errors should be fixed or otherwise handled by your authenticator.
+**Note:** When your custom authenticator is invoked by the request object's `.user` or `.auth` properties, you may see an `AttributeError` re-raised as a `WrappedAttributeError`. This is necessary to prevent the original exception from being suppressed by the outer property access. Python will not recognize that the `AttributeError` originates from your custom authenticator and will instead assume that the request object does not have a `.user` or `.auth` property. These errors should be fixed or otherwise handled by your authenticator.
 
 ---
 
 ## Example
 
-The following example will authenticate any incoming request as the user given by the username in a custom request header named 'X_USERNAME'.
+The following example will authenticate any incoming request as the user given by the username in a custom request header named 'X-USERNAME'.
 
 	from django.contrib.auth.models import User
     from rest_framework import authentication
@@ -335,7 +338,7 @@ The following example will authenticate any incoming request as the user given b
 
     class ExampleAuthentication(authentication.BaseAuthentication):
         def authenticate(self, request):
-            username = request.META.get('X_USERNAME')
+            username = request.META.get('HTTP_X_USERNAME')
             if not username:
                 return None
 
@@ -364,15 +367,15 @@ Install using `pip`.
 
 Add the package to your `INSTALLED_APPS` and modify your REST framework settings.
 
-    INSTALLED_APPS = (
+    INSTALLED_APPS = [
         ...
         'oauth2_provider',
-    )
+    ]
 
     REST_FRAMEWORK = {
-        'DEFAULT_AUTHENTICATION_CLASSES': (
+        'DEFAULT_AUTHENTICATION_CLASSES': [
             'oauth2_provider.contrib.rest_framework.OAuth2Authentication',
-        )
+        ]
     }
 
 For more details see the [Django REST framework - Getting started][django-oauth-toolkit-getting-started] documentation.

docs/api-guide/caching.md

@@ -1,6 +1,6 @@
 # Caching
 
-> A certain woman had a very sharp conciousness but almost no
+> A certain woman had a very sharp consciousness but almost no
 > memory ... She remembered enough to work, and she worked hard.
 > - Lydia Davis
 

docs/api-guide/content-negotiation.md

@@ -1,4 +1,7 @@
-source: negotiation.py
+---
+source:
+    - negotiation.py
+---
 
 # Content negotiation
 

docs/api-guide/exceptions.md

@@ -1,4 +1,7 @@
-source: exceptions.py
+---
+source:
+    - exceptions.py
+---
 
 # Exceptions
 

docs/api-guide/fields.md

@@ -1,4 +1,7 @@
-source: fields.py
+---
+source:
+    - fields.py
+---
 
 # Serializer fields
 
@@ -209,7 +212,7 @@ A field that ensures the input is a valid UUID string. The `to_internal_value` m
 **Signature:** `UUIDField(format='hex_verbose')`
 
 - `format`: Determines the representation format of the uuid value
-    - `'hex_verbose'` - The cannoncical hex representation, including hyphens: `"5ce0e9a5-5ffa-654b-cee0-1238041fb31a"`
+    - `'hex_verbose'` - The canonical hex representation, including hyphens: `"5ce0e9a5-5ffa-654b-cee0-1238041fb31a"`
     - `'hex'` - The compact hex representation of the UUID, not including hyphens: `"5ce0e9a55ffa654bcee01238041fb31a"`
     - `'int'` - A 128 bit integer representation of the UUID: `"123456789012312313134124512351145145114"`
     - `'urn'` - RFC 4122 URN representation of the UUID: `"urn:uuid:5ce0e9a5-5ffa-654b-cee0-1238041fb31a"`
@@ -448,9 +451,10 @@ Requires either the `Pillow` package or `PIL` package.  The `Pillow` package is
 
 A field class that validates a list of objects.
 
-**Signature**: `ListField(child=<A_FIELD_INSTANCE>, min_length=None, max_length=None)`
+**Signature**: `ListField(child=<A_FIELD_INSTANCE>, allow_empty=True, min_length=None, max_length=None)`
 
 - `child` - A field instance that should be used for validating the objects in the list. If this argument is not provided then objects in the list will not be validated.
+- `allow_empty` - Designates if empty lists are allowed.
 - `min_length` - Validates that the list contains no fewer than this number of elements.
 - `max_length` - Validates that the list contains no more than this number of elements.
 
@@ -471,9 +475,10 @@ We can now reuse our custom `StringListField` class throughout our application,
 
 A field class that validates a dictionary of objects. The keys in `DictField` are always assumed to be string values.
 
-**Signature**: `DictField(child=<A_FIELD_INSTANCE>)`
+**Signature**: `DictField(child=<A_FIELD_INSTANCE>, allow_empty=True)`
 
 - `child` - A field instance that should be used for validating the values in the dictionary. If this argument is not provided then values in the mapping will not be validated.
+- `allow_empty` - Designates if empty dictionaries are allowed.
 
 For example, to create a field that validates a mapping of strings to strings, you would write something like this:
 
@@ -488,9 +493,10 @@ You can also use the declarative style, as with `ListField`. For example:
 
 A preconfigured `DictField` that is compatible with Django's postgres `HStoreField`.
 
-**Signature**: `HStoreField(child=<A_FIELD_INSTANCE>)`
+**Signature**: `HStoreField(child=<A_FIELD_INSTANCE>, allow_empty=True)`
 
 - `child` - A field instance that is used for validating the values in the dictionary. The default child field accepts both empty strings and null values.
+- `allow_empty` - Designates if empty dictionaries are allowed.
 
 Note that the child field **must** be an instance of `CharField`, as the hstore extension stores values as strings.
 
@@ -498,9 +504,10 @@ Note that the child field **must** be an instance of `CharField`, as the hstore
 
 A field class that validates that the incoming data structure consists of valid JSON primitives. In its alternate binary mode, it will represent and validate JSON-encoded binary strings.
 
-**Signature**: `JSONField(binary)`
+**Signature**: `JSONField(binary, encoder)`
 
 - `binary` - If set to `True` then the field will output and validate a JSON encoded string, rather than a primitive data structure. Defaults to `False`.
+- `encoder` - Use this JSON encoder to serialize input object. Defaults to `None`.
 
 ---
 
@@ -519,7 +526,7 @@ For example, if `has_expired` was a property on the `Account` model, then the fo
     class AccountSerializer(serializers.ModelSerializer):
         class Meta:
             model = Account
-            fields = ('id', 'account_name', 'has_expired')
+            fields = ['id', 'account_name', 'has_expired']
 
 ## HiddenField
 
@@ -718,7 +725,7 @@ to the desired output.
         >>> instance = DataPoint(label='Example', x_coordinate=1, y_coordinate=2)
         >>> out_serializer = DataPointSerializer(instance)
         >>> out_serializer.data
-        ReturnDict([('label', 'testing'), ('coordinates', {'x': 1, 'y': 2})])
+        ReturnDict([('label', 'Example'), ('coordinates', {'x': 1, 'y': 2})])
 
 * Unless our field is to be read-only, `to_internal_value` must map back to a dict
 suitable for updating our target object. With `source='*'`, the return from

docs/api-guide/filtering.md

@@ -1,4 +1,7 @@
-source: filters.py
+---
+source:
+    - filters.py
+---
 
 # Filtering
 
@@ -92,7 +95,7 @@ Generic filters can also present themselves as HTML controls in the browsable AP
 The default filter backends may be set globally, using the `DEFAULT_FILTER_BACKENDS` setting. For example.
 
     REST_FRAMEWORK = {
-        'DEFAULT_FILTER_BACKENDS': ('django_filters.rest_framework.DjangoFilterBackend',)
+        'DEFAULT_FILTER_BACKENDS': ['django_filters.rest_framework.DjangoFilterBackend']
     }
 
 You can also set the filter backends on a per-view, or per-viewset basis,
@@ -106,7 +109,7 @@ using the `GenericAPIView` class-based views.
     class UserListView(generics.ListAPIView):
         queryset = User.objects.all()
         serializer_class = UserSerializer
-        filter_backends = (django_filters.rest_framework.DjangoFilterBackend,)
+        filter_backends = [django_filters.rest_framework.DjangoFilterBackend]
 
 ## Filtering and object lookups
 
@@ -139,7 +142,7 @@ Note that you can use both an overridden `.get_queryset()` and generic filtering
 
 ## DjangoFilterBackend
 
-The `django-filter` library includes a `DjangoFilterBackend` class which
+The [`django-filter`][django-filter-docs] library includes a `DjangoFilterBackend` class which
 supports highly customizable field filtering for REST framework.
 
 To use `DjangoFilterBackend`, first install `django-filter`. Then add `django_filters` to Django's `INSTALLED_APPS`
@@ -149,7 +152,7 @@ To use `DjangoFilterBackend`, first install `django-filter`. Then add `django_fi
 You should now either add the filter backend to your settings:
 
     REST_FRAMEWORK = {
-        'DEFAULT_FILTER_BACKENDS': ('django_filters.rest_framework.DjangoFilterBackend',)
+        'DEFAULT_FILTER_BACKENDS': ['django_filters.rest_framework.DjangoFilterBackend']
     }
 
 Or add the filter backend to an individual View or ViewSet.
@@ -158,15 +161,15 @@ Or add the filter backend to an individual View or ViewSet.
 
     class UserListView(generics.ListAPIView):
         ...
-        filter_backends = (DjangoFilterBackend,)
+        filter_backends = [DjangoFilterBackend]
 
 If all you need is simple equality-based filtering, you can set a `filterset_fields` attribute on the view, or viewset, listing the set of fields you wish to filter against.
 
     class ProductList(generics.ListAPIView):
         queryset = Product.objects.all()
         serializer_class = ProductSerializer
-        filter_backends = (DjangoFilterBackend,)
+        filter_backends = [DjangoFilterBackend]
-        filterset_fields = ('category', 'in_stock')
+        filterset_fields = ['category', 'in_stock']
 
 This will automatically create a `FilterSet` class for the given fields, and will allow you to make requests such as:
 
@@ -192,8 +195,8 @@ The `SearchFilter` class will only be applied if the view has a `search_fields`
     class UserListView(generics.ListAPIView):
         queryset = User.objects.all()
         serializer_class = UserSerializer
-        filter_backends = (filters.SearchFilter,)
+        filter_backends = [filters.SearchFilter]
-        search_fields = ('username', 'email')
+        search_fields = ['username', 'email']
 
 This will allow the client to filter the items in the list by making queries such as:
 
@@ -201,7 +204,7 @@ This will allow the client to filter the items in the list by making queries suc
 
 You can also perform a related lookup on a ForeignKey or ManyToManyField with the lookup API double-underscore notation:
 
-    search_fields = ('username', 'email', 'profile__profession')
+    search_fields = ['username', 'email', 'profile__profession']
 
 By default, searches will use case-insensitive partial matches.  The search parameter may contain multiple search terms, which should be whitespace and/or comma separated.  If multiple search terms are used then objects will be returned in the list only if all the provided terms are matched.
 
@@ -214,18 +217,18 @@ The search behavior may be restricted by prepending various characters to the `s
 
 For example:
 
-    search_fields = ('=username', '=email')
+    search_fields = ['=username', '=email']
 
-By default, the search parameter is named `'search`', but this may be overridden with the `SEARCH_PARAM` setting.
+By default, the search parameter is named `'search'`, but this may be overridden with the `SEARCH_PARAM` setting.
 
 To dynamically change search fields based on request content, it's possible to subclass the `SearchFilter` and override the `get_search_fields()` function. For example, the following subclass will only search on `title` if the query parameter `title_only` is in the request:
 
     from rest_framework import filters
-    
+
     class CustomSearchFilter(filters.SearchFilter):
         def get_search_fields(self, view, request):
             if request.query_params.get('title_only'):
-                return ('title',)
+                return ['title']
             return super(CustomSearchFilter, self).get_search_fields(view, request)
 
 For more details, see the [Django documentation][search-django-admin].
@@ -259,8 +262,8 @@ It's recommended that you explicitly specify which fields the API should allowin
     class UserListView(generics.ListAPIView):
         queryset = User.objects.all()
         serializer_class = UserSerializer
-        filter_backends = (filters.OrderingFilter,)
+        filter_backends = [filters.OrderingFilter]
-        ordering_fields = ('username', 'email')
+        ordering_fields = ['username', 'email']
 
 This helps prevent unexpected data leakage, such as allowing users to order against a password hash field or other sensitive data.
 
@@ -271,7 +274,7 @@ If you are confident that the queryset being used by the view doesn't contain an
     class BookingsListView(generics.ListAPIView):
         queryset = Booking.objects.all()
         serializer_class = BookingSerializer
-        filter_backends = (filters.OrderingFilter,)
+        filter_backends = [filters.OrderingFilter]
         ordering_fields = '__all__'
 
 ### Specifying a default ordering
@@ -283,61 +286,14 @@ Typically you'd instead control this by setting `order_by` on the initial querys
     class UserListView(generics.ListAPIView):
         queryset = User.objects.all()
         serializer_class = UserSerializer
-        filter_backends = (filters.OrderingFilter,)
+        filter_backends = [filters.OrderingFilter]
-        ordering_fields = ('username', 'email')
+        ordering_fields = ['username', 'email']
-        ordering = ('username',)
+        ordering = ['username']
 
 The `ordering` attribute may be either a string or a list/tuple of strings.
 
 ---
 
-## DjangoObjectPermissionsFilter
-
-The `DjangoObjectPermissionsFilter` is intended to be used together with the [`django-guardian`][guardian] package, with custom `'view'` permissions added.  The filter will ensure that querysets only returns objects for which the user has the appropriate view permission.
-
----
-
-**Note:** This filter has been deprecated as of version 3.9 and moved to the 3rd-party [`djangorestframework-guardian` package][django-rest-framework-guardian].
-
----
-
-If you're using `DjangoObjectPermissionsFilter`, you'll probably also want to add an appropriate object permissions class, to ensure that users can only operate on instances if they have the appropriate object permissions.  The easiest way to do this is to subclass `DjangoObjectPermissions` and add `'view'` permissions to the `perms_map` attribute.
-
-A complete example using both `DjangoObjectPermissionsFilter` and `DjangoObjectPermissions` might look something like this.
-
-**permissions.py**:
-
-    class CustomObjectPermissions(permissions.DjangoObjectPermissions):
-        """
-        Similar to `DjangoObjectPermissions`, but adding 'view' permissions.
-        """
-        perms_map = {
-            'GET': ['%(app_label)s.view_%(model_name)s'],
-            'OPTIONS': ['%(app_label)s.view_%(model_name)s'],
-            'HEAD': ['%(app_label)s.view_%(model_name)s'],
-            'POST': ['%(app_label)s.add_%(model_name)s'],
-            'PUT': ['%(app_label)s.change_%(model_name)s'],
-            'PATCH': ['%(app_label)s.change_%(model_name)s'],
-            'DELETE': ['%(app_label)s.delete_%(model_name)s'],
-        }
-
-**views.py**:
-
-    class EventViewSet(viewsets.ModelViewSet):
-        """
-        Viewset that only lists events if user has 'view' permissions, and only
-        allows operations on individual events if user has appropriate 'view', 'add',
-        'change' or 'delete' permissions.
-        """
-        queryset = Event.objects.all()
-        serializer_class = EventSerializer
-        filter_backends = (filters.DjangoObjectPermissionsFilter,)
-        permission_classes = (myapp.permissions.CustomObjectPermissions,)
-
-For more information on adding `'view'` permissions for models, see the [relevant section][view-permissions] of the `django-guardian` documentation, and [this blogpost][view-permissions-blogpost].
-
----
-
 # Custom generic filtering
 
 You can also provide your own generic filtering backend, or write an installable app for other developers to use.
@@ -399,12 +355,8 @@ The [djangorestframework-word-filter][django-rest-framework-word-search-filter]
 [cite]: https://docs.djangoproject.com/en/stable/topics/db/queries/#retrieving-specific-objects-with-filters
 [django-filter-docs]: https://django-filter.readthedocs.io/en/latest/index.html
 [django-filter-drf-docs]: https://django-filter.readthedocs.io/en/latest/guide/rest_framework.html
-[guardian]: https://django-guardian.readthedocs.io/
-[view-permissions]: https://django-guardian.readthedocs.io/en/latest/userguide/assign.html
-[view-permissions-blogpost]: https://blog.nyaruka.com/adding-a-view-permission-to-django-models
 [search-django-admin]: https://docs.djangoproject.com/en/stable/ref/contrib/admin/#django.contrib.admin.ModelAdmin.search_fields
 [django-rest-framework-filters]: https://github.com/philipn/django-rest-framework-filters
-[django-rest-framework-guardian]: https://github.com/rpkilby/django-rest-framework-guardian
 [django-rest-framework-word-search-filter]: https://github.com/trollknurr/django-rest-framework-word-search-filter
 [django-url-filter]: https://github.com/miki725/django-url-filter
 [drf-url-filter]: https://github.com/manjitkumar/drf-url-filters

docs/api-guide/format-suffixes.md

@@ -1,4 +1,7 @@
-source: urlpatterns.py
+---
+source:
+    - urlpatterns.py
+---
 
 # Format suffixes
 
@@ -38,7 +41,7 @@ Example:
 
 When using `format_suffix_patterns`, you must make sure to add the `'format'` keyword argument to the corresponding views.  For example:
 
-    @api_view(('GET', 'POST'))
+    @api_view(['GET', 'POST'])
     def comment_list(request, format=None):
         # do stuff...
 

docs/api-guide/generic-views.md

@@ -1,5 +1,8 @@
-source: mixins.py
+---
-        generics.py
+source:
+    - mixins.py
+    - generics.py
+---
 
 # Generic views
 
@@ -25,14 +28,14 @@ Typically when using the generic views, you'll override the view, and set severa
     class UserList(generics.ListCreateAPIView):
         queryset = User.objects.all()
         serializer_class = UserSerializer
-        permission_classes = (IsAdminUser,)
+        permission_classes = [IsAdminUser]
 
 For more complex cases you might also want to override various methods on the view class.  For example.
 
     class UserList(generics.ListCreateAPIView):
         queryset = User.objects.all()
         serializer_class = UserSerializer
-        permission_classes = (IsAdminUser,)
+        permission_classes = [IsAdminUser]
 
         def list(self, request):
             # Note the use of `get_queryset()` instead of `self.queryset`
@@ -120,12 +123,12 @@ Given a queryset, filter it with whichever filter backends are in use, returning
 For example:
 
     def filter_queryset(self, queryset):
-        filter_backends = (CategoryFilter,)
+        filter_backends = [CategoryFilter]
 
         if 'geo_route' in self.request.query_params:
-            filter_backends = (GeoRouteFilter, CategoryFilter)
+            filter_backends = [GeoRouteFilter, CategoryFilter]
         elif 'geo_point' in self.request.query_params:
-            filter_backends = (GeoPointFilter, CategoryFilter)
+            filter_backends = [GeoPointFilter, CategoryFilter]
 
         for backend in list(filter_backends):
             queryset = backend().filter_queryset(self.request, queryset, view=self)
@@ -339,7 +342,7 @@ You can then simply apply this mixin to a view or viewset anytime you need to ap
     class RetrieveUserView(MultipleFieldLookupMixin, generics.RetrieveAPIView):
         queryset = User.objects.all()
         serializer_class = UserSerializer
-        lookup_fields = ('account', 'username')
+        lookup_fields = ['account', 'username']
 
 Using custom mixins is a good option if you have custom behavior that needs to be used.
 

docs/api-guide/metadata.md

@@ -1,4 +1,7 @@
-source: metadata.py
+---
+source:
+    - metadata.py
+---
 
 # Metadata
 

docs/api-guide/pagination.md

@@ -1,4 +1,7 @@
-source: pagination.py
+---
+source:
+    - pagination.py
+---
 
 # Pagination
 
@@ -257,6 +260,10 @@ 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:
 
+![Link Header][link-header]
+
+*A custom pagination style, using the 'Link' header'*
+
 ## Pagination & schemas
 
 You can also make the pagination controls available to the schema autogeneration
@@ -268,12 +275,6 @@ The method should return a list of `coreapi.Field` instances.
 
 ---
 
-![Link Header][link-header]
-
-*A custom pagination style, using the 'Link' header'*
-
----
-
 # HTML pagination controls
 
 By default using the pagination classes will cause HTML pagination controls to be displayed in the browsable API. There are two built-in display styles. The `PageNumberPagination` and `LimitOffsetPagination` classes display a list of page numbers with previous and next controls. The `CursorPagination` class displays a simpler style that only displays a previous and next control.

docs/api-guide/parsers.md

@@ -1,4 +1,7 @@
-source: parsers.py
+---
+source:
+    - parsers.py
+---
 
 # Parsers
 
@@ -29,9 +32,9 @@ As an example, if you are sending `json` encoded data using jQuery with the [.aj
 The default set of parsers may be set globally, using the `DEFAULT_PARSER_CLASSES` setting. For example, the following settings would allow only requests with `JSON` content, instead of the default of JSON or form data.
 
     REST_FRAMEWORK = {
-        'DEFAULT_PARSER_CLASSES': (
+        'DEFAULT_PARSER_CLASSES': [
             'rest_framework.parsers.JSONParser',
-        )
+        ]
     }
 
 You can also set the parsers used for an individual view, or viewset,
@@ -45,7 +48,7 @@ using the `APIView` class-based views.
         """
         A view that can accept POST requests with JSON content.
         """
-        parser_classes = (JSONParser,)
+        parser_classes = [JSONParser]
 
         def post(self, request, format=None):
             return Response({'received data': request.data})
@@ -57,7 +60,7 @@ Or, if you're using the `@api_view` decorator with function based views.
     from rest_framework.parsers import JSONParser
 
     @api_view(['POST'])
-    @parser_classes((JSONParser,))
+    @parser_classes([JSONParser])
     def example_view(request, format=None):
         """
         A view that can accept POST requests with JSON content.
@@ -110,7 +113,7 @@ If it is called without a `filename` URL keyword argument, then the client must
 
     # views.py
     class FileUploadView(views.APIView):
-        parser_classes = (FileUploadParser,)
+        parser_classes = [FileUploadParser]
 
         def put(self, request, filename, format=None):
             file_obj = request.data['file']
@@ -186,12 +189,12 @@ Install using pip.
 Modify your REST framework settings.
 
     REST_FRAMEWORK = {
-        'DEFAULT_PARSER_CLASSES': (
+        'DEFAULT_PARSER_CLASSES': [
             'rest_framework_yaml.parsers.YAMLParser',
-        ),
+        ],
-        'DEFAULT_RENDERER_CLASSES': (
+        'DEFAULT_RENDERER_CLASSES': [
             'rest_framework_yaml.renderers.YAMLRenderer',
-        ),
+        ],
     }
 
 ## XML
@@ -207,12 +210,12 @@ Install using pip.
 Modify your REST framework settings.
 
     REST_FRAMEWORK = {
-        'DEFAULT_PARSER_CLASSES': (
+        'DEFAULT_PARSER_CLASSES': [
             'rest_framework_xml.parsers.XMLParser',
-        ),
+        ],
-        'DEFAULT_RENDERER_CLASSES': (
+        'DEFAULT_RENDERER_CLASSES': [
             'rest_framework_xml.renderers.XMLRenderer',
-        ),
+        ],
     }
 
 ## MessagePack

docs/api-guide/permissions.md

@@ -1,4 +1,7 @@
-source: permissions.py
+---
+source:
+    - permissions.py
+---
 
 # Permissions
 
@@ -72,16 +75,16 @@ Often when you're using object level permissions you'll also want to [filter the
 The default permission policy may be set globally, using the `DEFAULT_PERMISSION_CLASSES` setting.  For example.
 
     REST_FRAMEWORK = {
-        'DEFAULT_PERMISSION_CLASSES': (
+        'DEFAULT_PERMISSION_CLASSES': [
             'rest_framework.permissions.IsAuthenticated',
-        )
+        ]
     }
 
 If not specified, this setting defaults to allowing unrestricted access:
 
-    'DEFAULT_PERMISSION_CLASSES': (
+    'DEFAULT_PERMISSION_CLASSES': [
        'rest_framework.permissions.AllowAny',
-    )
+    ]
 
 You can also set the authentication policy on a per-view, or per-viewset basis,
 using the `APIView` class-based views.
@@ -91,7 +94,7 @@ using the `APIView` class-based views.
     from rest_framework.views import APIView
 
     class ExampleView(APIView):
-        permission_classes = (IsAuthenticated,)
+        permission_classes = [IsAuthenticated]
 
         def get(self, request, format=None):
             content = {
@@ -106,7 +109,7 @@ Or, if you're using the `@api_view` decorator with function based views.
     from rest_framework.response import Response
 
     @api_view(['GET'])
-    @permission_classes((IsAuthenticated, ))
+    @permission_classes([IsAuthenticated])
     def example_view(request, format=None):
         content = {
             'status': 'request was permitted'
@@ -126,7 +129,7 @@ Provided they inherit from `rest_framework.permissions.BasePermission`, permissi
             return request.method in SAFE_METHODS
 
     class ExampleView(APIView):
-        permission_classes = (IsAuthenticated|ReadOnly,)
+        permission_classes = [IsAuthenticated|ReadOnly]
 
         def get(self, request, format=None):
             content = {
@@ -281,6 +284,10 @@ Also note that the generic views will only check the object-level permissions fo
 
 The following third party packages are also available.
 
+## DRF - Access Policy
+
+The [Django REST - Access Policy][drf-access-policy] package provides a way to define complex access rules in declarative policy classes that are attached to view sets or function-based views. The policies are defined in JSON in a format similar to AWS' Identity & Access Management policies. 
+
 ## Composed Permissions
 
 The [Composed Permissions][composed-permissions] package provides a simple way to define complex and multi-depth (with logic operators) permission objects, using small and reusable components.
@@ -299,7 +306,7 @@ The [Django Rest Framework Roles][django-rest-framework-roles] package makes it
 
 ## Django REST Framework API Key
 
-The [Django REST Framework API Key][djangorestframework-api-key] package provides the ability to authorize clients based on customizable API key headers. This package is targeted at situations in which regular user-based authentication (e.g. `TokenAuthentication`) is not suitable, e.g. allowing non-human clients to safely use your API. API keys are generated and validated through cryptographic methods and can be created and revoked from the Django admin interface at anytime.
+The [Django REST Framework API Key][djangorestframework-api-key] package provides permissions classes, models and helpers to add API key authorization to your API. It can be used to authorize internal or third-party backends and services (i.e. _machines_) which do not have a user account. API keys are stored securely using Django's password hashing infrastructure, and they can be viewed, edited and revoked at anytime in the Django admin.
 
 ## Django Rest Framework Role Filters
 
@@ -317,6 +324,7 @@ The [Django Rest Framework Role Filters][django-rest-framework-role-filters] pac
 [rest-condition]: https://github.com/caxap/rest_condition
 [dry-rest-permissions]: https://github.com/Helioscene/dry-rest-permissions
 [django-rest-framework-roles]: https://github.com/computer-lab/django-rest-framework-roles
-[djangorestframework-api-key]: https://github.com/florimondmanca/djangorestframework-api-key
+[djangorestframework-api-key]: https://florimondmanca.github.io/djangorestframework-api-key/
 [django-rest-framework-role-filters]: https://github.com/allisson/django-rest-framework-role-filters
 [django-rest-framework-guardian]: https://github.com/rpkilby/django-rest-framework-guardian
+[drf-access-policy]: https://github.com/rsinger86/drf-access-policy

docs/api-guide/relations.md

@@ -1,4 +1,7 @@
-source: relations.py
+---
+source:
+    - relations.py
+---
 
 # Serializer relations
 
@@ -43,7 +46,7 @@ In order to explain the various types of relational fields, we'll use a couple o
         duration = models.IntegerField()
 
         class Meta:
-            unique_together = ('album', 'order')
+            unique_together = ['album', 'order']
             ordering = ['order']
 
         def __str__(self):
@@ -60,7 +63,7 @@ For example, the following serializer.
 
         class Meta:
             model = Album
-            fields = ('album_name', 'artist', 'tracks')
+            fields = ['album_name', 'artist', 'tracks']
 
 Would serialize to the following representation.
 
@@ -92,7 +95,7 @@ For example, the following serializer:
 
         class Meta:
             model = Album
-            fields = ('album_name', 'artist', 'tracks')
+            fields = ['album_name', 'artist', 'tracks']
 
 Would serialize to a representation like this:
 
@@ -132,7 +135,7 @@ For example, the following serializer:
 
         class Meta:
             model = Album
-            fields = ('album_name', 'artist', 'tracks')
+            fields = ['album_name', 'artist', 'tracks']
 
 Would serialize to a representation like this:
 
@@ -184,7 +187,7 @@ For example, the following serializer:
 
         class Meta:
             model = Album
-            fields = ('album_name', 'artist', 'tracks')
+            fields = ['album_name', 'artist', 'tracks']
 
 Would serialize to a representation like this:
 
@@ -219,7 +222,7 @@ This field can be applied as an identity relationship, such as the `'url'` field
 
         class Meta:
             model = Album
-            fields = ('album_name', 'artist', 'track_listing')
+            fields = ['album_name', 'artist', 'track_listing']
 
 Would serialize to a representation like this:
 
@@ -253,14 +256,14 @@ For example, the following serializer:
     class TrackSerializer(serializers.ModelSerializer):
         class Meta:
             model = Track
-            fields = ('order', 'title', 'duration')
+            fields = ['order', 'title', 'duration']
 
     class AlbumSerializer(serializers.ModelSerializer):
         tracks = TrackSerializer(many=True, read_only=True)
 
         class Meta:
             model = Album
-            fields = ('album_name', 'artist', 'tracks')
+            fields = ['album_name', 'artist', 'tracks']
 
 Would serialize to a nested representation like this:
 
@@ -291,14 +294,14 @@ By default nested serializers are read-only. If you want to support write-operat
     class TrackSerializer(serializers.ModelSerializer):
         class Meta:
             model = Track
-            fields = ('order', 'title', 'duration')
+            fields = ['order', 'title', 'duration']
 
     class AlbumSerializer(serializers.ModelSerializer):
         tracks = TrackSerializer(many=True)
 
         class Meta:
             model = Album
-            fields = ('album_name', 'artist', 'tracks')
+            fields = ['album_name', 'artist', 'tracks']
 
         def create(self, validated_data):
             tracks_data = validated_data.pop('tracks')
@@ -352,7 +355,7 @@ For example, we could define a relational field to serialize a track to a custom
 
         class Meta:
             model = Album
-            fields = ('album_name', 'artist', 'tracks')
+            fields = ['album_name', 'artist', 'tracks']
 
 This custom field would then serialize to the following representation.
 
@@ -477,7 +480,7 @@ Note that reverse relationships are not automatically included by the `ModelSeri
 
     class AlbumSerializer(serializers.ModelSerializer):
         class Meta:
-            fields = ('tracks', ...)
+            fields = ['tracks', ...]
 
 You'll normally want to ensure that you've set an appropriate `related_name` argument on the relationship, that you can use as the field name.  For example:
 
@@ -489,7 +492,7 @@ If you have not set a related name for the reverse relationship, you'll need to
 
     class AlbumSerializer(serializers.ModelSerializer):
         class Meta:
-            fields = ('track_set', ...)
+            fields = ['track_set', ...]
 
 See the Django documentation on [reverse relationships][reverse-relationships] for more details.
 
@@ -576,6 +579,8 @@ If you explicitly specify a relational field pointing to a
 ``ManyToManyField`` with a through model, be sure to set ``read_only``
 to ``True``.
 
+If you wish to represent [extra fields on a through model][django-intermediary-manytomany] then you may serialize the through model as [a nested object][dealing-with-nested-objects].
+
 ---
 
 # Third Party Packages
@@ -596,3 +601,5 @@ The [rest-framework-generic-relations][drf-nested-relations] library provides re
 [generic-relations]: https://docs.djangoproject.com/en/stable/ref/contrib/contenttypes/#id1
 [drf-nested-routers]: https://github.com/alanjds/drf-nested-routers
 [drf-nested-relations]: https://github.com/Ian-Foote/rest-framework-generic-relations
+[django-intermediary-manytomany]: https://docs.djangoproject.com/en/2.2/topics/db/models/#intermediary-manytomany
+[dealing-with-nested-objects]: https://www.django-rest-framework.org/api-guide/serializers/#dealing-with-nested-objects

docs/api-guide/renderers.md

@@ -1,4 +1,7 @@
-source: renderers.py
+---
+source:
+    - renderers.py
+---
 
 # Renderers
 
@@ -21,10 +24,10 @@ For more information see the documentation on [content negotiation][conneg].
 The default set of renderers may be set globally, using the `DEFAULT_RENDERER_CLASSES` setting.  For example, the following settings would use `JSON` as the main media type and also include the self describing API.
 
     REST_FRAMEWORK = {
-        'DEFAULT_RENDERER_CLASSES': (
+        'DEFAULT_RENDERER_CLASSES': [
             'rest_framework.renderers.JSONRenderer',
             'rest_framework.renderers.BrowsableAPIRenderer',
-        )
+        ]
     }
 
 You can also set the renderers used for an individual view, or viewset,
@@ -39,7 +42,7 @@ using the `APIView` class-based views.
         """
         A view that returns the count of active users in JSON.
         """
-        renderer_classes = (JSONRenderer, )
+        renderer_classes = [JSONRenderer]
 
         def get(self, request, format=None):
             user_count = User.objects.filter(active=True).count()
@@ -49,7 +52,7 @@ using the `APIView` class-based views.
 Or, if you're using the `@api_view` decorator with function based views.
 
     @api_view(['GET'])
-    @renderer_classes((JSONRenderer,))
+    @renderer_classes([JSONRenderer])
     def user_count_view(request, format=None):
         """
         A view that returns the count of active users in JSON.
@@ -113,7 +116,7 @@ An example of a view that uses `TemplateHTMLRenderer`:
         A view that returns a templated HTML representation of a given user.
         """
         queryset = User.objects.all()
-        renderer_classes = (TemplateHTMLRenderer,)
+        renderer_classes = [TemplateHTMLRenderer]
 
         def get(self, request, *args, **kwargs):
             self.object = self.get_object()
@@ -139,8 +142,8 @@ A simple renderer that simply returns pre-rendered HTML.  Unlike other renderers
 
 An example of a view that uses `StaticHTMLRenderer`:
 
-    @api_view(('GET',))
+    @api_view(['GET'])
-    @renderer_classes((StaticHTMLRenderer,))
+    @renderer_classes([StaticHTMLRenderer])
     def simple_html_view(request):
         data = '<html><body><h1>Hello, world</h1></body></html>'
         return Response(data)
@@ -325,8 +328,8 @@ In some cases you might want your view to use different serialization styles dep
 
 For example:
 
-    @api_view(('GET',))
+    @api_view(['GET'])
-    @renderer_classes((TemplateHTMLRenderer, JSONRenderer))
+    @renderer_classes([TemplateHTMLRenderer, JSONRenderer])
     def list_users(request):
         """
         A view that can return JSON or HTML representations
@@ -398,12 +401,12 @@ Install using pip.
 Modify your REST framework settings.
 
     REST_FRAMEWORK = {
-        'DEFAULT_PARSER_CLASSES': (
+        'DEFAULT_PARSER_CLASSES': [
             'rest_framework_yaml.parsers.YAMLParser',
-        ),
+        ],
-        'DEFAULT_RENDERER_CLASSES': (
+        'DEFAULT_RENDERER_CLASSES': [
             'rest_framework_yaml.renderers.YAMLRenderer',
-        ),
+        ],
     }
 
 ## XML
@@ -419,12 +422,12 @@ Install using pip.
 Modify your REST framework settings.
 
     REST_FRAMEWORK = {
-        'DEFAULT_PARSER_CLASSES': (
+        'DEFAULT_PARSER_CLASSES': [
             'rest_framework_xml.parsers.XMLParser',
-        ),
+        ],
-        'DEFAULT_RENDERER_CLASSES': (
+        'DEFAULT_RENDERER_CLASSES': [
             'rest_framework_xml.renderers.XMLRenderer',
-        ),
+        ],
     }
 
 ## JSONP
@@ -448,9 +451,9 @@ Install using pip.
 Modify your REST framework settings.
 
     REST_FRAMEWORK = {
-        'DEFAULT_RENDERER_CLASSES': (
+        'DEFAULT_RENDERER_CLASSES': [
             'rest_framework_jsonp.renderers.JSONPRenderer',
-        ),
+        ],
     }
 
 ## MessagePack
@@ -472,11 +475,11 @@ Modify your REST framework settings.
     REST_FRAMEWORK = {
         ...
 
-        'DEFAULT_RENDERER_CLASSES': (
+        'DEFAULT_RENDERER_CLASSES': [
             'rest_framework.renderers.JSONRenderer',
             'rest_framework.renderers.BrowsableAPIRenderer',
             'drf_renderer_xlsx.renderers.XLSXRenderer',
-        ),
+        ],
     }
 
 To avoid having a file streamed without a filename (which the browser will often default to the filename "download", with no extension), we need to use a mixin to override the `Content-Disposition` header. If no filename is provided, it will default to `export.xlsx`. For example:
@@ -491,7 +494,7 @@ To avoid having a file streamed without a filename (which the browser will often
     class MyExampleViewSet(XLSXFileMixin, ReadOnlyModelViewSet):
         queryset = MyExampleModel.objects.all()
         serializer_class = MyExampleSerializer
-        renderer_classes = (XLSXRenderer,)
+        renderer_classes = [XLSXRenderer]
         filename = 'my_export.xlsx'
 
 ## CSV
@@ -534,7 +537,7 @@ Comma-separated values are a plain-text tabular data format, that can be easily
 [messagepack]: https://msgpack.org/
 [juanriaza]: https://github.com/juanriaza
 [mjumbewu]: https://github.com/mjumbewu
-[flipperpa]: https://githuc.com/flipperpa
+[flipperpa]: https://github.com/flipperpa
 [wharton]: https://github.com/wharton
 [drf-renderer-xlsx]: https://github.com/wharton/drf-renderer-xlsx
 [vbabiy]: https://github.com/vbabiy

docs/api-guide/requests.md

@@ -1,4 +1,7 @@
-source: request.py
+---
+source:
+    - request.py
+---
 
 # Requests
 
@@ -90,7 +93,7 @@ You won't typically need to access this property.
 
 ---
 
-**Note:** You may see a `WrappedAttributeError` raised when calling the `.user` or `.auth` properties. These errors originate from an authenticator as a standard `AttributeError`, however it's necessary that they be re-raised as a different exception type in order to prevent them from being suppressed by the outer property access. Python will not recognize that the `AttributeError` orginates from the authenticator and will instead assume that the request object does not have a `.user` or `.auth` property. The authenticator will need to be fixed.
+**Note:** You may see a `WrappedAttributeError` raised when calling the `.user` or `.auth` properties. These errors originate from an authenticator as a standard `AttributeError`, however it's necessary that they be re-raised as a different exception type in order to prevent them from being suppressed by the outer property access. Python will not recognize that the `AttributeError` originates from the authenticator and will instead assume that the request object does not have a `.user` or `.auth` property. The authenticator will need to be fixed.
 
 ---
 

docs/api-guide/responses.md

@@ -1,4 +1,7 @@
-source: response.py
+---
+source:
+    - response.py
+---
 
 # Responses
 

docs/api-guide/reverse.md

@@ -1,4 +1,7 @@
-source: reverse.py
+---
+source:
+    - reverse.py
+---
 
 # Returning URLs
 

docs/api-guide/routers.md

@@ -1,4 +1,7 @@
-source: routers.py
+---
+source:
+    - routers.py
+---
 
 # Routers
 

docs/api-guide/schemas.md

@@ -1,6 +1,9 @@
-source: schemas.py
+---
+source:
+    - schemas.py
+---
 
-# Schemas
+# Schema
 
 > A machine-readable [schema] describes what resources are available via the API, what their URLs are, how they are represented and what operations they support.
 >
@@ -10,24 +13,24 @@ API schemas are a useful tool that allow for a range of use cases, including
 generating reference documentation, or driving dynamic client libraries that
 can interact with your API.
 
-## Install Core API & PyYAML
+Django REST Framework provides support for automatic generation of
+[OpenAPI][openapi] schemas.
 
-You'll need to install the `coreapi` package in order to add schema support
+## Generating an OpenAPI Schema
-for REST framework. You probably also want to install `pyyaml`, so that you
-can render the schema into the commonly used YAML-based OpenAPI format.
 
-    pip install coreapi pyyaml
+### Install `pyyaml`
 
-## Quickstart
+You'll need to install `pyyaml`, so that you can render your generated schema
+into the commonly used YAML-based OpenAPI format.
 
-There are two different ways you can serve a schema description for your API.
+    pip install pyyaml
 
-### Generating a schema with the `generateschema` management command
+### Generating a static schema with the `generateschema` management command
 
-To generate a static API schema, use the `generateschema` management command.
+If your schema is static, you can use the `generateschema` management command:
 
-```shell
+```bash
-$ python manage.py generateschema > schema.yml
+./manage.py generateschema > openapi-schema.yml
 ```
 
 Once you've generated a schema in this way you can annotate it with any
@@ -37,154 +40,136 @@ generator.
 You might want to check your API schema into version control and update it
 with each new release, or serve the API schema from your site's static media.
 
-### Adding a view with `get_schema_view`
+### Generating a dynamic schema with `SchemaView`
 
-To add a dynamically generated schema view to your API, use `get_schema_view`.
+If you require a dynamic schema, because foreign key choices depend on database
+values, for example, you can route a `SchemaView` that will generate and serve
+your schema on demand.
+
+To route a `SchemaView`, use the `get_schema_view()` helper.
+
+In `urls.py`:
 
 ```python
 from rest_framework.schemas import get_schema_view
 
-schema_view = get_schema_view(title="Example API")
-
 urlpatterns = [
-    url('^schema$', schema_view),
+    # ...
-    ...
+    # Use the `get_schema_view()` helper to add a `SchemaView` to project URLs.
+    #   * `title` and `description` parameters are passed to `SchemaGenerator`.
+    #   * Provide view name for use with `reverse()`.
+    path('openapi', get_schema_view(
+        title="Your Project",
+        description="API for all things …",
+        version="1.0.0"
+    ), name='openapi-schema'),
+    # ...
 ]
 ```
 
-See below [for more details](#the-get_schema_view-shortcut) on customizing a
+#### `get_schema_view()`
-dynamically generated schema view.
 
-## Internal schema representation
+The `get_schema_view()` helper takes the following keyword arguments:
 
-REST framework uses [Core API][coreapi] in order to model schema information in
+* `title`: May be used to provide a descriptive title for the schema definition.
-a format-independent representation. This information can then be rendered
+* `description`: Longer descriptive text.
-into various different schema formats, or used to generate API documentation.
+* `version`: The version of the API. Defaults to `0.1.0`.
+* `url`: May be used to pass a canonical base URL for the schema.
 
-When using Core API, a schema is represented as a `Document` which is the
+        schema_view = get_schema_view(
-top-level container object for information about the API. Available API
+            title='Server Monitoring API',
-interactions are represented using `Link` objects. Each link includes a URL,
+            url='https://www.example.org/api/'
-HTTP method, and may include a list of `Field` instances, which describe any
+        )
-parameters that may be accepted by the API endpoint. The `Link` and `Field`
-instances may also include descriptions, that allow an API schema to be
-rendered into user documentation.
 
-Here's an example of an API description that includes a single `search`
+* `urlconf`: A string representing the import path to the URL conf that you want
-endpoint:
+   to generate an API schema for. This defaults to the value of Django's
+   `ROOT_URLCONF` setting.
 
-    coreapi.Document(
+        schema_view = get_schema_view(
-        title='Flight Search API',
+            title='Server Monitoring API',
-        url='https://api.example.org/',
+            url='https://www.example.org/api/',
-        content={
+            urlconf='myproject.urls'
-            'search': coreapi.Link(
+        )
-                url='/search/',
+* `patterns`: List of url patterns to limit the schema introspection to. If you
-                action='get',
+  only want the `myproject.api` urls to be exposed in the schema:
-                fields=[
-                    coreapi.Field(
-                        name='from',
-                        required=True,
-                        location='query',
-                        description='City name or airport code.'
-                    ),
-                    coreapi.Field(
-                        name='to',
-                        required=True,
-                        location='query',
-                        description='City name or airport code.'
-                    ),
-                    coreapi.Field(
-                        name='date',
-                        required=True,
-                        location='query',
-                        description='Flight date in "YYYY-MM-DD" format.'
-                    )
-                ],
-                description='Return flight availability and prices.'
-            )
-        }
-    )
 
-## Schema output formats
+        schema_url_patterns = [
+            url(r'^api/', include('myproject.api.urls')),
+        ]
 
-In order to be presented in an HTTP response, the internal representation
+        schema_view = get_schema_view(
-has to be rendered into the actual bytes that are used in the response.
+            title='Server Monitoring API',
+            url='https://www.example.org/api/',
+            patterns=schema_url_patterns,
+        )
 
-REST framework includes a few different renderers that you can use for
+* `generator_class`: May be used to specify a `SchemaGenerator` subclass to be
-encoding the API schema.
+  passed to the `SchemaView`.
-
+* `authentication_classes`: May be used to specify the list of authentication
-* `renderers.OpenAPIRenderer` - Renders into YAML-based [OpenAPI][open-api], the most widely used API schema format.
+  classes that will apply to the schema endpoint. Defaults to
-* `renderers.JSONOpenAPIRenderer` - Renders into JSON-based [OpenAPI][open-api].
+  `settings.DEFAULT_AUTHENTICATION_CLASSES`
-* `renderers.CoreJSONRenderer` - Renders into [Core JSON][corejson], a format designed for
+* `permission_classes`: May be used to specify the list of permission classes
-use with the `coreapi` client library.
+  that will apply to the schema endpoint. Defaults to
+  `settings.DEFAULT_PERMISSION_CLASSES`.
+* `renderer_classes`: May be used to pass the set of renderer classes that can
+  be used to render the API root endpoint.
 
 
-[Core JSON][corejson] is designed as a canonical format for use with Core API.
+## Customizing Schema Generation
-REST framework includes a renderer class for handling this media type, which
-is available as `renderers.CoreJSONRenderer`.
 
+You may customize schema generation at the level of the schema as a whole, or
+on a per-view basis.
 
-## Schemas vs Hypermedia
+### Schema Level Customization
 
-It's worth pointing out here that Core API can also be used to model hypermedia
+In order to customize the top-level schema sublass
-responses, which present an alternative interaction style to API schemas.
+`rest_framework.schemas.openapi.SchemaGenerator` and provide it as an argument
+to the `generateschema` command or `get_schema_view()` helper function.
 
-With an API schema, the entire available interface is presented up-front
+#### SchemaGenerator
-as a single endpoint. Responses to individual API endpoints are then typically
-presented as plain data, without any further interactions contained in each
-response.
 
-With Hypermedia, the client is instead presented with a document containing
+A class that walks a list of routed URL patterns, requests the schema for each
-both data and available interactions. Each interaction results in a new
+view and collates the resulting OpenAPI schema.
-document, detailing both the current state and the available interactions.
 
-Further information and support on building Hypermedia APIs with REST framework
+Typically you'll instantiate `SchemaGenerator` with a `title` argument, like so:
-is planned for a future version.
 
+    generator = SchemaGenerator(title='Stock Prices API')
 
----
+Arguments:
 
-# Creating a schema
+* `title` **required**: The name of the API.
+* `description`: Longer descriptive text.
+* `version`: The version of the API. Defaults to `0.1.0`.
+* `url`: The root URL of the API schema. This option is not required unless the schema is included under path prefix.
+* `patterns`: A list of URLs to inspect when generating the schema. Defaults to the project's URL conf.
+* `urlconf`: A URL conf module name to use when generating the schema. Defaults to `settings.ROOT_URLCONF`.
 
-REST framework includes functionality for auto-generating a schema,
+##### get_schema(self, request)
-or allows you to specify one explicitly.
 
-## Manual Schema Specification
+Returns a dictionary that represents the OpenAPI schema:
 
-To manually specify a schema you create a Core API `Document`, similar to the
+    generator = SchemaGenerator(title='Stock Prices API')
-example above.
-
-    schema = coreapi.Document(
-        title='Flight Search API',
-        content={
-            ...
-        }
-    )
-
-
-## Automatic Schema Generation
-
-Automatic schema generation is provided by the `SchemaGenerator` class.
-
-`SchemaGenerator` processes a list of routed URL patterns and compiles the
-appropriately structured Core API Document.
-
-Basic usage is just to provide the title for your schema and call
-`get_schema()`:
-
-    generator = schemas.SchemaGenerator(title='Flight Search API')
     schema = generator.get_schema()
 
-## Per-View Schema Customisation
+The `request` argument is optional, and may be used if you want to apply
+per-user permissions to the resulting schema generation.
+
+This is a good point to override if you want to customise the generated
+dictionary,  for example to add custom
+[specification extensions][openapi-specification-extensions].
+
+### Per-View Customization
 
 By default, view introspection is performed by an `AutoSchema` instance
 accessible via the `schema` attribute on `APIView`. This provides the
-appropriate Core API `Link` object for the view, request method and path:
+appropriate [Open API operation object][openapi-operation] for the view,
+request method and path:
 
     auto_schema = view.schema
-    coreapi_link = auto_schema.get_link(...)
+    operation = auto_schema.get_operation(...)
 
-(In compiling the schema, `SchemaGenerator` calls `view.schema.get_link()` for
+In compiling the schema, `SchemaGenerator` calls `view.schema.get_operation()`
-each view, allowed method and path.)
+for each view, allowed method, and path.
 
 ---
 
@@ -198,641 +183,39 @@ provide richer path field descriptions. (The key hooks here are the relevant
 
 ---
 
-To customise the `Link` generation you may:
+In order to customise the operation generation, you should provide an `AutoSchema` subclass, overriding `get_operation()` as you need:
 
-* Instantiate `AutoSchema` on your view with the `manual_fields` kwarg:
 
         from rest_framework.views import APIView
-        from rest_framework.schemas import AutoSchema
+        from rest_framework.schemas.openapi import AutoSchema
-
-        class CustomView(APIView):
-            ...
-            schema = AutoSchema(
-                manual_fields=[
-                    coreapi.Field("extra_field", ...),
-                ]
-            )
-
-    This allows extension for the most common case without subclassing.
-
-* Provide an `AutoSchema` subclass with more complex customisation:
-
-        from rest_framework.views import APIView
-        from rest_framework.schemas import AutoSchema
 
         class CustomSchema(AutoSchema):
             def get_link(...):
                 # Implement custom introspection here (or in other sub-methods)
 
         class CustomView(APIView):
-            ...
+            """APIView subclass with custom schema introspection."""
             schema = CustomSchema()
 
-    This provides complete control over view introspection.
+This provides complete control over view introspection.
-
-* Instantiate `ManualSchema` on your view, providing the Core API `Fields` for
-  the view explicitly:
-
-        from rest_framework.views import APIView
-        from rest_framework.schemas import ManualSchema
-
-        class CustomView(APIView):
-            ...
-            schema = ManualSchema(fields=[
-                coreapi.Field(
-                    "first_field",
-                    required=True,
-                    location="path",
-                    schema=coreschema.String()
-                ),
-                coreapi.Field(
-                    "second_field",
-                    required=True,
-                    location="path",
-                    schema=coreschema.String()
-                ),
-            ])
-
-    This allows manually specifying the schema for some views whilst maintaining
-    automatic generation elsewhere.
 
 You may disable schema generation for a view by setting `schema` to `None`:
 
-        class CustomView(APIView):
+    class CustomView(APIView):
-            ...
+        ...
-            schema = None  # Will not appear in schema
+        schema = None  # Will not appear in schema
 
 This also applies to extra actions for `ViewSet`s:
 
-        class CustomViewSet(viewsets.ModelViewSet):
+    class CustomViewSet(viewsets.ModelViewSet):
 
-            @action(detail=True, schema=None)
+        @action(detail=True, schema=None)
-            def extra_action(self, request, pk=None):
+        def extra_action(self, request, pk=None):
-                ...
-
----
-
-**Note**: For full details on `SchemaGenerator` plus the `AutoSchema` and
-`ManualSchema` descriptors see the [API Reference below](#api-reference).
-
----
-
-# Adding a schema view
-
-There are a few different ways to add a schema view to your API, depending on
-exactly what you need.
-
-## The get_schema_view shortcut
-
-The simplest way to include a schema in your project is to use the
-`get_schema_view()` function.
-
-    from rest_framework.schemas import get_schema_view
-
-    schema_view = get_schema_view(title="Server Monitoring API")
-
-    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/coreapi+json
-    HTTP/1.0 200 OK
-    Allow: GET, HEAD, OPTIONS
-    Content-Type: application/vnd.coreapi+json
-
-    {
-        "_meta": {
-            "title": "Server Monitoring API"
-        },
-        "_type": "document",
-        ...
-    }
-
-The arguments to `get_schema_view()` are:
-
-#### `title`
-
-May be used to provide a descriptive title for the schema definition.
-
-#### `url`
-
-May be used to pass a canonical URL for the schema.
-
-    schema_view = get_schema_view(
-        title='Server Monitoring API',
-        url='https://www.example.org/api/'
-    )
-
-#### `urlconf`
-
-A string representing the import path to the URL conf that you want
-to generate an API schema for. This defaults to the value of Django's
-ROOT_URLCONF setting.
-
-    schema_view = get_schema_view(
-        title='Server Monitoring API',
-        url='https://www.example.org/api/',
-        urlconf='myproject.urls'
-    )
-
-#### `renderer_classes`
-
-May be used to pass the set of renderer classes that can be used to render the API root endpoint.
-
-    from rest_framework.schemas import get_schema_view
-    from rest_framework.renderers import JSONOpenAPIRenderer
-
-    schema_view = get_schema_view(
-        title='Server Monitoring API',
-        url='https://www.example.org/api/',
-        renderer_classes=[JSONOpenAPIRenderer]
-    )
-
-#### `patterns`
-
-List of url patterns to limit the schema introspection to. If you only want the `myproject.api` urls
-to be exposed in the schema:
-
-    schema_url_patterns = [
-        url(r'^api/', include('myproject.api.urls')),
-    ]
-
-    schema_view = get_schema_view(
-        title='Server Monitoring API',
-        url='https://www.example.org/api/',
-        patterns=schema_url_patterns,
-    )
-
-#### `generator_class`
-
-May be used to specify a `SchemaGenerator` subclass to be passed to the
-`SchemaView`.
-
-#### `authentication_classes`
-
-May be used to specify the list of authentication classes that will apply to the schema endpoint.
-Defaults to `settings.DEFAULT_AUTHENTICATION_CLASSES`
-
-#### `permission_classes`
-
-May be used to specify the list of permission classes that will apply to the schema endpoint.
-Defaults to `settings.DEFAULT_PERMISSION_CLASSES`
-
-## 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 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.
-
-**views.py:**
-
-    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.OpenAPIRenderer])
-    def schema_view(request):
-        schema = generator.get_schema(request)
-        return response.Response(schema)
-
-**urls.py:**
-
-    urlpatterns = [
-        url('/', schema_view),
-        ...
-    ]
-
-You can also serve different schemas to different users, depending on the
-permissions they have available. This approach can be used to ensure that
-unauthenticated requests are presented with a different schema to
-authenticated requests, or to ensure that different parts of the API are
-made visible to different users depending on their role.
-
-In order to present a schema with endpoints filtered by user permissions,
-you need to pass the `request` argument to the `get_schema()` method, like so:
-
-    @api_view()
-    @renderer_classes([renderers.OpenAPIRenderer])
-    def schema_view(request):
-        generator = schemas.SchemaGenerator(title='Bookings API')
-        return response.Response(generator.get_schema(request=request))
-
-## Explicit schema definition
-
-An alternative to the auto-generated approach is to specify the API schema
-explicitly, by declaring a `Document` object in your codebase. Doing so is a
-little more work, but ensures that you have full control over the schema
-representation.
-
-    import coreapi
-    from rest_framework.decorators import api_view, renderer_classes
-    from rest_framework import renderers, response
-
-    schema = coreapi.Document(
-        title='Bookings API',
-        content={
             ...
-        }
-    )
 
-    @api_view()
+If you wish to provide a base `AutoSchema` subclass to be used throughout your
-    @renderer_classes([renderers.OpenAPIRenderer])
+project you may adjust `settings.DEFAULT_SCHEMA_CLASS`  appropriately.
-    def schema_view(request):
-        return response.Response(schema)
 
----
+[openapi]: https://github.com/OAI/OpenAPI-Specification
-
+[openapi-specification-extensions]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#specification-extensions
-# Schemas as documentation
+[openapi-operation]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#operationObject
-
-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: List all the users.
-        post: Create a new user.
-        """
-        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
-
----
-
-# API Reference
-
-## SchemaGenerator
-
-A class that walks a list of routed URL patterns, requests the schema for each view,
-and collates the resulting CoreAPI Document.
-
-Typically you'll instantiate `SchemaGenerator` with a single argument, like so:
-
-    generator = SchemaGenerator(title='Stock Prices API')
-
-Arguments:
-
-* `title` **required** - The name of the API.
-* `url` - The root URL of the API schema. This option is not required unless the schema is included under path prefix.
-* `patterns` - A list of URLs to inspect when generating the schema. Defaults to the project's URL conf.
-* `urlconf` - A URL conf module name to use when generating the schema. Defaults to `settings.ROOT_URLCONF`.
-
-### get_schema(self, request)
-
-Returns a `coreapi.Document` instance that represents the API schema.
-
-    @api_view
-    @renderer_classes([renderers.OpenAPIRenderer])
-    def schema_view(request):
-        generator = schemas.SchemaGenerator(title='Bookings API')
-        return Response(generator.get_schema())
-
-The `request` argument is optional, and may be used if you want to apply per-user
-permissions to the resulting schema generation.
-
-### get_links(self, request)
-
-Return a nested dictionary containing all the links that should be included in the API schema.
-
-This is a good point to override if you want to modify the resulting structure of the generated schema,
-as you can build a new dictionary with a different layout.
-
-
-## AutoSchema
-
-A class that deals with introspection of individual views for schema generation.
-
-`AutoSchema` is attached to `APIView` via the `schema` attribute.
-
-The `AutoSchema` constructor takes a single keyword argument  `manual_fields`.
-
-**`manual_fields`**: a `list` of `coreapi.Field` instances that will be added to
-the generated fields. Generated fields with a matching `name` will be overwritten.
-
-    class CustomView(APIView):
-        schema = AutoSchema(manual_fields=[
-            coreapi.Field(
-                "my_extra_field",
-                required=True,
-                location="path",
-                schema=coreschema.String()
-            ),
-        ])
-
-For more advanced customisation subclass `AutoSchema` to customise schema generation.
-
-    class CustomViewSchema(AutoSchema):
-        """
-        Overrides `get_link()` to provide Custom Behavior X
-        """
-
-        def get_link(self, path, method, base_url):
-            link = super().get_link(path, method, base_url)
-            # Do something to customize link here...
-            return link
-
-    class MyView(APIView):
-      schema = CustomViewSchema()
-
-The following methods are available to override.
-
-### get_link(self, path, method, base_url)
-
-Returns a `coreapi.Link` instance corresponding to the given view.
-
-This is the main entry point.
-You can override this if you need to provide custom behaviors for particular views.
-
-### get_description(self, path, method)
-
-Returns a string to use as the link description. By default this is based on the
-view docstring as described in the "Schemas as Documentation" section above.
-
-### get_encoding(self, path, method)
-
-Returns a string to indicate the encoding for any request body, when interacting
-with the given view. Eg. `'application/json'`. May return a blank string for views
-that do not expect a request body.
-
-### get_path_fields(self, path, method):
-
-Return a list of `coreapi.Field()` instances. One for each path parameter in the URL.
-
-### get_serializer_fields(self, path, method)
-
-Return a list of `coreapi.Field()` instances. One for each field in the serializer class used by the view.
-
-### get_pagination_fields(self, path, method)
-
-Return a list of `coreapi.Field()` instances, as returned by the `get_schema_fields()` method on any pagination class used by the view.
-
-### get_filter_fields(self, path, method)
-
-Return a list of `coreapi.Field()` instances, as returned by the `get_schema_fields()` method of any filter classes used by the view.
-
-### get_manual_fields(self, path, method)
-
-Return a list of `coreapi.Field()` instances to be added to or replace generated fields. Defaults to (optional) `manual_fields` passed to `AutoSchema` constructor.
-
-May be overridden to customise manual fields by `path` or `method`. For example, a per-method adjustment may look like this:
-
-```python
-def get_manual_fields(self, path, method):
-    """Example adding per-method fields."""
-
-    extra_fields = []
-    if method=='GET':
-        extra_fields = # ... list of extra fields for GET ...
-    if method=='POST':
-        extra_fields = # ... list of extra fields for POST ...
-
-    manual_fields = super().get_manual_fields(path, method)
-    return manual_fields + extra_fields
-```
-
-### update_fields(fields, update_with)
-
-Utility `staticmethod`. Encapsulates logic to add or replace fields from a list
-by `Field.name`. May be overridden to adjust replacement criteria.
-
-
-## ManualSchema
-
-Allows manually providing a list of `coreapi.Field` instances for the schema,
-plus an optional description.
-
-    class MyView(APIView):
-      schema = ManualSchema(fields=[
-            coreapi.Field(
-                "first_field",
-                required=True,
-                location="path",
-                schema=coreschema.String()
-            ),
-            coreapi.Field(
-                "second_field",
-                required=True,
-                location="path",
-                schema=coreschema.String()
-            ),
-        ]
-      )
-
-The `ManualSchema` constructor takes two arguments:
-
-**`fields`**: A list of `coreapi.Field` instances. Required.
-
-**`description`**: A string description. Optional.
-
-**`encoding`**: Default `None`. A string encoding, e.g `application/json`. Optional.
-
----
-
-## Core API
-
-This documentation gives a brief overview of the components within the `coreapi`
-package that are used to represent an API schema.
-
-Note that these classes are imported from the `coreapi` package, rather than
-from the `rest_framework` package.
-
-### Document
-
-Represents a container for the API schema.
-
-#### `title`
-
-A name for the API.
-
-#### `url`
-
-A canonical URL for the API.
-
-#### `content`
-
-A dictionary, containing the `Link` objects that the schema contains.
-
-In order to provide more structure to the schema, the `content` dictionary
-may be nested, typically to a second level. For example:
-
-    content={
-        "bookings": {
-            "list": Link(...),
-            "create": Link(...),
-            ...
-        },
-        "venues": {
-            "list": Link(...),
-            ...
-        },
-        ...
-    }
-
-### Link
-
-Represents an individual API endpoint.
-
-#### `url`
-
-The URL of the endpoint. May be a URI template, such as `/users/{username}/`.
-
-#### `action`
-
-The HTTP method associated with the endpoint. Note that URLs that support
-more than one HTTP method, should correspond to a single `Link` for each.
-
-#### `fields`
-
-A list of `Field` instances, describing the available parameters on the input.
-
-#### `description`
-
-A short description of the meaning and intended usage of the endpoint.
-
-### Field
-
-Represents a single input parameter on a given API endpoint.
-
-#### `name`
-
-A descriptive name for the input.
-
-#### `required`
-
-A boolean, indicated if the client is required to included a value, or if
-the parameter can be omitted.
-
-#### `location`
-
-Determines how the information is encoded into the request. Should be one of
-the following strings:
-
-**"path"**
-
-Included in a templated URI. For example a `url` value of `/products/{product_code}/` could be used together with a `"path"` field, to handle API inputs in a URL path such as `/products/slim-fit-jeans/`.
-
-These fields will normally correspond with [named arguments in the project URL conf][named-arguments].
-
-**"query"**
-
-Included as a URL query parameter. For example `?search=sale`. Typically for `GET` requests.
-
-These fields will normally correspond with pagination and filtering controls on a view.
-
-**"form"**
-
-Included in the request body, as a single item of a JSON object or HTML form. For example `{"colour": "blue", ...}`. Typically for `POST`, `PUT` and `PATCH` requests. Multiple `"form"` fields may be included on a single link.
-
-These fields will normally correspond with serializer fields on a view.
-
-**"body"**
-
-Included as the complete request body. Typically for `POST`, `PUT` and `PATCH` requests. No more than one `"body"` field may exist on a link. May not be used together with `"form"` fields.
-
-These fields will normally correspond with views that use `ListSerializer` to validate the request input, or with file upload views.
-
-#### `encoding`
-
-**"application/json"**
-
-JSON encoded request content. Corresponds to views using `JSONParser`.
-Valid only if either one or more `location="form"` fields, or a single
-`location="body"` field is included on the `Link`.
-
-**"multipart/form-data"**
-
-Multipart encoded request content. Corresponds to views using `MultiPartParser`.
-Valid only if one or more `location="form"` fields is included on the `Link`.
-
-**"application/x-www-form-urlencoded"**
-
-URL encoded request content. Corresponds to views using `FormParser`. Valid
-only if one or more `location="form"` fields is included on the `Link`.
-
-**"application/octet-stream"**
-
-Binary upload request content. Corresponds to views using `FileUploadParser`.
-Valid only if a `location="body"` field is included on the `Link`.
-
-#### `description`
-
-A short description of the meaning and intended usage of the input field.
-
-
----
-
-# Third party packages
-
-## drf-yasg - Yet Another Swagger Generator
-
-[drf-yasg][drf-yasg] generates [OpenAPI][open-api] documents suitable for code generation - nested schemas,
-named models, response bodies, enum/pattern/min/max validators, form parameters, etc.
-
-[cite]: https://blog.heroku.com/archives/2014/1/8/json_schema_for_heroku_platform_api
-[coreapi]: https://www.coreapi.org/
-[corejson]: https://www.coreapi.org/specification/encoding/#core-json-encoding
-[drf-yasg]: https://github.com/axnsan12/drf-yasg/
-[open-api]: https://openapis.org/
-[json-hyperschema]: https://json-schema.org/latest/json-schema-hypermedia.html
-[api-blueprint]: https://apiblueprint.org/
-[static-files]: https://docs.djangoproject.com/en/stable/howto/static-files/
-[named-arguments]: https://docs.djangoproject.com/en/stable/topics/http/urls/#named-groups

docs/api-guide/serializers.md

@@ -1,4 +1,7 @@
-source: serializers.py
+---
+source:
+    - serializers.py
+---
 
 # Serializers
 
@@ -308,7 +311,7 @@ The following example demonstrates how you might handle creating a user with a n
 
         class Meta:
             model = User
-            fields = ('username', 'email', 'profile')
+            fields = ['username', 'email', 'profile']
 
         def create(self, validated_data):
             profile_data = validated_data.pop('profile')
@@ -438,7 +441,7 @@ Declaring a `ModelSerializer` looks like this:
     class AccountSerializer(serializers.ModelSerializer):
         class Meta:
             model = Account
-            fields = ('id', 'account_name', 'users', 'created')
+            fields = ['id', 'account_name', 'users', 'created']
 
 By default, all the model fields on the class will be mapped to a corresponding serializer fields.
 
@@ -467,7 +470,7 @@ For example:
     class AccountSerializer(serializers.ModelSerializer):
         class Meta:
             model = Account
-            fields = ('id', 'account_name', 'users', 'created')
+            fields = ['id', 'account_name', 'users', 'created']
 
 You can also set the `fields` attribute to the special value `'__all__'` to indicate that all fields in the model should be used.
 
@@ -485,7 +488,7 @@ For example:
     class AccountSerializer(serializers.ModelSerializer):
         class Meta:
             model = Account
-            exclude = ('users',)
+            exclude = ['users']
 
 In the example above, if the `Account` model had 3 fields `account_name`, `users`, and `created`, this will result in the fields `account_name` and `created` to be serialized.
 
@@ -502,7 +505,7 @@ The default `ModelSerializer` uses primary keys for relationships, but you can a
     class AccountSerializer(serializers.ModelSerializer):
         class Meta:
             model = Account
-            fields = ('id', 'account_name', 'users', 'created')
+            fields = ['id', 'account_name', 'users', 'created']
             depth = 1
 
 The `depth` option should be set to an integer value that indicates the depth of relationships that should be traversed before reverting to a flat representation.
@@ -531,8 +534,8 @@ This option should be a list or tuple of field names, and is declared as follows
     class AccountSerializer(serializers.ModelSerializer):
         class Meta:
             model = Account
-            fields = ('id', 'account_name', 'users', 'created')
+            fields = ['id', 'account_name', 'users', 'created']
-            read_only_fields = ('account_name',)
+            read_only_fields = ['account_name']
 
 Model fields which have `editable=False` set, and `AutoField` fields will be set to read-only by default, and do not need to be added to the `read_only_fields` option.
 
@@ -560,7 +563,7 @@ This option is a dictionary, mapping field names to a dictionary of keyword argu
     class CreateUserSerializer(serializers.ModelSerializer):
         class Meta:
             model = User
-            fields = ('email', 'username', 'password')
+            fields = ['email', 'username', 'password']
             extra_kwargs = {'password': {'write_only': True}}
 
         def create(self, validated_data):
@@ -670,7 +673,7 @@ You can explicitly include the primary key by adding it to the `fields` option,
     class AccountSerializer(serializers.HyperlinkedModelSerializer):
         class Meta:
             model = Account
-            fields = ('url', 'id', 'account_name', 'users', 'created')
+            fields = ['url', 'id', 'account_name', 'users', 'created']
 
 ## Absolute and relative URLs
 
@@ -702,7 +705,7 @@ You can override a URL field view name and lookup field by using either, or both
     class AccountSerializer(serializers.HyperlinkedModelSerializer):
         class Meta:
             model = Account
-            fields = ('account_url', 'account_name', 'users', 'created')
+            fields = ['account_url', 'account_name', 'users', 'created']
             extra_kwargs = {
                 'url': {'view_name': 'accounts', 'lookup_field': 'account_name'},
                 'users': {'lookup_field': 'username'}
@@ -724,7 +727,7 @@ Alternatively you can set the fields on the serializer explicitly. For example:
 
         class Meta:
             model = Account
-            fields = ('url', 'account_name', 'users', 'created')
+            fields = ['url', 'account_name', 'users', 'created']
 
 ---
 
@@ -963,6 +966,7 @@ The following class is an example of a generic serializer that can handle coerci
         into primitive representations.
         """
         def to_representation(self, obj):
+            output = {}
             for attribute_name in dir(obj):
                 attribute = getattr(obj, attribute_name)
                 if attribute_name.startswith('_'):
@@ -988,6 +992,7 @@ The following class is an example of a generic serializer that can handle coerci
                 else:
                     # Force anything else to its string representation.
                     output[attribute_name] = str(attribute)
+            return output
 
 ---
 
@@ -1094,7 +1099,7 @@ This would then allow you to do the following:
     >>> class UserSerializer(DynamicFieldsModelSerializer):
     >>>     class Meta:
     >>>         model = User
-    >>>         fields = ('id', 'username', 'email')
+    >>>         fields = ['id', 'username', 'email']
     >>>
     >>> print(UserSerializer(user))
     {'id': 2, 'username': 'jonwatts', 'email': 'jon@example.com'}

docs/api-guide/settings.md

@@ -1,4 +1,7 @@
-source: settings.py
+---
+source:
+    - settings.py
+---
 
 # Settings
 
@@ -11,12 +14,12 @@ Configuration for REST framework is all namespaced inside a single Django settin
 For example your project's `settings.py` file might include something like this:
 
     REST_FRAMEWORK = {
-        'DEFAULT_RENDERER_CLASSES': (
+        'DEFAULT_RENDERER_CLASSES': [
             'rest_framework.renderers.JSONRenderer',
-        ),
+        ],
-        'DEFAULT_PARSER_CLASSES': (
+        'DEFAULT_PARSER_CLASSES': [
             'rest_framework.parsers.JSONParser',
-        )
+        ]
     }
 
 ## Accessing settings
@@ -44,10 +47,10 @@ A list or tuple of renderer classes, that determines the default set of renderer
 
 Default:
 
-    (
+    [
         'rest_framework.renderers.JSONRenderer',
         'rest_framework.renderers.BrowsableAPIRenderer',
-    )
+    ]
 
 #### DEFAULT_PARSER_CLASSES
 
@@ -55,11 +58,11 @@ A list or tuple of parser classes, that determines the default set of parsers us
 
 Default:
 
-    (
+    [
         'rest_framework.parsers.JSONParser',
         'rest_framework.parsers.FormParser',
         'rest_framework.parsers.MultiPartParser'
-    )
+    ]
 
 #### DEFAULT_AUTHENTICATION_CLASSES
 
@@ -67,10 +70,10 @@ A list or tuple of authentication classes, that determines the default set of au
 
 Default:
 
-    (
+    [
         'rest_framework.authentication.SessionAuthentication',
         'rest_framework.authentication.BasicAuthentication'
-    )
+    ]
 
 #### DEFAULT_PERMISSION_CLASSES
 
@@ -78,15 +81,15 @@ A list or tuple of permission classes, that determines the default set of permis
 
 Default:
 
-    (
+    [
         'rest_framework.permissions.AllowAny',
-    )
+    ]
 
 #### DEFAULT_THROTTLE_CLASSES
 
 A list or tuple of throttle classes, that determines the default set of throttles checked at the start of a view.
 
-Default: `()`
+Default: `[]`
 
 #### DEFAULT_CONTENT_NEGOTIATION_CLASS
 
@@ -106,32 +109,19 @@ Default: `'rest_framework.schemas.AutoSchema'`
 
 *The following settings control the behavior of the generic class-based views.*
 
-#### DEFAULT_PAGINATION_SERIALIZER_CLASS
-
----
-
-**This setting has been removed.**
-
-The pagination API does not use serializers to determine the output format, and
-you'll need to instead override the `get_paginated_response method on a
-pagination class in order to specify how the output format is controlled.
-
----
-
 #### DEFAULT_FILTER_BACKENDS
 
 A list of filter backend classes that should be used for generic filtering.
 If set to `None` then generic filtering is disabled.
 
-#### PAGINATE_BY
+#### DEFAULT_PAGINATION_CLASS
 
----
+The default class to use for queryset pagination. If set to `None`, pagination
+is disabled by default. See the pagination documentation for further guidance on
+[setting](pagination.md#setting-the-pagination-style) and
+[modifying](pagination.md#modifying-the-pagination-style) the pagination style.
 
-**This setting has been removed.**
+Default: `None`
-
-See the pagination documentation for further guidance on [setting the pagination style](pagination.md#modifying-the-pagination-style).
-
----
 
 #### PAGE_SIZE
 
@@ -139,26 +129,6 @@ The default page size to use for pagination.  If set to `None`, pagination is di
 
 Default: `None`
 
-#### PAGINATE_BY_PARAM
-
----
-
-**This setting has been removed.**
-
-See the pagination documentation for further guidance on [setting the pagination style](pagination.md#modifying-the-pagination-style).
-
----
-
-#### MAX_PAGINATE_BY
-
----
-
-**This setting has been removed.**
-
-See the pagination documentation for further guidance on [setting the pagination style](pagination.md#modifying-the-pagination-style).
-
----
-
 ### SEARCH_PARAM
 
 The name of a query parameter, which can be used to specify the search term used by `SearchFilter`.
@@ -235,10 +205,10 @@ The format of any of these renderer classes may be used when constructing a test
 
 Default:
 
-    (
+    [
         'rest_framework.renderers.MultiPartRenderer',
         'rest_framework.renderers.JSONRenderer'
-    )
+    ]
 
 ---
 
@@ -404,7 +374,7 @@ This should be a function with the following signature:
 
 If the view instance inherits `ViewSet`, it may have been initialized with several optional arguments:
 
-* `name`: A name expliticly provided to a view in the viewset. Typically, this value should be used as-is when provided.
+* `name`: A name explicitly provided to a view in the viewset. Typically, this value should be used as-is when provided.
 * `suffix`: Text used when differentiating individual views in a viewset. This argument is mutually exclusive to `name`.
 * `detail`: Boolean that differentiates an individual view in a viewset as either being a 'list' or 'detail' view.
 

docs/api-guide/status-codes.md

@@ -1,4 +1,7 @@
-source: status.py
+---
+source:
+    - status.py
+---
 
 # Status Codes
 
@@ -20,13 +23,13 @@ The full set of HTTP status codes included in the `status` module is listed belo
 The module also includes a set of helper functions for testing if a status code is in a given range.
 
     from rest_framework import status
-	from rest_framework.test import APITestCase
+    from rest_framework.test import APITestCase
 
-	class ExampleTestCase(APITestCase):
+    class ExampleTestCase(APITestCase):
-	    def test_url_root(self):
+        def test_url_root(self):
-	        url = reverse('index')
+            url = reverse('index')
-	        response = self.client.get(url)
+            response = self.client.get(url)
-	        self.assertTrue(status.is_success(response.status_code))
+            self.assertTrue(status.is_success(response.status_code))
 
 
 For more information on proper usage of HTTP status codes see [RFC 2616][rfc2616]
@@ -51,6 +54,8 @@ This class of status code indicates that the client's request was successfully r
     HTTP_205_RESET_CONTENT
     HTTP_206_PARTIAL_CONTENT
     HTTP_207_MULTI_STATUS
+    HTTP_208_ALREADY_REPORTED
+    HTTP_226_IM_USED
 
 ## Redirection - 3xx
 
@@ -64,6 +69,7 @@ This class of status code indicates that further action needs to be taken by the
     HTTP_305_USE_PROXY
     HTTP_306_RESERVED
     HTTP_307_TEMPORARY_REDIRECT
+    HTTP_308_PERMANENT_REDIRECT
 
 ## Client Error - 4xx
 
@@ -90,6 +96,7 @@ The 4xx class of status code is intended for cases in which the client seems to
     HTTP_422_UNPROCESSABLE_ENTITY
     HTTP_423_LOCKED
     HTTP_424_FAILED_DEPENDENCY
+    HTTP_426_UPGRADE_REQUIRED
     HTTP_428_PRECONDITION_REQUIRED
     HTTP_429_TOO_MANY_REQUESTS
     HTTP_431_REQUEST_HEADER_FIELDS_TOO_LARGE
@@ -105,7 +112,11 @@ Response status codes beginning with the digit "5" indicate cases in which the s
     HTTP_503_SERVICE_UNAVAILABLE
     HTTP_504_GATEWAY_TIMEOUT
     HTTP_505_HTTP_VERSION_NOT_SUPPORTED
+    HTTP_506_VARIANT_ALSO_NEGOTIATES
     HTTP_507_INSUFFICIENT_STORAGE
+    HTTP_508_LOOP_DETECTED
+    HTTP_509_BANDWIDTH_LIMIT_EXCEEDED
+    HTTP_510_NOT_EXTENDED
     HTTP_511_NETWORK_AUTHENTICATION_REQUIRED
 
 ## Helper functions

docs/api-guide/testing.md

@@ -1,4 +1,7 @@
-source: test.py
+---
+source:
+    - test.py
+---
 
 # Testing
 
@@ -399,11 +402,11 @@ For example, to add support for using `format='html'` in test requests, you migh
 
     REST_FRAMEWORK = {
         ...
-        'TEST_REQUEST_RENDERER_CLASSES': (
+        'TEST_REQUEST_RENDERER_CLASSES': [
             'rest_framework.renderers.MultiPartRenderer',
             'rest_framework.renderers.JSONRenderer',
             'rest_framework.renderers.TemplateHTMLRenderer'
-        )
+        ]
     }
 
 [cite]: https://jacobian.org/writing/django-apps-with-buildout/#s-create-a-test-wrapper

docs/api-guide/throttling.md

@@ -1,4 +1,7 @@
-source: throttling.py
+---
+source:
+    - throttling.py
+---
 
 # Throttling
 
@@ -28,10 +31,10 @@ If any throttle check fails an `exceptions.Throttled` exception will be raised,
 The default throttling policy may be set globally, using the `DEFAULT_THROTTLE_CLASSES` and `DEFAULT_THROTTLE_RATES` settings.  For example.
 
     REST_FRAMEWORK = {
-        'DEFAULT_THROTTLE_CLASSES': (
+        'DEFAULT_THROTTLE_CLASSES': [
             'rest_framework.throttling.AnonRateThrottle',
             'rest_framework.throttling.UserRateThrottle'
-        ),
+        ],
         'DEFAULT_THROTTLE_RATES': {
             'anon': '100/day',
             'user': '1000/day'
@@ -48,7 +51,7 @@ using the `APIView` class-based views.
 	from rest_framework.views import APIView
 
     class ExampleView(APIView):
-        throttle_classes = (UserRateThrottle,)
+        throttle_classes = [UserRateThrottle]
 
         def get(self, request, format=None):
             content = {
@@ -74,7 +77,7 @@ If you need to strictly identify unique client IP addresses, you'll need to firs
 
 It is important to understand that if you configure the `NUM_PROXIES` setting, then all clients behind a unique [NAT'd](https://en.wikipedia.org/wiki/Network_address_translation) gateway will be treated as a single client.
 
-Further context on how the `X-Forwarded-For` header works, and identifying a remote client IP can be [found here][identifing-clients].
+Further context on how the `X-Forwarded-For` header works, and identifying a remote client IP can be [found here][identifying-clients].
 
 ## Setting up the cache
 
@@ -126,10 +129,10 @@ For example, multiple user throttle rates could be implemented by using the foll
 ...and the following settings.
 
     REST_FRAMEWORK = {
-        'DEFAULT_THROTTLE_CLASSES': (
+        'DEFAULT_THROTTLE_CLASSES': [
             'example.throttles.BurstRateThrottle',
             'example.throttles.SustainedRateThrottle'
-        ),
+        ],
         'DEFAULT_THROTTLE_RATES': {
             'burst': '60/min',
             'sustained': '1000/day'
@@ -161,9 +164,9 @@ For example, given the following views...
 ...and the following settings.
 
     REST_FRAMEWORK = {
-        'DEFAULT_THROTTLE_CLASSES': (
+        'DEFAULT_THROTTLE_CLASSES': [
             'rest_framework.throttling.ScopedRateThrottle',
-        ),
+        ],
         'DEFAULT_THROTTLE_RATES': {
             'contacts': '1000/day',
             'uploads': '20/day'
@@ -194,6 +197,6 @@ The following is an example of a rate throttle, that will randomly throttle 1 in
 
 [cite]: https://developer.twitter.com/en/docs/basics/rate-limiting
 [permissions]: permissions.md
-[identifing-clients]: http://oxpedia.org/wiki/index.php?title=AppSuite:Grizzly#Multiple_Proxies_in_front_of_the_cluster
+[identifying-clients]: http://oxpedia.org/wiki/index.php?title=AppSuite:Grizzly#Multiple_Proxies_in_front_of_the_cluster
 [cache-setting]: https://docs.djangoproject.com/en/stable/ref/settings/#caches
 [cache-docs]: https://docs.djangoproject.com/en/stable/topics/cache/#setting-up-the-cache

docs/api-guide/validators.md

@@ -1,4 +1,7 @@
-source: validators.py
+---
+source:
+    - validators.py
+---
 
 # Validators
 
@@ -94,7 +97,7 @@ The validator should be applied to *serializer classes*, like so:
             validators = [
                 UniqueTogetherValidator(
                     queryset=ToDoItem.objects.all(),
-                    fields=('list', 'position')
+                    fields=['list', 'position']
                 )
             ]
 
@@ -149,8 +152,6 @@ If you want the date field to be visible, but not editable by the user, then set
 
     published = serializers.DateTimeField(read_only=True, default=timezone.now)
 
-The field will not be writable to the user, but the default value will still be passed through to the `validated_data`.
-
 #### Using with a hidden date field.
 
 If you want the date field to be entirely hidden from the user, then use `HiddenField`. This field type does not accept user input, but instead always returns its default value to the `validated_data` in the serializer.
@@ -221,7 +222,7 @@ For example:
             # Apply custom validation either here, or in the view.
 
         class Meta:
-            fields = ('client', 'date', 'amount')
+            fields = ['client', 'date', 'amount']
             extra_kwargs = {'client': {'required': False}}
             validators = []  # Remove a default "unique together" constraint.
 

docs/api-guide/versioning.md

@@ -1,4 +1,7 @@
-source: versioning.py
+---
+source:
+    - versioning.py
+---
 
 # Versioning
 

docs/api-guide/views.md

@@ -1,5 +1,8 @@
-source: decorators.py
+---
-        views.py
+source:
+    - decorators.py
+    - views.py
+---
 
 # Class-based Views
 
@@ -32,8 +35,8 @@ For example:
         * Requires token authentication.
         * Only admin users are able to access this view.
         """
-        authentication_classes = (authentication.TokenAuthentication,)
+        authentication_classes = [authentication.TokenAuthentication]
-        permission_classes = (permissions.IsAdminUser,)
+        permission_classes = [permissions.IsAdminUser]
 
         def get(self, request, format=None):
             """

docs/api-guide/viewsets.md

@@ -1,4 +1,7 @@
-source: viewsets.py
+---
+source:
+    - viewsets.py
+---
 
 # ViewSets
 

docs/community/3.0-announcement.md

@@ -258,13 +258,13 @@ If you try to use a writable nested serializer without writing a custom `create(
     >>> class ProfileSerializer(serializers.ModelSerializer):
     >>>     class Meta:
     >>>         model = Profile
-    >>>         fields = ('address', 'phone')
+    >>>         fields = ['address', 'phone']
     >>>
     >>> class UserSerializer(serializers.ModelSerializer):
     >>>     profile = ProfileSerializer()
     >>>     class Meta:
     >>>         model = User
-    >>>         fields = ('username', 'email', 'profile')
+    >>>         fields = ['username', 'email', 'profile']
     >>>
     >>> data = {
     >>>     'username': 'lizzy',
@@ -283,7 +283,7 @@ To use writable nested serialization you'll want to declare a nested field on th
 
         class Meta:
             model = User
-            fields = ('username', 'email', 'profile')
+            fields = ['username', 'email', 'profile']
 
         def create(self, validated_data):
             profile_data = validated_data.pop('profile')
@@ -327,7 +327,7 @@ The `write_only_fields` option on `ModelSerializer` has been moved to `PendingDe
     class MySerializer(serializer.ModelSerializer):
         class Meta:
             model = MyModel
-            fields = ('id', 'email', 'notes', 'is_admin')
+            fields = ['id', 'email', 'notes', 'is_admin']
             extra_kwargs = {
                     'is_admin': {'write_only': True}
             }
@@ -339,7 +339,7 @@ Alternatively, specify the field explicitly on the serializer class:
 
         class Meta:
             model = MyModel
-            fields = ('id', 'email', 'notes', 'is_admin')
+            fields = ['id', 'email', 'notes', 'is_admin']
 
 The `read_only_fields` option remains as a convenient shortcut for the more common case.
 
@@ -350,7 +350,7 @@ The `view_name` and `lookup_field` options have been moved to `PendingDeprecatio
     class MySerializer(serializer.HyperlinkedModelSerializer):
         class Meta:
             model = MyModel
-            fields = ('url', 'email', 'notes', 'is_admin')
+            fields = ['url', 'email', 'notes', 'is_admin']
             extra_kwargs = {
                 'url': {'lookup_field': 'uuid'}
             }
@@ -365,7 +365,7 @@ Alternatively, specify the field explicitly on the serializer class:
 
         class Meta:
             model = MyModel
-            fields = ('url', 'email', 'notes', 'is_admin')
+            fields = ['url', 'email', 'notes', 'is_admin']
 
 #### Fields for model methods and properties.
 
@@ -384,7 +384,7 @@ You can include `expiry_date` as a field option on a `ModelSerializer` class.
     class InvitationSerializer(serializers.ModelSerializer):
         class Meta:
             model = Invitation
-            fields = ('to_email', 'message', 'expiry_date')
+            fields = ['to_email', 'message', 'expiry_date']
 
 These fields will be mapped to `serializers.ReadOnlyField()` instances.
 
@@ -738,7 +738,7 @@ The `UniqueTogetherValidator` should be applied to a serializer, and takes a `qu
         class Meta:
             validators = [UniqueTogetherValidator(
                 queryset=RaceResult.objects.all(),
-                fields=('category', 'position')
+                fields=['category', 'position']
             )]
 
 #### The `UniqueForDateValidator` classes.

docs/community/3.1-announcement.md

@@ -61,7 +61,7 @@ For example, when using `NamespaceVersioning`, and the following hyperlinked ser
     class AccountsSerializer(serializer.HyperlinkedModelSerializer):
         class Meta:
             model = Accounts
-            fields = ('account_name', 'users')
+            fields = ['account_name', 'users']
 
 The output representation would match the version used on the incoming request. Like so:
 

docs/community/3.10-announcement.md

@@ -0,0 +1,147 @@
+<style>
+.promo li a {
+    float: left;
+    width: 130px;
+    height: 20px;
+    text-align: center;
+    margin: 10px 30px;
+    padding: 150px 0 0 0;
+    background-position: 0 50%;
+    background-size: 130px auto;
+    background-repeat: no-repeat;
+    font-size: 120%;
+    color: black;
+}
+.promo li {
+    list-style: none;
+}
+</style>
+
+# Django REST framework 3.10
+
+The 3.10 release drops support for Python 2.
+
+* Our supported Python versions are now: 3.5, 3.6, and 3.7.
+* Our supported Django versions are now: 1.11, 2.0, 2.1, and 2.2.
+
+## OpenAPI Schema Generation
+
+Since we first introduced schema support in Django REST Framework 3.5, OpenAPI has emerged as the widely adopted standard for modeling Web APIs.
+
+This release begins the deprecation process for the CoreAPI based schema generation, and introduces OpenAPI schema generation in its place.
+
+---
+
+## Continuing to use CoreAPI
+
+If you're currently using the CoreAPI schemas, you'll need to make sure to
+update your REST framework settings to include `DEFAULT_SCHEMA_CLASS` explicitly.
+
+**settings.py**:
+
+```python
+REST_FRAMEWORK = {
+  ...
+  'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema'
+}
+```
+
+You'll still be able to keep using CoreAPI schemas, API docs, and client for the
+foreseeable future. We'll aim to ensure that the CoreAPI schema generator remains
+available as a third party package, even once it has eventually been removed
+from REST framework, scheduled for version 3.12.
+
+We have removed the old documentation for the CoreAPI based schema generation.
+You may view the [Legacy CoreAPI documentation here][legacy-core-api-docs].
+
+----
+
+## OpenAPI Quickstart
+
+You can generate a static OpenAPI schema, using the `generateschema` management
+command.
+
+Alternately, to have the project serve an API schema, use the `get_schema_view()`
+shortcut.
+
+In your `urls.py`:
+
+```python
+from rest_framework.schemas import get_schema_view
+
+urlpatterns = [
+    # ...
+    # Use the `get_schema_view()` helper to add a `SchemaView` to project URLs.
+    #   * `title` and `description` parameters are passed to `SchemaGenerator`.
+    #   * Provide view name for use with `reverse()`.
+    path('openapi', get_schema_view(
+        title="Your Project",
+        description="API for all things …"
+    ), name='openapi-schema'),
+    # ...
+]
+```
+
+### Customization
+
+For customizations that you want to apply across the the entire API, you can subclass `rest_framework.schemas.openapi.SchemaGenerator` and provide it as an argument
+to the `generateschema` command or `get_schema_view()` helper function.
+
+For specific per-view customizations, you can subclass `AutoSchema`,
+making sure to set `schema = <YourCustomClass>` on the view.
+
+For more details, see the [API Schema documentation](../api-guide/schemas.md).
+
+### API Documentation
+
+There are some great third party options for documenting your API, based on the
+OpenAPI schema.
+
+See the [Documenting you API](../topics/documenting-your-api.md) section for more details.
+
+---
+
+## Feature Roadmap
+
+Given that our OpenAPI schema generation is a new feature, it's likely that there
+will still be some iterative improvements for us to make. There will be two
+main cases here:
+
+* Expanding the supported range of OpenAPI schemas that are generated by default.
+* Improving the ability for developers to customize the output.
+
+We'll aim to bring the first type of change quickly in point releases. For the
+second kind we'd like to adopt a slower approach, to make sure we keep the API
+simple, and as widely applicable as possible, before we bring in API changes.
+
+It's also possible that we'll end up implementing API documentation and API client
+tooling that are driven by the OpenAPI schema. The `apistar` project has a
+significant amount of work towards this. However, if we do so, we'll plan
+on keeping any tooling outside of the core framework.
+
+---
+
+## Funding
+
+REST framework is a *collaboratively funded project*. If you use
+REST framework commercially we strongly encourage you to invest in its
+continued development by **[signing up for a paid plan][funding]**.
+
+*Every single sign-up helps us make REST framework long-term financially sustainable.*
+
+<ul class="premium-promo promo">
+    <li><a href="https://getsentry.com/welcome/" style="background-image: url(https://fund-rest-framework.s3.amazonaws.com/sentry130.png)">Sentry</a></li>
+    <li><a href="https://getstream.io/try-the-api/?utm_source=drf&utm_medium=banner&utm_campaign=drf" style="background-image: url(https://fund-rest-framework.s3.amazonaws.com/stream-130.png)">Stream</a></li>
+    <li><a href="https://software.esg-usa.com" style="background-image: url(https://fund-rest-framework.s3.amazonaws.com/esg-new-logo.png)">ESG</a></li>
+    <li><a href="https://rollbar.com" style="background-image: url(https://fund-rest-framework.s3.amazonaws.com/rollbar2.png)">Rollbar</a></li>
+    <li><a href="https://cadre.com" style="background-image: url(https://fund-rest-framework.s3.amazonaws.com/cadre.png)">Cadre</a></li>
+    <li><a href="https://hubs.ly/H0f30Lf0" style="background-image: url(https://fund-rest-framework.s3.amazonaws.com/kloudless-plus-text.png)">Kloudless</a></li>
+    <li><a href="https://lightsonsoftware.com" style="background-image: url(https://fund-rest-framework.s3.amazonaws.com/lightson-dark.png)">Lights On Software</a></li>
+</ul>
+<div style="clear: both; padding-bottom: 20px;"></div>
+
+*Many thanks to all our [wonderful sponsors][sponsors], and in particular to our premium backers, [Sentry](https://getsentry.com/welcome/), [Stream](https://getstream.io/?utm_source=drf&utm_medium=banner&utm_campaign=drf), [ESG](https://software.esg-usa.com/), [Rollbar](https://rollbar.com/?utm_source=django&utm_medium=sponsorship&utm_campaign=freetrial), [Cadre](https://cadre.com), [Kloudless](https://hubs.ly/H0f30Lf0), and [Lights On Software](https://lightsonsoftware.com).*
+
+[legacy-core-api-docs]:https://github.com/encode/django-rest-framework/blob/master/docs/coreapi/index.md
+[sponsors]: https://fund.django-rest-framework.org/topics/funding/#our-sponsors
+[funding]: community/funding.md

docs/community/3.6-announcement.md

@@ -60,7 +60,7 @@ REST framework's new API documentation supports a number of features:
 * Support for various authentication schemes.
 * Code snippets for the Python, JavaScript, and Command Line clients.
 
-The `coreapi` library is required as a dependancy for the API docs. Make sure
+The `coreapi` library is required as a dependency for the API docs. Make sure
 to install the latest version (2.3.0 or above). The `pygments` and `markdown`
 libraries are optional but recommended.
 

docs/community/jobs.md

@@ -9,6 +9,7 @@ Looking for a new Django REST Framework related role? On this site we provide a
 * [https://www.python.org/jobs/][python-org-jobs]
 * [https://djangogigs.com][django-gigs-com]
 * [https://djangojobs.net/jobs/][django-jobs-net]
+* [https://findwork.dev/django-rest-framework-jobs][findwork-dev]
 * [https://www.indeed.com/q-Django-jobs.html][indeed-com]
 * [https://stackoverflow.com/jobs/developer-jobs-using-django][stackoverflow-com]
 * [https://www.upwork.com/o/jobs/browse/skill/django-framework/][upwork-com]
@@ -26,6 +27,7 @@ Wonder how else you can help? One of the best ways you can help Django REST Fram
 [python-org-jobs]: https://www.python.org/jobs/
 [django-gigs-com]: https://djangogigs.com
 [django-jobs-net]: https://djangojobs.net/jobs/
+[findwork-dev]: https://findwork.dev/django-rest-framework-jobs
 [indeed-com]: https://www.indeed.com/q-Django-jobs.html
 [stackoverflow-com]: https://stackoverflow.com/jobs/developer-jobs-using-django
 [upwork-com]: https://www.upwork.com/o/jobs/browse/skill/django-framework/

docs/community/release-notes.md

@@ -38,11 +38,66 @@ You can determine your currently installed version using `pip show`:
 
 ---
 
+## 3.10.x series
+
+### 3.10.3
+
+* Include API version in OpenAPI schema generation, defaulting to empty string.
+* Add pagination properties to OpenAPI response schemas.
+* Add missing "description" property to OpenAPI response schemas.
+* Only include "required" for non-empty cases in OpenAPI schemas.
+* Fix response schemas for "DELETE" case in OpenAPI schemas.
+* Use an array type for list view response schemas.
+* Use consistent `lowerInitialCamelCase` style in OpenAPI operation IDs.
+* Fix `minLength`/`maxLength`/`minItems`/`maxItems` properties in OpenAPI schemas.
+* Only call `FileField.url` once in serialization, for improved performance.
+* Fix an edge case where throttling calcualtions could error after a configuration change.
+
+* TODO
+
+### 3.10.2
+
+**Date**: 29th July 2019
+
+* Various `OpenAPI` schema fixes.
+* Ability to specify urlconf in include_docs_urls.
+
+### 3.10.1
+
+**Date**: 17th July 2019
+
+* Don't include autocomplete fields on TokenAuth admin, since it forces constraints on custom user models & admin.
+* Require `uritemplate` for OpenAPI schema generation, but not `coreapi`.
+
+### 3.10.0
+
+**Date**: [15th July 2019][3.10.0-milestone]
+
+* Switch to OpenAPI schema generation.
+* Drop Python 2 support.
+* Add `generateschema --generator_class` CLI option
+* Updated PyYaml dependency for OpenAPI schema generation to `pyyaml>=5.1` [#6680][gh6680]
+* Resolve DeprecationWarning with markdown. [#6317][gh6317]
+* Use `user.get_username` in templates, in preference to `user.username`.
+* Fix for cursor pagination issue that could occur after object deletions.
+* Fix for nullable fields with `source="*"`
+* Always apply all throttle classes during throttling checks.
+* Updates to jQuery and Markdown dependencies.
+* Don't strict disallow redundant `SerializerMethodField` field name arguments.
+* Don't render extra actions in browable API if not authenticated.
+* Strip null characters from search parameters.
+
 ## 3.9.x series
 
+### 3.9.4
+
+**Date**: 10th May 2019
+
+This is a maintenance release that fixes an error handling bug under Python 2.
+
 ### 3.9.3
 
-**Date**: [29th April 2019]
+**Date**: 29th April 2019
 
 This is the last Django REST Framework release that will support Python 2.
 Be sure to upgrade to Python 3 before upgrading to Django REST Framework 3.10.
@@ -52,7 +107,7 @@ Be sure to upgrade to Python 3 before upgrading to Django REST Framework 3.10.
 
 ### 3.9.2
 
-**Date**: [3rd March 2019][3.9.1-milestone]
+**Date**: [3rd March 2019][3.9.2-milestone]
 
 * Routers: invalidate `_urls` cache on `register()` [#6407][gh6407]
 * Deferred schema renderer creation to avoid requiring pyyaml. [#6416][gh6416]
@@ -304,7 +359,7 @@ Be sure to upgrade to Python 3 before upgrading to Django REST Framework 3.10.
     Note: `AutoSchema.__init__` now ensures `manual_fields` is a list.
     Previously may have been stored internally as `None`.
 
-* Remove ulrparse compatability shim; use six instead [#5579][gh5579]
+* Remove ulrparse compatibility shim; use six instead [#5579][gh5579]
 * Drop compat wrapper for `TimeDelta.total_seconds()` [#5577][gh5577]
 * Clean up all whitespace throughout project [#5578][gh5578]
 * Compat cleanup [#5581][gh5581]
@@ -1175,7 +1230,8 @@ For older release notes, [please see the version 2.x documentation][old-release-
 [3.8.2-milestone]: https://github.com/encode/django-rest-framework/milestone/68?closed=1
 [3.9.0-milestone]: https://github.com/encode/django-rest-framework/milestone/66?closed=1
 [3.9.1-milestone]: https://github.com/encode/django-rest-framework/milestone/70?closed=1
-[3.9.1-milestone]: https://github.com/encode/django-rest-framework/milestone/71?closed=1
+[3.9.2-milestone]: https://github.com/encode/django-rest-framework/milestone/71?closed=1
+[3.10.0-milestone]: https://github.com/encode/django-rest-framework/milestone/69?closed=1
 
 <!-- 3.0.1 -->
 [gh2013]: https://github.com/encode/django-rest-framework/issues/2013
@@ -2119,3 +2175,7 @@ For older release notes, [please see the version 2.x documentation][old-release-
 
 <!-- 3.9.3 -->
 [gh6613]: https://github.com/encode/django-rest-framework/issues/6613
+
+<!-- 3.10.0 -->
+[gh6680]: https://github.com/encode/django-rest-framework/issues/6680
+[gh6317]: https://github.com/encode/django-rest-framework/issues/6317

docs/community/third-party-packages.md

@@ -20,7 +20,7 @@ If you have an idea for a new feature please consider how it may be packaged as
 
 You can use [this cookiecutter template][cookiecutter] for creating reusable Django REST Framework packages quickly. Cookiecutter creates projects from project templates. While optional, this cookiecutter template includes best practices from Django REST framework and other packages, as well as a Travis CI configuration, Tox configuration, and a sane setup.py for easy PyPI registration/distribution.
 
-Note: Let us know if you have an alternate cookiecuter package so we can also link to it.
+Note: Let us know if you have an alternate cookiecutter package so we can also link to it.
 
 #### Running the initial cookiecutter command
 
@@ -55,7 +55,7 @@ We recommend using [Travis CI][travis-ci], a hosted continuous integration servi
 
 To get started with Travis CI, [sign in][travis-ci] with your GitHub account. Once you're signed in, go to your [profile page][travis-profile] and enable the service hook for the repository you want.
 
-If you use the cookiecutter template, your project will already contain a `.travis.yml` file which Travis CI will use to build your project and run tests.  By default, builds are triggered everytime you push to your repository or create Pull Request.
+If you use the cookiecutter template, your project will already contain a `.travis.yml` file which Travis CI will use to build your project and run tests.  By default, builds are triggered every time you push to your repository or create Pull Request.
 
 #### Uploading to PyPI
 
@@ -197,6 +197,7 @@ To submit new content, [open an issue][drf-create-issue] or [create a pull reque
 * [djangorestframework-composed-permissions][djangorestframework-composed-permissions] - Provides a simple way to define complex permissions.
 * [rest_condition][rest-condition] - Another extension for building complex permissions in a simple and convenient way.
 * [dry-rest-permissions][dry-rest-permissions] - Provides a simple way to define permissions for individual api actions.
+* [drf-access-policy][drf-access-policy] - Declarative and flexible permissions inspired by AWS' IAM policies.
 
 ### Serializers
 
@@ -208,6 +209,8 @@ To submit new content, [open an issue][drf-create-issue] or [create a pull reque
 * [django-rest-framework-serializer-extensions][drf-serializer-extensions] -
   Enables black/whitelisting fields, and conditionally expanding child serializers on a per-view/request basis.
 * [djangorestframework-queryfields][djangorestframework-queryfields] - Serializer mixin allowing clients to control which fields will be sent in the API response.
+* [drf-flex-fields][drf-flex-fields] - Serializer providing dynamic field expansion and sparse field sets via URL parameters.
+* [drf-action-serializer][drf-action-serializer] - Serializer providing per-action fields config for use with ViewSets to prevent having to write multiple serializers.
 
 ### Serializer fields
 
@@ -244,6 +247,7 @@ To submit new content, [open an issue][drf-create-issue] or [create a pull reque
 * [djangorestframework-chain][djangorestframework-chain] - Allows arbitrary chaining of both relations and lookup filters.
 * [django-url-filter][django-url-filter] - Allows a safe way to filter data via human-friendly URLs. It is a generic library which is not tied to DRF but it provides easy integration with DRF.
 * [drf-url-filter][drf-url-filter] is a simple Django app to apply filters on drf `ModelViewSet`'s `Queryset` in a clean, simple and configurable way. It also supports validations on incoming query params and their values.
+* [django-rest-framework-guardian][django-rest-framework-guardian] - Provides integration with django-guardian, including the `DjangoObjectPermissionsFilter` previously found in DRF.
 
 ### Misc
 
@@ -264,6 +268,8 @@ To submit new content, [open an issue][drf-create-issue] or [create a pull reque
 * [djangorest-alchemy][djangorest-alchemy] - SQLAlchemy support for REST framework.
 * [djangorestframework-datatables][djangorestframework-datatables] - Seamless integration between Django REST framework and [Datatables](https://datatables.net).
 * [django-rest-framework-condition][django-rest-framework-condition] - Decorators for managing HTTP cache headers for Django REST framework (ETag and Last-modified).
+* [django-rest-witchcraft][django-rest-witchcraft] - Provides DRF integration with SQLAlchemy with SQLAlchemy model serializers/viewsets and a bunch of other goodies
+* [djangorestframework-mvt][djangorestframework-mvt] - An extension for creating views that serve Postgres data as Map Box Vector Tiles.
 
 [cite]: http://www.software-ecosystems.com/Software_Ecosystems/Ecosystems.html
 [cookiecutter]: https://github.com/jpadilla/cookiecutter-django-rest-framework
@@ -338,3 +344,9 @@ To submit new content, [open an issue][drf-create-issue] or [create a pull reque
 [djangorest-alchemy]: https://github.com/dealertrack/djangorest-alchemy
 [djangorestframework-datatables]: https://github.com/izimobil/django-rest-framework-datatables
 [django-rest-framework-condition]: https://github.com/jozo/django-rest-framework-condition
+[django-rest-witchcraft]: https://github.com/shosca/django-rest-witchcraft
+[drf-access-policy]: https://github.com/rsinger86/drf-access-policy
+[drf-flex-fields]: https://github.com/rsinger86/drf-flex-fields
+[drf-action-serializer]: https://github.com/gregschmit/drf-action-serializer
+[djangorestframework-mvt]: https://github.com/corteva/djangorestframework-mvt
+[django-rest-framework-guardian]: https://github.com/rpkilby/django-rest-framework-guardian

docs/community/tutorials-and-resources.md

@@ -85,11 +85,11 @@ Want your Django REST Framework talk/tutorial/article to be added to our website
 
 
 [beginners-guide-to-the-django-rest-framework]: https://code.tutsplus.com/tutorials/beginners-guide-to-the-django-rest-framework--cms-19786
-[getting-started-with-django-rest-framework-and-angularjs]: https://blog.kevinastone.com/getting-started-with-django-rest-framework-and-angularjs.html
+[getting-started-with-django-rest-framework-and-angularjs]: https://blog.kevinastone.com/django-rest-framework-and-angular-js
 [end-to-end-web-app-with-django-rest-framework-angularjs]: https://mourafiq.com/2013/07/01/end-to-end-web-app-with-django-angular-1.html
-[start-your-api-django-rest-framework-part-1]: https://godjango.com/41-start-your-api-django-rest-framework-part-1/
+[start-your-api-django-rest-framework-part-1]: https://www.youtube.com/watch?v=hqo2kk91WpE
-[permissions-authentication-django-rest-framework-part-2]: https://godjango.com/43-permissions-authentication-django-rest-framework-part-2/
+[permissions-authentication-django-rest-framework-part-2]: https://www.youtube.com/watch?v=R3xvUDUZxGU
-[viewsets-and-routers-django-rest-framework-part-3]: https://godjango.com/45-viewsets-and-routers-django-rest-framework-part-3/
+[viewsets-and-routers-django-rest-framework-part-3]: https://www.youtube.com/watch?v=2d6w4DGQ4OU
 [django-rest-framework-user-endpoint]: https://richardtier.com/2014/02/25/django-rest-framework-user-endpoint/
 [check-credentials-using-django-rest-framework]: https://richardtier.com/2014/03/06/110/
 [ember-and-django-part 1-video]: http://www.neckbeardrepublic.com/screencasts/ember-and-django-part-1

docs/coreapi/from-documenting-your-api.md

@@ -0,0 +1,171 @@
+
+## Built-in API documentation
+
+The built-in API documentation includes:
+
+* Documentation of API endpoints.
+* Automatically generated code samples for each of the available API client libraries.
+* Support for API interaction.
+
+### Installation
+
+The `coreapi` library is required as a dependency for the API docs. Make sure
+to install the latest version. The `Pygments` and `Markdown` libraries
+are optional but recommended.
+
+To install the API documentation, you'll need to include it in your project's URLconf:
+
+    from rest_framework.documentation import include_docs_urls
+
+    urlpatterns = [
+        ...
+        url(r'^docs/', include_docs_urls(title='My API title'))
+    ]
+
+This will include two different views:
+
+  * `/docs/` - The documentation page itself.
+  * `/docs/schema.js` - A JavaScript resource that exposes the API schema.
+
+---
+
+**Note**: By default `include_docs_urls` configures the underlying `SchemaView` to generate _public_ schemas.
+This means that views will not be instantiated with a `request` instance. i.e. Inside the view `self.request` will be `None`.
+
+To be compatible with this behaviour, methods (such as `get_serializer` or `get_serializer_class` etc.) which inspect `self.request` or, particularly, `self.request.user` may need to be adjusted to handle this case.
+
+You may ensure views are given a `request` instance by calling `include_docs_urls` with `public=False`:
+
+    from rest_framework.documentation import include_docs_urls
+
+    urlpatterns = [
+        ...
+        # Generate schema with valid `request` instance:
+        url(r'^docs/', include_docs_urls(title='My API title', public=False))
+    ]
+
+
+---
+
+
+### Documenting your views
+
+You can document your views by including docstrings that describe each of the available actions.
+For example:
+
+    class UserList(generics.ListAPIView):
+        """
+        Return a list of all the existing users.
+        """
+
+If a view supports multiple methods, you should split your documentation using `method:` style delimiters.
+
+    class UserList(generics.ListCreateAPIView):
+        """
+        get:
+        Return a list of all the existing users.
+
+        post:
+        Create a new user instance.
+        """
+
+When using viewsets, you should use the relevant action names as delimiters.
+
+    class UserViewSet(viewsets.ModelViewSet):
+        """
+        retrieve:
+        Return the given user.
+
+        list:
+        Return a list of all the existing users.
+
+        create:
+        Create a new user instance.
+        """
+
+Custom actions on viewsets can also be documented in a similar way using the method names
+as delimiters or by attaching the documentation to action mapping methods.
+
+    class UserViewSet(viewsets.ModelViewset):
+        ...
+
+        @action(detail=False, methods=['get', 'post'])
+        def some_action(self, request, *args, **kwargs):
+            """
+            get:
+            A description of the get method on the custom action.
+
+            post:
+            A description of the post method on the custom action.
+            """
+
+        @some_action.mapping.put
+        def put_some_action():
+            """
+            A description of the put method on the custom action.
+            """
+
+
+### `documentation` API Reference
+
+The `rest_framework.documentation` module provides three helper functions to help configure the interactive API documentation, `include_docs_urls` (usage shown above), `get_docs_view` and `get_schemajs_view`.
+
+ `include_docs_urls` employs `get_docs_view` and `get_schemajs_view` to generate the url patterns for the documentation page and JavaScript resource that exposes the API schema respectively. They expose the following options for customisation. (`get_docs_view` and `get_schemajs_view` ultimately call `rest_frameworks.schemas.get_schema_view()`, see the Schemas docs for more options there.)
+
+#### `include_docs_urls`
+
+* `title`: Default `None`. May be used to provide a descriptive title for the schema definition.
+* `description`: Default `None`. May be used to provide a description for the schema definition.
+* `schema_url`: Default `None`. May be used to pass a canonical base URL for the schema.
+* `public`: Default `True`. Should the schema be considered _public_? If `True` schema is generated without a `request` instance being passed to views.
+* `patterns`: Default `None`. A list of URLs to inspect when generating the schema. If `None` project's URL conf will be used.
+* `generator_class`: Default `rest_framework.schemas.SchemaGenerator`. May be used to specify a `SchemaGenerator` subclass to be passed to the `SchemaView`.
+* `authentication_classes`: Default `api_settings.DEFAULT_AUTHENTICATION_CLASSES`. May be used to pass custom authentication classes to the `SchemaView`.
+* `permission_classes`: Default `api_settings.DEFAULT_PERMISSION_CLASSES` May be used to pass custom permission classes to the `SchemaView`.
+* `renderer_classes`: Default `None`. May be used to pass custom renderer classes to the `SchemaView`.
+
+#### `get_docs_view`
+
+* `title`: Default `None`. May be used to provide a descriptive title for the schema definition.
+* `description`: Default `None`. May be used to provide a description for the schema definition.
+* `schema_url`: Default `None`. May be used to pass a canonical base URL for the schema.
+* `public`: Default `True`. If `True` schema is generated without a `request` instance being passed to views.
+* `patterns`: Default `None`. A list of URLs to inspect when generating the schema. If `None` project's URL conf will be used.
+* `generator_class`: Default `rest_framework.schemas.SchemaGenerator`. May be used to specify a `SchemaGenerator` subclass to be passed to the `SchemaView`.
+* `authentication_classes`: Default `api_settings.DEFAULT_AUTHENTICATION_CLASSES`. May be used to pass custom authentication classes to the `SchemaView`.
+* `permission_classes`: Default `api_settings.DEFAULT_PERMISSION_CLASSES`. May be used to pass custom permission classes to the `SchemaView`.
+* `renderer_classes`: Default `None`. May be used to pass custom renderer classes to the `SchemaView`. If `None` the `SchemaView` will be configured with `DocumentationRenderer` and `CoreJSONRenderer` renderers, corresponding to the (default) `html` and `corejson` formats.
+
+#### `get_schemajs_view`
+
+* `title`: Default `None`. May be used to provide a descriptive title for the schema definition.
+* `description`: Default `None`. May be used to provide a description for the schema definition.
+* `schema_url`: Default `None`. May be used to pass a canonical base URL for the schema.
+* `public`: Default `True`. If `True` schema is generated without a `request` instance being passed to views.
+* `patterns`: Default `None`. A list of URLs to inspect when generating the schema. If `None` project's URL conf will be used.
+* `generator_class`: Default `rest_framework.schemas.SchemaGenerator`. May be used to specify a `SchemaGenerator` subclass to be passed to the `SchemaView`.
+* `authentication_classes`: Default `api_settings.DEFAULT_AUTHENTICATION_CLASSES`. May be used to pass custom authentication classes to the `SchemaView`.
+* `permission_classes`: Default `api_settings.DEFAULT_PERMISSION_CLASSES` May be used to pass custom permission classes to the `SchemaView`.
+
+
+### Customising code samples
+
+The built-in API documentation includes automatically generated code samples for
+each of the available API client libraries.
+
+You may customise these samples by subclassing `DocumentationRenderer`, setting
+`languages` to the list of languages you wish to support:
+
+    from rest_framework.renderers import DocumentationRenderer
+
+
+    class CustomRenderer(DocumentationRenderer):
+        languages = ['ruby', 'go']
+
+For each language you need to provide an `intro` template, detailing installation instructions and such,
+plus a generic template for making API requests, that can be filled with individual request details.
+See the [templates for the bundled languages][client-library-templates] for examples.
+
+---
+
+[client-library-templates]: https://github.com/encode/django-rest-framework/tree/master/rest_framework/templates/rest_framework/docs/langs

docs/coreapi/index.md

@@ -0,0 +1,29 @@
+# Legacy CoreAPI Schemas Docs
+
+Use of CoreAPI-based schemas were deprecated with the introduction of native OpenAPI-based schema generation in Django REST Framework v3.10.
+
+See the [Version 3.10 Release Announcement](/community/3.10-announcement.md) for more details.
+
+----
+
+You can continue to use CoreAPI schemas by setting the appropriate default schema class:
+
+```python
+# In settings.py
+REST_FRAMEWORK = {
+    'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema',
+}
+```
+
+Under-the-hood, any subclass of `coreapi.AutoSchema` here will trigger use of the old CoreAPI schemas.
+**Otherwise** you will automatically be opted-in to the new OpenAPI schemas.
+
+All CoreAPI related code will be removed in Django REST Framework v3.12. Switch to OpenAPI schemas by then.
+
+----
+
+For reference this folder contains the old CoreAPI related documentation:
+
+* [Tutorial 7: Schemas & client libraries](https://github.com/encode/django-rest-framework/blob/master/docs/coreapi//7-schemas-and-client-libraries.md).
+* [Excerpts from _Documenting your API_ topic page](https://github.com/encode/django-rest-framework/blob/master/docs/coreapi//from-documenting-your-api.md).
+* [`rest_framework.schemas` API Reference](https://github.com/encode/django-rest-framework/blob/master/docs/coreapi//schemas.md).

docs/coreapi/schemas.md

@@ -0,0 +1,838 @@
+source: schemas.py
+
+# Schemas
+
+> A machine-readable [schema] describes what resources are available via the API, what their URLs are, how they are represented and what operations they support.
+>
+> — Heroku, [JSON Schema for the Heroku Platform API][cite]
+
+API schemas are a useful tool that allow for a range of use cases, including
+generating reference documentation, or driving dynamic client libraries that
+can interact with your API.
+
+## Install Core API & PyYAML
+
+You'll need to install the `coreapi` package in order to add schema support
+for REST framework. You probably also want to install `pyyaml`, so that you
+can render the schema into the commonly used YAML-based OpenAPI format.
+
+    pip install coreapi pyyaml
+
+## Quickstart
+
+There are two different ways you can serve a schema description for your API.
+
+### Generating a schema with the `generateschema` management command
+
+To generate a static API schema, use the `generateschema` management command.
+
+```shell
+$ python manage.py generateschema > schema.yml
+```
+
+Once you've generated a schema in this way you can annotate it with any
+additional information that cannot be automatically inferred by the schema
+generator.
+
+You might want to check your API schema into version control and update it
+with each new release, or serve the API schema from your site's static media.
+
+### Adding a view with `get_schema_view`
+
+To add a dynamically generated schema view to your API, use `get_schema_view`.
+
+```python
+from rest_framework.schemas import get_schema_view
+
+schema_view = get_schema_view(title="Example API")
+
+urlpatterns = [
+    url('^schema$', schema_view),
+    ...
+]
+```
+
+See below [for more details](#the-get_schema_view-shortcut) on customizing a
+dynamically generated schema view.
+
+## Internal schema representation
+
+REST framework uses [Core API][coreapi] in order to model schema information in
+a format-independent representation. This information can then be rendered
+into various different schema formats, or used to generate API documentation.
+
+When using Core API, a schema is represented as a `Document` which is the
+top-level container object for information about the API. Available API
+interactions are represented using `Link` objects. Each link includes a URL,
+HTTP method, and may include a list of `Field` instances, which describe any
+parameters that may be accepted by the API endpoint. The `Link` and `Field`
+instances may also include descriptions, that allow an API schema to be
+rendered into user documentation.
+
+Here's an example of an API description that includes a single `search`
+endpoint:
+
+    coreapi.Document(
+        title='Flight Search API',
+        url='https://api.example.org/',
+        content={
+            'search': coreapi.Link(
+                url='/search/',
+                action='get',
+                fields=[
+                    coreapi.Field(
+                        name='from',
+                        required=True,
+                        location='query',
+                        description='City name or airport code.'
+                    ),
+                    coreapi.Field(
+                        name='to',
+                        required=True,
+                        location='query',
+                        description='City name or airport code.'
+                    ),
+                    coreapi.Field(
+                        name='date',
+                        required=True,
+                        location='query',
+                        description='Flight date in "YYYY-MM-DD" format.'
+                    )
+                ],
+                description='Return flight availability and prices.'
+            )
+        }
+    )
+
+## Schema output formats
+
+In order to be presented in an HTTP response, the internal representation
+has to be rendered into the actual bytes that are used in the response.
+
+REST framework includes a few different renderers that you can use for
+encoding the API schema.
+
+* `renderers.OpenAPIRenderer` - Renders into YAML-based [OpenAPI][open-api], the most widely used API schema format.
+* `renderers.JSONOpenAPIRenderer` - Renders into JSON-based [OpenAPI][open-api].
+* `renderers.CoreJSONRenderer` - Renders into [Core JSON][corejson], a format designed for
+use with the `coreapi` client library.
+
+
+[Core JSON][corejson] is designed as a canonical format for use with Core API.
+REST framework includes a renderer class for handling this media type, which
+is available as `renderers.CoreJSONRenderer`.
+
+
+## Schemas vs Hypermedia
+
+It's worth pointing out here that Core API can also be used to model hypermedia
+responses, which present an alternative interaction style to API schemas.
+
+With an API schema, the entire available interface is presented up-front
+as a single endpoint. Responses to individual API endpoints are then typically
+presented as plain data, without any further interactions contained in each
+response.
+
+With Hypermedia, the client is instead presented with a document containing
+both data and available interactions. Each interaction results in a new
+document, detailing both the current state and the available interactions.
+
+Further information and support on building Hypermedia APIs with REST framework
+is planned for a future version.
+
+
+---
+
+# Creating a schema
+
+REST framework includes functionality for auto-generating a schema,
+or allows you to specify one explicitly.
+
+## Manual Schema Specification
+
+To manually specify a schema you create a Core API `Document`, similar to the
+example above.
+
+    schema = coreapi.Document(
+        title='Flight Search API',
+        content={
+            ...
+        }
+    )
+
+
+## Automatic Schema Generation
+
+Automatic schema generation is provided by the `SchemaGenerator` class.
+
+`SchemaGenerator` processes a list of routed URL patterns and compiles the
+appropriately structured Core API Document.
+
+Basic usage is just to provide the title for your schema and call
+`get_schema()`:
+
+    generator = schemas.SchemaGenerator(title='Flight Search API')
+    schema = generator.get_schema()
+
+## Per-View Schema Customisation
+
+By default, view introspection is performed by an `AutoSchema` instance
+accessible via the `schema` attribute on `APIView`. This provides the
+appropriate Core API `Link` object for the view, request method and path:
+
+    auto_schema = view.schema
+    coreapi_link = auto_schema.get_link(...)
+
+(In compiling the schema, `SchemaGenerator` calls `view.schema.get_link()` for
+each view, allowed method and path.)
+
+---
+
+**Note**: For basic `APIView` subclasses, default introspection is essentially
+limited to the URL kwarg path parameters. For `GenericAPIView`
+subclasses, which includes all the provided class based views, `AutoSchema` will
+attempt to introspect serialiser, pagination and filter fields, as well as
+provide richer path field descriptions. (The key hooks here are the relevant
+`GenericAPIView` attributes and methods: `get_serializer`, `pagination_class`,
+`filter_backends` and so on.)
+
+---
+
+To customise the `Link` generation you may:
+
+* Instantiate `AutoSchema` on your view with the `manual_fields` kwarg:
+
+        from rest_framework.views import APIView
+        from rest_framework.schemas import AutoSchema
+
+        class CustomView(APIView):
+            ...
+            schema = AutoSchema(
+                manual_fields=[
+                    coreapi.Field("extra_field", ...),
+                ]
+            )
+
+    This allows extension for the most common case without subclassing.
+
+* Provide an `AutoSchema` subclass with more complex customisation:
+
+        from rest_framework.views import APIView
+        from rest_framework.schemas import AutoSchema
+
+        class CustomSchema(AutoSchema):
+            def get_link(...):
+                # Implement custom introspection here (or in other sub-methods)
+
+        class CustomView(APIView):
+            ...
+            schema = CustomSchema()
+
+    This provides complete control over view introspection.
+
+* Instantiate `ManualSchema` on your view, providing the Core API `Fields` for
+  the view explicitly:
+
+        from rest_framework.views import APIView
+        from rest_framework.schemas import ManualSchema
+
+        class CustomView(APIView):
+            ...
+            schema = ManualSchema(fields=[
+                coreapi.Field(
+                    "first_field",
+                    required=True,
+                    location="path",
+                    schema=coreschema.String()
+                ),
+                coreapi.Field(
+                    "second_field",
+                    required=True,
+                    location="path",
+                    schema=coreschema.String()
+                ),
+            ])
+
+    This allows manually specifying the schema for some views whilst maintaining
+    automatic generation elsewhere.
+
+You may disable schema generation for a view by setting `schema` to `None`:
+
+        class CustomView(APIView):
+            ...
+            schema = None  # Will not appear in schema
+
+This also applies to extra actions for `ViewSet`s:
+
+        class CustomViewSet(viewsets.ModelViewSet):
+
+            @action(detail=True, schema=None)
+            def extra_action(self, request, pk=None):
+                ...
+
+---
+
+**Note**: For full details on `SchemaGenerator` plus the `AutoSchema` and
+`ManualSchema` descriptors see the [API Reference below](#api-reference).
+
+---
+
+# Adding a schema view
+
+There are a few different ways to add a schema view to your API, depending on
+exactly what you need.
+
+## The get_schema_view shortcut
+
+The simplest way to include a schema in your project is to use the
+`get_schema_view()` function.
+
+    from rest_framework.schemas import get_schema_view
+
+    schema_view = get_schema_view(title="Server Monitoring API")
+
+    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/coreapi+json
+    HTTP/1.0 200 OK
+    Allow: GET, HEAD, OPTIONS
+    Content-Type: application/vnd.coreapi+json
+
+    {
+        "_meta": {
+            "title": "Server Monitoring API"
+        },
+        "_type": "document",
+        ...
+    }
+
+The arguments to `get_schema_view()` are:
+
+#### `title`
+
+May be used to provide a descriptive title for the schema definition.
+
+#### `url`
+
+May be used to pass a canonical URL for the schema.
+
+    schema_view = get_schema_view(
+        title='Server Monitoring API',
+        url='https://www.example.org/api/'
+    )
+
+#### `urlconf`
+
+A string representing the import path to the URL conf that you want
+to generate an API schema for. This defaults to the value of Django's
+ROOT_URLCONF setting.
+
+    schema_view = get_schema_view(
+        title='Server Monitoring API',
+        url='https://www.example.org/api/',
+        urlconf='myproject.urls'
+    )
+
+#### `renderer_classes`
+
+May be used to pass the set of renderer classes that can be used to render the API root endpoint.
+
+    from rest_framework.schemas import get_schema_view
+    from rest_framework.renderers import JSONOpenAPIRenderer
+
+    schema_view = get_schema_view(
+        title='Server Monitoring API',
+        url='https://www.example.org/api/',
+        renderer_classes=[JSONOpenAPIRenderer]
+    )
+
+#### `patterns`
+
+List of url patterns to limit the schema introspection to. If you only want the `myproject.api` urls
+to be exposed in the schema:
+
+    schema_url_patterns = [
+        url(r'^api/', include('myproject.api.urls')),
+    ]
+
+    schema_view = get_schema_view(
+        title='Server Monitoring API',
+        url='https://www.example.org/api/',
+        patterns=schema_url_patterns,
+    )
+
+#### `generator_class`
+
+May be used to specify a `SchemaGenerator` subclass to be passed to the
+`SchemaView`.
+
+#### `authentication_classes`
+
+May be used to specify the list of authentication classes that will apply to the schema endpoint.
+Defaults to `settings.DEFAULT_AUTHENTICATION_CLASSES`
+
+#### `permission_classes`
+
+May be used to specify the list of permission classes that will apply to the schema endpoint.
+Defaults to `settings.DEFAULT_PERMISSION_CLASSES`
+
+## 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 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.
+
+**views.py:**
+
+    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.OpenAPIRenderer])
+    def schema_view(request):
+        schema = generator.get_schema(request)
+        return response.Response(schema)
+
+**urls.py:**
+
+    urlpatterns = [
+        url('/', schema_view),
+        ...
+    ]
+
+You can also serve different schemas to different users, depending on the
+permissions they have available. This approach can be used to ensure that
+unauthenticated requests are presented with a different schema to
+authenticated requests, or to ensure that different parts of the API are
+made visible to different users depending on their role.
+
+In order to present a schema with endpoints filtered by user permissions,
+you need to pass the `request` argument to the `get_schema()` method, like so:
+
+    @api_view()
+    @renderer_classes([renderers.OpenAPIRenderer])
+    def schema_view(request):
+        generator = schemas.SchemaGenerator(title='Bookings API')
+        return response.Response(generator.get_schema(request=request))
+
+## Explicit schema definition
+
+An alternative to the auto-generated approach is to specify the API schema
+explicitly, by declaring a `Document` object in your codebase. Doing so is a
+little more work, but ensures that you have full control over the schema
+representation.
+
+    import coreapi
+    from rest_framework.decorators import api_view, renderer_classes
+    from rest_framework import renderers, response
+
+    schema = coreapi.Document(
+        title='Bookings API',
+        content={
+            ...
+        }
+    )
+
+    @api_view()
+    @renderer_classes([renderers.OpenAPIRenderer])
+    def schema_view(request):
+        return response.Response(schema)
+
+---
+
+# 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 explicit 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: List all the users.
+        post: Create a new user.
+        """
+        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
+
+---
+
+# API Reference
+
+## SchemaGenerator
+
+A class that walks a list of routed URL patterns, requests the schema for each view,
+and collates the resulting CoreAPI Document.
+
+Typically you'll instantiate `SchemaGenerator` with a single argument, like so:
+
+    generator = SchemaGenerator(title='Stock Prices API')
+
+Arguments:
+
+* `title` **required** - The name of the API.
+* `url` - The root URL of the API schema. This option is not required unless the schema is included under path prefix.
+* `patterns` - A list of URLs to inspect when generating the schema. Defaults to the project's URL conf.
+* `urlconf` - A URL conf module name to use when generating the schema. Defaults to `settings.ROOT_URLCONF`.
+
+### get_schema(self, request)
+
+Returns a `coreapi.Document` instance that represents the API schema.
+
+    @api_view
+    @renderer_classes([renderers.OpenAPIRenderer])
+    def schema_view(request):
+        generator = schemas.SchemaGenerator(title='Bookings API')
+        return Response(generator.get_schema())
+
+The `request` argument is optional, and may be used if you want to apply per-user
+permissions to the resulting schema generation.
+
+### get_links(self, request)
+
+Return a nested dictionary containing all the links that should be included in the API schema.
+
+This is a good point to override if you want to modify the resulting structure of the generated schema,
+as you can build a new dictionary with a different layout.
+
+
+## AutoSchema
+
+A class that deals with introspection of individual views for schema generation.
+
+`AutoSchema` is attached to `APIView` via the `schema` attribute.
+
+The `AutoSchema` constructor takes a single keyword argument  `manual_fields`.
+
+**`manual_fields`**: a `list` of `coreapi.Field` instances that will be added to
+the generated fields. Generated fields with a matching `name` will be overwritten.
+
+    class CustomView(APIView):
+        schema = AutoSchema(manual_fields=[
+            coreapi.Field(
+                "my_extra_field",
+                required=True,
+                location="path",
+                schema=coreschema.String()
+            ),
+        ])
+
+For more advanced customisation subclass `AutoSchema` to customise schema generation.
+
+    class CustomViewSchema(AutoSchema):
+        """
+        Overrides `get_link()` to provide Custom Behavior X
+        """
+
+        def get_link(self, path, method, base_url):
+            link = super().get_link(path, method, base_url)
+            # Do something to customize link here...
+            return link
+
+    class MyView(APIView):
+      schema = CustomViewSchema()
+
+The following methods are available to override.
+
+### get_link(self, path, method, base_url)
+
+Returns a `coreapi.Link` instance corresponding to the given view.
+
+This is the main entry point.
+You can override this if you need to provide custom behaviors for particular views.
+
+### get_description(self, path, method)
+
+Returns a string to use as the link description. By default this is based on the
+view docstring as described in the "Schemas as Documentation" section above.
+
+### get_encoding(self, path, method)
+
+Returns a string to indicate the encoding for any request body, when interacting
+with the given view. Eg. `'application/json'`. May return a blank string for views
+that do not expect a request body.
+
+### get_path_fields(self, path, method):
+
+Return a list of `coreapi.Field()` instances. One for each path parameter in the URL.
+
+### get_serializer_fields(self, path, method)
+
+Return a list of `coreapi.Field()` instances. One for each field in the serializer class used by the view.
+
+### get_pagination_fields(self, path, method)
+
+Return a list of `coreapi.Field()` instances, as returned by the `get_schema_fields()` method on any pagination class used by the view.
+
+### get_filter_fields(self, path, method)
+
+Return a list of `coreapi.Field()` instances, as returned by the `get_schema_fields()` method of any filter classes used by the view.
+
+### get_manual_fields(self, path, method)
+
+Return a list of `coreapi.Field()` instances to be added to or replace generated fields. Defaults to (optional) `manual_fields` passed to `AutoSchema` constructor.
+
+May be overridden to customise manual fields by `path` or `method`. For example, a per-method adjustment may look like this:
+
+```python
+def get_manual_fields(self, path, method):
+    """Example adding per-method fields."""
+
+    extra_fields = []
+    if method=='GET':
+        extra_fields = # ... list of extra fields for GET ...
+    if method=='POST':
+        extra_fields = # ... list of extra fields for POST ...
+
+    manual_fields = super().get_manual_fields(path, method)
+    return manual_fields + extra_fields
+```
+
+### update_fields(fields, update_with)
+
+Utility `staticmethod`. Encapsulates logic to add or replace fields from a list
+by `Field.name`. May be overridden to adjust replacement criteria.
+
+
+## ManualSchema
+
+Allows manually providing a list of `coreapi.Field` instances for the schema,
+plus an optional description.
+
+    class MyView(APIView):
+      schema = ManualSchema(fields=[
+            coreapi.Field(
+                "first_field",
+                required=True,
+                location="path",
+                schema=coreschema.String()
+            ),
+            coreapi.Field(
+                "second_field",
+                required=True,
+                location="path",
+                schema=coreschema.String()
+            ),
+        ]
+      )
+
+The `ManualSchema` constructor takes two arguments:
+
+**`fields`**: A list of `coreapi.Field` instances. Required.
+
+**`description`**: A string description. Optional.
+
+**`encoding`**: Default `None`. A string encoding, e.g `application/json`. Optional.
+
+---
+
+## Core API
+
+This documentation gives a brief overview of the components within the `coreapi`
+package that are used to represent an API schema.
+
+Note that these classes are imported from the `coreapi` package, rather than
+from the `rest_framework` package.
+
+### Document
+
+Represents a container for the API schema.
+
+#### `title`
+
+A name for the API.
+
+#### `url`
+
+A canonical URL for the API.
+
+#### `content`
+
+A dictionary, containing the `Link` objects that the schema contains.
+
+In order to provide more structure to the schema, the `content` dictionary
+may be nested, typically to a second level. For example:
+
+    content={
+        "bookings": {
+            "list": Link(...),
+            "create": Link(...),
+            ...
+        },
+        "venues": {
+            "list": Link(...),
+            ...
+        },
+        ...
+    }
+
+### Link
+
+Represents an individual API endpoint.
+
+#### `url`
+
+The URL of the endpoint. May be a URI template, such as `/users/{username}/`.
+
+#### `action`
+
+The HTTP method associated with the endpoint. Note that URLs that support
+more than one HTTP method, should correspond to a single `Link` for each.
+
+#### `fields`
+
+A list of `Field` instances, describing the available parameters on the input.
+
+#### `description`
+
+A short description of the meaning and intended usage of the endpoint.
+
+### Field
+
+Represents a single input parameter on a given API endpoint.
+
+#### `name`
+
+A descriptive name for the input.
+
+#### `required`
+
+A boolean, indicated if the client is required to included a value, or if
+the parameter can be omitted.
+
+#### `location`
+
+Determines how the information is encoded into the request. Should be one of
+the following strings:
+
+**"path"**
+
+Included in a templated URI. For example a `url` value of `/products/{product_code}/` could be used together with a `"path"` field, to handle API inputs in a URL path such as `/products/slim-fit-jeans/`.
+
+These fields will normally correspond with [named arguments in the project URL conf][named-arguments].
+
+**"query"**
+
+Included as a URL query parameter. For example `?search=sale`. Typically for `GET` requests.
+
+These fields will normally correspond with pagination and filtering controls on a view.
+
+**"form"**
+
+Included in the request body, as a single item of a JSON object or HTML form. For example `{"colour": "blue", ...}`. Typically for `POST`, `PUT` and `PATCH` requests. Multiple `"form"` fields may be included on a single link.
+
+These fields will normally correspond with serializer fields on a view.
+
+**"body"**
+
+Included as the complete request body. Typically for `POST`, `PUT` and `PATCH` requests. No more than one `"body"` field may exist on a link. May not be used together with `"form"` fields.
+
+These fields will normally correspond with views that use `ListSerializer` to validate the request input, or with file upload views.
+
+#### `encoding`
+
+**"application/json"**
+
+JSON encoded request content. Corresponds to views using `JSONParser`.
+Valid only if either one or more `location="form"` fields, or a single
+`location="body"` field is included on the `Link`.
+
+**"multipart/form-data"**
+
+Multipart encoded request content. Corresponds to views using `MultiPartParser`.
+Valid only if one or more `location="form"` fields is included on the `Link`.
+
+**"application/x-www-form-urlencoded"**
+
+URL encoded request content. Corresponds to views using `FormParser`. Valid
+only if one or more `location="form"` fields is included on the `Link`.
+
+**"application/octet-stream"**
+
+Binary upload request content. Corresponds to views using `FileUploadParser`.
+Valid only if a `location="body"` field is included on the `Link`.
+
+#### `description`
+
+A short description of the meaning and intended usage of the input field.
+
+
+---
+
+# Third party packages
+
+## drf-yasg - Yet Another Swagger Generator
+
+[drf-yasg][drf-yasg] generates [OpenAPI][open-api] documents suitable for code generation - nested schemas,
+named models, response bodies, enum/pattern/min/max validators, form parameters, etc.
+
+[cite]: https://blog.heroku.com/archives/2014/1/8/json_schema_for_heroku_platform_api
+[coreapi]: https://www.coreapi.org/
+[corejson]: https://www.coreapi.org/specification/encoding/#core-json-encoding
+[drf-yasg]: https://github.com/axnsan12/drf-yasg/
+[open-api]: https://openapis.org/
+[json-hyperschema]: https://json-schema.org/latest/json-schema-hypermedia.html
+[api-blueprint]: https://apiblueprint.org/
+[static-files]: https://docs.djangoproject.com/en/stable/howto/static-files/
+[named-arguments]: https://docs.djangoproject.com/en/stable/topics/http/urls/#named-groups

docs/index.md

@@ -68,7 +68,7 @@ continued development by **[signing up for a paid plan][funding]**.
 <ul class="premium-promo promo">
     <li><a href="https://getsentry.com/welcome/" style="background-image: url(https://fund-rest-framework.s3.amazonaws.com/sentry130.png)">Sentry</a></li>
     <li><a href="https://getstream.io/try-the-api/?utm_source=drf&utm_medium=banner&utm_campaign=drf" style="background-image: url(https://fund-rest-framework.s3.amazonaws.com/stream-130.png)">Stream</a></li>
-    <li><a href="https://releasehistory.io" style="background-image: url(https://fund-rest-framework.s3.amazonaws.com/release-history.png)">Release History</a></li>
+    <li><a href="https://software.esg-usa.com" style="background-image: url(https://fund-rest-framework.s3.amazonaws.com/esg-new-logo.png)">ESG</a></li>
     <li><a href="https://rollbar.com" style="background-image: url(https://fund-rest-framework.s3.amazonaws.com/rollbar2.png)">Rollbar</a></li>
     <li><a href="https://cadre.com" style="background-image: url(https://fund-rest-framework.s3.amazonaws.com/cadre.png)">Cadre</a></li>
     <li><a href="https://hubs.ly/H0f30Lf0" style="background-image: url(https://fund-rest-framework.s3.amazonaws.com/kloudless-plus-text.png)">Kloudless</a></li>
@@ -76,7 +76,7 @@ continued development by **[signing up for a paid plan][funding]**.
 </ul>
 <div style="clear: both; padding-bottom: 20px;"></div>
 
-*Many thanks to all our [wonderful sponsors][sponsors], and in particular to our premium backers, [Sentry](https://getsentry.com/welcome/), [Stream](https://getstream.io/?utm_source=drf&utm_medium=banner&utm_campaign=drf), [Release History](https://releasehistory.io), [Rollbar](https://rollbar.com), [Cadre](https://cadre.com), [Kloudless](https://hubs.ly/H0f30Lf0), and [Lights On Software](https://lightsonsoftware.com).*
+*Many thanks to all our [wonderful sponsors][sponsors], and in particular to our premium backers, [Sentry](https://getsentry.com/welcome/), [Stream](https://getstream.io/?utm_source=drf&utm_medium=banner&utm_campaign=drf), [ESG](https://software.esg-usa.com/), [Rollbar](https://rollbar.com/?utm_source=django&utm_medium=sponsorship&utm_campaign=freetrial), [Cadre](https://cadre.com), [Kloudless](https://hubs.ly/H0f30Lf0), and [Lights On Software](https://lightsonsoftware.com).*
 
 ---
 
@@ -84,7 +84,7 @@ continued development by **[signing up for a paid plan][funding]**.
 
 REST framework requires the following:
 
-* Python (3.4, 3.5, 3.6, 3.7)
+* Python (3.5, 3.6, 3.7)
 * Django (1.11, 2.0, 2.1, 2.2)
 
 We **highly recommend** and only officially support the latest patch release of
@@ -93,9 +93,9 @@ each Python and Django series.
 The following packages are optional:
 
 * [coreapi][coreapi] (1.32.0+) - Schema generation support.
-* [Markdown][markdown] (2.1.0+) - Markdown support for the browsable API.
+* [Markdown][markdown] (3.0.0+) - Markdown support for the browsable API.
+* [Pygments][pygments] (2.4.0+) - Add syntax highlighting to Markdown processing.
 * [django-filter][django-filter] (1.0.1+) - Filtering support.
-* [django-crispy-forms][django-crispy-forms] - Improved HTML display for filtering.
 * [django-guardian][django-guardian] (1.1.1+) - Object level permissions support.
 
 ## Installation
@@ -112,10 +112,10 @@ Install using `pip`, including any optional packages you want...
 
 Add `'rest_framework'` to your `INSTALLED_APPS` setting.
 
-    INSTALLED_APPS = (
+    INSTALLED_APPS = [
         ...
         'rest_framework',
-    )
+    ]
 
 If you're intending to use the browsable API you'll probably also want to add REST framework's login and logout views.  Add the following to your root `urls.py` file.
 
@@ -155,7 +155,7 @@ Here's our project's root `urls.py` module:
     class UserSerializer(serializers.HyperlinkedModelSerializer):
         class Meta:
             model = User
-            fields = ('url', 'username', 'email', 'is_staff')
+            fields = ['url', 'username', 'email', 'is_staff']
 
     # ViewSets define the view behavior.
     class UserViewSet(viewsets.ModelViewSet):
@@ -238,8 +238,8 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 [eventbrite]: https://www.eventbrite.co.uk/about/
 [coreapi]: https://pypi.org/project/coreapi/
 [markdown]: https://pypi.org/project/Markdown/
+[pygments]: https://pypi.org/project/Pygments/
 [django-filter]: https://pypi.org/project/django-filter/
-[django-crispy-forms]: https://github.com/maraujop/django-crispy-forms
 [django-guardian]: https://github.com/django-guardian/django-guardian
 [index]: .
 [oauth1-section]: api-guide/authentication/#django-rest-framework-oauth

docs/topics/browser-enhancements.md

@@ -51,13 +51,15 @@ For example:
 
     METHOD_OVERRIDE_HEADER = 'HTTP_X_HTTP_METHOD_OVERRIDE'
 
-    class MethodOverrideMiddleware(object):
+    class MethodOverrideMiddleware:
-        def process_view(self, request, callback, callback_args, callback_kwargs):
+
-            if request.method != 'POST':
+        def __init__(self, get_response):
-                return
+            self.get_response = get_response
-            if METHOD_OVERRIDE_HEADER not in request.META:
+
-                return
+        def __call__(self, request):
-            request.method = request.META[METHOD_OVERRIDE_HEADER]
+            if request.method == 'POST' and METHOD_OVERRIDE_HEADER in request.META:
+                request.method = request.META[METHOD_OVERRIDE_HEADER]
+            return self.get_response(request)
 
 ## URL based accept headers
 

docs/topics/documenting-your-api.md

@@ -4,176 +4,121 @@
 >
 > — Roy Fielding, [REST APIs must be hypertext driven][cite]
 
-REST framework provides built-in support for API documentation. There are also a number of great third-party documentation tools available.
+REST framework provides built-in support for generating OpenAPI schemas, which
+can be used with tools that allow you to build API documentation.
 
-## Built-in API documentation
+There are also a number of great third-party documentation packages available.
 
-The built-in API documentation includes:
+## Generating documentation from OpenAPI schemas
 
-* Documentation of API endpoints.
+There are a number of packages available that allow you to generate HTML
-* Automatically generated code samples for each of the available API client libraries.
+documentation pages from OpenAPI schemas.
-* Support for API interaction.
 
-### Installation
+Two popular options are [Swagger UI][swagger-ui] and [ReDoc][redoc].
 
-The `coreapi` library is required as a dependency for the API docs. Make sure
+Both require little more than the location of your static schema file or
-to install the latest version. The `Pygments` and `Markdown` libraries
+dynamic `SchemaView` endpoint.
-are optional but recommended.
 
-To install the API documentation, you'll need to include it in your project's URLconf:
+### A minimal example with Swagger UI
 
-    from rest_framework.documentation import include_docs_urls
+Assuming you've followed the example from the schemas documentation for routing
+a dynamic `SchemaView`, a minimal Django template for using Swagger UI might be
+this:
 
-    urlpatterns = [
+```html
-        ...
+<!DOCTYPE html>
-        url(r'^docs/', include_docs_urls(title='My API title'))
+<html>
-    ]
+  <head>
+    <title>Swagger</title>
+    <meta charset="utf-8"/>
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <link rel="stylesheet" type="text/css" href="//unpkg.com/swagger-ui-dist@3/swagger-ui.css" />
+  </head>
+  <body>
+    <div id="swagger-ui"></div>
+    <script src="//unpkg.com/swagger-ui-dist@3/swagger-ui-bundle.js"></script>
+    <script>
+    const ui = SwaggerUIBundle({
+        url: "{% url schema_url %}",
+        dom_id: '#swagger-ui',
+        presets: [
+          SwaggerUIBundle.presets.apis,
+          SwaggerUIBundle.SwaggerUIStandalonePreset
+        ],
+        layout: "BaseLayout"
+      })
+    </script>
+  </body>
+</html>
+```
 
-This will include two different views:
+Save this in your templates folder as `swagger-ui.html`. Then route a
+`TemplateView` in your project's URL conf:
 
-  * `/docs/` - The documentation page itself.
+```python
-  * `/docs/schema.js` - A JavaScript resource that exposes the API schema.
+from django.views.generic import TemplateView
 
----
+urlpatterns = [
+    # ...
+    # Route TemplateView to serve Swagger UI template.
+    #   * Provide `extra_context` with view name of `SchemaView`.
+    path('swagger-ui/', TemplateView.as_view(
+        template_name='swagger-ui.html',
+        extra_context={'schema_url':'openapi-schema'}
+    ), name='swagger-ui'),
+]
+```
 
-**Note**: By default `include_docs_urls` configures the underlying `SchemaView` to generate _public_ schemas.
+See the [Swagger UI documentation][swagger-ui] for advanced usage.
-This means that views will not be instantiated with a `request` instance. i.e. Inside the view `self.request` will be `None`.
 
-To be compatible with this behaviour, methods (such as `get_serializer` or `get_serializer_class` etc.) which inspect `self.request` or, particularly, `self.request.user` may need to be adjusted to handle this case.
+### A minimal example with ReDoc.
 
-You may ensure views are given a `request` instance by calling `include_docs_urls` with `public=False`:
+Assuming you've followed the example from the schemas documentation for routing
+a dynamic `SchemaView`, a minimal Django template for using Swagger UI might be
+this:
 
-    from rest_framework.documentation import include_docs_urls
+```html
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>ReDoc</title>
+    <!-- needed for adaptive design -->
+    <meta charset="utf-8"/>
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
+    <!-- ReDoc doesn't change outer page styles -->
+    <style>
+      body {
+        margin: 0;
+        padding: 0;
+      }
+    </style>
+  </head>
+  <body>
+    <redoc spec-url='{% url schema_url %}'></redoc>
+    <script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script>
+  </body>
+</html>
+```
 
-    urlpatterns = [
+Save this in your templates folder as `redoc.html`. Then route a `TemplateView`
-        ...
+in your project's URL conf:
-        # Generate schema with valid `request` instance:
-        url(r'^docs/', include_docs_urls(title='My API title', public=False))
-    ]
 
+```python
+from django.views.generic import TemplateView
 
----
+urlpatterns = [
+    # ...
+    # Route TemplateView to serve the ReDoc template.
+    #   * Provide `extra_context` with view name of `SchemaView`.
+    path('redoc/', TemplateView.as_view(
+        template_name='redoc.html',
+        extra_context={'schema_url':'openapi-schema'}
+    ), name='redoc'),
+]
+```
 
-
+See the [ReDoc documentation][redoc] for advanced usage.
-### Documenting your views
-
-You can document your views by including docstrings that describe each of the available actions.
-For example:
-
-    class UserList(generics.ListAPIView):
-        """
-        Return a list of all the existing users.
-        """
-
-If a view supports multiple methods, you should split your documentation using `method:` style delimiters.
-
-    class UserList(generics.ListCreateAPIView):
-        """
-        get:
-        Return a list of all the existing users.
-
-        post:
-        Create a new user instance.
-        """
-
-When using viewsets, you should use the relevant action names as delimiters.
-
-    class UserViewSet(viewsets.ModelViewSet):
-        """
-        retrieve:
-        Return the given user.
-
-        list:
-        Return a list of all the existing users.
-
-        create:
-        Create a new user instance.
-        """
-
-Custom actions on viewsets can also be documented in a similar way using the method names
-as delimiters or by attaching the documentation to action mapping methods.
-    
-    class UserViewSet(viewsets.ModelViewset):
-        ...
-        
-        @action(detail=False, methods=['get', 'post'])
-        def some_action(self, request, *args, **kwargs):
-            """
-            get:
-            A description of the get method on the custom action.
-    
-            post:
-            A description of the post method on the custom action.
-            """
-
-        @some_action.mapping.put
-        def put_some_action():
-            """
-            A description of the put method on the custom action.
-            """
-
-
-### `documentation` API Reference
-
-The `rest_framework.documentation` module provides three helper functions to help configure the interactive API documentation, `include_docs_urls` (usage shown above), `get_docs_view` and `get_schemajs_view`.
-
- `include_docs_urls` employs `get_docs_view` and `get_schemajs_view` to generate the url patterns for the documentation page and JavaScript resource that exposes the API schema respectively. They expose the following options for customisation. (`get_docs_view` and `get_schemajs_view` ultimately call `rest_frameworks.schemas.get_schema_view()`, see the Schemas docs for more options there.)
-
-#### `include_docs_urls`
-
-* `title`: Default `None`. May be used to provide a descriptive title for the schema definition.
-* `description`: Default `None`. May be used to provide a description for the schema definition.
-* `schema_url`: Default `None`. May be used to pass a canonical base URL for the schema.
-* `public`: Default `True`. Should the schema be considered _public_? If `True` schema is generated without a `request` instance being passed to views.
-* `patterns`: Default `None`. A list of URLs to inspect when generating the schema. If `None` project's URL conf will be used.
-* `generator_class`: Default `rest_framework.schemas.SchemaGenerator`. May be used to specify a `SchemaGenerator` subclass to be passed to the `SchemaView`.
-* `authentication_classes`: Default `api_settings.DEFAULT_AUTHENTICATION_CLASSES`. May be used to pass custom authentication classes to the `SchemaView`.
-* `permission_classes`: Default `api_settings.DEFAULT_PERMISSION_CLASSES` May be used to pass custom permission classes to the `SchemaView`.
-* `renderer_classes`: Default `None`. May be used to pass custom renderer classes to the `SchemaView`.
-
-#### `get_docs_view`
-
-* `title`: Default `None`. May be used to provide a descriptive title for the schema definition.
-* `description`: Default `None`. May be used to provide a description for the schema definition.
-* `schema_url`: Default `None`. May be used to pass a canonical base URL for the schema.
-* `public`: Default `True`. If `True` schema is generated without a `request` instance being passed to views.
-* `patterns`: Default `None`. A list of URLs to inspect when generating the schema. If `None` project's URL conf will be used.
-* `generator_class`: Default `rest_framework.schemas.SchemaGenerator`. May be used to specify a `SchemaGenerator` subclass to be passed to the `SchemaView`.
-* `authentication_classes`: Default `api_settings.DEFAULT_AUTHENTICATION_CLASSES`. May be used to pass custom authentication classes to the `SchemaView`.
-* `permission_classes`: Default `api_settings.DEFAULT_PERMISSION_CLASSES`. May be used to pass custom permission classes to the `SchemaView`.
-* `renderer_classes`: Default `None`. May be used to pass custom renderer classes to the `SchemaView`. If `None` the `SchemaView` will be configured with `DocumentationRenderer` and `CoreJSONRenderer` renderers, corresponding to the (default) `html` and `corejson` formats.
-
-#### `get_schemajs_view`
-
-* `title`: Default `None`. May be used to provide a descriptive title for the schema definition.
-* `description`: Default `None`. May be used to provide a description for the schema definition.
-* `schema_url`: Default `None`. May be used to pass a canonical base URL for the schema.
-* `public`: Default `True`. If `True` schema is generated without a `request` instance being passed to views.
-* `patterns`: Default `None`. A list of URLs to inspect when generating the schema. If `None` project's URL conf will be used.
-* `generator_class`: Default `rest_framework.schemas.SchemaGenerator`. May be used to specify a `SchemaGenerator` subclass to be passed to the `SchemaView`.
-* `authentication_classes`: Default `api_settings.DEFAULT_AUTHENTICATION_CLASSES`. May be used to pass custom authentication classes to the `SchemaView`.
-* `permission_classes`: Default `api_settings.DEFAULT_PERMISSION_CLASSES` May be used to pass custom permission classes to the `SchemaView`.
-
-
-### Customising code samples
-
-The built-in API documentation includes automatically generated code samples for
-each of the available API client libraries.
-
-You may customise these samples by subclassing `DocumentationRenderer`, setting
-`languages` to the list of languages you wish to support:
-
-    from rest_framework.renderers import DocumentationRenderer
-
-
-    class CustomRenderer(DocumentationRenderer):
-        languages = ['ruby', 'go']
-
-For each language you need to provide an `intro` template, detailing installation instructions and such,
-plus a generic template for making API requests, that can be filled with individual request details.
-See the [templates for the bundled languages][client-library-templates] for examples.
-
----
 
 ## Third party packages
 
@@ -195,18 +140,6 @@ This also translates into a very useful interactive documentation viewer in the
 
 ---
 
-#### DRF Docs
-
-[DRF Docs][drfdocs-repo] allows you to document Web APIs made with Django REST Framework and it is authored by Emmanouil Konstantinidis. It's made to work out of the box and its setup should not take more than a couple of minutes. Complete documentation can be found on the [website][drfdocs-website] while there is also a [demo][drfdocs-demo] available for people to see what it looks like. **Live API Endpoints** allow you to utilize the endpoints from within the documentation in a neat way.
-
-Features include customizing the template with your branding, settings for hiding the docs depending on the environment and more.
-
-Both this package and Django REST Swagger are fully documented, well supported, and come highly recommended.
-
-![Screenshot - DRF docs][image-drf-docs]
-
----
-
 #### Django REST Swagger
 
 Marc Gibbons' [Django REST Swagger][django-rest-swagger] integrates REST framework with the [Swagger][swagger] API documentation tool.  The package produces well presented API documentation, and includes interactive tools for testing API endpoints.
@@ -215,7 +148,7 @@ Django REST Swagger supports REST framework versions 2.3 and above.
 
 Mark is also the author of the [REST Framework Docs][rest-framework-docs] package which offers clean, simple autogenerated documentation for your API but is deprecated and has moved to Django REST Swagger.
 
-Both this package and DRF docs are fully documented, well supported, and come highly recommended.
+This package is fully documented, well supported, and comes highly recommended.
 
 ![Screenshot - Django REST Swagger][image-django-rest-swagger]
 
@@ -322,9 +255,6 @@ To implement a hypermedia API you'll need to decide on an appropriate media type
 [cite]: https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
 [drf-yasg]: https://github.com/axnsan12/drf-yasg/
 [image-drf-yasg]: ../img/drf-yasg.png
-[drfdocs-repo]: https://github.com/ekonstantinidis/django-rest-framework-docs
-[drfdocs-website]: https://www.drfdocs.com/
-[drfdocs-demo]: http://demo.drfdocs.com/
 [drfautodocs-repo]: https://github.com/iMakedonsky/drf-autodocs
 [django-rest-swagger]: https://github.com/marcgibbons/django-rest-swagger
 [swagger]: https://swagger.io/
@@ -333,10 +263,12 @@ To implement a hypermedia API you'll need to decide on an appropriate media type
 [apiary]: https://apiary.io/
 [markdown]: https://daringfireball.net/projects/markdown/syntax
 [hypermedia-docs]: rest-hypermedia-hateoas.md
-[image-drf-docs]: ../img/drfdocs.png
 [image-django-rest-swagger]: ../img/django-rest-swagger.png
 [image-apiary]: ../img/apiary.png
 [image-self-describing-api]: ../img/self-describing.png
-[schemas-examples]: ../api-guide/schemas/#examples
 [metadata-docs]: ../api-guide/metadata/
-[client-library-templates]: https://github.com/encode/django-rest-framework/tree/master/rest_framework/templates/rest_framework/docs/langs
+
+[schemas-examples]: ../api-guide/schemas/#examples
+[swagger-ui]: https://swagger.io/tools/swagger-ui/
+[redoc]: https://github.com/Rebilly/ReDoc
+

docs/topics/writable-nested-serializers.md

@@ -15,14 +15,14 @@ Nested data structures are easy enough to work with if they're read-only - simpl
     class ToDoItemSerializer(serializers.ModelSerializer):
         class Meta:
             model = ToDoItem
-            fields = ('text', 'is_completed')
+            fields = ['text', 'is_completed']
 
     class ToDoListSerializer(serializers.ModelSerializer):
         items = ToDoItemSerializer(many=True, read_only=True)
 
         class Meta:
             model = ToDoList
-            fields = ('title', 'items')
+            fields = ['title', 'items']
 
 Some example output from our serializer.
 

docs/tutorial/1-serialization.md

@@ -42,11 +42,11 @@ Once that's done we can create an app that we'll use to create a simple Web API.
 
 We'll need to add our new `snippets` app and the `rest_framework` app to `INSTALLED_APPS`. Let's edit the `tutorial/settings.py` file:
 
-    INSTALLED_APPS = (
+    INSTALLED_APPS = [
         ...
         'rest_framework',
         'snippets.apps.SnippetsConfig',
-    )
+    ]
 
 Okay, we're ready to roll.
 
@@ -60,7 +60,7 @@ For the purposes of this tutorial we're going to start by creating a simple `Sni
 
     LEXERS = [item for item in get_all_lexers() if item[1]]
     LANGUAGE_CHOICES = sorted([(item[1][0], item[0]) for item in LEXERS])
-    STYLE_CHOICES = sorted((item, item) for item in get_all_styles())
+    STYLE_CHOICES = sorted([(item, item) for item in get_all_styles()])
 
 
     class Snippet(models.Model):
@@ -72,7 +72,7 @@ For the purposes of this tutorial we're going to start by creating a simple `Sni
         style = models.CharField(choices=STYLE_CHOICES, default='friendly', max_length=100)
 
         class Meta:
-            ordering = ('created',)
+            ordering = ['created']
 
 We'll also need to create an initial migration for our snippet model, and sync the database for the first time.
 
@@ -189,7 +189,7 @@ Open the file `snippets/serializers.py` again, and replace the `SnippetSerialize
     class SnippetSerializer(serializers.ModelSerializer):
         class Meta:
             model = Snippet
-            fields = ('id', 'title', 'code', 'linenos', 'language', 'style')
+            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 its representation. Open the Django shell with `python manage.py shell`, then try the following:
 

docs/tutorial/4-authentication-and-permissions.md

@@ -63,7 +63,7 @@ Now that we've got some users to work with, we'd better add representations of t
 
         class Meta:
             model = User
-            fields = ('id', 'username', 'snippets')
+            fields = ['id', 'username', 'snippets']
 
 Because `'snippets'` is a *reverse* relationship on the User model, it will not be included by default when using the `ModelSerializer` class, so we needed to add an explicit field for it.
 
@@ -127,7 +127,7 @@ First add the following import in the views module
 
 Then, add the following property to **both** the `SnippetList` and `SnippetDetail` view classes.
 
-    permission_classes = (permissions.IsAuthenticatedOrReadOnly,)
+    permission_classes = [permissions.IsAuthenticatedOrReadOnly]
 
 ## Adding login to the Browsable API
 
@@ -178,8 +178,8 @@ In the snippets app, create a new file, `permissions.py`
 
 Now we can add that custom permission to our snippet instance endpoint, by editing the `permission_classes` property on the `SnippetDetail` view class:
 
-    permission_classes = (permissions.IsAuthenticatedOrReadOnly,
+    permission_classes = [permissions.IsAuthenticatedOrReadOnly,
-                          IsOwnerOrReadOnly,)
+                          IsOwnerOrReadOnly]
 
 Make sure to also import the `IsOwnerOrReadOnly` class.
 

docs/tutorial/5-relationships-and-hyperlinked-apis.md

@@ -35,7 +35,7 @@ Instead of using a concrete generic view, we'll use the base class for represent
 
     class SnippetHighlight(generics.GenericAPIView):
         queryset = Snippet.objects.all()
-        renderer_classes = (renderers.StaticHTMLRenderer,)
+        renderer_classes = [renderers.StaticHTMLRenderer]
 
         def get(self, request, *args, **kwargs):
             snippet = self.get_object()
@@ -80,8 +80,8 @@ We can easily re-write our existing serializers to use hyperlinking. In your `sn
 
         class Meta:
             model = Snippet
-            fields = ('url', 'id', 'highlight', 'owner',
+            fields = ['url', 'id', 'highlight', 'owner',
-                      'title', 'code', 'linenos', 'language', 'style')
+                      'title', 'code', 'linenos', 'language', 'style']
 
 
     class UserSerializer(serializers.HyperlinkedModelSerializer):
@@ -89,7 +89,7 @@ We can easily re-write our existing serializers to use hyperlinking. In your `sn
 
         class Meta:
             model = User
-            fields = ('url', 'id', 'username', 'snippets')
+            fields = ['url', 'id', 'username', 'snippets']
 
 Notice that we've also added a new `'highlight'` field.  This field is of the same type as the `url` field, except that it points to the `'snippet-highlight'` url pattern, instead of the `'snippet-detail'` url pattern.
 

docs/tutorial/6-viewsets-and-routers.md

@@ -37,8 +37,8 @@ Next we're going to replace the `SnippetList`, `SnippetDetail` and `SnippetHighl
         """
         queryset = Snippet.objects.all()
         serializer_class = SnippetSerializer
-        permission_classes = (permissions.IsAuthenticatedOrReadOnly,
+        permission_classes = [permissions.IsAuthenticatedOrReadOnly,
-                              IsOwnerOrReadOnly,)
+                              IsOwnerOrReadOnly]
 
         @action(detail=True, renderer_classes=[renderers.StaticHTMLRenderer])
         def highlight(self, request, *args, **kwargs):
@@ -128,8 +128,3 @@ The `DefaultRouter` class we're using also automatically creates the API root vi
 Using viewsets can be a really useful abstraction.  It helps ensure that URL conventions will be consistent across your API, minimizes the amount of code you need to write, and allows you to concentrate on the interactions and representations your API provides rather than the specifics of the URL conf.
 
 That doesn't mean it's always the right approach to take.  There's a similar set of trade-offs to consider as when using class-based views instead of function based views.  Using viewsets is less explicit than building your views individually.
-
-In [part 7][tut-7] of the tutorial we'll look at how we can add an API schema,
-and interact with our API using a client library or command line tool.
-
-[tut-7]: 7-schemas-and-client-libraries.md

docs/tutorial/quickstart.md

@@ -69,13 +69,13 @@ First up we're going to define some serializers. Let's create a new module named
     class UserSerializer(serializers.HyperlinkedModelSerializer):
         class Meta:
             model = User
-            fields = ('url', 'username', 'email', 'groups')
+            fields = ['url', 'username', 'email', 'groups']
 
 
     class GroupSerializer(serializers.HyperlinkedModelSerializer):
         class Meta:
             model = Group
-            fields = ('url', 'name')
+            fields = ['url', 'name']
 
 Notice that we're using hyperlinked relations in this case with `HyperlinkedModelSerializer`.  You can also use primary key and various other relationships, but hyperlinking is good RESTful design.
 
@@ -144,10 +144,10 @@ Pagination allows you to control how many objects per page are returned. To enab
 
 Add `'rest_framework'` to `INSTALLED_APPS`. The settings module will be in `tutorial/settings.py`
 
-    INSTALLED_APPS = (
+    INSTALLED_APPS = [
         ...
         'rest_framework',
-    )
+    ]
 
 Okay, we're done.
 

docs_theme/js/theme.js

@@ -9,11 +9,6 @@ var getSearchTerm = function() {
   }
 };
 
-var initilizeSearch = function() {
-  require.config({ baseUrl: '/mkdocs/js' });
-  require(['search']);
-};
-
 $(function() {
   var searchTerm = getSearchTerm(),
     $searchModal = $('#mkdocs_search_modal'),
@@ -30,6 +25,5 @@ $(function() {
 
   $searchModal.on('shown', function() {
     $searchQuery.focus();
-    initilizeSearch();
   });
 });

docs_theme/main.html

@@ -6,7 +6,7 @@
   <meta charset="utf-8">
   <title>{% if page.title %}{{ page.title }} - {% endif %}{{ config.site_name }}</title>
   <link href="{{ base_url }}/img/favicon.ico" rel="icon" type="image/x-icon">
-  <link rel="canonical" href="{{ page.canonical_url }}" />
+  <link rel="canonical" href="{{ page.canonical_url|url }}" />
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <meta name="description" content="Django, API, REST{% if page %}, {{ page.title }}{% endif %}">
   <meta name="author" content="Tom Christie">
@@ -138,14 +138,17 @@
   <!-- Le javascript
   ================================================== -->
   <!-- Placed at the end of the document so the pages load faster -->
+  <script async src="https://fund.django-rest-framework.org/sidebar_include.js"></script>
   <script src="{{ base_url }}/js/jquery-1.8.1-min.js"></script>
   <script src="{{ base_url }}/js/prettify-1.0.js"></script>
   <script src="{{ base_url }}/js/bootstrap-2.1.1-min.js"></script>
-  <script src="https://fund.django-rest-framework.org/sidebar_include.js"></script>
-  <script>var base_url = '{{ base_url }}';</script>
-  <script src="{{ base_url }}/mkdocs/js/require.js"></script>
   <script src="{{ base_url }}/js/theme.js"></script>
 
+  <script>var base_url = '{{ base_url }}';</script>
+  {% for path in config.extra_javascript %}
+  <script src="{{ path|url }}" defer></script>
+  {% endfor %}
+
   <script>
     var shiftWindow = function() {
       scrollBy(0, -50)

docs_theme/nav.html

@@ -2,10 +2,10 @@
       <div class="navbar-inner">
         <div class="container-fluid">
           <a class="repo-link btn btn-primary btn-small" href="https://github.com/encode/django-rest-framework/tree/master">GitHub</a>
-          <a class="repo-link btn btn-inverse btn-small {% if not page.next_page %}disabled{% endif %}" rel="prev" {% if page.next_page %}href="{{ page.next_page.url }}"{% endif %}>
+          <a class="repo-link btn btn-inverse btn-small {% if not page.next_page %}disabled{% endif %}" rel="next" {% if page.next_page %}href="{{ page.next_page.url|url }}"{% endif %}>
             Next <i class="icon-arrow-right icon-white"></i>
           </a>
-          <a class="repo-link btn btn-inverse btn-small {% if not page.previous_page %}disabled{% endif %}" rel="next" {% if page.previous_page %}href="{{ page.previous_page.url }}"{% endif %}>
+          <a class="repo-link btn btn-inverse btn-small {% if not page.previous_page %}disabled{% endif %}" rel="prev" {% if page.previous_page %}href="{{ page.previous_page.url|url }}"{% endif %}>
             <i class="icon-arrow-left icon-white"></i> Previous
           </a>
           <a id="search_modal_show" class="repo-link btn btn-inverse btn-small" href="#mkdocs_search_modal" data-toggle="modal" data-target="#mkdocs_search_modal"><i class="icon-search icon-white"></i> Search</a>
@@ -25,14 +25,14 @@
                 <ul class="dropdown-menu">
                   {% for nav_item in nav_item.children %}
                   <li {% if nav_item.active %}class="active" {% endif %}>
-                    <a href="{{ nav_item.url }}">{{ nav_item.title }}</a>
+                    <a href="{{ nav_item.url|url }}">{{ nav_item.title }}</a>
                   </li>
                   {% endfor %}
                 </ul>
               </li>
               {% else %}
               <li {% if nav_item.active %}class="active" {% endif %}>
-                <a href="{{ nav_item.url }}">{{ nav_item.title }}</a>
+                <a href="{{ nav_item.url|url }}">{{ nav_item.title }}</a>
               </li>
               {% endif %} {% endfor %}
 

mkdocs.yml

@@ -4,13 +4,15 @@ site_description: Django REST framework - Web APIs for Django
 
 repo_url: https://github.com/encode/django-rest-framework
 
-theme_dir: docs_theme
+theme:
+    name: mkdocs
+    custom_dir: docs_theme
 
 markdown_extensions:
  - toc:
     anchorlink: True
 
-pages:
+nav:
  - Home: 'index.md'
  - Tutorial:
     - 'Quickstart': 'tutorial/quickstart.md'
@@ -20,7 +22,6 @@ pages:
     - '4 - Authentication and permissions': 'tutorial/4-authentication-and-permissions.md'
     - '5 - Relationships and hyperlinked APIs': 'tutorial/5-relationships-and-hyperlinked-apis.md'
     - '6 - Viewsets and routers': 'tutorial/6-viewsets-and-routers.md'
-    - '7 - Schemas and client libraries': 'tutorial/7-schemas-and-client-libraries.md'
  - API Guide:
     - 'Requests': 'api-guide/requests.md'
     - 'Responses': 'api-guide/responses.md'
@@ -65,6 +66,7 @@ pages:
      - 'Contributing to REST framework': 'community/contributing.md'
      - 'Project management': 'community/project-management.md'
      - 'Release Notes': 'community/release-notes.md'
+     - '3.10 Announcement': 'community/3.10-announcement.md'
      - '3.9 Announcement': 'community/3.9-announcement.md'
      - '3.8 Announcement': 'community/3.8-announcement.md'
      - '3.7 Announcement': 'community/3.7-announcement.md'

requirements.txt

@@ -2,8 +2,8 @@
 # just Django, but for the purposes of development and testing
 # there are a number of packages that are useful to install.
 
-# Laying these out as seperate requirements files, allows us to
+# Laying these out as separate requirements files, allows us to
-# only included the relevent sets when running tox, and ensures
+# only included the relevant sets when running tox, and ensures
 # we are only ever declaring our dependencies in one place.
 
 -r requirements/requirements-optionals.txt

requirements/requirements-documentation.txt

@@ -1,2 +1,2 @@
 # MkDocs to build our documentation.
-mkdocs==0.16.3
+mkdocs==1.0.4

requirements/requirements-optionals.txt

@@ -1,8 +1,9 @@
 # Optional packages which may be used with REST framework.
-psycopg2-binary==2.7.5
+psycopg2-binary>=2.8.2, <2.9
-markdown==2.6.11
+markdown==3.1.1
+pygments==2.4.2
 django-guardian==1.5.0
-django-filter==1.1.0
+django-filter>=2.2.0, <2.3
 coreapi==2.3.1
 coreschema==0.0.4
-pyyaml
+pyyaml>=5.1

requirements/requirements-testing.txt

@@ -1,4 +1,4 @@
 # Pytest for running the tests.
-pytest==4.3.0
+pytest>=5.0,<5.1
-pytest-django==3.4.8
+pytest-django>=3.5.1,<3.6
-pytest-cov==2.6.1
+pytest-cov>=2.7.1

rest_framework/__init__.py

@@ -8,7 +8,7 @@ ______ _____ _____ _____    __
 """
 
 __title__ = 'Django REST framework'
-__version__ = '3.9.3'
+__version__ = '3.10.3'
 __author__ = 'Tom Christie'
 __license__ = 'BSD 2-Clause'
 __copyright__ = 'Copyright 2011-2019 Encode OSS Ltd'
@@ -25,9 +25,9 @@ ISO_8601 = 'iso-8601'
 default_app_config = 'rest_framework.apps.RestFrameworkConfig'
 
 
-class RemovedInDRF310Warning(DeprecationWarning):
+class RemovedInDRF311Warning(DeprecationWarning):
     pass
 
 
-class RemovedInDRF311Warning(PendingDeprecationWarning):
+class RemovedInDRF312Warning(PendingDeprecationWarning):
     pass

rest_framework/compat.py

@@ -5,7 +5,6 @@ versions of Django/Python, and compatibility wrappers around optional packages.
 import sys
 
 from django.conf import settings
-from django.core import validators
 from django.views.generic import View
 
 try:
@@ -94,12 +93,16 @@ except ImportError:
     postgres_fields = None
 
 
-# coreapi is optional (Note that uritemplate is a dependency of coreapi)
+# coreapi is required for CoreAPI schema generation
 try:
     import coreapi
-    import uritemplate
 except ImportError:
     coreapi = None
+
+# uritemplate is required for OpenAPI and CoreAPI schema generation
+try:
+    import uritemplate
+except ImportError:
     uritemplate = None
 
 
@@ -117,13 +120,6 @@ except ImportError:
     yaml = None
 
 
-# django-crispy-forms is optional
-try:
-    import crispy_forms
-except ImportError:
-    crispy_forms = None
-
-
 # requests is optional
 try:
     import requests
@@ -131,31 +127,17 @@ except ImportError:
     requests = None
 
 
-def is_guardian_installed():
-    """
-    django-guardian is optional and only imported if in INSTALLED_APPS.
-    """
-    return 'guardian' in settings.INSTALLED_APPS
-
-
 # PATCH method is not implemented by Django
 if 'patch' not in View.http_method_names:
     View.http_method_names = View.http_method_names + ['patch']
 
 
-# Markdown is optional
+# Markdown is optional (version 3.0+ required)
 try:
     import markdown
 
-    if markdown.version <= '2.2':
+    HEADERID_EXT_PATH = 'markdown.extensions.toc'
-        HEADERID_EXT_PATH = 'headerid'
+    LEVEL_PARAM = 'baselevel'
-        LEVEL_PARAM = 'level'
-    elif markdown.version < '2.6':
-        HEADERID_EXT_PATH = 'markdown.extensions.headerid'
-        LEVEL_PARAM = 'level'
-    else:
-        HEADERID_EXT_PATH = 'markdown.extensions.toc'
-        LEVEL_PARAM = 'baselevel'
 
     def apply_markdown(text):
         """
@@ -228,7 +210,7 @@ if markdown is not None and pygments is not None:
             return ret.split("\n")
 
     def md_filter_add_syntax_highlight(md):
-        md.preprocessors.add('highlight', CodeBlockPreprocessor(), "_begin")
+        md.preprocessors.register(CodeBlockPreprocessor(), 'highlight', 40)
         return True
 else:
     def md_filter_add_syntax_highlight(md):
@@ -252,34 +234,5 @@ LONG_SEPARATORS = (', ', ': ')
 INDENT_SEPARATORS = (',', ': ')
 
 
-class CustomValidatorMessage:
-    """
-    We need to avoid evaluation of `lazy` translated `message` in `django.core.validators.BaseValidator.__init__`.
-    https://github.com/django/django/blob/75ed5900321d170debef4ac452b8b3cf8a1c2384/django/core/validators.py#L297
-
-    Ref: https://github.com/encode/django-rest-framework/pull/5452
-    """
-
-    def __init__(self, *args, **kwargs):
-        self.message = kwargs.pop('message', self.message)
-        super().__init__(*args, **kwargs)
-
-
-class MinValueValidator(CustomValidatorMessage, validators.MinValueValidator):
-    pass
-
-
-class MaxValueValidator(CustomValidatorMessage, validators.MaxValueValidator):
-    pass
-
-
-class MinLengthValidator(CustomValidatorMessage, validators.MinLengthValidator):
-    pass
-
-
-class MaxLengthValidator(CustomValidatorMessage, validators.MaxLengthValidator):
-    pass
-
-
 # Version Constants.
 PY36 = sys.version_info >= (3, 6)

rest_framework/decorators.py

@@ -3,15 +3,13 @@ The most important decorator in this module is `@api_view`, which is used
 for writing function-based views with REST framework.
 
 There are also various decorators for setting the API policies on function
-based views, as well as the `@detail_route` and `@list_route` decorators, which are
+based views, as well as the `@action` decorator, which is used to annotate
-used to annotate methods on viewsets that should be included by routers.
+methods on viewsets that should be included by routers.
 """
 import types
-import warnings
 
 from django.forms.utils import pretty_name
 
-from rest_framework import RemovedInDRF310Warning
 from rest_framework.views import APIView
 
 
@@ -214,39 +212,3 @@ class MethodMapper(dict):
 
     def trace(self, func):
         return self._map('trace', func)
-
-
-def detail_route(methods=None, **kwargs):
-    """
-    Used to mark a method on a ViewSet that should be routed for detail requests.
-    """
-    warnings.warn(
-        "`detail_route` is deprecated and will be removed in 3.10 in favor of "
-        "`action`, which accepts a `detail` bool. Use `@action(detail=True)` instead.",
-        RemovedInDRF310Warning, stacklevel=2
-    )
-
-    def decorator(func):
-        func = action(methods, detail=True, **kwargs)(func)
-        if 'url_name' not in kwargs:
-            func.url_name = func.url_path.replace('_', '-')
-        return func
-    return decorator
-
-
-def list_route(methods=None, **kwargs):
-    """
-    Used to mark a method on a ViewSet that should be routed for list requests.
-    """
-    warnings.warn(
-        "`list_route` is deprecated and will be removed in 3.10 in favor of "
-        "`action`, which accepts a `detail` bool. Use `@action(detail=False)` instead.",
-        RemovedInDRF310Warning, stacklevel=2
-    )
-
-    def decorator(func):
-        func = action(methods, detail=False, **kwargs)(func)
-        if 'url_name' not in kwargs:
-            func.url_name = func.url_path.replace('_', '-')
-        return func
-    return decorator

rest_framework/documentation.py

@@ -8,8 +8,8 @@ from rest_framework.settings import api_settings
 
 
 def get_docs_view(
-        title=None, description=None, schema_url=None, public=True,
+        title=None, description=None, schema_url=None, urlconf=None,
-        patterns=None, generator_class=SchemaGenerator,
+        public=True, patterns=None, generator_class=SchemaGenerator,
         authentication_classes=api_settings.DEFAULT_AUTHENTICATION_CLASSES,
         permission_classes=api_settings.DEFAULT_PERMISSION_CLASSES,
         renderer_classes=None):
@@ -20,6 +20,7 @@ def get_docs_view(
     return get_schema_view(
         title=title,
         url=schema_url,
+        urlconf=urlconf,
         description=description,
         renderer_classes=renderer_classes,
         public=public,
@@ -31,8 +32,8 @@ def get_docs_view(
 
 
 def get_schemajs_view(
-        title=None, description=None, schema_url=None, public=True,
+        title=None, description=None, schema_url=None, urlconf=None,
-        patterns=None, generator_class=SchemaGenerator,
+        public=True, patterns=None, generator_class=SchemaGenerator,
         authentication_classes=api_settings.DEFAULT_AUTHENTICATION_CLASSES,
         permission_classes=api_settings.DEFAULT_PERMISSION_CLASSES):
     renderer_classes = [SchemaJSRenderer]
@@ -40,6 +41,7 @@ def get_schemajs_view(
     return get_schema_view(
         title=title,
         url=schema_url,
+        urlconf=urlconf,
         description=description,
         renderer_classes=renderer_classes,
         public=public,
@@ -51,8 +53,8 @@ def get_schemajs_view(
 
 
 def include_docs_urls(
-        title=None, description=None, schema_url=None, public=True,
+        title=None, description=None, schema_url=None, urlconf=None,
-        patterns=None, generator_class=SchemaGenerator,
+        public=True, patterns=None, generator_class=SchemaGenerator,
         authentication_classes=api_settings.DEFAULT_AUTHENTICATION_CLASSES,
         permission_classes=api_settings.DEFAULT_PERMISSION_CLASSES,
         renderer_classes=None):
@@ -60,6 +62,7 @@ def include_docs_urls(
         title=title,
         description=description,
         schema_url=schema_url,
+        urlconf=urlconf,
         public=public,
         patterns=patterns,
         generator_class=generator_class,
@@ -71,6 +74,7 @@ def include_docs_urls(
         title=title,
         description=description,
         schema_url=schema_url,
+        urlconf=urlconf,
         public=public,
         patterns=patterns,
         generator_class=generator_class,

rest_framework/exceptions.py

@@ -7,7 +7,7 @@ In addition Django's built in 403 and 404 exceptions are handled.
 import math
 
 from django.http import JsonResponse
-from django.utils.encoding import force_text
+from django.utils.encoding import force_str
 from django.utils.translation import gettext_lazy as _
 from django.utils.translation import ngettext
 
@@ -36,7 +36,7 @@ def _get_error_details(data, default_code=None):
             return ReturnDict(ret, serializer=data.serializer)
         return ret
 
-    text = force_text(data)
+    text = force_str(data)
     code = getattr(data, 'code', default_code)
     return ErrorDetail(text, code)
 
@@ -191,7 +191,7 @@ class MethodNotAllowed(APIException):
 
     def __init__(self, method, detail=None, code=None):
         if detail is None:
-            detail = force_text(self.default_detail).format(method=method)
+            detail = force_str(self.default_detail).format(method=method)
         super().__init__(detail, code)
 
 
@@ -212,27 +212,27 @@ class UnsupportedMediaType(APIException):
 
     def __init__(self, media_type, detail=None, code=None):
         if detail is None:
-            detail = force_text(self.default_detail).format(media_type=media_type)
+            detail = force_str(self.default_detail).format(media_type=media_type)
         super().__init__(detail, code)
 
 
 class Throttled(APIException):
     status_code = status.HTTP_429_TOO_MANY_REQUESTS
     default_detail = _('Request was throttled.')
-    extra_detail_singular = 'Expected available in {wait} second.'
+    extra_detail_singular = _('Expected available in {wait} second.')
-    extra_detail_plural = 'Expected available in {wait} seconds.'
+    extra_detail_plural = _('Expected available in {wait} seconds.')
     default_code = 'throttled'
 
     def __init__(self, wait=None, detail=None, code=None):
         if detail is None:
-            detail = force_text(self.default_detail)
+            detail = force_str(self.default_detail)
         if wait is not None:
             wait = math.ceil(wait)
             detail = ' '.join((
                 detail,
-                force_text(ngettext(self.extra_detail_singular.format(wait=wait),
+                force_str(ngettext(self.extra_detail_singular.format(wait=wait),
-                                    self.extra_detail_plural.format(wait=wait),
+                                   self.extra_detail_plural.format(wait=wait),
-                                    wait))))
+                                   wait))))
         self.wait = wait
         super().__init__(detail, code)
 

rest_framework/fields.py

@@ -12,7 +12,8 @@ from django.conf import settings
 from django.core.exceptions import ObjectDoesNotExist
 from django.core.exceptions import ValidationError as DjangoValidationError
 from django.core.validators import (
-    EmailValidator, RegexValidator, URLValidator, ip_address_validators
+    EmailValidator, MaxLengthValidator, MaxValueValidator, MinLengthValidator,
+    MinValueValidator, RegexValidator, URLValidator, ip_address_validators
 )
 from django.forms import FilePathField as DjangoFilePathField
 from django.forms import ImageField as DjangoImageField
@@ -23,20 +24,17 @@ from django.utils.dateparse import (
 from django.utils.duration import duration_string
 from django.utils.encoding import is_protected_type, smart_text
 from django.utils.formats import localize_input, sanitize_separators
-from django.utils.functional import lazy
 from django.utils.ipv6 import clean_ipv6_address
 from django.utils.timezone import utc
 from django.utils.translation import gettext_lazy as _
 from pytz.exceptions import InvalidTimeError
 
 from rest_framework import ISO_8601
-from rest_framework.compat import (
+from rest_framework.compat import ProhibitNullCharactersValidator
-    MaxLengthValidator, MaxValueValidator, MinLengthValidator,
-    MinValueValidator, ProhibitNullCharactersValidator
-)
 from rest_framework.exceptions import ErrorDetail, ValidationError
 from rest_framework.settings import api_settings
 from rest_framework.utils import html, humanize_datetime, json, representation
+from rest_framework.utils.formatting import lazy_format
 
 
 class empty:
@@ -49,10 +47,24 @@ class empty:
     pass
 
 
+class BuiltinSignatureError(Exception):
+    """
+    Built-in function signatures are not inspectable. This exception is raised
+    so the serializer can raise a helpful error message.
+    """
+    pass
+
+
 def is_simple_callable(obj):
     """
     True if the object is a callable that takes no arguments.
     """
+    # Bail early since we cannot inspect built-in function signatures.
+    if inspect.isbuiltin(obj):
+        raise BuiltinSignatureError(
+            'Built-in function signatures are not inspectable. '
+            'Wrap the function call in a simple, pure Python function.')
+
     if not (inspect.isfunction(obj) or inspect.ismethod(obj) or isinstance(obj, functools.partial)):
         return False
 
@@ -219,12 +231,12 @@ def get_error_detail(exc_info):
         error_dict = exc_info.error_dict
     except AttributeError:
         return [
-            ErrorDetail(error.message % (error.params or ()),
+            ErrorDetail((error.message % error.params) if error.params else error.message,
                         code=error.code if error.code else code)
             for error in exc_info.error_list]
     return {
         k: [
-            ErrorDetail(error.message % (error.params or ()),
+            ErrorDetail((error.message % error.params) if error.params else error.message,
                         code=error.code if error.code else code)
             for error in errors
         ] for k, errors in error_dict.items()
@@ -429,6 +441,18 @@ class Field:
         """
         try:
             return get_attribute(instance, self.source_attrs)
+        except BuiltinSignatureError as exc:
+            msg = (
+                'Field source for `{serializer}.{field}` maps to a built-in '
+                'function type and is invalid. Define a property or method on '
+                'the `{instance}` instance that wraps the call to the built-in '
+                'function.'.format(
+                    serializer=self.parent.__class__.__name__,
+                    field=self.field_name,
+                    instance=instance.__class__.__name__,
+                )
+            )
+            raise type(exc)(msg)
         except (KeyError, AttributeError) as exc:
             if self.default is not empty:
                 return self.get_default()
@@ -493,6 +517,11 @@ class Field:
         if data is None:
             if not self.allow_null:
                 self.fail('null')
+            # Nullable `source='*'` fields should not be skipped when its named
+            # field is given a null value. This is because `source='*'` means
+            # the field is passed the entire object, which is not null.
+            elif self.source == '*':
+                return (False, None)
             return (True, None)
 
         return (False, data)
@@ -614,7 +643,7 @@ class Field:
             for item in self._args
         ]
         kwargs = {
-            key: (copy.deepcopy(value) if (key not in ('validators', 'regex')) else value)
+            key: (copy.deepcopy(value, memo) if (key not in ('validators', 'regex')) else value)
             for key, value in self._kwargs.items()
         }
         return self.__class__(*args, **kwargs)
@@ -744,12 +773,11 @@ class CharField(Field):
         self.min_length = kwargs.pop('min_length', None)
         super().__init__(**kwargs)
         if self.max_length is not None:
-            message = lazy(self.error_messages['max_length'].format, str)(max_length=self.max_length)
+            message = lazy_format(self.error_messages['max_length'], max_length=self.max_length)
             self.validators.append(
                 MaxLengthValidator(self.max_length, message=message))
         if self.min_length is not None:
-            message = lazy(
+            message = lazy_format(self.error_messages['min_length'], min_length=self.min_length)
-                self.error_messages['min_length'].format, str)(min_length=self.min_length)
             self.validators.append(
                 MinLengthValidator(self.min_length, message=message))
 
@@ -910,13 +938,11 @@ class IntegerField(Field):
         self.min_value = kwargs.pop('min_value', None)
         super().__init__(**kwargs)
         if self.max_value is not None:
-            message = lazy(
+            message = lazy_format(self.error_messages['max_value'], max_value=self.max_value)
-                self.error_messages['max_value'].format, str)(max_value=self.max_value)
             self.validators.append(
                 MaxValueValidator(self.max_value, message=message))
         if self.min_value is not None:
-            message = lazy(
+            message = lazy_format(self.error_messages['min_value'], min_value=self.min_value)
-                self.error_messages['min_value'].format, str)(min_value=self.min_value)
             self.validators.append(
                 MinValueValidator(self.min_value, message=message))
 
@@ -948,15 +974,11 @@ class FloatField(Field):
         self.min_value = kwargs.pop('min_value', None)
         super().__init__(**kwargs)
         if self.max_value is not None:
-            message = lazy(
+            message = lazy_format(self.error_messages['max_value'], max_value=self.max_value)
-                self.error_messages['max_value'].format,
-                str)(max_value=self.max_value)
             self.validators.append(
                 MaxValueValidator(self.max_value, message=message))
         if self.min_value is not None:
-            message = lazy(
+            message = lazy_format(self.error_messages['min_value'], min_value=self.min_value)
-                self.error_messages['min_value'].format,
-                str)(min_value=self.min_value)
             self.validators.append(
                 MinValueValidator(self.min_value, message=message))
 
@@ -1007,14 +1029,11 @@ class DecimalField(Field):
         super().__init__(**kwargs)
 
         if self.max_value is not None:
-            message = lazy(
+            message = lazy_format(self.error_messages['max_value'], max_value=self.max_value)
-                self.error_messages['max_value'].format,
-                str)(max_value=self.max_value)
             self.validators.append(
                 MaxValueValidator(self.max_value, message=message))
         if self.min_value is not None:
-            message = lazy(
+            message = lazy_format(self.error_messages['min_value'], min_value=self.min_value)
-                self.error_messages['min_value'].format, str)(min_value=self.min_value)
             self.validators.append(
                 MinValueValidator(self.min_value, message=message))
 
@@ -1352,15 +1371,11 @@ class DurationField(Field):
         self.min_value = kwargs.pop('min_value', None)
         super().__init__(**kwargs)
         if self.max_value is not None:
-            message = lazy(
+            message = lazy_format(self.error_messages['max_value'], max_value=self.max_value)
-                self.error_messages['max_value'].format,
-                str)(max_value=self.max_value)
             self.validators.append(
                 MaxValueValidator(self.max_value, message=message))
         if self.min_value is not None:
-            message = lazy(
+            message = lazy_format(self.error_messages['min_value'], min_value=self.min_value)
-                self.error_messages['min_value'].format,
-                str)(min_value=self.min_value)
             self.validators.append(
                 MinValueValidator(self.min_value, message=message))
 
@@ -1531,16 +1546,16 @@ class FileField(Field):
             return None
 
         use_url = getattr(self, 'use_url', api_settings.UPLOADED_FILES_USE_URL)
-
         if use_url:
-            if not getattr(value, 'url', None):
+            try:
-                # If the file has not been saved it may not have a URL.
+                url = value.url
+            except AttributeError:
                 return None
-            url = value.url
             request = self.context.get('request', None)
             if request is not None:
                 return request.build_absolute_uri(url)
             return url
+
         return value.name
 
 
@@ -1605,10 +1620,10 @@ class ListField(Field):
         super().__init__(*args, **kwargs)
         self.child.bind(field_name='', parent=self)
         if self.max_length is not None:
-            message = self.error_messages['max_length'].format(max_length=self.max_length)
+            message = lazy_format(self.error_messages['max_length'], max_length=self.max_length)
             self.validators.append(MaxLengthValidator(self.max_length, message=message))
         if self.min_length is not None:
-            message = self.error_messages['min_length'].format(min_length=self.min_length)
+            message = lazy_format(self.error_messages['min_length'], min_length=self.min_length)
             self.validators.append(MinLengthValidator(self.min_length, message=message))
 
     def get_value(self, dictionary):
@@ -1663,11 +1678,13 @@ class DictField(Field):
     child = _UnvalidatedField()
     initial = {}
     default_error_messages = {
-        'not_a_dict': _('Expected a dictionary of items but got type "{input_type}".')
+        'not_a_dict': _('Expected a dictionary of items but got type "{input_type}".'),
+        'empty': _('This dictionary may not be empty.'),
     }
 
     def __init__(self, *args, **kwargs):
         self.child = kwargs.pop('child', copy.deepcopy(self.child))
+        self.allow_empty = kwargs.pop('allow_empty', True)
 
         assert not inspect.isclass(self.child), '`child` has not been instantiated.'
         assert self.child.source is None, (
@@ -1693,6 +1710,9 @@ class DictField(Field):
             data = html.parse_html_dict(data)
         if not isinstance(data, dict):
             self.fail('not_a_dict', input_type=type(data).__name__)
+        if not self.allow_empty and len(data) == 0:
+            self.fail('empty')
+
         return self.run_child_validation(data)
 
     def to_representation(self, value):
@@ -1736,6 +1756,7 @@ class JSONField(Field):
 
     def __init__(self, *args, **kwargs):
         self.binary = kwargs.pop('binary', False)
+        self.encoder = kwargs.pop('encoder', None)
         super().__init__(*args, **kwargs)
 
     def get_value(self, dictionary):
@@ -1757,14 +1778,14 @@ class JSONField(Field):
                     data = data.decode()
                 return json.loads(data)
             else:
-                json.dumps(data)
+                json.dumps(data, cls=self.encoder)
         except (TypeError, ValueError):
             self.fail('invalid')
         return data
 
     def to_representation(self, value):
         if self.binary:
-            value = json.dumps(value)
+            value = json.dumps(value, cls=self.encoder)
             value = value.encode()
         return value
 
@@ -1840,12 +1861,6 @@ class SerializerMethodField(Field):
         # 'method_name' argument has been used. For example:
         # my_field = serializer.SerializerMethodField(method_name='get_my_field')
         default_method_name = 'get_{field_name}'.format(field_name=field_name)
-        assert self.method_name != default_method_name, (
-            "It is redundant to specify `%s` on SerializerMethodField '%s' in "
-            "serializer '%s', because it is the same as the default method name. "
-            "Remove the `method_name` argument." %
-            (self.method_name, field_name, parent.__class__.__name__)
-        )
 
         # The method name should default to `get_{field_name}`.
         if self.method_name is None:
@@ -1873,11 +1888,10 @@ class ModelField(Field):
         self.model_field = model_field
         # The `max_length` option is supported by Django's base `Field` class,
         # so we'd better support it here.
-        max_length = kwargs.pop('max_length', None)
+        self.max_length = kwargs.pop('max_length', None)
         super().__init__(**kwargs)
-        if max_length is not None:
+        if self.max_length is not None:
-            message = lazy(
+            message = lazy_format(self.error_messages['max_length'], max_length=self.max_length)
-                self.error_messages['max_length'].format, str)(max_length=self.max_length)
             self.validators.append(
                 MaxLengthValidator(self.max_length, message=message))
 

rest_framework/filters.py

@@ -3,7 +3,6 @@ Provides generic filtering backends that can be used to filter the results
 returned by list views.
 """
 import operator
-import warnings
 from functools import reduce
 
 from django.core.exceptions import ImproperlyConfigured
@@ -11,13 +10,10 @@ from django.db import models
 from django.db.models.constants import LOOKUP_SEP
 from django.db.models.sql.constants import ORDER_PATTERN
 from django.template import loader
-from django.utils.encoding import force_text
+from django.utils.encoding import force_str
 from django.utils.translation import gettext_lazy as _
 
-from rest_framework import RemovedInDRF310Warning
+from rest_framework.compat import coreapi, coreschema, distinct
-from rest_framework.compat import (
-    coreapi, coreschema, distinct, is_guardian_installed
-)
 from rest_framework.settings import api_settings
 
 
@@ -37,6 +33,9 @@ class BaseFilterBackend:
         assert coreschema is not None, 'coreschema must be installed to use `get_schema_fields()`'
         return []
 
+    def get_schema_operation_parameters(self, view):
+        return []
+
 
 class SearchFilter(BaseFilterBackend):
     # The URL query parameter used for the search.
@@ -65,7 +64,9 @@ class SearchFilter(BaseFilterBackend):
         and may be comma and/or whitespace delimited.
         """
         params = request.query_params.get(self.search_param, '')
-        return params.replace(',', ' ').split()
+        params = params.replace('\x00', '')  # strip null characters
+        params = params.replace(',', ' ')
+        return params.split()
 
     def construct_search(self, field_name):
         lookup = self.lookup_prefixes.get(field_name[0])
@@ -150,12 +151,25 @@ class SearchFilter(BaseFilterBackend):
                 required=False,
                 location='query',
                 schema=coreschema.String(
-                    title=force_text(self.search_title),
+                    title=force_str(self.search_title),
-                    description=force_text(self.search_description)
+                    description=force_str(self.search_description)
                 )
             )
         ]
 
+    def get_schema_operation_parameters(self, view):
+        return [
+            {
+                'name': self.search_param,
+                'required': False,
+                'in': 'query',
+                'description': force_str(self.search_description),
+                'schema': {
+                    'type': 'string',
+                },
+            },
+        ]
+
 
 class OrderingFilter(BaseFilterBackend):
     # The URL query parameter used for the ordering.
@@ -281,46 +295,21 @@ class OrderingFilter(BaseFilterBackend):
                 required=False,
                 location='query',
                 schema=coreschema.String(
-                    title=force_text(self.ordering_title),
+                    title=force_str(self.ordering_title),
-                    description=force_text(self.ordering_description)
+                    description=force_str(self.ordering_description)
                 )
             )
         ]
 
-
+    def get_schema_operation_parameters(self, view):
-class DjangoObjectPermissionsFilter(BaseFilterBackend):
+        return [
-    """
+            {
-    A filter backend that limits results to those where the requesting user
+                'name': self.ordering_param,
-    has read object level permissions.
+                'required': False,
-    """
+                'in': 'query',
-    def __init__(self):
+                'description': force_str(self.ordering_description),
-        warnings.warn(
+                'schema': {
-            "`DjangoObjectPermissionsFilter` has been deprecated and moved to "
+                    'type': 'string',
-            "the 3rd-party django-rest-framework-guardian package.",
+                },
-            RemovedInDRF310Warning, stacklevel=2
+            },
-        )
+        ]
-        assert is_guardian_installed(), 'Using DjangoObjectPermissionsFilter, but django-guardian is not installed'
-
-    perm_format = '%(app_label)s.view_%(model_name)s'
-
-    def filter_queryset(self, request, queryset, view):
-        # We want to defer this import until run-time, rather than import-time.
-        # See https://github.com/encode/django-rest-framework/issues/4608
-        # (Also see #1624 for why we need to make this import explicitly)
-        from guardian import VERSION as guardian_version
-        from guardian.shortcuts import get_objects_for_user
-
-        extra = {}
-        user = request.user
-        model_cls = queryset.model
-        kwargs = {
-            'app_label': model_cls._meta.app_label,
-            'model_name': model_cls._meta.model_name
-        }
-        permission = self.perm_format % kwargs
-        if tuple(guardian_version) >= (1, 3):
-            # Maintain behavior compatibility with versions prior to 1.3
-            extra = {'accept_global_perms': False}
-        else:
-            extra = {}
-        return get_objects_for_user(user, permission, queryset, **extra)