Merge branch 'encode:master' into add-max-page-setting-for-pagination

.github/ISSUE_TEMPLATE/1-issue.md

@@ -5,6 +5,13 @@ about: Please only raise an issue if you've been advised to do so after discussi
 
 ## Checklist
 
+<!--
+Note: REST framework is considered feature-complete. New functionality should be implemented outside the core REST framework. For details, please check the docs: https://www.django-rest-framework.org/community/third-party-packages/#about-third-party-packages
+-->
+
 - [ ] Raised initially as discussion #...
-- [ ] This cannot be dealt with as a third party library. (We prefer new functionality to be [in the form of third party libraries](https://www.django-rest-framework.org/community/third-party-packages/#about-third-party-packages) where possible.)
+- [ ] This is not a feature request suitable for implementation outside this project. Please elaborate what it is:
+  - [ ] compatibility fix for new Django/Python version ...
+  - [ ] other type of bug fix
+  - [ ] other type of improvement that does not touch existing code or change existing behavior (e.g. wrapper for new Django field)
 - [ ] I have reduced the issue to the simplest possible case.

.github/dependabot.yml

@@ -0,0 +1,13 @@
+# Keep GitHub Actions up to date with GitHub's Dependabot...
+# https://docs.github.com/en/code-security/dependabot/working-with-dependabot/keeping-your-actions-up-to-date-with-dependabot
+# https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#package-ecosystem
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    groups:
+      github-actions:
+        patterns:
+          - "*"  # Group all Action updates into a single larger pull request
+    schedule:
+      interval: weekly

.github/workflows/main.yml

@@ -14,17 +14,16 @@ jobs:
     strategy:
       matrix:
         python-version:
-        - '3.6'
-        - '3.7'
         - '3.8'
         - '3.9'
         - '3.10'
         - '3.11'
+        - '3.12'
 
     steps:
     - uses: actions/checkout@v4
 
-    - uses: actions/setup-python@v4
+    - uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
         cache: 'pip'
@@ -36,18 +35,9 @@ jobs:
     - name: Install dependencies
       run: python -m pip install --upgrade codecov tox
 
-    - name: Install tox-py
-      if: ${{ matrix.python-version == '3.6' }}
-      run: python -m pip install --upgrade tox-py
-
     - name: Run tox targets for ${{ matrix.python-version }}
-      if: ${{ matrix.python-version != '3.6' }}
       run: tox run -f py$(echo ${{ matrix.python-version }} | tr -d .)
 
-    - name: Run tox targets for ${{ matrix.python-version }}
-      if: ${{ matrix.python-version == '3.6' }}
-      run: tox --py current
-
     - name: Run extra tox targets
       if: ${{ matrix.python-version == '3.9' }}
       run: |
@@ -61,9 +51,9 @@ jobs:
     name: Test documentation links
     runs-on: ubuntu-22.04
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
 
-    - uses: actions/setup-python@v4
+    - uses: actions/setup-python@v5
       with:
         python-version: '3.9'
 

.github/workflows/pre-commit.yml

@@ -11,14 +11,12 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           fetch-depth: 0
 
-      - uses: actions/setup-python@v4
+      - uses: actions/setup-python@v5
         with:
           python-version: "3.10"
 
-      - uses: pre-commit/[email protected]
-        with:
-          token: ${{ secrets.GITHUB_TOKEN }}
+      - uses: pre-commit/[email protected]

.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
 - repo: https://github.com/pre-commit/pre-commit-hooks
-  rev: v3.4.0
+  rev: v4.5.0
   hooks:
   - id: check-added-large-files
   - id: check-case-conflict
@@ -9,12 +9,25 @@ repos:
   - id: check-symlinks
   - id: check-toml
 - repo: https://github.com/pycqa/isort
-  rev: 5.12.0
+  rev: 5.13.2
   hooks:
   - id: isort
 - repo: https://github.com/PyCQA/flake8
-  rev: 3.9.0
+  rev: 7.0.0
   hooks:
   - id: flake8
     additional_dependencies:
     - flake8-tidy-imports
+- repo: https://github.com/adamchainz/blacken-docs
+  rev: 1.16.0
+  hooks:
+  - id: blacken-docs
+    exclude: ^(?!docs).*$
+    additional_dependencies:
+    - black==23.1.0
+- repo: https://github.com/codespell-project/codespell
+  # Configuration for codespell is in .codespellrc
+  rev: v2.2.6
+  hooks:
+  - id: codespell
+    exclude: locale|kickstarter-announcement.md|coreapi-0.1.1.js

PULL_REQUEST_TEMPLATE.md

@@ -1,4 +1,4 @@
-*Note*: Before submitting this pull request, please review our [contributing guidelines](https://www.django-rest-framework.org/community/contributing/#pull-requests).
+*Note*: Before submitting a code change, please review our [contributing guidelines](https://www.django-rest-framework.org/community/contributing/#pull-requests).
 
 ## Description
 

README.md

@@ -27,8 +27,10 @@ The initial aim is to provide a single full-time position on REST framework.
 [![][posthog-img]][posthog-url]
 [![][cryptapi-img]][cryptapi-url]
 [![][fezto-img]][fezto-url]
+[![][svix-img]][svix-url]
+[![][zuplo-img]][zuplo-url]
 
-Many thanks to all our [wonderful sponsors][sponsors], and in particular to our premium backers, [Sentry][sentry-url], [Stream][stream-url], [Spacinov][spacinov-url], [Retool][retool-url], [bit.io][bitio-url], [PostHog][posthog-url], [CryptAPI][cryptapi-url], and [FEZTO][fezto-url].
+Many thanks to all our [wonderful sponsors][sponsors], and in particular to our premium backers, [Sentry][sentry-url], [Stream][stream-url], [Spacinov][spacinov-url], [Retool][retool-url], [bit.io][bitio-url], [PostHog][posthog-url], [CryptAPI][cryptapi-url], [FEZTO][fezto-url], [Svix][svix-url], and [Zuplo][zuplo-url].
 
 ---
 
@@ -38,14 +40,12 @@ Django REST framework is a powerful and flexible toolkit for building Web APIs.
 
 Some reasons you might want to use REST framework:
 
-* The [Web browsable API][sandbox] is a huge usability win for your developers.
+* The Web browsable API is a huge usability win for your developers.
 * [Authentication policies][authentication] including optional packages for [OAuth1a][oauth1-section] and [OAuth2][oauth2-section].
 * [Serialization][serializers] that supports both [ORM][modelserializer-section] and [non-ORM][serializer-section] data sources.
 * Customizable all the way down - just use [regular function-based views][functionview-section] if you don't need the [more][generic-views] [powerful][viewsets] [features][routers].
 * [Extensive documentation][docs], and [great community support][group].
 
-There is a live example API for testing purposes, [available here][sandbox].
-
 **Below**: *Screenshot from the browsable API*
 
 ![Screenshot][image]
@@ -54,8 +54,8 @@ There is a live example API for testing purposes, [available here][sandbox].
 
 # Requirements
 
-* Python 3.6+
-* Django 4.2, 4.1, 4.0, 3.2, 3.1, 3.0
+* Python 3.8+
+* Django 5.0, 4.2
 
 We **highly recommend** and only officially support the latest patch release of
 each Python and Django series.
@@ -173,8 +173,6 @@ Full documentation for the project is available at [https://www.django-rest-fram
 
 For questions and support, use the [REST framework discussion group][group], or `#restframework` on libera.chat IRC.
 
-You may also want to [follow the author on Twitter][twitter].
-
 # Security
 
 Please see the [security policy][security-policy].
@@ -185,9 +183,7 @@ Please see the [security policy][security-policy].
 [codecov]: https://codecov.io/github/encode/django-rest-framework?branch=master
 [pypi-version]: https://img.shields.io/pypi/v/djangorestframework.svg
 [pypi]: https://pypi.org/project/djangorestframework/
-[twitter]: https://twitter.com/starletdreaming
 [group]: https://groups.google.com/forum/?fromgroups#!forum/django-rest-framework
-[sandbox]: https://restframework.herokuapp.com/
 
 [funding]: https://fund.django-rest-framework.org/topics/funding/
 [sponsors]: https://fund.django-rest-framework.org/topics/funding/#our-sponsors
@@ -200,6 +196,8 @@ Please see the [security policy][security-policy].
 [posthog-img]: https://raw.githubusercontent.com/encode/django-rest-framework/master/docs/img/premium/posthog-readme.png
 [cryptapi-img]: https://raw.githubusercontent.com/encode/django-rest-framework/master/docs/img/premium/cryptapi-readme.png
 [fezto-img]: https://raw.githubusercontent.com/encode/django-rest-framework/master/docs/img/premium/fezto-readme.png
+[svix-img]: https://raw.githubusercontent.com/encode/django-rest-framework/master/docs/img/premium/svix-premium.png
+[zuplo-img]: https://raw.githubusercontent.com/encode/django-rest-framework/master/docs/img/premium/zuplo-readme.png
 
 [sentry-url]: https://getsentry.com/welcome/
 [stream-url]: https://getstream.io/?utm_source=DjangoRESTFramework&utm_medium=Webpage_Logo_Ad&utm_content=Developer&utm_campaign=DjangoRESTFramework_Jan2022_HomePage
@@ -209,6 +207,8 @@ Please see the [security policy][security-policy].
 [posthog-url]: https://posthog.com?utm_source=drf&utm_medium=sponsorship&utm_campaign=open-source-sponsorship
 [cryptapi-url]: https://cryptapi.io
 [fezto-url]: https://www.fezto.xyz/?utm_source=DjangoRESTFramework
+[svix-url]: https://www.svix.com/?utm_source=django-REST&utm_medium=sponsorship
+[zuplo-url]: https://zuplo.link/django-gh
 
 [oauth1-section]: https://www.django-rest-framework.org/api-guide/authentication/#django-rest-framework-oauth
 [oauth2-section]: https://www.django-rest-framework.org/api-guide/authentication/#django-oauth-toolkit

docs/api-guide/authentication.md

@@ -454,7 +454,7 @@ More information can be found in the [Documentation](https://django-rest-durin.r
 [basicauth]: https://tools.ietf.org/html/rfc2617
 [permission]: permissions.md
 [throttling]: throttling.md
-[csrf-ajax]: https://docs.djangoproject.com/en/stable/ref/csrf/#ajax
+[csrf-ajax]: https://docs.djangoproject.com/en/stable/howto/csrf/#using-csrf-protection-with-ajax
 [mod_wsgi_official]: https://modwsgi.readthedocs.io/en/develop/configuration-directives/WSGIPassAuthorization.html
 [django-oauth-toolkit-getting-started]: https://django-oauth-toolkit.readthedocs.io/en/latest/rest-framework/getting_started.html
 [django-rest-framework-oauth]: https://jpadilla.github.io/django-rest-framework-oauth/

docs/api-guide/caching.md

@@ -28,37 +28,60 @@ from rest_framework import viewsets
 
 class UserViewSet(viewsets.ViewSet):
     # With cookie: cache requested url for each user for 2 hours
-    @method_decorator(cache_page(60*60*2))
+    @method_decorator(cache_page(60 * 60 * 2))
     @method_decorator(vary_on_cookie)
     def list(self, request, format=None):
         content = {
-            'user_feed': request.user.get_user_feed()
+            "user_feed": request.user.get_user_feed(),
         }
         return Response(content)
 
 
 class ProfileView(APIView):
     # With auth: cache requested url for each user for 2 hours
-    @method_decorator(cache_page(60*60*2))
-    @method_decorator(vary_on_headers("Authorization",))
+    @method_decorator(cache_page(60 * 60 * 2))
+    @method_decorator(vary_on_headers("Authorization"))
     def get(self, request, format=None):
         content = {
-            'user_feed': request.user.get_user_feed()
+            "user_feed": request.user.get_user_feed(),
         }
         return Response(content)
 
 
 class PostView(APIView):
     # Cache page for the requested url
-    @method_decorator(cache_page(60*60*2))
+    @method_decorator(cache_page(60 * 60 * 2))
     def get(self, request, format=None):
         content = {
-            'title': 'Post title',
-            'body': 'Post content'
+            "title": "Post title",
+            "body": "Post content",
         }
         return Response(content)
 ```
 
+
+## Using cache with @api_view decorator
+
+When using @api_view decorator, the Django-provided method-based cache decorators such as [`cache_page`][page],
+[`vary_on_cookie`][cookie] and [`vary_on_headers`][headers] can be called directly.
+
+```python
+from django.views.decorators.cache import cache_page
+from django.views.decorators.vary import vary_on_cookie
+
+from rest_framework.decorators import api_view
+from rest_framework.response import Response
+
+
+@cache_page(60 * 15)
+@vary_on_cookie
+@api_view(["GET"])
+def get_user_list(request):
+    content = {"user_feed": request.user.get_user_feed()}
+    return Response(content)
+```
+
+
 **NOTE:** The [`cache_page`][page] decorator only caches the
 `GET` and `HEAD` responses with status 200.
 

docs/api-guide/fields.md

@@ -68,14 +68,6 @@ When serializing the instance, default will be used if the object attribute or d
 
 Note that setting a `default` value implies that the field is not required. Including both the `default` and `required` keyword arguments is invalid and will raise an error.
 
-Notes regarding default value propagation from model to serializer:
-
-All the default values from model will pass as default to the serializer and the options method.
-
-If the default is callable then it will be propagated to & evaluated every time in the serializer but not in options method.
-
-If the value for given field is not given then default value will be present in the serializer and available in serializer's methods. Specified validation on given field will be evaluated on default value as that field will be present in the serializer.
-
 ### `allow_null`
 
 Normally an error will be raised if `None` is passed to a serializer field. Set this keyword argument to `True` if `None` should be considered a valid value.
@@ -303,7 +295,7 @@ Corresponds to `django.db.models.fields.DecimalField`.
 * `min_value` Validate that the number provided is no less than this value.
 * `localize` Set to `True` to enable localization of input and output based on the current locale. This will also force `coerce_to_string` to `True`. Defaults to `False`. Note that data formatting is enabled if you have set `USE_L10N=True` in your settings file.
 * `rounding` Sets the rounding mode used when quantizing to the configured precision. Valid values are [`decimal` module rounding modes][python-decimal-rounding-modes]. Defaults to `None`.
-* `normalize_output` Will normalize the decimal value when serialized. This will strip all trailing zeroes and change the value's precision to the minimum required precision to be able to represent the value without loosing data. Defaults to `False`.
+* `normalize_output` Will normalize the decimal value when serialized. This will strip all trailing zeroes and change the value's precision to the minimum required precision to be able to represent the value without losing data. Defaults to `False`.
 
 #### Example usage
 

docs/api-guide/permissions.md

@@ -173,12 +173,11 @@ This permission is suitable if you want to your API to allow read permissions to
 
 This permission class ties into Django's standard `django.contrib.auth` [model permissions][contribauth].  This permission must only be applied to views that have a `.queryset` property or `get_queryset()` method. Authorization will only be granted if the user *is authenticated* and has the *relevant model permissions* assigned. The appropriate model is determined by checking `get_queryset().model` or `queryset.model`.
 
-* `GET` requests require the user to have the `view` or `change` permission on the model
 * `POST` requests require the user to have the `add` permission on the model.
 * `PUT` and `PATCH` requests require the user to have the `change` permission on the model.
 * `DELETE` requests require the user to have the `delete` permission on the model.
 
-The default behaviour can also be overridden to support custom model permissions.
+The default behavior can also be overridden to support custom model permissions.  For example, you might want to include a `view` model permission for `GET` requests.
 
 To use custom model permissions, override `DjangoModelPermissions` and set the `.perms_map` property.  Refer to the source code for details.
 

docs/api-guide/renderers.md

@@ -283,7 +283,7 @@ By default this will include the following keys: `view`, `request`, `response`,
 
 The following is an example plaintext renderer that will return a response with the `data` parameter as the content of the response.
 
-    from django.utils.encoding import smart_text
+    from django.utils.encoding import smart_str
     from rest_framework import renderers
 
 
@@ -292,7 +292,7 @@ The following is an example plaintext renderer that will return a response with
         format = 'txt'
 
         def render(self, data, accepted_media_type=None, renderer_context=None):
-            return smart_text(data, encoding=self.charset)
+            return smart_str(data, encoding=self.charset)
 
 ## Setting the character set