Drf response error - Исправление ошибок и поиск оптимальных решений проблем

exceptions.py

Exceptions… allow error handling to be organized cleanly in a central or high-level place within the program structure.

— Doug Hellmann, Python Exception Handling Techniques

Exception handling in REST framework views

REST framework’s views handle various exceptions, and deal with returning appropriate error responses.

The handled exceptions are:

Subclasses of APIException raised inside REST framework.
Django’s Http404 exception.
Django’s PermissionDenied exception.

In each case, REST framework will return a response with an appropriate status code and content-type. The body of the response will include any additional details regarding the nature of the error.

Most error responses will include a key detail in the body of the response.

For example, the following request:

DELETE http://api.example.com/foo/bar HTTP/1.1
Accept: application/json

Might receive an error response indicating that the DELETE method is not allowed on that resource:

HTTP/1.1 405 Method Not Allowed
Content-Type: application/json
Content-Length: 42

{"detail": "Method 'DELETE' not allowed."}

Validation errors are handled slightly differently, and will include the field names as the keys in the response. If the validation error was not specific to a particular field then it will use the «non_field_errors» key, or whatever string value has been set for the NON_FIELD_ERRORS_KEY setting.

An example validation error might look like this:

HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 94

{"amount": ["A valid integer is required."], "description": ["This field may not be blank."]}

Custom exception handling

You can implement custom exception handling by creating a handler function that converts exceptions raised in your API views into response objects. This allows you to control the style of error responses used by your API.

The function must take a pair of arguments, the first is the exception to be handled, and the second is a dictionary containing any extra context such as the view currently being handled. The exception handler function should either return a Response object, or return None if the exception cannot be handled. If the handler returns None then the exception will be re-raised and Django will return a standard HTTP 500 ‘server error’ response.

For example, you might want to ensure that all error responses include the HTTP status code in the body of the response, like so:

HTTP/1.1 405 Method Not Allowed
Content-Type: application/json
Content-Length: 62

{"status_code": 405, "detail": "Method 'DELETE' not allowed."}

In order to alter the style of the response, you could write the following custom exception handler:

from rest_framework.views import exception_handler

def custom_exception_handler(exc, context):
    # Call REST framework's default exception handler first,
    # to get the standard error response.
    response = exception_handler(exc, context)

    # Now add the HTTP status code to the response.
    if response is not None:
        response.data['status_code'] = response.status_code

    return response

The context argument is not used by the default handler, but can be useful if the exception handler needs further information such as the view currently being handled, which can be accessed as context['view'].

The exception handler must also be configured in your settings, using the EXCEPTION_HANDLER setting key. For example:

REST_FRAMEWORK = {
    'EXCEPTION_HANDLER': 'my_project.my_app.utils.custom_exception_handler'
}

If not specified, the 'EXCEPTION_HANDLER' setting defaults to the standard exception handler provided by REST framework:

REST_FRAMEWORK = {
    'EXCEPTION_HANDLER': 'rest_framework.views.exception_handler'
}

Note that the exception handler will only be called for responses generated by raised exceptions. It will not be used for any responses returned directly by the view, such as the HTTP_400_BAD_REQUEST responses that are returned by the generic views when serializer validation fails.

API Reference

APIException

Signature: APIException()

The base class for all exceptions raised inside an APIView class or @api_view.

To provide a custom exception, subclass APIException and set the .status_code, .default_detail, and default_code attributes on the class.

For example, if your API relies on a third party service that may sometimes be unreachable, you might want to implement an exception for the «503 Service Unavailable» HTTP response code. You could do this like so:

from rest_framework.exceptions import APIException

class ServiceUnavailable(APIException):
    status_code = 503
    default_detail = 'Service temporarily unavailable, try again later.'
    default_code = 'service_unavailable'

Inspecting API exceptions

There are a number of different properties available for inspecting the status
of an API exception. You can use these to build custom exception handling
for your project.

The available attributes and methods are:

.detail — Return the textual description of the error.
.get_codes() — Return the code identifier of the error.
.get_full_details() — Return both the textual description and the code identifier.

In most cases the error detail will be a simple item:

>>> print(exc.detail)
You do not have permission to perform this action.
>>> print(exc.get_codes())
permission_denied
>>> print(exc.get_full_details())
{'message':'You do not have permission to perform this action.','code':'permission_denied'}

In the case of validation errors the error detail will be either a list or
dictionary of items:

>>> print(exc.detail)
{"name":"This field is required.","age":"A valid integer is required."}
>>> print(exc.get_codes())
{"name":"required","age":"invalid"}
>>> print(exc.get_full_details())
{"name":{"message":"This field is required.","code":"required"},"age":{"message":"A valid integer is required.","code":"invalid"}}

ParseError

Signature: ParseError(detail=None, code=None)

Raised if the request contains malformed data when accessing request.data.

By default this exception results in a response with the HTTP status code «400 Bad Request».

AuthenticationFailed

Signature: AuthenticationFailed(detail=None, code=None)

Raised when an incoming request includes incorrect authentication.

By default this exception results in a response with the HTTP status code «401 Unauthenticated», but it may also result in a «403 Forbidden» response, depending on the authentication scheme in use. See the authentication documentation for more details.

NotAuthenticated

Signature: NotAuthenticated(detail=None, code=None)

Raised when an unauthenticated request fails the permission checks.

PermissionDenied

Signature: PermissionDenied(detail=None, code=None)

Raised when an authenticated request fails the permission checks.

By default this exception results in a response with the HTTP status code «403 Forbidden».

NotFound

Signature: NotFound(detail=None, code=None)

Raised when a resource does not exists at the given URL. This exception is equivalent to the standard Http404 Django exception.

By default this exception results in a response with the HTTP status code «404 Not Found».

MethodNotAllowed

Signature: MethodNotAllowed(method, detail=None, code=None)

Raised when an incoming request occurs that does not map to a handler method on the view.

By default this exception results in a response with the HTTP status code «405 Method Not Allowed».

NotAcceptable

Signature: NotAcceptable(detail=None, code=None)

Raised when an incoming request occurs with an Accept header that cannot be satisfied by any of the available renderers.

By default this exception results in a response with the HTTP status code «406 Not Acceptable».

Signature: UnsupportedMediaType(media_type, detail=None, code=None)

Raised if there are no parsers that can handle the content type of the request data when accessing request.data.

By default this exception results in a response with the HTTP status code «415 Unsupported Media Type».

Throttled

Signature: Throttled(wait=None, detail=None, code=None)

Raised when an incoming request fails the throttling checks.

By default this exception results in a response with the HTTP status code «429 Too Many Requests».

ValidationError

Signature: ValidationError(detail, code=None)

The ValidationError exception is slightly different from the other APIException classes:

The detail argument is mandatory, not optional.
The detail argument may be a list or dictionary of error details, and may also be a nested data structure. By using a dictionary, you can specify field-level errors while performing object-level validation in the validate() method of a serializer. For example. raise serializers.ValidationError({'name': 'Please enter a valid name.'})
By convention you should import the serializers module and use a fully qualified ValidationError style, in order to differentiate it from Django’s built-in validation error. For example. raise serializers.ValidationError('This field must be an integer value.')

The ValidationError class should be used for serializer and field validation, and by validator classes. It is also raised when calling serializer.is_valid with the raise_exception keyword argument:

serializer.is_valid(raise_exception=True)

The generic views use the raise_exception=True flag, which means that you can override the style of validation error responses globally in your API. To do so, use a custom exception handler, as described above.

By default this exception results in a response with the HTTP status code «400 Bad Request».

Generic Error Views

Django REST Framework provides two error views suitable for providing generic JSON 500 Server Error and
400 Bad Request responses. (Django’s default error views provide HTML responses, which may not be appropriate for an
API-only application.)

Use these as per Django’s Customizing error views documentation.

`rest_framework.exceptions.server_error`

Returns a response with status code 500 and application/json content type.

Set as handler500:

handler500 = 'rest_framework.exceptions.server_error'

`rest_framework.exceptions.bad_request`

Returns a response with status code 400 and application/json content type.

Set as handler400:

handler400 = 'rest_framework.exceptions.bad_request'

Third party packages

The following third-party packages are also available.

DRF Standardized Errors

The drf-standardized-errors package provides an exception handler that generates the same format for all 4xx and 5xx responses. It is a drop-in replacement for the default exception handler and allows customizing the error response format without rewriting the whole exception handler. The standardized error response format is easier to document and easier to handle by API consumers.

Источник

source
exceptions.py

Exceptions… allow error handling to be organized cleanly in a central or high-level place within the program structure.

— Doug Hellmann, Python Exception Handling Techniques

Exception handling in REST framework views

REST framework’s views handle various exceptions, and deal with returning appropriate error responses.

The handled exceptions are:

Subclasses of APIException raised inside REST framework.
Django’s Http404 exception.
Django’s PermissionDenied exception.

In each case, REST framework will return a response with an appropriate status code and content-type. The body of the response will include any additional details regarding the nature of the error.

