Merge branch 'main' into issue-5363

Author: browniebroke

.pre-commit-config.yaml

@@ -1,47 +1,49 @@
 repos:
 - repo: https://github.com/pre-commit/pre-commit-hooks
-  rev: v4.5.0
+  rev: v6.0.0
   hooks:
   - id: check-added-large-files
   - id: check-case-conflict
   - id: check-json
   - id: check-merge-conflict
   - id: check-symlinks
   - id: check-toml
-- repo: https://github.com/pycqa/isort
-  rev: 5.13.2
+- repo: https://github.com/PyCQA/isort
+  rev: 7.0.0
   hooks:
   - id: isort
 - repo: https://github.com/PyCQA/flake8
-  rev: 7.0.0
+  rev: 7.3.0
   hooks:
   - id: flake8
     additional_dependencies:
     - flake8-tidy-imports
 - repo: https://github.com/adamchainz/blacken-docs
-  rev: 1.16.0
+  rev: 1.20.0
   hooks:
   - id: blacken-docs
-    exclude: ^(?!docs).*$
     additional_dependencies:
-    - black==23.1.0
+    - black==25.9.0
 - repo: https://github.com/codespell-project/codespell
   # Configuration for codespell is in .codespellrc
-  rev: v2.2.6
+  rev: v2.4.1
   hooks:
   - id: codespell
+    args: [
+            "--builtin", "clear,rare,code,names,en-GB_to_en-US",
+            "--ignore-words", "codespell-ignore-words.txt",
+            "--skip", "*.css",
+          ]
     exclude: locale|kickstarter-announcement.md|coreapi-0.1.1.js
     additional_dependencies:
       # 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.19.1
+  rev: v3.21.0
   hooks:
   - id: pyupgrade
-    args: ["--py39-plus", "--keep-percent-format"]
-
+    args: ["--py310-plus", "--keep-percent-format"]
 - repo: https://github.com/tox-dev/pyproject-fmt
-  rev: v2.6.0
+  rev: v2.11.0
   hooks:
   - id: pyproject-fmt

README.md

@@ -67,10 +67,11 @@ Install using `pip`...
     pip install djangorestframework
 
 Add `'rest_framework'` to your `INSTALLED_APPS` setting.
+
 ```python
 INSTALLED_APPS = [
-    ...
-    'rest_framework',
+    # ...
+    "rest_framework",
 ]
 ```
 
@@ -99,7 +100,7 @@ from rest_framework import routers, serializers, viewsets
 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.
@@ -110,13 +111,13 @@ class UserViewSet(viewsets.ModelViewSet):
 
 # Routers provide a way of automatically determining the URL conf.
 router = routers.DefaultRouter()
