Merge branch 'main' into python-support-315

Author: p-r-a-v-i-n

.github/workflows/prepare-release.yml

@@ -119,12 +119,18 @@ jobs:
               f.write(content)
           EOF
 
+      - name: Install gettext
+        run: sudo apt install -y gettext
+
+      - name: Ensure translations are up to date
+        run: uv tool run --from django django-admin compilemessages
+
       - name: Create branch and commit
         run: |
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
           git checkout -b feat/release-${{ github.event.inputs.version }}
-          git add rest_framework/__init__.py docs/community/release-notes.md
+          git add rest_framework/__init__.py docs/community/release-notes.md rest_framework/locale
           git commit -m "Prepare release ${{ github.event.inputs.version }}"
           git push origin feat/release-${{ github.event.inputs.version }}
 

.pre-commit-config.yaml

@@ -9,7 +9,7 @@ repos:
   - id: check-symlinks
   - id: check-toml
 - repo: https://github.com/PyCQA/isort
-  rev: 7.0.0
+  rev: 9.0.1
   hooks:
   - id: isort
 - repo: https://github.com/PyCQA/flake8
@@ -28,7 +28,7 @@ repos:
     - black==26.1.0
 - repo: https://github.com/codespell-project/codespell
   # Configuration for codespell is in pyproject.toml
-  rev: v2.4.1
+  rev: v2.4.3
   hooks:
   - id: codespell
     additional_dependencies:
@@ -40,10 +40,10 @@ repos:
   - id: pyupgrade
     args: ["--py310-plus", "--keep-percent-format"]
 - repo: https://github.com/tox-dev/pyproject-fmt
-  rev: v2.11.1
+  rev: v2.29.4
   hooks:
   - id: pyproject-fmt
 - repo: https://github.com/adamchainz/django-upgrade
-  rev: 1.24.0
+  rev: 1.32.0
   hooks:
   - id: django-upgrade

docs/api-guide/fields.md

@@ -63,7 +63,7 @@ For example:
 
 When serializing the instance, default will be used if the object attribute or dictionary key is not present in the instance.
 
-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.
+Note that setting a `default` value implies that the field is not required. Combining `default` with `required=True` is invalid and will raise an error. An explicit `required=False` alongside `default` is allowed, but redundant.
 
 ### `allow_null`
 

docs/api-guide/pagination.md