Most error responses will include a key detail in the body of the response.

For example, the following request:

DELETE http://api.example.com/foo/bar HTTP/1.1
Accept: application/json

Might receive an error response indicating that the DELETE method is not allowed on that resource:

HTTP/1.1 405 Method Not Allowed
Content-Type: application/json
Content-Length: 42

{"detail": "Method 'DELETE' not allowed."}

An example validation error might look like this:

HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 94

{"amount": ["A valid integer is required."], "description": ["This field may not be blank."]}

Custom exception handling

For example, you might want to ensure that all error responses include the HTTP status code in the body of the response, like so:

HTTP/1.1 405 Method Not Allowed
Content-Type: application/json
Content-Length: 62

{"status_code": 405, "detail": "Method 'DELETE' not allowed."}

In order to alter the style of the response, you could write the following custom exception handler:

from rest_framework.views import exception_handler

def custom_exception_handler(exc, context):
    # Call REST framework's default exception handler first,
    # to get the standard error response.
    response = exception_handler(exc, context)

    # Now add the HTTP status code to the response.
    if response is not None:
        response.data['status_code'] = response.status_code

    return response

The exception handler must also be configured in your settings, using the EXCEPTION_HANDLER setting key. For example:

REST_FRAMEWORK = {
    'EXCEPTION_HANDLER': 'my_project.my_app.utils.custom_exception_handler'
}

If not specified, the 'EXCEPTION_HANDLER' setting defaults to the standard exception handler provided by REST framework:

REST_FRAMEWORK = {
    'EXCEPTION_HANDLER': 'rest_framework.views.exception_handler'
}

API Reference

APIException

Signature: APIException()

The base class for all exceptions raised inside an APIView class or @api_view.

To provide a custom exception, subclass APIException and set the .status_code, .default_detail, and default_code attributes on the class.

from rest_framework.exceptions import APIException

class ServiceUnavailable(APIException):
    status_code = 503
    default_detail = 'Service temporarily unavailable, try again later.'
    default_code = 'service_unavailable'

Inspecting API exceptions

There are a number of different properties available for inspecting the status
of an API exception. You can use these to build custom exception handling
for your project.

The available attributes and methods are:

.detail — Return the textual description of the error.
.get_codes() — Return the code identifier of the error.
.get_full_details() — Return both the textual description and the code identifier.

In most cases the error detail will be a simple item:

>>> print(exc.detail)
You do not have permission to perform this action.
>>> print(exc.get_codes())
permission_denied
>>> print(exc.get_full_details())
{'message':'You do not have permission to perform this action.','code':'permission_denied'}

In the case of validation errors the error detail will be either a list or
dictionary of items:

>>> print(exc.detail)
{"name":"This field is required.","age":"A valid integer is required."}
>>> print(exc.get_codes())
{"name":"required","age":"invalid"}
>>> print(exc.get_full_details())
{"name":{"message":"This field is required.","code":"required"},"age":{"message":"A valid integer is required.","code":"invalid"}}

ParseError

Signature: ParseError(detail=None, code=None)

Raised if the request contains malformed data when accessing request.data.

By default this exception results in a response with the HTTP status code «400 Bad Request».

AuthenticationFailed

Signature: AuthenticationFailed(detail=None, code=None)

Raised when an incoming request includes incorrect authentication.

NotAuthenticated

Signature: NotAuthenticated(detail=None, code=None)

Raised when an unauthenticated request fails the permission checks.

PermissionDenied

Signature: PermissionDenied(detail=None, code=None)

Raised when an authenticated request fails the permission checks.

By default this exception results in a response with the HTTP status code «403 Forbidden».

NotFound

Signature: NotFound(detail=None, code=None)

Raised when a resource does not exists at the given URL. This exception is equivalent to the standard Http404 Django exception.

By default this exception results in a response with the HTTP status code «404 Not Found».

MethodNotAllowed

Signature: MethodNotAllowed(method, detail=None, code=None)

Raised when an incoming request occurs that does not map to a handler method on the view.

By default this exception results in a response with the HTTP status code «405 Method Not Allowed».

NotAcceptable

Signature: NotAcceptable(detail=None, code=None)

Raised when an incoming request occurs with an Accept header that cannot be satisfied by any of the available renderers.

By default this exception results in a response with the HTTP status code «406 Not Acceptable».

UnsupportedMediaType

Signature: UnsupportedMediaType(media_type, detail=None, code=None)

Raised if there are no parsers that can handle the content type of the request data when accessing request.data.

By default this exception results in a response with the HTTP status code «415 Unsupported Media Type».

Throttled

Signature: Throttled(wait=None, detail=None, code=None)

Raised when an incoming request fails the throttling checks.

By default this exception results in a response with the HTTP status code «429 Too Many Requests».

ValidationError

Signature: ValidationError(detail=None, code=None)

The ValidationError exception is slightly different from the other APIException classes:

The detail argument may be a list or dictionary of error details, and may also be a nested data structure. By using a dictionary, you can specify field-level errors while performing object-level validation in the validate() method of a serializer. For example. raise serializers.ValidationError({'name': 'Please enter a valid name.'})
By convention you should import the serializers module and use a fully qualified ValidationError style, in order to differentiate it from Django’s built-in validation error. For example. raise serializers.ValidationError('This field must be an integer value.')

serializer.is_valid(raise_exception=True)

By default this exception results in a response with the HTTP status code «400 Bad Request».

Generic Error Views

Use these as per Django’s Customizing error views documentation.

`rest_framework.exceptions.server_error`

Returns a response with status code 500 and application/json content type.

Set as handler500:

handler500 = 'rest_framework.exceptions.server_error'

`rest_framework.exceptions.bad_request`

Returns a response with status code 400 and application/json content type.

Set as handler400:

handler400 = 'rest_framework.exceptions.bad_request'

Third party packages

The following third-party packages are also available.

DRF Standardized Errors

Источник

Содержание

Exceptions
Exception handling in REST framework views
Custom exception handling
API Reference
APIException
Inspecting API exceptions
ParseError
AuthenticationFailed
NotAuthenticated
PermissionDenied
NotFound
MethodNotAllowed
NotAcceptable
UnsupportedMediaType
Throttled
ValidationError
Generic Error Views
rest_framework.exceptions.server_error
rest_framework.exceptions.bad_request
Third party packages
DRF Standardized Errors
Исключения¶
Обработка исключений в представлениях фреймворка REST¶
Пользовательская обработка исключений¶
Справочник по API¶
APIException¶
Проверка исключений API¶
ParseError¶
AuthenticationFailed¶
NotAuthenticated¶
PermissionDenied¶
NotFound¶
MethodNotAllowed¶
Неприемлемо¶
UnsupportedMediaType¶
Дросселированный¶
ValidationError¶
Общие представления ошибок¶
rest_framework.exceptions.server_error ¶
rest_framework.exceptions.bad_request ¶

Exceptions

Exceptions… allow error handling to be organized cleanly in a central or high-level place within the program structure.

Exception handling in REST framework views

REST framework’s views handle various exceptions, and deal with returning appropriate error responses.

The handled exceptions are:

Subclasses of APIException raised inside REST framework.
Django’s Http404 exception.
Django’s PermissionDenied exception.

In each case, REST framework will return a response with an appropriate status code and content-type. The body of the response will include any additional details regarding the nature of the error.

Most error responses will include a key detail in the body of the response.

For example, the following request:

Might receive an error response indicating that the DELETE method is not allowed on that resource:

An example validation error might look like this:

Custom exception handling

The function must take a pair of arguments, the first is the exception to be handled, and the second is a dictionary containing any extra context such as the view currently being handled. The exception handler function should either return a Response object, or return None if the exception cannot be handled. If the handler returns None then the exception will be re-raised and Django will return a standard HTTP 500 ‘server error’ response.

For example, you might want to ensure that all error responses include the HTTP status code in the body of the response, like so:

In order to alter the style of the response, you could write the following custom exception handler:

The exception handler must also be configured in your settings, using the EXCEPTION_HANDLER setting key. For example:

If not specified, the ‘EXCEPTION_HANDLER’ setting defaults to the standard exception handler provided by REST framework:

Note that the exception handler will only be called for responses generated by raised exceptions. It will not be used for any responses returned directly by the view, such as the HTTP_400_BAD_REQUEST responses that are returned by the generic views when serializer validation fails.

API Reference

APIException

Signature: APIException()

The base class for all exceptions raised inside an APIView class or @api_view .

To provide a custom exception, subclass APIException and set the .status_code , .default_detail , and default_code attributes on the class.

Inspecting API exceptions

There are a number of different properties available for inspecting the status of an API exception. You can use these to build custom exception handling for your project.

The available attributes and methods are:

.detail — Return the textual description of the error.
.get_codes() — Return the code identifier of the error.
.get_full_details() — Return both the textual description and the code identifier.

In most cases the error detail will be a simple item:

In the case of validation errors the error detail will be either a list or dictionary of items:

ParseError

Signature: ParseError(detail=None, code=None)

