Merge branch 'main' into fix/nulls-distinct-validator-8409

Author: mag123c

.pre-commit-config.yaml

@@ -24,7 +24,7 @@ repos:
   hooks:
   - id: blacken-docs
     additional_dependencies:
-    - black==25.9.0
+    - black==26.1.0
 - repo: https://github.com/codespell-project/codespell
   # Configuration for codespell is in pyproject.toml
   rev: v2.4.1
@@ -34,11 +34,11 @@ repos:
       # python doesn't come with a toml parser prior to 3.11
       - "tomli; python_version < '3.11'"
 - repo: https://github.com/asottile/pyupgrade
-  rev: v3.21.0
+  rev: v3.21.2
   hooks:
   - id: pyupgrade
     args: ["--py310-plus", "--keep-percent-format"]
 - repo: https://github.com/tox-dev/pyproject-fmt
-  rev: v2.11.0
+  rev: v2.11.1
   hooks:
   - id: pyproject-fmt

docs/api-guide/permissions.md

@@ -138,7 +138,10 @@ Provided they inherit from `rest_framework.permissions.BasePermission`, permissi
             return Response(content)
 
 !!! note
-    Composition of permissions supports `&` (and), `|` (or) and `~` (not) operators.
+    Composition of permissions supports the `&` (and), `|` (or) and `~` (not) operators, and also allows the use of brackets `(` `)` to group expressions.
+
+    Operators follow the same precedence and associativity rules as standard logical operators (`~` highest, then `&`, then `|`).
+
 
 # API Reference
 

docs/index.md

@@ -69,7 +69,7 @@ each Python and Django series.
 
 The following packages are optional:
 
-* [PyYAML][pyyaml], [uritemplate][uriteemplate] (5.1+, 3.0.0+) - Schema generation support.
+* [PyYAML][pyyaml], [uritemplate][uritemplate] (5.1+, 3.0.0+) - Schema generation support.
 * [Markdown][markdown] (3.3.0+) - Markdown support for the browsable API.
 * [Pygments][pygments] (2.7.0+) - Add syntax highlighting to Markdown processing.
 * [django-filter][django-filter] (1.0.1+) - Filtering support.
@@ -207,7 +207,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 [heroku]: https://www.heroku.com/
 [eventbrite]: https://www.eventbrite.co.uk/about/
 [pyyaml]: https://pypi.org/project/PyYAML/
-[uriteemplate]: https://pypi.org/project/uritemplate/
+[uritemplate]: https://pypi.org/project/uritemplate/
 [markdown]: https://pypi.org/project/Markdown/
 [pygments]: https://pypi.org/project/Pygments/
 [django-filter]: https://pypi.org/project/django-filter/

docs/topics/documenting-your-api.md

@@ -4,10 +4,11 @@
 >
 > — Roy Fielding, [REST APIs must be hypertext driven][cite]
 
-REST framework provides a range of different choices for documenting your API. The following
-is a non-exhaustive list of the most popular ones.
+REST framework provides a range of different choices for documenting your API. The following is a non-exhaustive list of some of the most popular options.
 
-## Third party packages for OpenAPI support
+## Third-party packages for OpenAPI support
+
+REST framework recommends using third-party packages for generating and presenting OpenAPI schemas, as they provide more features and flexibility than the built-in (deprecated) implementation.
 
 ### drf-spectacular
 
@@ -37,9 +38,9 @@ This also translates into a very useful interactive documentation viewer in the
 
 ## Built-in OpenAPI schema generation (deprecated)
 
-**Deprecation notice: REST framework's built-in support for generating OpenAPI schemas is
-deprecated in favor of 3rd party packages that can provide this functionality instead.
-As replacement, we recommend using the [drf-spectacular](#drf-spectacular) package.**
+!!! warning
+    **Deprecation notice:** REST framework's built-in support for generating OpenAPI schemas is deprecated in favor of third-party packages that provide this functionality instead. As a replacement, we recommend using **drf-spectacular**.
+
 
 There are a number of packages available that allow you to generate HTML
 documentation pages from OpenAPI schemas.