Merge branch 'main' into master

Author: auvipy

.github/dependabot.yml

@@ -11,3 +11,5 @@ updates:
           - "*"  # Group all Action updates into a single larger pull request
     schedule:
       interval: weekly
+    cooldown:
+      default-days: 7

.github/workflows/main.yml

@@ -6,6 +6,10 @@ on:
     - main
   pull_request:
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   tests:
     name: Python ${{ matrix.python-version }}
@@ -28,7 +32,6 @@ jobs:
         python-version: ${{ matrix.python-version }}
         allow-prereleases: true
         cache: 'pip'
-        cache-dependency-path: 'requirements/*.txt'
 
     - name: Upgrade packaging tools
       run: python -m pip install --upgrade pip setuptools virtualenv wheel
@@ -60,7 +63,7 @@ jobs:
         python-version: '3.13'
 
     - name: Install dependencies
-      run: pip install -r requirements/requirements-documentation.txt
+      run: pip install --group docs
 
     # Start mkdocs server and wait for it to be ready
     - run: mkdocs serve &

.github/workflows/mkdocs-deploy.yml

@@ -7,7 +7,7 @@ on:
     paths:
       - docs/**
       - docs_theme/**
-      - requirements/requirements-documentation.txt
+      - pyproject.toml
       - mkdocs.yml
       - .github/workflows/mkdocs-deploy.yml
 
@@ -25,5 +25,5 @@ jobs:
       - uses: actions/setup-python@v6
         with:
           python-version: 3.x
-      - run: pip install -r requirements/requirements-documentation.txt
+      - run: pip install --group docs
       - run: mkdocs gh-deploy

docs/api-guide/authentication.md

@@ -19,13 +19,10 @@ The `request.user` property will typically be set to an instance of the `contrib
 
 The `request.auth` property is used for any additional authentication information, for example, it may be used to represent an authentication token that the request was signed with.
 
----
-
-**Note:** Don't forget that **authentication by itself won't allow or disallow an incoming request**, it simply identifies the credentials that the request was made with.
+!!! note
+    Don't forget that **authentication by itself won't allow or disallow an incoming request**, it simply identifies the credentials that the request was made with.
 
-For information on how to set up the permission policies for your API please see the [permissions documentation][permission].
-
----
+    For information on how to set up the permission policies for your API please see the [permissions documentation][permission].
 
 ## How authentication is determined
 
@@ -122,17 +119,15 @@ Unauthenticated responses that are denied permission will result in an `HTTP 401
 
     WWW-Authenticate: Basic realm="api"
 
-**Note:** If you use `BasicAuthentication` in production you must ensure that your API is only available over `https`.  You should also ensure that your API clients will always re-request the username and password at login, and will never store those details to persistent storage.
+!!! note
+    If you use `BasicAuthentication` in production you must ensure that your API is only available over `https`.  You should also ensure that your API clients will always re-request the username and password at login, and will never store those details to persistent storage.
 
 ## TokenAuthentication
 
----
-
-**Note:** The token authentication provided by Django REST framework is a fairly simple implementation.
+!!! note
+    The token authentication provided by Django REST framework is a fairly simple implementation.
 
-For an implementation which allows more than one token per user, has some tighter security implementation details, and supports token expiry, please see the [Django REST Knox][django-rest-knox] third party package.
-
----
+    For an implementation which allows more than one token per user, has some tighter security implementation details, and supports token expiry, please see the [Django REST Knox][django-rest-knox] third party package.
 
 This authentication scheme uses a simple token-based HTTP Authentication scheme.  Token authentication is appropriate for client-server setups, such as native desktop and mobile clients.
 
@@ -173,11 +168,8 @@ The `curl` command line tool may be useful for testing token authenticated APIs.
 
     curl -X GET http://127.0.0.1:8000/api/example/ -H 'Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b'
 
----
-
-**Note:** If you use `TokenAuthentication` in production you must ensure that your API is only available over `https`.
-
----
+!!! note
+    If you use `TokenAuthentication` in production you must ensure that your API is only available over `https`.
 
 ### Generating Tokens
 
@@ -293,7 +285,8 @@ Unauthenticated responses that are denied permission will result in an `HTTP 403
 
 If you're using an AJAX-style API with SessionAuthentication, you'll need to make sure you include a valid CSRF token for any "unsafe" HTTP method calls, such as `PUT`, `PATCH`, `POST` or `DELETE` requests.  See the [Django CSRF documentation][csrf-ajax] for more details.
 
-**Warning**: Always use Django's standard login view when creating login pages. This will ensure your login views are properly protected.
+!!! warning
+    Always use Django's standard login view when creating login pages. This will ensure your login views are properly protected.
 
 CSRF validation in REST framework works slightly differently from standard Django due to the need to support both session and non-session based authentication to the same views. This means that only authenticated requests require CSRF tokens, and anonymous requests may be sent without CSRF tokens. This behavior is not suitable for login views, which should always have CSRF validation applied.
 
@@ -334,11 +327,8 @@ You *may* also override the `.authenticate_header(self, request)` method.  If im
 
 If the `.authenticate_header()` method is not overridden, the authentication scheme will return `HTTP 403 Forbidden` responses when an unauthenticated request is denied access.
 
----
-
-**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.
-
----
+!!! 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
 
@@ -461,7 +451,7 @@ More information can be found in the [Documentation](https://django-rest-durin.r
 
 ## 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.
+[django_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.
 
 More information can be found in the [Documentation](https://django-pyoidc.readthedocs.io/latest/index.html).
 

docs/api-guide/caching.md

@@ -82,8 +82,8 @@ def get_user_list(request):
 ```
 
 
-**NOTE:** The [`cache_page`][page] decorator only caches the
-`GET` and `HEAD` responses with status 200.
+!!! note
+    The [`cache_page`][page] decorator only caches the `GET` and `HEAD` responses with status 200.
 
 [page]: https://docs.djangoproject.com/en/stable/topics/cache/#the-per-view-cache
 [cookie]: https://docs.djangoproject.com/en/stable/topics/http/decorators/#django.views.decorators.vary.vary_on_cookie

docs/api-guide/content-negotiation.md

@@ -34,13 +34,11 @@ If the requested view was only configured with renderers for `YAML` and `HTML`,
 
 For more information on the `HTTP Accept` header, see [RFC 2616][accept-header]
 
----
-
-**Note**: "q" values are not taken into account by REST framework when determining preference.  The use of "q" values negatively impacts caching, and in the author's opinion they are an unnecessary and overcomplicated approach to content negotiation.
 
-This is a valid approach as the HTTP spec deliberately underspecifies how a server should weight server-based preferences against client-based preferences.
+!!! note
+    "q" values are not taken into account by REST framework when determining preference.  The use of "q" values negatively impacts caching, and in the author's opinion they are an unnecessary and overcomplicated approach to content negotiation.
 
----
+    This is a valid approach as the HTTP spec deliberately underspecifies how a server should weight server-based preferences against client-based preferences.
 
 # Custom content negotiation
 

docs/api-guide/fields.md

@@ -11,11 +11,8 @@ source:
 
 Serializer fields handle converting between primitive values and internal datatypes.  They also deal with validating input values, as well as retrieving and setting the values from their parent objects.
 
----
-
-**Note:** The serializer fields are declared in `fields.py`, but by convention you should import them using `from rest_framework import serializers` and refer to fields as `serializers.<FieldName>`.
-
----
+!!! note
+    The serializer fields are declared in `fields.py`, but by convention you should import them using `from rest_framework import serializers` and refer to fields as `serializers.<FieldName>`.
 
 ## Core arguments
 
@@ -565,11 +562,8 @@ The `HiddenField` class is usually only needed if you have some validation that
 
 For further examples on `HiddenField` see the [validators](validators.md) documentation.
 
----
-
-**Note:** `HiddenField()` does not appear in `partial=True` serializer (when making `PATCH` request).
-
----
+!!! note
+    `HiddenField()` does not appear in `partial=True` serializer (when making `PATCH` request).
 
 ## ModelField
 

docs/api-guide/generic-views.md

@@ -96,11 +96,8 @@ For example:
         user = self.request.user
         return user.accounts.all()
 
----
-
-**Note:** If the `serializer_class` used in the generic view spans orm relations, leading to an n+1 problem, you could optimize your queryset in this method using `select_related` and `prefetch_related`. To get more information about n+1 problem and use cases of the mentioned methods refer to related section in [django documentation][django-docs-select-related].
-
----
+!!! tip
+    If the `serializer_class` used in the generic view spans ORM relations, leading to an N+1 problem, you could optimize your queryset in this method using `select_related` and `prefetch_related`. To get more information about N+1 problem and use cases of the mentioned methods refer to related section in [django documentation][django-docs-select-related].
 
 ### Avoiding N+1 Queries
 

docs/api-guide/parsers.md

@@ -17,15 +17,12 @@ REST framework includes a number of built-in Parser classes, that allow you to a
 
 The set of valid parsers for a view is always defined as a list of classes.  When `request.data` is accessed, REST framework will examine the `Content-Type` header on the incoming request, and determine which parser to use to parse the request content.
 
----
-
-**Note**: When developing client applications always remember to make sure you're setting the `Content-Type` header when sending data in an HTTP request.
+!!! note
+    When developing client applications always remember to make sure you're setting the `Content-Type` header when sending data in an HTTP request.
 
-If you don't set the content type, most clients will default to using `'application/x-www-form-urlencoded'`, which may not be what you wanted.
+    If you don't set the content type, most clients will default to using `'application/x-www-form-urlencoded'`, which may not be what you want.
 
-As an example, if you are sending `json` encoded data using jQuery with the [.ajax() method][jquery-ajax], you should make sure to include the `contentType: 'application/json'` setting.
-
----
+    As an example, if you are sending `json` encoded data using jQuery with the [.ajax() method][jquery-ajax], you should make sure to include the `contentType: 'application/json'` setting.
 
 ## Setting the parsers
 

docs/api-guide/permissions.md

@@ -51,18 +51,15 @@ For example:
         self.check_object_permissions(self.request, obj)
         return obj
 
----
-
-**Note**: With the exception of `DjangoObjectPermissions`, the provided
-permission classes in `rest_framework.permissions` **do not** implement the
-methods necessary to check object permissions.
+!!! note
+    With the exception of `DjangoObjectPermissions`, the provided
+    permission classes in `rest_framework.permissions` **do not** implement the
+    methods necessary to check object permissions.
 
-If you wish to use the provided permission classes in order to check object
-permissions, **you must** subclass them and implement the
-`has_object_permission()` method described in the [_Custom
-permissions_](#custom-permissions) section (below).
-
----
+    If you wish to use the provided permission classes in order to check object
+    permissions, **you must** subclass them and implement the
+    `has_object_permission()` method described in the [_Custom
+    permissions_](#custom-permissions) section (below).
 
 #### Limitations of object level permissions
 
@@ -118,7 +115,8 @@ Or, if you're using the `@api_view` decorator with function based views.
         }
         return Response(content)
 
-__Note:__ when you set new permission classes via the class attribute or decorators you're telling the view to ignore the default list set in the __settings.py__ file.
+!!! note
+    When you set new permission classes via the class attribute or decorators you're telling the view to ignore the default list set in the ``settings.py`` file.
 
 Provided they inherit from `rest_framework.permissions.BasePermission`, permissions can be composed using standard Python bitwise operators. For example, `IsAuthenticatedOrReadOnly` could be written:
 
@@ -131,17 +129,16 @@ 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 = {
                 'status': 'request was permitted'
             }
             return Response(content)
 
-__Note:__ it supports & (and), | (or) and ~ (not).
-
----
+!!! note
+    Composition of permissions supports `&` (and), `|` (or) and `~` (not) operators.
 
 # API Reference
 
@@ -185,7 +182,7 @@ To use custom model permissions, override `DjangoModelPermissions` and set the `
 
 Similar to `DjangoModelPermissions`, but also allows unauthenticated users to have read-only access to the API.
 
-## DjangoObjectPermissions
+## DjangoObjectPermissions
 
 This permission class ties into Django's standard [object permissions framework][objectpermissions] that allows per-object permissions on models.  In order to use this permission class, you'll also need to add a permission backend that supports object-level permissions, such as [django-guardian][guardian].
 
@@ -199,11 +196,8 @@ Note that `DjangoObjectPermissions` **does not** require the `django-guardian` p
 
 As with `DjangoModelPermissions` you can use custom model permissions by overriding `DjangoObjectPermissions` and setting the `.perms_map` property.  Refer to the source code for details.
 
----
-
-**Note**: If you need object level `view` permissions for `GET`, `HEAD` and `OPTIONS` requests and are using django-guardian for your object-level permissions backend, you'll want to consider using the `DjangoObjectPermissionsFilter` class provided by the [`djangorestframework-guardian` package][django-rest-framework-guardian]. It ensures that list endpoints only return results including objects for which the user has appropriate view permissions.
-
----
+!!! note
+    If you need object level `view` permissions for `GET`, `HEAD` and `OPTIONS` requests and are using django-guardian for your object-level permissions backend, you'll want to consider using the `DjangoObjectPermissionsFilter` class provided by the [`djangorestframework-guardian` package][django-rest-framework-guardian]. It ensures that list endpoints only return results including objects for which the user has appropriate view permissions.
 
 # Custom permissions
 
@@ -221,11 +215,8 @@ If you need to test if a request is a read operation or a write operation, you s
     else:
         # Check permissions for write request
 
----
-
-**Note**: The instance-level `has_object_permission` method will only be called if the view-level `has_permission` checks have already passed. Also note that in order for the instance-level checks to run, the view code should explicitly call `.check_object_permissions(request, obj)`. If you are using the generic views then this will be handled for you by default. (Function-based views will need to check object permissions explicitly, raising `PermissionDenied` on failure.)
-
----
+!!! note
+    The instance-level `has_object_permission` method will only be called if the view-level `has_permission` checks have already passed. Also note that in order for the instance-level checks to run, the view code should explicitly call `.check_object_permissions(request, obj)`. If you are using the generic views then this will be handled for you by default. (Function-based views will need to check object permissions explicitly, raising `PermissionDenied` on failure.)
 
 Custom permissions will raise a `PermissionDenied` exception if the test fails. To change the error message associated with the exception, implement a `message` attribute directly on your custom permission. Otherwise the `default_detail` attribute from `PermissionDenied` will be used. Similarly, to change the code identifier associated with the exception, implement a `code` attribute directly on your custom permission - otherwise the `default_code` attribute from `PermissionDenied` will be used.