Raised if the request contains malformed data when accessing request.data .

By default this exception results in a response with the HTTP status code «400 Bad Request».

AuthenticationFailed

Signature: AuthenticationFailed(detail=None, code=None)

Raised when an incoming request includes incorrect authentication.

NotAuthenticated

Signature: NotAuthenticated(detail=None, code=None)

Raised when an unauthenticated request fails the permission checks.

PermissionDenied

Signature: PermissionDenied(detail=None, code=None)

Raised when an authenticated request fails the permission checks.

By default this exception results in a response with the HTTP status code «403 Forbidden».

NotFound

Signature: NotFound(detail=None, code=None)

Raised when a resource does not exists at the given URL. This exception is equivalent to the standard Http404 Django exception.

By default this exception results in a response with the HTTP status code «404 Not Found».

MethodNotAllowed

Signature: MethodNotAllowed(method, detail=None, code=None)

Raised when an incoming request occurs that does not map to a handler method on the view.

By default this exception results in a response with the HTTP status code «405 Method Not Allowed».

NotAcceptable

Signature: NotAcceptable(detail=None, code=None)

Raised when an incoming request occurs with an Accept header that cannot be satisfied by any of the available renderers.

By default this exception results in a response with the HTTP status code «406 Not Acceptable».

Signature: UnsupportedMediaType(media_type, detail=None, code=None)

Raised if there are no parsers that can handle the content type of the request data when accessing request.data .

By default this exception results in a response with the HTTP status code «415 Unsupported Media Type».

Throttled

Signature: Throttled(wait=None, detail=None, code=None)

Raised when an incoming request fails the throttling checks.

By default this exception results in a response with the HTTP status code «429 Too Many Requests».

ValidationError

Signature: ValidationError(detail, code=None)

The ValidationError exception is slightly different from the other APIException classes:

The detail argument is mandatory, not optional.
The detail argument may be a list or dictionary of error details, and may also be a nested data structure. By using a dictionary, you can specify field-level errors while performing object-level validation in the validate() method of a serializer. For example. raise serializers.ValidationError(<‘name’: ‘Please enter a valid name.’>)
By convention you should import the serializers module and use a fully qualified ValidationError style, in order to differentiate it from Django’s built-in validation error. For example. raise serializers.ValidationError(‘This field must be an integer value.’)

The ValidationError class should be used for serializer and field validation, and by validator classes. It is also raised when calling serializer.is_valid with the raise_exception keyword argument:

The generic views use the raise_exception=True flag, which means that you can override the style of validation error responses globally in your API. To do so, use a custom exception handler, as described above.

By default this exception results in a response with the HTTP status code «400 Bad Request».

Generic Error Views

Django REST Framework provides two error views suitable for providing generic JSON 500 Server Error and 400 Bad Request responses. (Django’s default error views provide HTML responses, which may not be appropriate for an API-only application.)

rest_framework.exceptions.server_error

Returns a response with status code 500 and application/json content type.

Set as handler500 :

rest_framework.exceptions.bad_request

Returns a response with status code 400 and application/json content type.

Set as handler400 :

Third party packages

The following third-party packages are also available.

DRF Standardized Errors

Источник

Исключения¶

Исключения… позволяют чисто организовать обработку ошибок в центральном или высокоуровневом месте в структуре программы.

‒ Doug Hellmann, Python Exception Handling Techniques

Обработка исключений в представлениях фреймворка REST¶

Представления фреймворка REST обрабатывают различные исключения и возвращают соответствующие ответы на ошибки.

Обрабатываемыми исключениями являются:

Подклассы APIException , поднятые внутри фреймворка REST.

Исключение Django Http404 .

Исключение Django PermissionDenied .

В каждом случае фреймворк REST возвращает ответ с соответствующим кодом состояния и типом содержимого. В теле ответа будут содержаться любые дополнительные сведения о характере ошибки.

Большинство ответов на ошибки будут содержать ключ detail в теле ответа.

Например, следующий запрос:

Может быть получен ответ об ошибке, указывающий на то, что метод DELETE не разрешен на данном ресурсе:

Ошибки валидации обрабатываются несколько иначе, и в качестве ключей в ответе будут указаны имена полей. Если ошибка валидации не относится к конкретному полю, то будет использован ключ «non_field_errors» или любое строковое значение, установленное для параметра NON_FIELD_ERRORS_KEY .

Пример ошибки валидации может выглядеть следующим образом:

Пользовательская обработка исключений¶

Вы можете реализовать пользовательскую обработку исключений, создав функцию-обработчик, которая преобразует исключения, возникающие в представлениях вашего API, в объекты ответа. Это позволит вам контролировать стиль ответов на ошибки, используемый вашим API.

Функция должна принимать пару аргументов, первый из которых — обрабатываемое исключение, а второй — словарь, содержащий любой дополнительный контекст, например, обрабатываемое в данный момент представление. Функция обработчика исключения должна либо вернуть объект Response , либо вернуть None , если исключение не может быть обработано. Если обработчик возвращает None , то исключение будет повторно поднято и Django вернет стандартный ответ HTTP 500 „server error“.

Например, вы можете захотеть убедиться, что все ответы на ошибки включают код состояния HTTP в теле ответа, например, так:

Чтобы изменить стиль ответа, вы можете написать следующий пользовательский обработчик исключений:

Аргумент context не используется обработчиком по умолчанию, но может быть полезен, если обработчику исключения нужна дополнительная информация, например, обрабатываемое в данный момент представление, доступ к которому можно получить в виде context[‘view’] .

Обработчик исключений также должен быть настроен в ваших настройках, используя клавишу настройки EXCEPTION_HANDLER . Например:

Если параметр ‘EXCEPTION_HANDLER’ не указан, то по умолчанию используется стандартный обработчик исключений, предоставляемый фреймворком REST:

Обратите внимание, что обработчик исключений будет вызываться только для ответов, сгенерированных поднятыми исключениями. Он не будет использоваться для любых ответов, возвращаемых непосредственно представлением, например, ответов HTTP_400_BAD_REQUEST , которые возвращаются общими представлениями при неудачной проверке сериализатора.

Справочник по API¶

APIException¶

Подпись: APIException()

базовый класс для всех исключений, возникающих внутри класса APIView или @api_view .

Чтобы обеспечить пользовательское исключение, подкласс APIException и установите атрибуты .status_code , .default_detail , и default_code на класс.

Например, если ваш API полагается на сторонний сервис, который иногда может быть недоступен, вы можете захотеть реализовать исключение для кода ответа HTTP «503 Service Unavailable». Это можно сделать следующим образом:

Проверка исключений API¶

Существует ряд различных свойств, доступных для проверки состояния исключения API. Вы можете использовать их для создания пользовательской обработки исключений в вашем проекте.

Доступными атрибутами и методами являются:

.detail — Возвращает текстовое описание ошибки.

.get_codes() — Возвращает идентификатор кода ошибки.

.get_full_details() — Возвращает как текстовое описание, так и идентификатор кода.

В большинстве случаев деталь ошибки будет простым элементом:

В случае ошибок валидации деталь ошибки будет представлять собой список или словарь элементов:

ParseError¶

Подпись: ParseError(detail=None, code=None)

Возникает, если запрос содержит неправильно сформированные данные при доступе к request.data .

По умолчанию это исключение приводит к ответу с кодом состояния HTTP «400 Bad Request».

AuthenticationFailed¶

Подпись: AuthenticationFailed(detail=None, code=None)

Возникает, когда входящий запрос содержит неправильную аутентификацию.

По умолчанию это исключение приводит к ответу с кодом состояния HTTP «401 Unauthenticated», но оно также может привести к ответу «403 Forbidden», в зависимости от используемой схемы аутентификации. Более подробную информацию см. в authentication documentation .

NotAuthenticated¶

Подпись: NotAuthenticated(detail=None, code=None)

Возникает, когда неаутентифицированный запрос не прошел проверку на разрешение.

PermissionDenied¶

Подпись: PermissionDenied(detail=None, code=None)

Возникает, когда аутентифицированный запрос не прошел проверку на разрешение.

По умолчанию это исключение приводит к ответу с кодом состояния HTTP «403 Forbidden».

NotFound¶

Подпись: NotFound(detail=None, code=None)

Возникает, когда ресурс не существует по заданному URL. Это исключение эквивалентно стандартному исключению Django Http404 .

По умолчанию это исключение приводит к ответу с кодом состояния HTTP «404 Not Found».

MethodNotAllowed¶

Подпись: MethodNotAllowed(method, detail=None, code=None)

Возникает, когда происходит входящий запрос, который не сопоставлен с методом-обработчиком на представлении.

По умолчанию это исключение приводит к ответу с кодом состояния HTTP «405 Method Not Allowed».

Неприемлемо¶

Подпись: NotAcceptable(detail=None, code=None)

Возникает, когда поступает запрос с заголовком Accept , который не может быть удовлетворен ни одним из доступных рендереров.