@@ -369,7 +369,7 @@ The [`DRF-extensions` package][drf-extensions] includes a [`PaginateByMaxMixin`
 
 ### drf-proxy-pagination
 
-The [`drf-proxy-pagination` package][drf-proxy-pagination] includes a `ProxyPagination` class which allows to choose pagination class with a query parameter.
+The [`drf-proxy-pagination` package][drf-proxy-pagination] includes a `ProxyPagination` class which allows choosing the pagination class with a query parameter.
 
 ### link-header-pagination
 

docs/api-guide/serializers.md

@@ -159,7 +159,9 @@ When deserializing data, you always need to call `is_valid()` before attempting
 
 Each key in the dictionary will be the field name, and the values will be lists of strings of any error messages corresponding to that field.  The `non_field_errors` key may also be present, and will list any general validation errors. The name of the `non_field_errors` key may be customized using the `NON_FIELD_ERRORS_KEY` REST framework setting.
 
-When deserializing a list of items, errors will be returned as a list of dictionaries representing each of the deserialized items.
+When deserializing a list of items, errors are returned as a dictionary keyed by the indexes of invalid items. Valid items are omitted from the dictionary.
+
+To temporarily use the list-based format from versions before REST framework 3.18, set `LIST_SERIALIZER_ERRORS_AS_DICT` to `False`. This format includes an empty dictionary for each valid item and is deprecated. It will be removed in REST framework 3.20.
 
 #### Raising an exception on invalid data
 
@@ -559,6 +561,8 @@ This option should be a list or tuple of field names, and is declared as follows
 
 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.
 
+Please keep in mind that, if a field has already been explicitly declared on the serializer class (or a parent class), then the `read_only_fields` option will not apply to that field. Set `read_only=True` on the field itself instead.
+
 !!! note
     There is a special-case where a read-only field is part of a `unique_together` constraint at the model level. In this case the field is required by the serializer class in order to validate the constraint, but should also not be editable by the user.
 
@@ -591,7 +595,7 @@ This option is a dictionary, mapping field names to a dictionary of keyword argu
             user.save()
             return user
 
-Please keep in mind that, if the field has already been explicitly declared on the serializer class, then the `extra_kwargs` option will be ignored.
+Please keep in mind that, if the field has already been explicitly declared on the serializer class, then the `extra_kwargs` option will be ignored. The same is true of `read_only_fields`, which is implemented using `extra_kwargs`.
 
 ### Relational fields
 
@@ -852,6 +856,30 @@ Here's an example of how you might choose to implement multiple updates:
         class Meta:
             list_serializer_class = BookListSerializer
 
+If the child serializer includes uniqueness validators (`UniqueValidator`, `UniqueTogetherValidator`, or the
+`UniqueForDateValidator` family), they need to know which object each item in the list is updating, so
+that the object itself is not reported as a uniqueness conflict. By default the child serializer's
+`.instance` is the whole queryset or list that was passed to the list serializer, so these validators will
+raise a `RuntimeError` during a multiple update. To support this, override `run_child_validation()` on
+your `ListSerializer` subclass to set the child's `.instance` and `.initial_data` for each item before
+validation. For example, if `self.instance` is a queryset:
+
+    class BookListSerializer(serializers.ListSerializer):
+        def run_child_validation(self, data):
+            # `.instance` stays `None` for items that do not exist yet, and
+            # for malformed items, which child validation will then reject
+            # as usual.
+            self.child.instance = None
+            try:
+                self.child.instance = self.instance.filter(pk=data['id']).first()
+            except (TypeError, KeyError, ValueError):
+                pass
+            self.child.initial_data = data
+            return super().run_child_validation(data)
+
+        def update(self, instance, validated_data):
+            ...
+
 ### Customizing ListSerializer initialization
 
 When a serializer with `many=True` is instantiated, we need to determine which arguments and keyword arguments should be passed to the `.__init__()` method for both the child `Serializer` class, and for the parent `ListSerializer` class.
@@ -1190,7 +1218,7 @@ The [html-json-forms][html-json-forms] package provides an algorithm and seriali
 
 ### DRF Writable Nested
 
-The [drf-writable-nested][drf-writable-nested] package provides writable nested model serializer which allows to create/update models with nested related data.
+The [drf-writable-nested][drf-writable-nested] package provides writable nested model serializer which allows creating/updating models with nested related data.
 
 ### DRF Encrypt Content
 

docs/api-guide/settings.md

@@ -462,6 +462,16 @@ A string representing the key that should be used for serializer errors that do
 
 Default: `'non_field_errors'`
 
+#### LIST_SERIALIZER_ERRORS_AS_DICT
+
+Controls the format of per-item validation errors produced by `ListSerializer`, including serializers instantiated with `many=True`.
+
+When set to `True`, errors are returned as a dictionary keyed by the indexes of invalid items. Valid items are omitted from the dictionary. This format was introduced in REST framework 3.18.0.
+
+When set to `False`, errors are returned in the list-based format used before REST framework 3.18, with one entry for each input item and an empty dictionary for each valid item. This format is deprecated and will be removed in REST framework 3.20.
+
+Default: `True`
+
 #### URL_FIELD_NAME
 
 A string representing the key that should be used for the URL fields generated by `HyperlinkedModelSerializer`.

docs/api-guide/validators.md

@@ -102,7 +102,7 @@ The validator should be applied to *serializer classes*, like so:
             ]
 
 !!! note
-    The `UniqueTogetherValidator` class always imposes an implicit constraint that all the fields it applies to are always treated as required. Fields with `default` values are an exception to this as they always supply a value even when omitted from user input.
+    The `UniqueTogetherValidator` class always imposes an implicit constraint that all the fields it applies to are always treated as required. Fields with `default` values are an exception to this as they always supply a value even when omitted from user input. When using `ModelSerializer`, model fields with `null=True` default to `None`, and `CharField` or `TextField` model fields with `blank=True` default to an empty string, so these are not treated as required either.
 
 ## UniqueForDateValidator
 
@@ -222,6 +222,28 @@ For example:
             extra_kwargs = {'client': {'required': False}}
             validators = []  # Remove a default "unique together" constraint.
 