-router.register(r'users', UserViewSet)
+router.register(r"users", UserViewSet)
 
 # Wire up our API using automatic URL routing.
 # Additionally, we include login URLs for the browsable API.
 urlpatterns = [
-    path('', include(router.urls)),
-    path('api-auth/', include('rest_framework.urls', namespace='rest_framework')),
+    path("", include(router.urls)),
+    path("api-auth/", include("rest_framework.urls", namespace="rest_framework")),
 ]
 ```
 
@@ -126,15 +127,15 @@ Add the following to your `settings.py` module:
 
 ```python
 INSTALLED_APPS = [
-    ...  # Make sure to include the default installed apps here.
-    'rest_framework',
+    # ... make sure to include the default installed apps here.
+    "rest_framework",
 ]
 
 REST_FRAMEWORK = {
     # Use Django's standard `django.contrib.auth` permissions,
     # or allow read-only access for unauthenticated users.
-    'DEFAULT_PERMISSION_CLASSES': [
-        'rest_framework.permissions.DjangoModelPermissionsOrAnonReadOnly',
+    "DEFAULT_PERMISSION_CLASSES": [
+        "rest_framework.permissions.DjangoModelPermissionsOrAnonReadOnly",
     ]
 }
 ```

codespell-ignore-words.txt

@@ -0,0 +1,6 @@
+Tim
+assertIn
+IAM
+endcode
+deque
+thead

docs/api-guide/authentication.md

@@ -416,7 +416,7 @@ JSON Web Token is a fairly new standard which can be used for token-based authen
 
 ## Hawk HTTP Authentication
 
-The [HawkREST][hawkrest] library builds on the [Mohawk][mohawk] library to let you work with [Hawk][hawk] signed requests and responses in your API. [Hawk][hawk] lets two parties securely communicate with each other using messages signed by a shared key. It is based on [HTTP MAC access authentication][mac] (which was based on parts of [OAuth 1.0][oauth-1.0a]).
+The [HawkREST][hawkrest] library builds on the [Mohawk][mohawk] library to let you work with [Hawk][hawk] signed requests and responses in your API. [Hawk][hawk] let's two parties securely communicate with each other using messages signed by a shared key. It is based on [HTTP MAC access authentication][mac] (which was based on parts of [OAuth 1.0][oauth-1.0a]).
 
 ## HTTP Signature Authentication
 
@@ -426,6 +426,11 @@ HTTP Signature (currently a [IETF draft][http-signature-ietf-draft]) provides a
 
 [Djoser][djoser] library provides a set of views to handle basic actions such as registration, login, logout, password reset and account activation. The package works with a custom user model and uses token-based authentication. This is a ready to use REST implementation of the Django authentication system.
 
+## DRF Auth Kit
+
+[DRF Auth Kit][drf-auth-kit] library provides a modern REST authentication solution with JWT cookies, social login, multi-factor authentication, and comprehensive user management. The package offers full type safety, automatic OpenAPI schema generation with DRF Spectacular. It supports multiple authentication types (JWT, DRF Token, or Custom) and includes built-in internationalization for 50+ languages.
+
+
 ## django-rest-auth / dj-rest-auth
 
 This library provides a set of REST API endpoints for registration, authentication (including social media authentication), password reset, retrieve and update user details, etc. By having these API endpoints, your client apps such as AngularJS, iOS, Android, and others can communicate to your Django backend site independently via REST APIs for user management.
@@ -454,7 +459,7 @@ There are currently two forks of this project.
 
 More information can be found in the [Documentation](https://django-rest-durin.readthedocs.io/en/latest/index.html).
 
-## django-pyoidc
+## django-pyoidc
 
 [dango-pyoidc][django_pyoidc] adds support for OpenID Connect (OIDC) authentication. This allows you to delegate user management to an Identity Provider, which can be used to implement Single-Sign-On (SSO). It provides support for most uses-cases, such as customizing how token info are mapped to user models, using OIDC audiences for access control, etc.
 
@@ -497,4 +502,5 @@ More information can be found in the [Documentation](https://django-pyoidc.readt
 [django-rest-authemail]: https://github.com/celiao/django-rest-authemail
 [django-rest-durin]: https://github.com/eshaan7/django-rest-durin
 [login-required-middleware]: https://docs.djangoproject.com/en/stable/ref/middleware/#django.contrib.auth.middleware.LoginRequiredMiddleware
-[django-pyoidc] : https://github.com/makinacorpus/django_pyoidc
+[django-pyoidc]: https://github.com/makinacorpus/django_pyoidc
+[drf-auth-kit]: https://github.com/huynguyengl99/drf-auth-kit

docs/api-guide/fields.md

@@ -180,7 +180,7 @@ The `allow_null` option is also available for string fields, although its usage
 
 ## EmailField
 
-A text representation, validates the text to be a valid e-mail address.
+A text representation, validates the text to be a valid email address.
 
 Corresponds to `django.db.models.fields.EmailField`
 
@@ -762,7 +762,7 @@ suitable for updating our target object. With `source='*'`, the return from
                      ('y_coordinate', 4),
                      ('x_coordinate', 3)])
 
-For completeness lets do the same thing again but with the nested serializer
+For completeness let's do the same thing again but with the nested serializer
 approach suggested above:
 
     class NestedCoordinateSerializer(serializers.Serializer):

docs/api-guide/generic-views.md

@@ -102,6 +102,39 @@ For example:
 
 ---
 
+### Avoiding N+1 Queries
+
+When listing objects (e.g. using `ListAPIView` or `ModelViewSet`), serializers may trigger an N+1 query pattern if related objects are accessed individually for each item.
+
+To prevent this, optimize the queryset in `get_queryset()` or by setting the `queryset` class attribute using [`select_related()`](https://docs.djangoproject.com/en/stable/ref/models/querysets/#select-related) and [`prefetch_related()`](https://docs.djangoproject.com/en/stable/ref/models/querysets/#prefetch-related), depending on the type of relationship.
+
+**For ForeignKey and OneToOneField**:
+
+Use `select_related()` to fetch related objects in the same query:
+
+    def get_queryset(self):
+        return Order.objects.select_related("customer", "billing_address")
+
+**For reverse and many-to-many relationships**:
+
+Use `prefetch_related()` to efficiently load collections of related objects:
+
+    def get_queryset(self):
+        return Book.objects.prefetch_related("categories", "reviews__user")
+
+**Combining both**:
+
+    def get_queryset(self):
+        return (
+            Order.objects
+            .select_related("customer")
+            .prefetch_related("items__product")
+        )
+
+These optimizations reduce repeated database access and improve list view performance.
+
+---
+
 #### `get_object(self)`
 
 Returns an object instance that should be used for detail views.  Defaults to using the `lookup_field` parameter to filter the base queryset.

docs/api-guide/metadata.md

@@ -66,7 +66,7 @@ The REST framework package only includes a single metadata class implementation,
 
 ## Creating schema endpoints
 
-If you have specific requirements for creating schema endpoints that are accessed with regular `GET` requests, you might consider re-using the metadata API for doing so.
+If you have specific requirements for creating schema endpoints that are accessed with regular `GET` requests, you might consider reusing the metadata API for doing so.
 
 For example, the following additional route could be used on a viewset to provide a linkable schema endpoint.
 

docs/api-guide/pagination.md

@@ -108,7 +108,7 @@ To set these attributes you should override the `PageNumberPagination` class, an
 * `page_query_param` - A string value indicating the name of the query parameter to use for the pagination control.
 * `page_size_query_param` - If set, this is a string value indicating the name of a query parameter that allows the client to set the page size on a per-request basis. Defaults to `None`, indicating that the client may not control the requested page size.
 * `max_page_size` - If set, this is a numeric value indicating the maximum allowable requested page size. This attribute is only valid if `page_size_query_param` is also set.
-* `last_page_strings` - A list or tuple of string values indicating values that may be used with the `page_query_param` to request the final page in the set. Defaults to `('last',)`
+* `last_page_strings` - A list or tuple of string values indicating values that may be used with the `page_query_param` to request the final page in the set. Defaults to `('last',)`. For example, use `?page=last` to go directly to the last page.
 * `template` - The name of a template to use when rendering pagination controls in the browsable API. May be overridden to modify the rendering style, or set to `None` to disable HTML pagination controls completely. Defaults to `"rest_framework/pagination/numbers.html"`.
 
 ---

docs/api-guide/relations.md

@@ -300,7 +300,7 @@ For example, the following serializer:
 
 Would serialize to a nested representation like this:
 
-    >>> album = Album.objects.create(album_name="The Grey Album", artist='Danger Mouse')
+    >>> album = Album.objects.create(album_name="The Gray Album", artist='Danger Mouse')
     >>> Track.objects.create(album=album, order=1, title='Public Service Announcement', duration=245)
     <Track: Track object>
     >>> Track.objects.create(album=album, order=2, title='What More Can I Say', duration=264)
@@ -310,7 +310,7 @@ Would serialize to a nested representation like this:
     >>> serializer = AlbumSerializer(instance=album)
     >>> serializer.data
     {
-        'album_name': 'The Grey Album',
+        'album_name': 'The Gray Album',
         'artist': 'Danger Mouse',
         'tracks': [
             {'order': 1, 'title': 'Public Service Announcement', 'duration': 245},
@@ -344,7 +344,7 @@ By default nested serializers are read-only. If you want to support write-operat
             return album
 
     >>> data = {
-        'album_name': 'The Grey Album',
+        'album_name': 'The Gray Album',
         'artist': 'Danger Mouse',
         'tracks': [
             {'order': 1, 'title': 'Public Service Announcement', 'duration': 245},

docs/api-guide/renderers.md

@@ -134,7 +134,7 @@ An example of a view that uses `TemplateHTMLRenderer`:
 
 You can use `TemplateHTMLRenderer` either to return regular HTML pages using REST framework, or to return both HTML and API responses from a single endpoint.
 
-If you're building websites that use `TemplateHTMLRenderer` along with other renderer classes, you should consider listing `TemplateHTMLRenderer` as the first class in the `renderer_classes` list, so that it will be prioritised first even for browsers that send poorly formed `ACCEPT:` headers.
+If you're building websites that use `TemplateHTMLRenderer` along with other renderer classes, you should consider listing `TemplateHTMLRenderer` as the first class in the `renderer_classes` list, so that it will be prioritized first even for browsers that send poorly formed `ACCEPT:` headers.
 
 See the [_HTML & Forms_ Topic Page][html-and-forms] for further examples of `TemplateHTMLRenderer` usage.