По умолчанию это исключение приводит к ответу с кодом состояния HTTP «406 Not Acceptable».

Подпись: UnsupportedMediaType(media_type, detail=None, code=None)

Возникает, если при обращении к request.data нет парсеров, способных обработать тип содержимого данных запроса.

По умолчанию это исключение приводит к ответу с кодом состояния HTTP «415 Unsupported Media Type».

Дросселированный¶

Подпись: Throttled(wait=None, detail=None, code=None)

Возникает, когда входящий запрос не проходит проверку на дросселирование.

По умолчанию это исключение приводит к ответу с кодом состояния HTTP «429 Too Many Requests».

ValidationError¶

Подпись: ValidationError(detail, code=None)

Исключение ValidationError несколько отличается от других классов APIException :

Аргумент detail является обязательным, а не опциональным.

Аргумент detail может представлять собой список или словарь сведений об ошибках, а также может быть вложенной структурой данных. Используя словарь, вы можете указать ошибки на уровне полей при выполнении проверки на уровне объектов в методе validate() сериализатора. Например. raise serializers.ValidationError(<‘name’: ‘Please enter a valid name.’>)

По соглашению вы должны импортировать модуль serializers и использовать полностью квалифицированный стиль ValidationError , чтобы отличить его от встроенной ошибки валидации Django. Например. raise serializers.ValidationError(‘This field must be an integer value.’)

Класс ValidationError следует использовать для сериализатора и валидации полей, а также классами валидаторов. Он также возникает при вызове serializer.is_valid с аргументом ключевого слова raise_exception :

Общие представления используют флаг raise_exception=True , что означает, что вы можете переопределить стиль ответов на ошибки валидации глобально в вашем API. Для этого используйте пользовательский обработчик исключений, как описано выше.

По умолчанию это исключение приводит к ответу с кодом состояния HTTP «400 Bad Request».

Общие представления ошибок¶

Django REST Framework предоставляет два представления ошибок, подходящих для предоставления общих JSON 500 Server Error и 400 Bad Request ответов. (Стандартные представления ошибок Django предоставляют ответы в формате HTML, что может не подойти для приложения, использующего только API).

rest_framework.exceptions.server_error ¶

Возвращает ответ с кодом состояния 500 и типом содержимого application/json .

Установить как handler500 :

rest_framework.exceptions.bad_request ¶

Возвращает ответ с кодом состояния 400 и типом содержимого application/json .

Источник

Исключения¶

Исключения… позволяют чисто организовать обработку ошибок в центральном или высокоуровневом месте в структуре программы.

‒ Doug Hellmann, Python Exception Handling Techniques

Обрабатываемыми исключениями являются:

Подклассы APIException, поднятые внутри фреймворка REST.
Исключение Django Http404.
Исключение Django PermissionDenied.

Большинство ответов на ошибки будут содержать ключ detail в теле ответа.

Например, следующий запрос:

DELETE http://api.example.com/foo/bar HTTP/1.1
Accept: application/json

Может быть получен ответ об ошибке, указывающий на то, что метод DELETE не разрешен на данном ресурсе:

HTTP/1.1 405 Method Not Allowed
Content-Type: application/json
Content-Length: 42

{"detail": "Method 'DELETE' not allowed."}

Пример ошибки валидации может выглядеть следующим образом:

HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 94

{"amount": ["A valid integer is required."], "description": ["This field may not be blank."]}

Пользовательская обработка исключений¶

Функция должна принимать пару аргументов, первый из которых — обрабатываемое исключение, а второй — словарь, содержащий любой дополнительный контекст, например, обрабатываемое в данный момент представление. Функция обработчика исключения должна либо вернуть объект Response, либо вернуть None, если исключение не может быть обработано. Если обработчик возвращает None, то исключение будет повторно поднято и Django вернет стандартный ответ HTTP 500 „server error“.

HTTP/1.1 405 Method Not Allowed
Content-Type: application/json
Content-Length: 62

{"status_code": 405, "detail": "Method 'DELETE' not allowed."}

Чтобы изменить стиль ответа, вы можете написать следующий пользовательский обработчик исключений:

from rest_framework.views import exception_handler

def custom_exception_handler(exc, context):
    # Call REST framework's default exception handler first,
    # to get the standard error response.
    response = exception_handler(exc, context)

    # Now add the HTTP status code to the response.
    if response is not None:
        response.data['status_code'] = response.status_code

    return response

Обработчик исключений также должен быть настроен в ваших настройках, используя клавишу настройки EXCEPTION_HANDLER. Например:

REST_FRAMEWORK = {
    'EXCEPTION_HANDLER': 'my_project.my_app.utils.custom_exception_handler'
}

Если параметр 'EXCEPTION_HANDLER' не указан, то по умолчанию используется стандартный обработчик исключений, предоставляемый фреймворком REST:

REST_FRAMEWORK = {
    'EXCEPTION_HANDLER': 'rest_framework.views.exception_handler'
}

Обратите внимание, что обработчик исключений будет вызываться только для ответов, сгенерированных поднятыми исключениями. Он не будет использоваться для любых ответов, возвращаемых непосредственно представлением, например, ответов HTTP_400_BAD_REQUEST, которые возвращаются общими представлениями при неудачной проверке сериализатора.

Справочник по API¶

APIException¶

Подпись: APIException()

базовый класс для всех исключений, возникающих внутри класса APIView или @api_view.

Чтобы обеспечить пользовательское исключение, подкласс APIException и установите атрибуты .status_code , .default_detail , и default_code на класс.

from rest_framework.exceptions import APIException

class ServiceUnavailable(APIException):
    status_code = 503
    default_detail = 'Service temporarily unavailable, try again later.'
    default_code = 'service_unavailable'

Проверка исключений API¶

Доступными атрибутами и методами являются:

.detail — Возвращает текстовое описание ошибки.
.get_codes() — Возвращает идентификатор кода ошибки.
.get_full_details() — Возвращает как текстовое описание, так и идентификатор кода.

В большинстве случаев деталь ошибки будет простым элементом:

>>> print(exc.detail)
You do not have permission to perform this action.
>>> print(exc.get_codes())
permission_denied
>>> print(exc.get_full_details())
{'message':'You do not have permission to perform this action.','code':'permission_denied'}

В случае ошибок валидации деталь ошибки будет представлять собой список или словарь элементов:

>>> print(exc.detail)
{"name":"This field is required.","age":"A valid integer is required."}
>>> print(exc.get_codes())
{"name":"required","age":"invalid"}
>>> print(exc.get_full_details())
{"name":{"message":"This field is required.","code":"required"},"age":{"message":"A valid integer is required.","code":"invalid"}}

ParseError¶

Подпись: ParseError(detail=None, code=None)

Возникает, если запрос содержит неправильно сформированные данные при доступе к request.data.

По умолчанию это исключение приводит к ответу с кодом состояния HTTP «400 Bad Request».

AuthenticationFailed¶

Подпись: AuthenticationFailed(detail=None, code=None)

Возникает, когда входящий запрос содержит неправильную аутентификацию.

NotAuthenticated¶

Подпись: NotAuthenticated(detail=None, code=None)

Возникает, когда неаутентифицированный запрос не прошел проверку на разрешение.

PermissionDenied¶

Подпись: PermissionDenied(detail=None, code=None)

Возникает, когда аутентифицированный запрос не прошел проверку на разрешение.

По умолчанию это исключение приводит к ответу с кодом состояния HTTP «403 Forbidden».

NotFound¶

Подпись: NotFound(detail=None, code=None)

Возникает, когда ресурс не существует по заданному URL. Это исключение эквивалентно стандартному исключению Django Http404.

По умолчанию это исключение приводит к ответу с кодом состояния HTTP «404 Not Found».

MethodNotAllowed¶

Подпись: MethodNotAllowed(method, detail=None, code=None)

По умолчанию это исключение приводит к ответу с кодом состояния HTTP «405 Method Not Allowed».

Неприемлемо¶

Подпись: NotAcceptable(detail=None, code=None)

Возникает, когда поступает запрос с заголовком Accept, который не может быть удовлетворен ни одним из доступных рендереров.

По умолчанию это исключение приводит к ответу с кодом состояния HTTP «406 Not Acceptable».

Дросселированный¶

Подпись: Throttled(wait=None, detail=None, code=None)

Возникает, когда входящий запрос не проходит проверку на дросселирование.

По умолчанию это исключение приводит к ответу с кодом состояния HTTP «429 Too Many Requests».

ValidationError¶

Подпись: ValidationError(detail, code=None)

Исключение ValidationError несколько отличается от других классов APIException:

Аргумент detail является обязательным, а не опциональным.
Аргумент detail может представлять собой список или словарь сведений об ошибках, а также может быть вложенной структурой данных. Используя словарь, вы можете указать ошибки на уровне полей при выполнении проверки на уровне объектов в методе validate() сериализатора. Например. raise serializers.ValidationError({'name': 'Please enter a valid name.'})
По соглашению вы должны импортировать модуль serializers и использовать полностью квалифицированный стиль ValidationError, чтобы отличить его от встроенной ошибки валидации Django. Например. raise serializers.ValidationError('This field must be an integer value.')

