Парсеры

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

— Малкольм Трединник, Группа разработчиков Django

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

Как определяется парсер

Набор допустимых парсеров для представления всегда определяется как список классов. При обращении к request.data, REST фреймворк проверит заголовок Content-Type в входящем запросе и определит, какой парсер использовать для разбора содержимого запроса.

Примечание: При разработке клиентских приложений всегда помните, что необходимо установить заголовок Content-Type при отправке данных в HTTP-запросе.

Если вы не зададите тип контента, большинство клиентов по умолчанию будут использовать 'application/x-www-form-urlencoded', что может не соответствовать вашим ожиданиям.

Например, если вы отправляете данные, закодированные в json, с помощью jQuery с методом .ajax(), убедитесь, что включен параметр contentType: 'application/json'.

Установка парсеров

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

REST_FRAMEWORK = {
    'DEFAULT_PARSER_CLASSES': [
        'rest_framework.parsers.JSONParser',
    ]
}

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

from rest_framework.parsers import JSONParser
from rest_framework.response import Response
from rest_framework.views import APIView

class ExampleView(APIView):
    """
    A view that can accept POST requests with JSON content.
    """
    parser_classes = [JSONParser]

    def post(self, request, format=None):
        return Response({'received data': request.data})

Или, если вы используете декоратор @api_view с представлениями на основе функций.

from rest_framework.decorators import api_view
from rest_framework.decorators import parser_classes
from rest_framework.parsers import JSONParser

@api_view(['POST'])
@parser_classes([JSONParser])
def example_view(request, format=None):
    """
    A view that can accept POST requests with JSON content.
    """
    return Response({'received data': request.data})

Справочник API

JSONParser

Парсит содержимое запроса JSON. request.data будет заполнен словарем данных.

.media_type: application/json

FormParser

Парсит содержимое HTML-формы. request.data будет заполнен QueryDict данных.

Обычно рекомендуется использовать вместе FormParser и MultiPartParser для полной поддержки данных HTML-форм.

.media_type: application/x-www-form-urlencoded

MultiPartParser

Парсит содержимое multipart HTML-формы, поддерживающее загрузку файлов. request.data и request.FILES будут заполнены QueryDict и MultiValueDict соответственно.

Обычно рекомендуется использовать вместе FormParser и MultiPartParser для полной поддержки данных HTML-форм.

.media_type: multipart/form-data

FileUploadParser

Парсит содержимое сырой загрузки файла. Свойство request.data будет словарем с единственным ключом 'file', содержащим загруженный файл.

Если представление, используемое с FileUploadParser, вызывается с аргументом URL filename, то этот аргумент будет использован как имя файла.

Если представление вызывается без аргумента filename URL, то клиент должен установить имя файла в заголовке Content-Disposition HTTP. Например, Content-Disposition: attachment; filename=upload.jpg.

.media_type: */*

Примечания:

• FileUploadParser предназначен для использования с собственными клиентами, которые могут загрузить файл в виде запроса с сырыми данными. Для загрузки файлов через веб или для собственных клиентов с поддержкой multipart загрузки следует использовать MultiPartParser.
• Поскольку соответствие парсера media_type совпадает с любым типом контента, FileUploadParser обычно должен быть единственным установленным парсером на представлении API.
• FileUploadParser учитывает стандартный параметр Django FILE_UPLOAD_HANDLERS и атрибут request.upload_handlers. См. документацию Django для получения дополнительной информации.

Пример использования:

# views.py
class FileUploadView(views.APIView):
    parser_classes = [FileUploadParser]

    def put(self, request, filename, format=None):
        file_obj = request.data['file']
        # ...
        # do some stuff with uploaded file
        # ...
        return Response(status=204)

# urls.py
urlpatterns = [
    # ...
    re_path(r'^upload/(?P<filename>[^/]+)$', FileUploadView.as_view())
]

Пользовательские парсеры

Для реализации пользовательского парсера необходимо переопределить BaseParser, установить свойство .media_type и реализовать метод .parse(self, stream, media_type, parser_context).

Метод должен вернуть данные, которые будут использоваться для заполнения свойства request.data.

Аргументы, передаваемые в .parse(), это:

Поток

Объект потокового типа, представляющий тело запроса.

Тип медиа

Необязательно. Если предоставлен, это тип медиа входящего содержимого запроса.

В зависимости от заголовка Content-Type: запроса, он может быть более конкретным, чем атрибут media_type обработчика, и может включать параметры типа медиа. Например, "text/plain; charset=utf-8".

Контекст парсера

Необязательно. Если указан, этот аргумент будет словарем, содержащим дополнительный контекст, который может потребоваться для разбора содержимого запроса.

По умолчанию он будет включать следующие ключи: view, request, args, kwargs.

Пример

Следующий пример парсера обычного текста, который заполнит свойство request.data строкой, представляющей тело запроса.

class PlainTextParser(BaseParser):
    """
    Plain text parser.
    """
    media_type = 'text/plain'

    def parse(self, stream, media_type=None, parser_context=None):
        """
        Simply return a string representing the body of the request.
        """
        return stream.read()

Пакеты сторонних разработчиков

Также доступны следующие пакеты сторонних разработчиков.

YAML

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

Установка и настройка

Установите с помощью pip.

$ pip install djangorestframework-yaml

Измените настройки REST фреймворка.

REST_FRAMEWORK = {
    'DEFAULT_PARSER_CLASSES': [
        'rest_framework_yaml.parsers.YAMLParser',
    ],
    'DEFAULT_RENDERER_CLASSES': [
        'rest_framework_yaml.renderers.YAMLRenderer',
    ],
}

XML

REST фреймворк XML предоставляет простой неформатированный формат XML. Ранее он был включён непосредственно в пакет REST фреймворка, теперь он поддерживается как пакет сторонних разработчиков.

Установка и настройка

Установите с помощью pip.

$ pip install djangorestframework-xml

Измените настройки REST фреймворка.

REST_FRAMEWORK = {
    'DEFAULT_PARSER_CLASSES': [
        'rest_framework_xml.parsers.XMLParser',
    ],
    'DEFAULT_RENDERER_CLASSES': [
        'rest_framework_xml.renderers.XMLRenderer',
    ],
}

MessagePack

MessagePack — это быстрый и эффективный бинарный формат сериализации. Хуан Риаза поддерживает пакет djangorestframework-msgpack, который предоставляет поддержку MessagePack рендеринга и парсинга для REST фреймворка.

CamelCase JSON

djangorestframework-camel-case предоставляет рендеры и парсеры JSON с использованием camelCase для REST фреймворка. Это позволяет сериализаторам использовать имена полей с нижним подчеркиванием Python, но отображать их в API с именами полей camelCase JavaScript. Поддерживается Виталием Бабием.

parsers.py