+### UniqueConstraint with conditions
+
+When using Django's `UniqueConstraint` with conditions that reference other model fields, DRF will automatically use
+`UniqueTogetherValidator` instead of field-level `UniqueValidator`. This ensures proper validation behavior when the constraint
+effectively involves multiple fields.
+
+For example, a single-field constraint with a condition becomes a multi-field validation when the condition references other fields.
+
+    class MyModel(models.Model):
+        name = models.CharField(max_length=100)
+        status = models.CharField(max_length=20)
+
+        class Meta:
+            constraints = [
+                models.UniqueConstraint(
+                    fields=['name'],
+                    condition=models.Q(status='active'),
+                    name='unique_active_name'
+                )
+            ]
+
+
 ### Updating nested serializers
 
 When applying an update to an existing instance, uniqueness validators will

docs/community/contributing.md

@@ -160,6 +160,52 @@ Once you've made a pull request take a look at the build status in the GitHub in
 
 Sometimes, in order to ensure your code works on various different versions of Django, Python or third party libraries, you'll need to run slightly different code depending on the environment.  Any code that branches in this way should be isolated into the `compat.py` module, and should provide a single common interface that the rest of the codebase can use.
 
+### Deprecating a feature
+
+REST framework follows a formal [deprecation policy][deprecation-policy]: a feature deprecated during the development of `3.X` keeps working until `3.X+2` removes it. In practice this means that a pull request that deprecates something should not change any behavior, only warn about the change to come.
+
+The warning classes live in `rest_framework/deprecation.py`, and are named after the release that removes the feature. For example, during the development of 3.0 you'll find:
+
+* `RemovedInDRF31Warning`, a `DeprecationWarning`, aliased as `RemovedInNextDRFVersionWarning`. Features flagged with it were deprecated one cycle ago, and are removed in the next release.
+* `RemovedInDRF32Warning`, a `PendingDeprecationWarning`, aliased as `RemovedAfterNextDRFVersionWarning`. This is the class **new deprecations** should use.
+
+To deprecate a feature:
+
+1. Keep the existing behavior working, and raise the pending deprecation warning from the deprecated code path. Refer to the warning class by its concrete name rather than the alias, so that it's easy to grep for everything that has to go when the removal comes around.
+
+    ```python
+    import warnings
+
+    from rest_framework.deprecation import RemovedInDRF32Warning
+
+    warnings.warn(
+        "The `foo` argument is deprecated and will be removed in DRF 3.2. "
+        "Use `bar` instead.",
+        RemovedInDRF32Warning,
+        stacklevel=2,
+    )
+    ```
+
+    The message should say what is deprecated, which release removes it, and what to use instead. Pick a `stacklevel` that points the warning at the user's code rather than at REST framework internals.
+
+2. If the deprecation can be worked around ahead of time, consider adding a setting that opts into the new behavior early, and mention it in the warning message.
+
+3. Add a test asserting that the warning is raised, and update the existing tests of the old behavior to expect it:
+
+    ```python
+    with pytest.warns(RemovedInDRF32Warning, match="Use `bar` instead"):
+        ...
+    ```
+
+4. Update the documentation for the feature, flagging the deprecation with an admonition:
+
+    ```
+    !!! warning
+        The `foo` argument is deprecated and will be removed in DRF 3.2. Use `bar` instead.
+    ```
+
+Removing a deprecated feature is the mirror image, and happens as part of the release process. When 3.1 is released, everything raising a `RemovedInDRF31Warning` is deleted, along with the class itself and the documentation of the deprecated behavior, `RemovedInDRF32Warning` is escalated to subclass `DeprecationWarning`, a fresh `RemovedInDRF33Warning` is added for the next cycle's deprecations, and the two aliases are moved on to point at them.
+
 ## Documentation
 
 The documentation for REST framework is built from the [Markdown][markdown] source files in [the docs directory][docs].
@@ -244,3 +290,4 @@ The documentation theme styles `info`, `warning`, `tip` and `danger` admonition
 [repo]: https://github.com/encode/django-rest-framework
 [how-to-fork]: https://help.github.com/articles/fork-a-repo/
 [admonition]: https://python-markdown.github.io/extensions/admonition/
+[deprecation-policy]: release-notes.md#deprecation-policy

docs/community/project-management.md

@@ -58,7 +58,8 @@ Our PyPI releases is automated in GitHub actions on tag pushes. The following te
     - `pyproject.toml` Python & Django version trove classifiers
     - `README` Python & Django versions
     - `docs` Python & Django versions