Класс ValidationError следует использовать для сериализатора и валидации полей, а также классами валидаторов. Он также возникает при вызове serializer.is_valid с аргументом ключевого слова raise_exception:

serializer.is_valid(raise_exception=True)

Общие представления используют флаг raise_exception=True, что означает, что вы можете переопределить стиль ответов на ошибки валидации глобально в вашем API. Для этого используйте пользовательский обработчик исключений, как описано выше.

По умолчанию это исключение приводит к ответу с кодом состояния HTTP «400 Bad Request».

Общие представления ошибок¶

Django REST Framework предоставляет два представления ошибок, подходящих для предоставления общих JSON 500 Server Error и 400 Bad Request ответов. (Стандартные представления ошибок Django предоставляют ответы в формате HTML, что может не подойти для приложения, использующего только API).

Используйте их в соответствии с Django’s Customizing error views documentation.

`rest_framework.exceptions.server_error`¶

Возвращает ответ с кодом состояния 500 и типом содержимого application/json.

Установить как handler500 :

handler500 = 'rest_framework.exceptions.server_error'

`rest_framework.exceptions.bad_request`¶

Возвращает ответ с кодом состояния 400 и типом содержимого application/json.

Установить как handler400 :

handler400 = 'rest_framework.exceptions.bad_request'

Вернуться на верх

Источник

Exceptions… allow error handling to be organized cleanly in a central or high-level place within the program structure.

— Doug Hellmann, Python Exception Handling Techniques

Exception handling in REST framework views

REST framework’s views handle various exceptions, and deal with returning appropriate error responses.

The handled exceptions are:

Subclasses of APIException raised inside REST framework.
Django’s Http404 exception.
Django’s PermissionDenied exception.

In each case, REST framework will return a response with an appropriate status code and content-type. The body of the response will include any additional details regarding the nature of the error.

Most error responses will include a key detail in the body of the response.

For example, the following request:

DELETE http://api.example.com/foo/bar HTTP/1.1
Accept: application/json

Might receive an error response indicating that the DELETE method is not allowed on that resource:

HTTP/1.1 405 Method Not Allowed
Content-Type: application/json
Content-Length: 42

{"detail": "Method 'DELETE' not allowed."}

An example validation error might look like this:

HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 94

{"amount": ["A valid integer is required."], "description": ["This field may not be blank."]}

Custom exception handling

For example, you might want to ensure that all error responses include the HTTP status code in the body of the response, like so:

HTTP/1.1 405 Method Not Allowed
Content-Type: application/json
Content-Length: 62

{"status_code": 405, "detail": "Method 'DELETE' not allowed."}

In order to alter the style of the response, you could write the following custom exception handler:

from rest_framework.views import exception_handler

def custom_exception_handler(exc, context):
    
    
    response = exception_handler(exc, context)

    
    if response is not None:
        response.data['status_code'] = response.status_code

    return response

The exception handler must also be configured in your settings, using the EXCEPTION_HANDLER setting key. For example:

REST_FRAMEWORK = {
    'EXCEPTION_HANDLER': 'my_project.my_app.utils.custom_exception_handler'
}

If not specified, the 'EXCEPTION_HANDLER' setting defaults to the standard exception handler provided by REST framework:

REST_FRAMEWORK = {
    'EXCEPTION_HANDLER': 'rest_framework.views.exception_handler'
}

API Reference

APIException

Signature:APIException()

The base class for all exceptions raised inside an APIView class or @api_view.

To provide a custom exception, subclass APIException and set the .status_code, .default_detail, and default_code attributes on the class.

from rest_framework.exceptions import APIException

class ServiceUnavailable(APIException):
    status_code = 503
    default_detail = 'Service temporarily unavailable, try again later.'
    default_code = 'service_unavailable'

Inspecting API exceptions

There are a number of different properties available for inspecting the status of an API exception. You can use these to build custom exception handling for your project.

The available attributes and methods are:

.detail — Return the textual description of the error.
.get_codes() — Return the code identifier of the error.
.get_full_details() — Return both the textual description and the code identifier.

In most cases the error detail will be a simple item:

>>> print(exc.detail)
You do not have permission to perform this action.
>>> print(exc.get_codes())
permission_denied
>>> print(exc.get_full_details())
{'message':'You do not have permission to perform this action.','code':'permission_denied'}

In the case of validation errors the error detail will be either a list or dictionary of items:

>>> print(exc.detail)
{"name":"This field is required.","age":"A valid integer is required."}
>>> print(exc.get_codes())
{"name":"required","age":"invalid"}
>>> print(exc.get_full_details())
{"name":{"message":"This field is required.","code":"required"},"age":{"message":"A valid integer is required.","code":"invalid"}}

ParseError

Signature:ParseError(detail=None, code=None)

Raised if the request contains malformed data when accessing request.data.

By default this exception results in a response with the HTTP status code «400 Bad Request».

AuthenticationFailed

Signature:AuthenticationFailed(detail=None, code=None)

Raised when an incoming request includes incorrect authentication.

NotAuthenticated

Signature:NotAuthenticated(detail=None, code=None)

Raised when an unauthenticated request fails the permission checks.

PermissionDenied

Signature:PermissionDenied(detail=None, code=None)

Raised when an authenticated request fails the permission checks.

By default this exception results in a response with the HTTP status code «403 Forbidden».

NotFound

Signature:NotFound(detail=None, code=None)

Raised when a resource does not exists at the given URL. This exception is equivalent to the standard Http404 Django exception.

By default this exception results in a response with the HTTP status code «404 Not Found».

MethodNotAllowed

Signature:MethodNotAllowed(method, detail=None, code=None)

Raised when an incoming request occurs that does not map to a handler method on the view.

By default this exception results in a response with the HTTP status code «405 Method Not Allowed».

NotAcceptable

Signature:NotAcceptable(detail=None, code=None)

Raised when an incoming request occurs with an Accept header that cannot be satisfied by any of the available renderers.

By default this exception results in a response with the HTTP status code «406 Not Acceptable».

UnsupportedMediaType

Signature:UnsupportedMediaType(media_type, detail=None, code=None)

Raised if there are no parsers that can handle the content type of the request data when accessing request.data.

By default this exception results in a response with the HTTP status code «415 Unsupported Media Type».

Throttled

Signature:Throttled(wait=None, detail=None, code=None)

Raised when an incoming request fails the throttling checks.

By default this exception results in a response with the HTTP status code «429 Too Many Requests».

ValidationError

Signature:ValidationError(detail, code=None)

The ValidationError exception is slightly different from the other APIException classes:

The detail argument is mandatory, not optional.
The detail argument may be a list or dictionary of error details, and may also be a nested data structure. By using a dictionary, you can specify field-level errors while performing object-level validation in the validate() method of a serializer. For example. raise serializers.ValidationError({'name': 'Please enter a valid name.'})
By convention you should import the serializers module and use a fully qualified ValidationError style, in order to differentiate it from Django’s built-in validation error. For example. raise serializers.ValidationError('This field must be an integer value.')

serializer.is_valid(raise_exception=True)

By default this exception results in a response with the HTTP status code «400 Bad Request».

Generic Error Views

Django REST Framework provides two error views suitable for providing generic JSON 500 Server Error and 400 Bad Request responses. (Django’s default error views provide HTML responses, which may not be appropriate for an API-only application.)

Use these as per Django’s Customizing error views documentation.

rest_framework.exceptions.server_error

Returns a response with status code 500 and application/json content type.

Set as handler500:

handler500 = 'rest_framework.exceptions.server_error'

rest_framework.exceptions.bad_request

Returns a response with status code 400 and application/json content type.

Set as handler400:

handler400 = 'rest_framework.exceptions.bad_request'

exceptions.py

Django REST Framework

3.14

Caching

A certain woman had very sharp consciousness but almost no memory Caching REST Framework works well with the cache utilities provided Django.
Content negotiation

HTTP has provisions for several mechanisms «content negotiation» the process of selecting best representation given response when there are multiple representations
Serializer fields

Each field in Form class is responsible not only validating data, but also «cleaning» it normalizing consistent format.
Custom fields

If you want to create custom field, you’ll need subclass and then override either one or both of .to_representation() .to_internal_value() methods.

Источник

Есть такая частая задача в бэкенд-разработке: “Как проверить данные, прилетевшие от клиента?”. Действительно ли заполнены обязательные поля? А указанный id существует в БД? А список действительно является списком? Буквально каждый шаг приходится проверять. Выливается всё это к кучу однотипного, простого, но крайне громоздкого кода. Задача это частая, и у неё есть своё название — валидация данных.

Но и проверкой данных дело обычно не заканчивается. Клиент мог прислать строку, а база данных хочет число. Или снова получили строку, но нужна дата datetime.Date. Приходится писать дополнительный код, преобразующий входные данные к нормальному виду. Потому и называют эту задачу нормализацией данных.

