Skip to content

docs: lint #8688

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
shyamkumaryadav wants to merge 3 commits into from
Closed

docs: lint #8688

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
e3bc805
docs: fix
shyamkumaryadav Oct 8, 2022
79604a8
remove space
shyamkumaryadav Oct 8, 2022
7ff1fac
docs: lint
shyamkumaryadav Oct 8, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 1 addition & 9 deletions docs/api-guide/authentication.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -247,7 +247,6 @@ And in your `urls.py`:
path('api-token-auth/', CustomAuthToken.as_view())
]


#### With Django admin

It is also possible to create Tokens manually through the admin interface. In case you are using a large user base, we recommend that you monkey patch the `TokenAdmin` class customize it to your needs, more specifically by declaring the `user` field as `raw_field`.
Expand All @@ -258,7 +257,6 @@ It is also possible to create Tokens manually through the admin interface. In ca

TokenAdmin.raw_id_fields = ['user']


#### Using Django manage.py command

Since version 3.6.4 it's possible to generate a user token using the following command:
Expand All @@ -273,7 +271,6 @@ In case you want to regenerate the token (for example if it has been compromised

./manage.py drf_create_token -r <username>


## SessionAuthentication

This authentication scheme uses Django's default session backend for authentication. Session authentication is appropriate for AJAX clients that are running in the same session context as your website.
Expand All @@ -291,7 +288,6 @@ If you're using an AJAX-style API with SessionAuthentication, you'll need to mak

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 behaviour is not suitable for login views, which should always have CSRF validation applied.


## RemoteUserAuthentication

This authentication scheme allows you to delegate authentication to your web server, which sets the `REMOTE_USER`
Expand All @@ -312,7 +308,6 @@ Consult your web server's documentation for information about configuring an aut
* [Apache Authentication How-To](https://httpd.apache.org/docs/2.4/howto/auth.html)
* [NGINX (Restricting Access)](https://docs.nginx.com/nginx/admin-guide/security-controls/configuring-http-basic-authentication/)


# Custom authentication

To implement a custom authentication scheme, subclass `BaseAuthentication` and override the `.authenticate(self, request)` method. The method should return a two-tuple of `(user, auth)` if authentication succeeds, or `None` otherwise.
Expand All @@ -338,7 +333,7 @@ If the `.authenticate_header()` method is not overridden, the authentication sch

The following example will authenticate any incoming request as the user given by the username in a custom request header named 'X-USERNAME'.

from django.contrib.auth.models import User
from django.contrib.auth.models import User
from rest_framework import authentication
from rest_framework import exceptions

Expand Down Expand Up @@ -424,7 +419,6 @@ HTTP Signature (currently a [IETF draft][http-signature-ietf-draft]) provides a

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.


There are currently two forks of this project.

* [Django-rest-auth][django-rest-auth] is the original project, [but is not currently receiving updates](https://github.com/Tivix/django-rest-auth/issues/568).
Expand Down Expand Up @@ -460,8 +454,6 @@ More information can be found in the [Documentation](https://django-rest-durin.r
[django-rest-framework-oauth]: https://jpadilla.github.io/django-rest-framework-oauth/
[django-rest-framework-oauth-authentication]: https://jpadilla.github.io/django-rest-framework-oauth/authentication/
[django-rest-framework-oauth-permissions]: https://jpadilla.github.io/django-rest-framework-oauth/permissions/
[juanriaza]: https://github.com/juanriaza
[djangorestframework-digestauth]: https://github.com/juanriaza/django-rest-framework-digestauth
[oauth-1.0a]: https://oauth.net/core/1.0a/
[django-oauth-toolkit]: https://github.com/evonove/django-oauth-toolkit
[jazzband]: https://github.com/jazzband/
Expand Down
2 changes: 1 addition & 1 deletion docs/api-guide/content-negotiation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -82,9 +82,9 @@ The default content negotiation class may be set globally, using the `DEFAULT_CO

You can also set the content negotiation used for an individual view, or viewset, using the `APIView` class-based views.

from myapp.negotiation import IgnoreClientContentNegotiation
from rest_framework.response import Response
from rest_framework.views import APIView
from myapp.negotiation import IgnoreClientContentNegotiation

class NoNegotiationView(APIView):
"""
Expand Down
111 changes: 55 additions & 56 deletions docs/api-guide/fields.md
View file
Open in desktop

Large diffs are not rendered by default.

4 changes: 1 addition & 3 deletions docs/api-guide/filtering.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,6 @@ For example:
user = self.request.user
return Purchase.objects.filter(purchaser=user)


## Filtering against the URL

Another style of filtering might involve restricting the queryset based on some part of the URL.
Expand Down Expand Up @@ -187,7 +186,6 @@ For more advanced filtering requirements you can specify a `FilterSet` class tha
You can read more about `FilterSet`s in the [django-filter documentation][django-filter-docs].
It's also recommended that you read the section on [DRF integration][django-filter-drf-docs].


## SearchFilter

The `SearchFilter` class supports simple single query parameter based searching, and is based on the [Django admin's search functionality][search-django-admin].
Expand All @@ -213,7 +211,7 @@ This will allow the client to filter the items in the list by making queries suc
You can also perform a related lookup on a ForeignKey or ManyToManyField with the lookup API double-underscore notation:

search_fields = ['username', 'email', 'profile__profession']

For [JSONField][JSONField] and [HStoreField][HStoreField] fields you can filter based on nested values within the data structure using the same double-underscore notation:

search_fields = ['data__breed', 'data__owner__other_pets__0__name']
Expand Down
1 change: 0 additions & 1 deletion docs/api-guide/generic-views.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -386,7 +386,6 @@ The following third party packages provide additional generic view implementatio

[Django Rest Multiple Models][django-rest-multiple-models] provides a generic view (and mixin) for sending multiple serialized models and/or querysets via a single API request.


[cite]: https://docs.djangoproject.com/en/stable/ref/class-based-views/#base-vs-generic-views
[GenericAPIView]: #genericapiview
[ListModelMixin]: #listmodelmixin
Expand Down
88 changes: 66 additions & 22 deletions docs/api-guide/permissions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,8 +59,8 @@ 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).
`has_object_permission()` method described in the [*Custom
permissions*](#custom-permissions) section (below).

---

Expand Down Expand Up @@ -118,7 +118,7 @@ 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:

Expand All @@ -139,7 +139,7 @@ Provided they inherit from `rest_framework.permissions.BasePermission`, permissi
}
return Response(content)

__Note:__ it supports & (and), | (or) and ~ (not).
**Note:** it supports & (and), | (or) and ~ (not).

---

Expand Down Expand Up @@ -185,7 +185,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].

Expand Down Expand Up @@ -278,22 +278,68 @@ Also note that the generic views will only check the object-level permissions fo

REST framework offers three different methods to customize access restrictions on a case-by-case basis. These apply in different scenarios and have different effects and limitations.

* `queryset`/`get_queryset()`: Limits the general visibility of existing objects from the database. The queryset limits which objects will be listed and which objects can be modified or deleted. The `get_queryset()` method can apply different querysets based on the current action.
* `permission_classes`/`get_permissions()`: General permission checks based on the current action, request and targeted object. Object level permissions can only be applied to retrieve, modify and deletion actions. Permission checks for list and create will be applied to the entire object type. (In case of list: subject to restrictions in the queryset.)
* `serializer_class`/`get_serializer()`: Instance level restrictions that apply to all objects on input and output. The serializer may have access to the request context. The `get_serializer()` method can apply different serializers based on the current action.
* `queryset`/`get_queryset()`: Limits the general visibility of existing objects from the database. The queryset limits which objects will be listed and which objects can be modified or deleted. The `get_queryset()` method can apply different querysets based on the current action.
* `permission_classes`/`get_permissions()`: General permission checks based on the current action, request and targeted object. Object level permissions can only be applied to retrieve, modify and deletion actions. Permission checks for list and create will be applied to the entire object type. (In case of list: subject to restrictions in the queryset.)
* `serializer_class`/`get_serializer()`: Instance level restrictions that apply to all objects on input and output. The serializer may have access to the request context. The `get_serializer()` method can apply different serializers based on the current action.

The following table lists the access restriction methods and the level of control they offer over which actions.

| | `queryset` | `permission_classes` | `serializer_class` |
|------------------------------------|------------|----------------------|--------------------|
| Action: list | global | global | object-level* |
| Action: create | no | global | object-level |
| Action: retrieve | global | object-level | object-level |
| Action: update | global | object-level | object-level |
| Action: partial_update | global | object-level | object-level |
| Action: destroy | global | object-level | no |
| Can reference action in decision | no** | yes | no** |
| Can reference request in decision | no** | yes | yes |
<table border=1>
<tr>
<th></th>
<th><code>queryset</code></th>
<th><code>permission_classes</code></th>
<th><code>serializer_class</code></th>
</tr>
<tr>
<td>Action: list</td>
<td>global</td>
<td>global</td>
<td>object-level*</td>
</tr>
<tr>
<td>Action: create</td>
<td>no</td>
<td>global</td>
<td>object-level</td>
</tr>
<tr>
<td>Action: retrieve</td>
<td>global</td>
<td>object-level</td>
<td>object-level</td>
</tr>
<tr>
<td>Action: update</td>
<td>global</td>
<td>object-level</td>
<td>object-level</td>
</tr>
<tr>
<td>Action: partial_update</td>
<td>global</td>
<td>object-level</td>
<td>object-level</td>
</tr>
<tr>
<td>Action: destroy</td>
<td>global</td>
<td>object-level</td>
<td>no</td>
</tr>
<tr>
<td>Can reference action in decision</td>
<td>no**</td>
<td>yes</td>
<td>no**</td>
</tr>
<tr>
<td>Can reference request in decision</td>
<td>no**</td>
<td>yes</td>
<td>yes</td>
</tr>
</table>

\* A Serializer class should not raise PermissionDenied in a list action, or the entire list would not be returned. <br>
\** The `get_*()` methods have access to the current view and can return different Serializer or QuerySet instances based on the request or action.
Expand All @@ -306,7 +352,7 @@ The following third party packages are also available.

## DRF - Access Policy

The [Django REST - Access Policy][drf-access-policy] package provides a way to define complex access rules in declarative policy classes that are attached to view sets or function-based views. The policies are defined in JSON in a format similar to AWS' Identity & Access Management policies.
The [Django REST - Access Policy][drf-access-policy] package provides a way to define complex access rules in declarative policy classes that are attached to view sets or function-based views. The policies are defined in JSON in a format similar to AWS' Identity & Access Management policies.

## Composed Permissions

Expand All @@ -326,7 +372,7 @@ The [Django Rest Framework Roles][django-rest-framework-roles] package makes it

## Django REST Framework API Key

The [Django REST Framework API Key][djangorestframework-api-key] package provides permissions classes, models and helpers to add API key authorization to your API. It can be used to authorize internal or third-party backends and services (i.e. _machines_) which do not have a user account. API keys are stored securely using Django's password hashing infrastructure, and they can be viewed, edited and revoked at anytime in the Django admin.
The [Django REST Framework API Key][djangorestframework-api-key] package provides permissions classes, models and helpers to add API key authorization to your API. It can be used to authorize internal or third-party backends and services (i.e. *machines*) which do not have a user account. API keys are stored securely using Django's password hashing infrastructure, and they can be viewed, edited and revoked at anytime in the Django admin.

## Django Rest Framework Role Filters

Expand All @@ -336,15 +382,13 @@ The [Django Rest Framework Role Filters][django-rest-framework-role-filters] pac

The [Django Rest Framework PSQ][drf-psq] package is an extension that gives support for having action-based **permission_classes**, **serializer_class**, and **queryset** dependent on permission-based rules.


[cite]: https://developer.apple.com/library/mac/#documentation/security/Conceptual/AuthenticationAndAuthorizationGuide/Authorization/Authorization.html
[authentication]: authentication.md
[throttling]: throttling.md
[filtering]: filtering.md
[contribauth]: https://docs.djangoproject.com/en/stable/topics/auth/customizing/#custom-permissions
[objectpermissions]: https://docs.djangoproject.com/en/stable/topics/auth/customizing/#handling-object-permissions
[guardian]: https://github.com/lukaszb/django-guardian
[filtering]: filtering.md
[composed-permissions]: https://github.com/niwibe/djangorestframework-composed-permissions
[rest-condition]: https://github.com/caxap/rest_condition
[dry-rest-permissions]: https://github.com/FJNR-inc/dry-rest-permissions
Expand Down
Loading