-- Ensure the pull request increments the version to `*.*.*` in [`restframework/__init__.py`](https://github.com/encode/django-rest-framework/blob/main/rest_framework/__init__.py).
+- Ensure the pull request increments the version to `*.*.*` in [`rest_framework/__init__.py`](https://github.com/encode/django-rest-framework/blob/main/rest_framework/__init__.py).
+- Ensure the deprecation warnings in [`rest_framework/deprecation.py`](https://github.com/encode/django-rest-framework/blob/main/rest_framework/deprecation.py) have been rotated for the release, following the [deprecation policy](release-notes.md#deprecation-policy).
 - Ensure documentation validates
     - Build and serve docs `mkdocs serve`
     - Validate links `pylinkvalidate.py -P http://127.0.0.1:8000`

docs/community/release-notes.md

@@ -22,8 +22,29 @@ The timeline for deprecation of a feature present in version 1.0 would work as f
 
 * Version 1.3 would remove the deprecated bits of API entirely.
 
+Two aliases always point at the warning classes for the current release cycle, so you can refer to them without updating your configuration on every release:
+
+* `RemovedInNextDRFVersionWarning` — features that the next feature release removes. Always a `DeprecationWarning`.
+* `RemovedAfterNextDRFVersionWarning` — features that the release after next removes. Always a `PendingDeprecationWarning`.
+
 Note that in line with Django's policy, any parts of the framework not mentioned in the documentation should generally be considered private API, and may be subject to change.
 
+### Surfacing deprecations in your test suite
+
+Deprecations are much easier to deal with one release at a time, so it's worth failing your test suite on anything that is due to be removed in the next release, while keeping the earlier warnings visible.
+
+If you run your tests with pytest, add the following to your `pyproject.toml`:
+
+```toml
+[tool.pytest]
+filterwarnings = [
+  "error::rest_framework.deprecation.RemovedInNextDRFVersionWarning",
+  "always::rest_framework.deprecation.RemovedAfterNextDRFVersionWarning",
+]
+```
+
+When a warning does fire, the message names the release that removes the feature and what to use instead. Once you have dealt with them all, drop the `always` filter down to `error` too, and you'll be ready for the release after next as well.
+
 ## Upgrading
 
 To upgrade Django REST framework to the latest version, use pip:
@@ -38,6 +59,31 @@ You can determine your currently installed version using `pip show`:
 
 ## 3.18.x series
 
+### 3.18.1
+
+**Date**: 7th September 2026
+
+#### Bug fixes
+
+* Fix duplicate validation errors for GenericIPAddressField with protocol by [@browniebroke](https://github.com/browniebroke) in [#10011](https://github.com/encode/django-rest-framework/pull/10011)
+* Fix int64 format detection for negative `IntegerField` minimums in OpenAPI schema definition by [@zainnadeem786](https://github.com/zainnadeem786) in [#9989](https://github.com/encode/django-rest-framework/pull/9989)
+* Fix list serializer on unique constraint validator by [@MehrazRumman](https://github.com/MehrazRumman) in [#10033](https://github.com/encode/django-rest-framework/pull/10033)
+* Reject non-finite values (nan, inf) in FloatField by [@winklemad](https://github.com/winklemad) in [#9998](https://github.com/encode/django-rest-framework/pull/9998)
+
+#### Other changes
+
+* Add a compatibility setting for `ListSerializer` error formats by [@Kub-AT](https://github.com/Kub-AT) in [#10027](https://github.com/encode/django-rest-framework/pull/10027)
+* Expand deprecation classes and review deprecation policy by [@browniebroke](https://github.com/browniebroke) in [#10034](https://github.com/encode/django-rest-framework/pull/10034)
+
+#### New Contributors
+
+* [@abidaliamanat9](https://github.com/abidaliamanat9) made their first contribution in [#10028](https://github.com/encode/django-rest-framework/pull/10028)
+* [@epuronta](https://github.com/epuronta) made their first contribution in [#10030](https://github.com/encode/django-rest-framework/pull/10030)
+* [@Kub-AT](https://github.com/Kub-AT) made their first contribution in [#10027](https://github.com/encode/django-rest-framework/pull/10027)
+* [@winklemad](https://github.com/winklemad) made their first contribution in [#9998](https://github.com/encode/django-rest-framework/pull/9998)
+
+**Full Changelog**: [3.18.0...3.18.1](https://github.com/encode/django-rest-framework/compare/3.18.0...3.18.1)
+
 ### 3.18.0
 
 **Date**: 7th August 2026