Два этих процесса — проверка данных и нормализация — тесно связаны друг с другом, и, обычно их объединяют вместе. Называют этот новый процесс десериализацией данных.

Валидация + Нормализация = Десериализация

Из туториала вы узнаете как эффективно провести десерилизацию: всё надёжно проверить, нормализовать и при этом избавиться от всего этого громоздкого кода.

Работать будем со страничкой сайта ежегодной конференции по маркетингу TheEvent. Это лендинг, сделанный с помощью Bootstrap 4 и Django. На стартовой странице есть форма покупки билетов. К концу этого туториала вы её оживите, написав ручку API для приёма заявок:

Что надо знать

Туториал предполагает, что вы уже хорошо знакомы с Django: легко пишете свои модели, вьюхи и добавляете урлы. Также вам понадобятся общие представления о работе с Django Rest Framework: кто такие @api_view, Parsers и Renderes.

Если знаний у вас пока недостаточно, подтяните их с помощью туториалов:

Как добавить страницу в Django
Модели данных и поля
Как подключить DRF

1. Запустите сайт

Прежде всего вам понадобится заготовка сайта. Возьмите код с GitHub и разверните его у себя. В точности следуйте инструкциям в README. Вот ссылка на репозиторий на GitHub.

Если всё сделано правильно, у вас заработает сайт:

Теперь найдите в репозитории файл enrollment/views.py и загляните в код. Там вы найдёте функцию def enroll(request). Она принимает заявки на участие в конференции и состоит из двух блоков кода. Первый отвечает за проверку данных:

@api_view(['POST'])
def enroll(request):
    if 'contact_phone' not in request.data:
        return Response(['Contact phone field is required.'], status=400)

    if 'ticket_type' not in request.data:
        return Response(['Ticket type field is required.'], status=400)
    # TODO check if ticket_type is one of available choices
    ...

Код проверяет, что клиент указал в заявке оба поля contact_phone и ticket_type. А если одного из них не хватает, то сервер сразу вернёт HTTP 400 с описанием проблемы.

Потестировать работу функции можно с помощью Browsable API. Зайдите на страницу http://127.0.0.1:8000/enroll/ и отправьте пустой JSON объект {}. В ответ прилетит список с одной единственной ошибкой — той, что была обнаружена первой:

[
    "Contact phone field is required."
]

Второй блок кода внутри функции def enroll(request) отвечает за сохранение данных в БД. Он сильно связан с моделью данных в файле enrollment/models.py. Модель включает в себя заявку Application и набор прикреплённых к ней участников Participant:

class Application(models.Model):
    contact_phone = models.CharField(max_length=20)
    ticket_type = models.CharField(max_length=20, db_index=True, ...)
    confirmed = models.BooleanField(default=False, db_index=True)


class Participant(models.Model):
    application = models.ForeignKey(Application, related_name='participants', on_delete=models.CASCADE)
    first_name = models.CharField(max_length=30)
    last_name = models.CharField(max_length=30)
    email = models.EmailField()

Теперь, зная модель данных, можно разобраться со вторым блоком кода функции def enroll(request). Он кладёт поступившую заявку в БД и возвращает её id:

@api_view(['POST'])
def enroll(request):
    ...

    participants = request.data.get('participants', [])  # TODO validate data!

    application = Application.objects.create(
        contact_phone=str(request.data['contact_phone']),
        ticket_type=str(request.data['ticket_type']),
    )

    participants = [Participant(application=application, **fields) for fields in participants]
    Participant.objects.bulk_create(participants)

    return Response({
        'application_id': application.id,
    })

2. Используйте ValidationError

Вот первый фокус, о котором следует знать: декоратор @api_view умеет перехватывать некоторые виды исключений и превращать их в объекты Response. В частности исключение ValidationError будет заменено на Response со статусом HTTP 400. Используйте это. Так было:

@api_view(['POST'])
def enroll(request):
    if 'contact_phone' not in request.data:
        return Response(['Contact phone field is required.'], status=400)

    if 'ticket_type' not in request.data:
        return Response(['Ticket type field is required.'], status=400)
    # TODO check if ticket_type is one of available choices
    ...

Так стало:

from rest_framework.serializers import ValidationError


@api_view(['POST'])
def enroll(request):
    if 'contact_phone' not in request.data:
        raise ValidationError(['Contact phone field is required.'])

    if 'ticket_type' not in request.data:
        raise ValidationError(['Ticket type field is required.'])
    # TODO check if ticket_type is one of available choices
    ...

Новый код делает то же самое, что и старый. Если зайти на страницу http://127.0.0.1:8000/enroll/ и отправить пустой JSON объект {}, то в ответ прилетит HTTP 400 с ошибкой:

[
    "Contact phone field is required."
]

Что удивительно, с исключением ValidationError оказывается работать проще, чем с Response. Теперь код проверки данных не обязательно держать внутри def enroll(request). Можно вынести его наружу в отдельную функцию и тем самым упростить код основной функции enroll:

from rest_framework.serializers import ValidationError


def validate(data):
    if 'contact_phone' not in data:
        raise ValidationError(['Contact phone field is required.'])

    if 'ticket_type' not in data:
        raise ValidationError(['Ticket type field is required.'])
    # TODO check if ticket_type is one of available choices


@api_view(['POST'])
def enroll(request):
    validate(request.data)
    ...

3. Соберите все ошибки

Вы уже заметили этот серьёзный недостаток в коде валидации? Мало того, что данные проверены не особо надёжно, так ещё и валидация обрывается сразу после первой же обнаруженной ошибки. Это крайне раздражающая “фича”. Клиенту придется раз за разом отправлять данные на сервер, только для того, чтобы узнать о следующей своей проблеме. Издевательство …

Можно решить проблему в лоб. Допишите код функции def validate(data), накопите ошибки внутри списка errors прежде, чем выкинуть исключение:

def validate(data):
    errors = []
    if 'contact_phone' not in data:
        errors.append('Contact phone field is required.')

    if 'ticket_type' not in data:
        errors.append('Ticket type field is required.')
    # TODO check if ticket_type is one of available choices

    if errors:
        raise ValidationError(errors)

Проверьте как это работает. Зайдите на страницу http://127.0.0.1:8000/enroll/, отправьте пустой JSON объект {}. В ответ прилетит сразу пара ошибок:

[
    "Contact phone field is required.",
    "Ticket type field is required."
]

4. Подключите Serializer

Теперь Django Rest Framework может предложить вам ещё кое-что очень интересное! У него есть замена для вашей функции def validate(data). В DRF встроен механизм десериализации на базе всё того же исключения ValidationError, но с кучей плюшек и готовых решений.

Основной инструмент для десериализации в DRF — это класс Serializer или, по-русски, сериализатор. Да-да, вам не почудилось. В DRF и сериализацию и десериализацию выполняет один и тот же класс. Причём в этом туториале вы будете использовать Serializer исключительно в качестве десериализатора. Такая вот странная несостыковка в названиях.

Класс Serializer позволяет описать схему данных таким образом, что DRF сам сгенерует код аналогичный вашей функции def validate(data). Так было:

def validate(data):
    errors = []
    if 'contact_phone' not in data:
        errors.append('Contact phone field is required.')

    if 'ticket_type' not in data:
        errors.append('Ticket type field is required.')
    # TODO check if ticket_type is one of available choices

    if errors:
        raise ValidationError(errors)

А так стало:

from rest_framework.serializers import Serializer
from rest_framework.serializers import CharField


class ApplicationSerializer(Serializer):
    contact_phone = CharField()
    ticket_type = CharField()


def validate(data):
    serializer = ApplicationSerializer(data=data)
    serializer.is_valid(raise_exception=True)  # выкинет ValidationError

Вот что здесь происходит. Сначала создаётся класс ApplicationSerializer — он описывает схему данных. Здесь указаны текстовые поля contact_phone и ticket_type. DRF будет считать эти поля обязательными для заполнения, если не указать обратное в дополнительных настройках CharField.

Внутри функции def validate(data) всего две строки кода. Сначала сериализатор ApplicationSerializer получает входные данные data, после чего запускается их проверка с помощью метода is_valid. Если данные не будут соответствовать схеме, описанной внутри ApplicationSerializer, то вызов метода is_valid(raise_exception=True) приведёт к исключению ValidationError.

Поведение функции def validate(data) осталось прежним, но код с условиями if теперь заменён на простую и наглядную декларацию схемы данных. Теперь можно пойти дальше и отказаться от более ненужной функции def validate(data). Её код переезжает внутрь enroll:

from rest_framework.serializers import Serializer
from rest_framework.serializers import CharField


class ApplicationSerializer(Serializer):
    contact_phone = CharField()
    ticket_type = CharField()


@api_view(['POST'])
def enroll(request):
    serializer = ApplicationSerializer(data=request.data)
    serializer.is_valid(raise_exception=True)  # выкинет ValidationError
    ...

Проверьте как это работает. Зайдите на страницу http://127.0.0.1:8000/enroll/, отправьте пустой JSON объект {}. В ответ прилетят ошибки:

{
    "contact_phone": [
        "This field is required."
    ],
    "ticket_type": [
        "This field is required."
    ]
}

Формат ответа немного отличается от того, что было раньше. Теперь каждая ошибка привязана к полю, в котором она возникла. Это весьма удобно, когда данных становится много и из текста ошибки уже не понять о каком поле идёт речь.

5. Проверьте ticket_type

В коде не хватает ещё одной проверки. База данных требует, чтобы поле ticket_type соответствовало одному из трёх разрешённых значений. В файле enrollment/models.py есть такой код:

class Application(models.Model):
    ...
    ticket_type = models.CharField(max_length=20, db_index=True, choices=(
        ('standard-access', 'Standard Access'),
        ('pro-access', 'Pro Access'),
        ('premium-access', 'Premium Access'),
    ))

Настройка choices разрешает лишь три возможных значения для поля ticket_type: 'standard-access', 'pro-access' и 'premium-access'. Добавьте соответствующую проверку в API.

Вам понадобится новый метод validate_ticket_type. DRF уже знает о том, что в схеме данных есть поле ticket_type, а потому будет искать и метод с похожим названием вида validate_{fieldname}. Если такой метод найдётся внутри сериализатора, то DRF автоматически вызовет его в конце проверки данных.

class ApplicationSerializer(Serializer):
    contact_phone = CharField()
    ticket_type = CharField()

    def validate_ticket_type(self, value):
        if value not in ['standard-access', 'pro-access', 'premium-access']:
            raise ValidationError('Wrong value')
        return value

Метод validate_ticket_type очень похож на старую функцию def validate(data). Первое отличие здесь в том, что метод validate_ticket_type проверяет одно единственное поле ticket_type и ничего не знает об остальных данных. Второе отличие — метод не только проверяет данные, но и возвращает значение return value. Дело здесь в том, что DRF позволяет не только проверять данные, но и нормализовать их. Например, можно было привести текст к верхнему регистру или нижнему, обрезать или обработать другим образом. Здесь эта возможность не используется, но DRF требует вернуть значение, и поэтому функция возвращает то, что сама получила на вход — аргумент value.

Проверьте как это работает. Со страницы http://127.0.0.1:8000/enroll/ отправьте такой JSON:

{"ticket_type": "unknown"}

В ответ прилетит новое сообщение об ошибке 'Wrong value':

{
    "contact_phone": [
        "This field is required."
    ],
    "ticket_type": [
        "Wrong value"
    ]
}

Обратите внимание, что ошибка в поле contact_phone никак не повлияла на проверку поля ticket_type. DRF проверяет поля раздельно и независимо друг от друга. Более того, ValidationError в функциях validate_ticket_type и is_valid — это не одно, а два разных исключения. Присмотритесь внимательно к коду:

class ApplicationSerializer(Serializer):
    ...

    def validate_ticket_type(self, value):
        if value not in ['standard-access', 'pro-access', 'premium-access']:
            raise ValidationError('Wrong value')
        return value

@api_view(['POST'])
def enroll(request):
    serializer = ApplicationSerializer(data=request.data)
    serializer.is_valid(raise_exception=True)  # выкинет ValidationError
    ...

В первом случае ValidationError содержит описание одной единственной проблемы 'Wrong value' для поля ticket_type. Во втором случае исключение получает целый словарь с набором ошибок:


{
    "contact_phone": [
        "This field is required."
    ],
    "ticket_type": [
        "Wrong value"
    ]
}

Фокус здесь в том, что сериализатор ApplicationSerializer перехватывает внутри себя все исключения ValidationError. Сначала он накапливает их, переупаковывает их данные в словарь, а в конце проверки выкидывает новое исключение ValidationError с полным набором ошибок внутри.

6. Замените код на ModelSerializer

На это магия DRF не заканчивается. Помимо класса Serializer есть аналогичный класс ModelSerializer. Отличается он тем, что сам умеет описывать схему данных на основе модели данных. Всё что нужно сделать — это указать на модель данных и перечислить интересующие поля:

from rest_framework.serializers import ModelSerializer


class ApplicationSerializer(ModelSerializer):
    class Meta:
        model = Application
        fields = ['contact_phone', 'ticket_type']

И что совсем здорово, ModelSerializer проверяет данные идеально точно. Вы помните об ограничении на максимальную длину строки contact_phone в модели данных? Нет? А ведь она там есть! Файл :

class Application(models.Model):
    contact_phone = models.CharField(max_length=20)
    ...

Вы только полюбуйтесь, насколько точно сработал ModalSerializer! Добавьте отладочный print:

class ApplicationSerializer(ModelSerializer):
    class Meta:
        model = Application
        fields = ['contact_phone', 'ticket_type']


print(repr(ApplicationSerializer()))

В консоли вы увидите все настройки сериализатора:

ApplicationSerializer():
    contact_phone = CharField(max_length=20)
    ticket_type = ChoiceField(choices=(('standard-access', 'Standard Access'), ('pro-access', 'Pro Access'), ('premium-access', 'Premium Access')))

Ну не прекрасно ли это! На самом деле, пропустить что-то в настройках схемы данных довольно просто, поэтому при любой возможности старайтесь использовать ModelSerializer.

ModelSerializer — когда пишешь данные в БД

И теперь увесистая такая ложка дёгтя… Класс ModelSerializer превращается в тыкву, если клиент API присылает вам данные с другими названиями полей, отличными от того, что лежит у вас в БД. Если клиент присылает firstname, а в БД поле называется first_name, то никакого легального способа переименовать автоматически сгенерированное поле ModelSerializer у вас не будет. Варианта действий здесь два. Первый — пойти ругаться с фронтендером и требовать переименовать поля. Второй — отказаться от автоматической генерации полей и добавить их вручную. Вот обсуждение проблемы на StackOverflow. А в документации можно почитать про настройку source.

В остальном поведение ModelSerializer в точности повторяет обычный Serializer. Ему точно так же можно добавлять методы, поля и прочие настройки. В любой ситуации Serializer можно заменить на ModelSerializer и наоборот.

7. Проверьте участников

Заявка от клиента помимо двух полей contact_phone и ticket_type может содержать ещё целый список полей participants. Им тоже нужна своя валидация.

Подход к проблеме здесь прежний. Просто создайте ещё один ModelSerializer для модели Participant. Так выглядил прежний код:

@api_view(['POST'])
def enroll(request):
    serializer = ApplicationSerializer(data=request.data)
    serializer.is_valid(raise_exception=True)  # выкинет ValidationError

    participants = request.data.get('participants', [])  # TODO validate data!
    ...

Так выглядит новая версия:

class ParticipantSerializer(ModelSerializer):
    class Meta:
        model = Participant
        fields = ['first_name', 'last_name', 'email']


@api_view(['POST'])
def enroll(request):
    serializer = ApplicationSerializer(data=request.data)
    serializer.is_valid(raise_exception=True)  # выкинет ValidationError

    participants = request.data.get('participants', [])
    if not isinstance(participants, list):
        raise ValidationError('Expects participants field be a list')

    for fields in participants:
        serializer = ParticipantSerializer(data=fields)
        serializer.is_valid(raise_exception=True)  # выкинет ValidationError
    ...

Проверьте как это работает. Со страницы http://127.0.0.1:8000/enroll/ отправьте пустой JSON объект {}. Ответ будет таким:

{
    "contact_phone": [
        "This field is required."
    ],
    "ticket_type": [
        "This field is required."
    ]
}

Примечательно, что до проверки поля participants дело даже не дошло. Снова всплыла старая проблема — валидация прерывается после первого же “сломанного” сериализатора ApplicationSerializer, и второй ParticipantSerializer даже не запускается. Решить проблему можно собрав все проверки внутри одного основного сериализатора ApplicationSerializer. Для этого пригодится новый трюк DRF — вложенные сериализаторы.

8. Объедините сериализаторы

Каждый сериализатор в DRF описывает свою схему данных и, комбинируя их, можно из нескольких простых схем собрать одну большую сложную. Есть несколько способов такой композиции. Например, можно использовать сериализатор подобно обычному полю CharField:

class ApplicationSerializer(ModelSerializer):
    participant = ParticipantSerializer()

    class Meta:
        model = Application
        fields = ['contact_phone', 'ticket_type', 'participant']

Такая схема данных помимо полей contact_phone и ticket_type будет ожидать словарь participant. Вот пример входных данных:

{
    "contact_phone": "+1 5612 ...",
    "ticket_type": "pro-access",
    "participant": {
        "first_name": "Bob",
        "last_name": "Smith",
        "email": "mail@example.com"
    }
}

Однако, вам в заявке от клиента прилетает не словарь, а целый список словарей. На этот случай в DRF есть специальный тип поля ListField. Он представляет из себя список любых объектов: строк, чисел, чего угодно. Даже можно положить туда другой сериализатор:

from rest_framework.serializers import ListField


class ApplicationSerializer(ModelSerializer):
    participants = ListField(
        child=ParticipantSerializer()
    )
    class Meta:
        model = Application
        fields = ['contact_phone', 'ticket_type', 'participants']

Пора проверить как всё это работает. Снова зайдите на страницу http://127.0.0.1:8000/enroll/ и отправьте JSON:

{
    "ticket_type": "pro-access",
    "participants": [
        { "first_name": "Bob" }
    ]
}

Ответ сервера будет таким:

{
    "contact_phone": [ "This field is required." ],
    "participants": {
        "0": {
            "last_name": [ "This field is required." ],
            "email": [ "This field is required." ]
        }
    }
}

Для ListField в DRF существует альтернативная короткая форма записи:

class ApplicationSerializer(ModelSerializer):
    participants = ParticipantSerializer(many=True)  # обратите внимание на many=True

    class Meta:
        model = Application
        fields = ['contact_phone', 'ticket_type', 'participants']

Интересно, как это работает? Без чёрной магии тут не обошлось… Сериализатор ParticipantSerializer меняет стандартное поведение конструктора __new__. Обычно конструктор просто создаёт экземпляр своего класса ParticipantSerializer, но здесь всё хитрее. Конструктор замечает параметр many=True и вместо экземпляра ParticipantSerializer создаёт экземпляр другого класса ListField. Получается тот же результат, что и при явном вызове:

ListField(
    child=ParticipantSerializer()
)

9. Откажитесь от сырых данных

Наконец-то можно переписать и вторую последнюю часть кода функции def enroll(request) — ту часть, где происходит запись в БД.

@api_view(['POST'])
def enroll(request):
    serializer = ApplicationSerializer(data=request.data)
    serializer.is_valid(raise_exception=True)  # выкинет ValidationError

    participants = request.data.get('participants', [])

    application = Application.objects.create(
        contact_phone=str(request.data['contact_phone']),
        ticket_type=str(request.data['ticket_type']),
    )

    participants = [Participant(application=application, **fields) for fields in participants]
    Participant.objects.bulk_create(participants)

    return Response({
        'application_id': application.id,
    })

Этот код исправно работает. И выглядит он лаконично. Тогда что же с ним не так?! Здесь нарушен запрет на работу с сырыми данными.

Объект request.data содержит в себе абсолютно все данные, что прислал вам пользователь. Здесь есть и те поля, что вы надёжно проверили, и те, о проверке которых вы могли забыть. Чистые обработанные данные здесь смешаны с грязными и сырыми. Стоит один раз промахнуться ключом или забыть что-то проверить, и вы получите угрозу взлома сервера и ещё гору мусора в БД в придачу.

Здесь снова выручит сериализатор ApplicationSerializer. Помимо проверки данных (валидации) он берёт на себя и нормализацию. Все обработанные чистые данные он складывает в атрибут validated_data. В отличии от request.data там не может быть сырых данных, а потому использовать validated_data вполне безопасно. Так будет выглядеть исправленный код:

@api_view(['POST'])
def enroll(request):
    serializer = ApplicationSerializer(data=request.data)
    serializer.is_valid(raise_exception=True)  # выкинет ValidationError


    application = Application.objects.create(
        contact_phone=serializer.validated_data['contact_phone'],
        ticket_type=serializer.validated_data['ticket_type'],
    )

    participants_fields = serializer.validated_data['participants']
    participants = [Participant(application=application, **fields) for fields in participants_fields]
    Participant.objects.bulk_create(participants)

    return Response({
        'application_id': application.id,
    })

Теперь вместо request.data всюду используется serializer.validated_data, что защищает код от неосторожной работы с сырыми данными.

Никогда не берите данные напрямую из request.data

Читать дальше

Официальный туториал по сериализации
Документация к Serializer
Документация к Serializer fields
Marshmallow — альтернативная библиотека для сериализации и десериализации

Источник

Writing in the front

These two days, I have been thinking about the basic knowledge about DRF which is necessary for the project and has not been mentioned yet. This is not written yesterday to log related functions directly think of the exception handling functions, in fact in the early project was not a uniform means of exception catching. Either the DRF has built-in exceptions that fit most of the functionality, or it is lazy and throws exceptions in a rude way, using status code 500, and then you can see all the exception information in the log. In this way, the code is not robust enough, and the front end is not friendly enough to invoke 500, so today I will supplement the knowledge about exceptions.

DRF exception handling

1. Common DRF exceptions

AuthenticationFailed/ NotAuthenticated Generally, the exception status code is «401 Unauthenticated», which is returned when there is no login authentication. It can be used for custom login.
PermissionDenied Is used during authentication. The normal status code is 403 Forbidden.
The ValidationError status code is «400 Bad Request». It is used in serializers to verify fields, such as field types, field length, and custom field formats.

2. Customize exceptions

The main idea for defining an exception here comes from ValidationError, to unify the format of the return of an exception so that the front end can handle similar exceptions uniformly.

Custom exception

# new utils/custom_exception. Py

class CustomException(Exception) :
    _default_code = 400

    def __init__(
        self,
        message: str = "",
        status_code=status.HTTP_400_BAD_REQUEST,
        data=None,
        code: int = _default_code,
    ) :

        self.code = code
        self.status = status_code
        self.message = message
        if data is None:
            self.data = {"detail": message}
        else:
            self.data = data

    def __str__(self) :
        return self.message
Copy the code

Custom exception handling

# utils/custom_exception.py
from rest_framework.views import exception_handler

def custom_exception_handler(exc, context) :

Configure a custom exception handling class

REST_FRAMEWORK = {
    # ...
    "EXCEPTION_HANDLER": "utils.custom_exception.custom_exception_handler",
}
Copy the code

3. Use user-defined exceptions

Use the interface from the previous article to test the handling of custom exceptions

class ArticleViewSet(viewsets.ModelViewSet) :
    API path that allows users to view or edit. "" "
    queryset = Article.objects.all()
    serializer_class = ArticleSerializer

    @action(detail=False, methods=["get"], url_name="exception", url_path="exception")
    def exception(self, request, *args, **kwargs) :

4. Verify the result

$ curl -H 'Accept: application/json; indent=4'{-u admin: admin http://127.0.0.1:8000/api/article/exception/"detail": "Custom exceptions"
}
Copy the code

Exception handling advanced

The above code satisfies 90% of the requirements, but the error definition is too general. It is difficult to centrally define management errors and has the advantage of flexibility over custom exceptions in common projects, but with more exceptions thrown in the code and scattered around the corners, it is not easy to update and maintain. So let’s change the code to have a uniform definition of exceptions, as well as support for custom HTTP status codes.

1. Modify user-defined exceptions

# utils/custom_exception.py

class CustomException(Exception) :

2. Customize more exceptions

class ExecuteError(CustomException) :
    """ Execution error """
    default_code = 500
    default_message = "Execution error"


class UnKnowError(CustomException) :
    """ Execution error """
    default_code = 500
    default_message = "Unknown error"

Copy the code

3. Add test interfaces

class ArticleViewSet(viewsets.ModelViewSet) :
    API path that allows users to view or edit. "" "
    queryset = Article.objects.all()
    serializer_class = ArticleSerializer

    @action(detail=False, methods=["get"], url_name="exception", url_path="exception")
    def exception(self, request, *args, **kwargs) :

4. Verify the result

curl -H 'Accept: application/json; indent=4' -u admin:admin http://127.0. 01.:8000/api/article/unknown/
{
    "detail": "Unknown error"."code": 500
}
$ curl -H 'Accept: application/json; indent=4' -u admin:admin http://127.0. 01.:8000/api/article/execute/
{
    "detail": "Execution error"."code": 500
}

Copy the code

conclusion

Note that the custom exception handler needs to continue executing after the custom exception is processedrest_framework.views.exception_handlerBecause the execution here still needs to be compatible with existing exception handling; Here is the drF-related exception handling logic.

By default, this handler handles APIException and Django’s internal Http404 PermissionDenied. Other exceptions will return None, which will trigger a DRF 500 error.


def exception_handler(exc, context) :
    """ Returns the response that should be used for any given exception. By default we handle the REST framework `APIException`, and also Django's built-in `Http404` and `PermissionDenied` exceptions. Any unhandled exceptions may return `None`, which will cause a 500 error to be raised. """
    if isinstance(exc, Http404):
        exc = exceptions.NotFound()
    elif isinstance(exc, PermissionDenied):
        exc = exceptions.PermissionDenied()

    if isinstance(exc, exceptions.APIException):
        headers = {}
        if getattr(exc, 'auth_header'.None):
            headers['WWW-Authenticate'] = exc.auth_header
        if getattr(exc, 'wait'.None):
            headers['Retry-After'] = '%d' % exc.wait

        if isinstance(exc.detail, (list.dict)):
            data = exc.detail
        else:
            data = {'detail': exc.detail}

        set_rollback()
        return Response(data, status=exc.status_code, headers=headers)

    return None

Copy the code

The resources

Django REST Framework exception documentation
Django Exception Documentation

Источник