Объекты запроса и ответа

Краткий обзор

Django использует объекты запроса и ответа для передачи состояния через систему.

Когда страница запрашивается, Django создает объект HttpRequest, содержащий метаданные о запросе. Затем Django загружает соответствующий вид, передавая объект HttpRequest в качестве первого аргумента функции представления. Каждое представление отвечает за возврат объекта HttpResponse.

Этот документ объясняет API для объектов HttpRequest и HttpResponse, которые определены в модуле django.http.

HttpRequest объекты

class HttpRequest

Атрибуты

Все атрибуты следует считать только для чтения, если не указано иное.

HttpRequest.scheme

Строка, представляющая схему запроса (http или https обычно).

HttpRequest.body

Необработанное тело HTTP-запроса в виде байтовой строки. Это полезно для обработки данных нестандартными способами, отличными от обычных HTML-форм: бинарные изображения, XML-payload и т. д. Для обработки обычных данных форм используйте HttpRequest.POST.

Вы также можете читать из HttpRequest с помощью интерфейса типа файла с помощью HttpRequest.read() или HttpRequest.readline(). Доступ к атрибуту body после чтения запроса с помощью любого из этих методов потока ввода/вывода приведет к RawPostDataException.

HttpRequest.path

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

Пример: "/music/bands/the_beatles/"

HttpRequest.path_info

При некоторых конфигурациях веб-сервера часть URL после имени хоста разделяется на часть префикса скрипта и часть path info. Атрибут path_info всегда содержит часть path info пути, независимо от используемого веб-сервера. Использование этого вместо path может сделать ваш код более совместимым между тестовыми и развернутыми серверами.

Например, если префикс скрипта WSGIScriptAlias для вашего приложения установлен на "/minfo", то path может быть "/minfo/music/bands/the_beatles/", а path_info будет "/music/bands/the_beatles/".

HttpRequest.method

Строка, представляющая HTTP-метод, используемый в запросе. Гарантируется, что он будет в верхнем регистре. Например:

if request.method == 'GET':
    do_something()
elif request.method == 'POST':
    do_something_else()

HttpRequest.encoding

Строка, представляющая текущее кодирование, используемое для декодирования данных отправки формы (или None, что означает, что используется настройка DEFAULT_CHARSET). Вы можете записать в этот атрибут, чтобы изменить кодировку, используемую при доступе к данным формы. Любые последующие обращения к атрибутам (такие как чтение из GET или POST) будут использовать новое значение encoding. Полезно, если вы знаете, что данные формы не находятся в кодировке DEFAULT_CHARSET.

HttpRequest.content_type

Строка, представляющая MIME-тип запроса, полученная из заголовка CONTENT_TYPE.

HttpRequest.content_params

Словарь параметров ключ/значение, включенных в заголовок CONTENT_TYPE.

HttpRequest.GET

Объект, подобный словарю, содержащий все параметры HTTP GET. См. документацию QueryDict ниже.

HttpRequest.POST

Объект, подобный словарю, содержащий все параметры HTTP POST, при условии, что запрос содержит данные формы. См. документацию QueryDict ниже. Если вам нужно получить доступ к сырым или неформатированным данным, отправленным в запросе, обратитесь к атрибуту HttpRequest.body вместо этого.

Возможен случай, когда запрос приходит по POST с пустым POST словарем – если, скажем, форма запрошена через HTTP-метод POST, но не содержит данных формы. Поэтому не следует использовать if request.POST для проверки использования метода POST; вместо этого используйте if request.method == "POST" (см. HttpRequest.method).

POST не включает информацию о загрузке файлов. См. FILES.

HttpRequest.COOKIES

Словарь, содержащий все cookie. Ключи и значения являются строками.

HttpRequest.FILES

Объект, подобный словарю, содержащий все загруженные файлы. Каждый ключ в FILES – это name из <input type="file" name="">. Каждое значение в FILES – это UploadedFile.

См. Управление файлами для получения дополнительной информации.

FILES будет содержать данные только в том случае, если метод запроса был POST, и <form>, отправленный в запрос, содержал enctype="multipart/form-data". В противном случае FILES будет пустым объектом, подобным словарю.

HttpRequest.META

Словарь, содержащий все доступные HTTP-заголовки. Доступные заголовки зависят от клиента и сервера, но вот некоторые примеры:

• CONTENT_LENGTH – Длина тела запроса (как строка).
• CONTENT_TYPE – MIME-тип тела запроса.
• HTTP_ACCEPT – Допустимые типы содержимого для ответа.
• HTTP_ACCEPT_ENCODING – Допустимые кодировки для ответа.
• HTTP_ACCEPT_LANGUAGE – Допустимые языки для ответа.
• HTTP_HOST – Заголовок HTTP Host, отправленный клиентом.
• HTTP_REFERER – Ссылка на страницу, если она есть.
• HTTP_USER_AGENT – Строка user-agent клиента.
• QUERY_STRING – Строка запроса как единая (неразборная) строка.
• REMOTE_ADDR – IP-адрес клиента.
• REMOTE_HOST – Имя хоста клиента.
• REMOTE_USER – Пользователь, авторизованный веб-сервером, если он есть.
• REQUEST_METHOD – Строка, такая как "GET" или "POST".
• SERVER_NAME – Имя хоста сервера.
• SERVER_PORT – Порт сервера (как строка).

За исключением CONTENT_LENGTH и CONTENT_TYPE, как указано выше, все HTTP-заголовки в запросе преобразуются в ключи META путем преобразования всех символов в верхний регистр, замены дефисов на подчеркивания и добавления префикса HTTP_ к имени. Таким образом, заголовок с именем X-Bender будет сопоставлен с ключом META HTTP_X_BENDER.

Обратите внимание, что runserver удаляет все заголовки с подчеркиваниями в имени, поэтому вы их не увидите в META. Это предотвращает подделку заголовков, основанную на неоднозначности между подчеркиваниями и дефисами, которые оба нормализуются до подчеркиваний в переменных среды WSGI. Это поведение соответствует поведению веб-серверов, таких как Nginx и Apache 2.4+.

HttpRequest.headers является более простым способом доступа ко всем заголовкам, начинающимся с HTTP (плюс CONTENT_LENGTH и CONTENT_TYPE).

HttpRequest.headers

New in Django 2.2.

Объект типа словаря, нечувствительный к регистру, предоставляющий доступ ко всем заголовкам HTTP (плюс Content-Length и Content-Type в запросе).

Имя каждого заголовка стилизуется с использованием заглавных букв (например, User-Agent) при отображении. Вы можете получить доступ к заголовкам, не обращая внимания на регистр:

>>> request.headers
{'User-Agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6', ...}

>>> 'User-Agent' in request.headers
True
>>> 'user-agent' in request.headers
True

>>> request.headers['User-Agent']
Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6)
>>> request.headers['user-agent']
Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6)

>>> request.headers.get('User-Agent')
Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6)
>>> request.headers.get('user-agent')
Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6)

Для использования, например, в шаблонах Django, заголовки также можно искать, используя подчеркивания вместо дефисов:

{{ request.headers.user_agent }}

Изменено в Django 3.0:

Добавлена поддержка поиска с использованием подчеркиваний.

HttpRequest.resolver_match

Экземпляр ResolverMatch, представляющий разрешенный URL. Этот атрибут устанавливается только после разрешения URL, что означает, что он доступен во всех представлениях, но не в middleware, которые выполняются до разрешения URL (хотя вы можете использовать его в process_view()).

Атрибуты, устанавливаемые кодом приложения

Django не устанавливает эти атрибуты самостоятельно, но использует их, если они установлены вашим приложением.

HttpRequest.current_app

Тег шаблона url будет использовать его значение в качестве аргумента current_app к reverse().

HttpRequest.urlconf

Это будет использоваться как корневой URLconf для текущего запроса, перезаписывая настройку ROOT_URLCONF. Подробности см. в Как Django обрабатывает запрос.

urlconf может быть установлено в None для отмены любых изменений, внесенных предыдущим middleware, и возвращения к использованию ROOT_URLCONF.

Атрибуты, устанавливаемые middleware

Некоторые из middleware, включённые в приложения Django's contrib, устанавливают атрибуты на запрос. Если вы не видите атрибут в запросе, убедитесь, что соответствующий класс middleware указан в MIDDLEWARE.

HttpRequest.session

Из SessionMiddleware: Читаемый и записываемый, подобный словарю объект, представляющий текущую сессию.

HttpRequest.site

Из CurrentSiteMiddleware: Экземпляр Site или RequestSite, как возвращается get_current_site(), представляющий текущий сайт.

HttpRequest.user

Из AuthenticationMiddleware: Экземпляр AUTH_USER_MODEL, представляющий текущего пользователя, авторизованного в системе. Если пользователь не авторизован, user будет установлено в экземпляр AnonymousUser. Их можно отличить с помощью is_authenticated, как показано ниже:

if request.user.is_authenticated:
    ... # Do something for logged-in users.
else:
    ... # Do something for anonymous users.

Методы

HttpRequest.get_host()

Возвращает исходный хост запроса, используя информацию из HTTP_X_FORWARDED_HOST (если USE_X_FORWARDED_HOST включено) и HTTP_HOST заголовков, в указанном порядке. Если они не предоставляют значения, метод использует комбинацию SERVER_NAME и SERVER_PORT, как описано в PEP 3333.

Пример: "127.0.0.1:8000"

Примечание

Метод get_host() терпит неудачу, когда хост находится за несколькими прокси-серверами. Одним из решений является использование middleware для переписывания заголовков прокси, как в следующем примере:

class MultipleProxyMiddleware:
    FORWARDED_FOR_FIELDS = [
        'HTTP_X_FORWARDED_FOR',
        'HTTP_X_FORWARDED_HOST',
        'HTTP_X_FORWARDED_SERVER',
    ]

    def __init__(self, get_response):
        self.get_response = get_response

    def __call__(self, request):
        """
        Rewrites the proxy headers so that only the most
        recent proxy is used.
        """
        for field in self.FORWARDED_FOR_FIELDS:
            if field in request.META:
                if ',' in request.META[field]:
                    parts = request.META[field].split(',')
                    request.META[field] = parts[-1].strip()
        return self.get_response(request)

Этот middleware должен быть размещен перед любым другим middleware, который полагается на значение get_host() – например, CommonMiddleware или CsrfViewMiddleware.

HttpRequest.get_port()

Возвращает исходный порт запроса, используя информацию из HTTP_X_FORWARDED_PORT (если USE_X_FORWARDED_PORT включено) и SERVER_PORT META переменных, в указанном порядке.

HttpRequest.get_full_path()

Возвращает path, плюс присоединённую строку запроса, если применимо.

Пример: "/music/bands/the_beatles/?print=true"

HttpRequest.get_full_path_info()

Как get_full_path(), но использует path_info вместо path.

Пример: "/minfo/music/bands/the_beatles/?print=true"

HttpRequest.build_absolute_uri(location=None)

Возвращает абсолютную URI-форму location. Если местоположение не указано, местоположение будет установлено в request.get_full_path().

Если местоположение уже является абсолютной URI, оно не будет изменено. В противном случае абсолютная URI строится с использованием доступных в этом запросе переменных сервера. Например:

>>> request.build_absolute_uri()
'https://example.com/music/bands/the_beatles/?print=true'
>>> request.build_absolute_uri('/bands/')
'https://example.com/bands/'
>>> request.build_absolute_uri('https://example2.com/bands/')
'https://example2.com/bands/'

Примечание

Смешение HTTP и HTTPS в одном сайте не рекомендуется, поэтому build_absolute_uri() всегда будет генерировать абсолютную URI со схемой, имеющейся в текущем запросе. Если вам нужно перенаправить пользователей на HTTPS, лучше всего позволить вашему веб-серверу перенаправлять весь трафик HTTP на HTTPS.

HttpRequest.get_signed_cookie(key, default=RAISE_ERROR, salt='', max_age=None)

Возвращает значение cookie для подписанной cookie или вызывает исключение django.core.signing.BadSignature , если подпись больше не действительна. Если вы укажите аргумент default, исключение будет подавлено, и вместо этого будет возвращено это значение по умолчанию.

Необязательный аргумент salt может быть использован для дополнительной защиты от атак методом грубой силы на ваш секретный ключ. Если он предоставлен, аргумент max_age будет проверен на соответствие подписанной временной метке, прикреплённой к значению cookie, чтобы гарантировать, что cookie не старше max_age секунд.

Например:

>>> request.get_signed_cookie('name')
'Tony'
>>> request.get_signed_cookie('name', salt='name-salt')
'Tony' # assuming cookie was set using the same salt
>>> request.get_signed_cookie('nonexistent-cookie')
...
KeyError: 'nonexistent-cookie'
>>> request.get_signed_cookie('nonexistent-cookie', False)
False
>>> request.get_signed_cookie('cookie-that-was-tampered-with')
...
BadSignature: ...
>>> request.get_signed_cookie('name', max_age=60)
...
SignatureExpired: Signature age 1677.3839159 > 60 seconds
>>> request.get_signed_cookie('name', False, max_age=60)
False

См. криптографическое подписание для получения дополнительной информации.

HttpRequest.is_secure()

Возвращает True, если запрос защищён; то есть, если он был выполнен с помощью HTTPS.

HttpRequest.is_ajax()

Возвращает True , если запрос был выполнен через XMLHttpRequest, проверяя заголовок HTTP_X_REQUESTED_WITH на строку 'XMLHttpRequest'. Большинство современных библиотек JavaScript отправляют этот заголовок. Если вы пишете свой собственный XMLHttpRequest вызов (со стороны браузера), вам необходимо вручную установить этот заголовок, если вы хотите, чтобы is_ajax() работал.

Если ответ меняется в зависимости от того, запрошен ли он через AJAX, и вы используете какой-либо вид кеширования, например, кеширование Django's cache middleware, вы должны декорировать представление с помощью vary_on_headers('X-Requested-With'), чтобы ответы должным образом кешировались.

HttpRequest.read(size=None)

HttpRequest.readline()

HttpRequest.readlines()

HttpRequest.__iter__()

Методы, реализующие интерфейс файла для чтения из экземпляра HttpRequest. Это позволяет потреблять входящий запрос в потоковом режиме. Типичный случай использования — обработка большого XML-payload с итерационным парсером без построения всего XML-дерева в памяти.

С учётом этого стандартного интерфейса экземпляр HttpRequest может быть передан напрямую XML-парсеру, например, ElementTree:

import xml.etree.ElementTree as ET
for element in ET.iterparse(request):
    process(element)

QueryDict объекты

class QueryDict

В объекте HttpRequest атрибуты GET и POST являются экземплярами django.http.QueryDict, класса, подобного словарю, настроенного для обработки нескольких значений для одного ключа. Это необходимо, потому что некоторые элементы HTML-форм, в частности <select multiple>, передают несколько значений для одного ключа.

Экземпляры QueryDict в request.POST и request.GET будут неизменяемыми при обращении в обычном цикле запроса/ответа. Чтобы получить изменяемую версию, необходимо использовать QueryDict.copy().

Методы

QueryDict реализует все стандартные методы словаря, поскольку он является подклассом словаря. Исключение составляет следующее:

QueryDict.__init__(query_string=None, mutable=False, encoding=None)

Инициализирует объект QueryDict на основе query_string.

>>> QueryDict('a=1&a=2&c=3')
<QueryDict: {'a': ['1', '2'], 'c': ['3']}>

Если query_string не передан, полученный QueryDict будет пустым (он не будет иметь ключей или значений).

Большинство QueryDictвстречимых вами, и, в частности, те, что в request.POST и request.GET, будут неизменяемыми. Если вы инициализируете их самостоятельно, вы можете сделать их изменяемыми, передав mutable=True в его __init__().

Строки для установки ключей и значений будут преобразованы из encoding в str Если encoding не задано, по умолчанию используется DEFAULT_CHARSET.

classmethod QueryDict.fromkeys(iterable, value='', mutable=False, encoding=None)

Создаёт новый QueryDict с ключами из iterable и каждым значением, равным value Например:

>>> QueryDict.fromkeys(['a', 'a', 'b'], value='val')
<QueryDict: {'a': ['val', 'val'], 'b': ['val']}>

QueryDict.__getitem__(key)

Возвращает значение для заданного ключа. Если у ключа более одного значения, возвращается последнее значение. Вызывает django.utils.datastructures.MultiValueDictKeyError если ключ не существует. (Это подкласс стандартного Python KeyError, поэтому вы можете продолжать ловить KeyError.)

QueryDict.__setitem__(key, value)

Устанавливает заданный ключ в [value] (список, единственный элемент которого — value). Обратите внимание, что это, как и другие функции словаря, имеющие побочные эффекты, может быть вызвано только на изменяемом QueryDict (таком, который был создан с помощью QueryDict.copy()).

QueryDict.__contains__(key)

Возвращает True если заданный ключ установлен. Это позволяет, например, делать if "foo" in request.GET.

QueryDict.get(key, default=None)

Использует ту же логику, что и __getitem__(), с возможностью возвращать значение по умолчанию, если ключ не существует.

QueryDict.setdefault(key, default=None)

Аналогично dict.setdefault(), но использует __setitem__() внутри.

QueryDict.update(other_dict)

Принимает либо QueryDict , либо словарь. Как и dict.update(), но добавляет к текущим элементам словаря вместо их замены. Например:

>>> q = QueryDict('a=1', mutable=True)
>>> q.update({'a': '2'})
>>> q.getlist('a')
['1', '2']
>>> q['a'] # returns the last
'2'

QueryDict.items()

Аналогично dict.items(), но использует ту же логику, что и __getitem__(), и возвращает объект-итератор вместо объекта-представления. Например:

>>> q = QueryDict('a=1&a=2&a=3')
>>> list(q.items())
[('a', '3')]

QueryDict.values()

Аналогично dict.values(), но использует ту же логику, что и __getitem__(), и возвращает итератор вместо объекта-представления. Например:

>>> q = QueryDict('a=1&a=2&a=3')
>>> list(q.values())
['3']

Кроме того, QueryDict имеет следующие методы:

QueryDict.copy()

Возвращает копию объекта, используя copy.deepcopy(). Эта копия будет изменяемой, даже если исходная не была.

QueryDict.getlist(key, default=None)

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

QueryDict.setlist(key, list_)

Устанавливает заданный ключ в list_ (в отличие от __setitem__()).

QueryDict.appendlist(key, item)

Добавляет элемент в внутренний список, связанный с ключом.

QueryDict.setlistdefault(key, default_list=None)

Аналогично setdefault(), но принимает список значений вместо одного значения.

QueryDict.lists()

Аналогично items(), но включает все значения в виде списка для каждого элемента словаря. Например:

>>> q = QueryDict('a=1&a=2&a=3')
>>> q.lists()
[('a', ['1', '2', '3'])]

QueryDict.pop(key)

Возвращает список значений для данного ключа и удаляет их из словаря. Вызывает KeyError если ключ не существует. Например:

>>> q = QueryDict('a=1&a=2&a=3', mutable=True)
>>> q.pop('a')
['1', '2', '3']

QueryDict.popitem()

Удаляет произвольный элемент из словаря (поскольку нет понятия порядка) и возвращает кортеж из двух значений, содержащий ключ и список всех значений для ключа. Вызывает KeyError при вызове на пустом словаре. Например:

>>> q = QueryDict('a=1&a=2&a=3', mutable=True)
>>> q.popitem()
('a', ['1', '2', '3'])

QueryDict.dict()

Возвращает представление dict объекта QueryDict. Для каждой пары (ключ, список) в QueryDict, dict будет содержать (ключ, элемент), где элемент — один элемент из списка, используя ту же логику, что и QueryDict.__getitem__():

>>> q = QueryDict('a=1&a=3&a=5')
>>> q.dict()
{'a': '5'}

QueryDict.urlencode(safe=None)

Возвращает строку данных в формате строки запроса. Например:

>>> q = QueryDict('a=2&b=3&b=5')
>>> q.urlencode()
'a=2&b=3&b=5'

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

>>> q = QueryDict(mutable=True)
>>> q['next'] = '/a&b/'
>>> q.urlencode(safe='/')
'next=/a%26b/'

HttpResponse объекты

class HttpResponse

В отличие от объектов HttpRequest, которые создаются автоматически Django, объекты HttpResponse вы создаёте самостоятельно. Каждый написанный вами вид отвечает за создание, заполнение и возвращение объекта HttpResponse.

Класс HttpResponse находится в модуле django.http.

Использование

Передача строк

Типичное использование заключается в передаче содержимого страницы в виде строки, байтовой строки или memoryview конструктору HttpResponse:

>>> from django.http import HttpResponse
>>> response = HttpResponse("Here's the text of the Web page.")
>>> response = HttpResponse("Text only, please.", content_type="text/plain")
>>> response = HttpResponse(b'Bytestrings are also accepted.')
>>> response = HttpResponse(memoryview(b'Memoryview as well.'))

Но если вы хотите добавлять содержимое по частям, вы можете использовать response как объект, похожий на файл:

>>> response = HttpResponse()
>>> response.write("<p>Here's the text of the Web page.</p>")
>>> response.write("<p>Here's another paragraph.</p>")

Передача итераторов

Наконец, вы можете передать HttpResponse итератор вместо строк. HttpResponse сразу же обработает итератор, сохранит его содержимое в виде строки и удалит его. Объекты с методом close(), такие как файлы и генераторы, будут немедленно закрыты.

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

Установка полей заголовков

Для установки или удаления поля заголовка в ответе, используйте его как словарь:

>>> response = HttpResponse()
>>> response['Age'] = 120
>>> del response['Age']

Обратите внимание, что в отличие от словаря, del не вызывает KeyError при отсутствии поля заголовка.

Для установки полей заголовков Cache-Control и Vary рекомендуется использовать методы patch_cache_control() и patch_vary_headers() из django.utils.cache, поскольку эти поля могут иметь несколько значений, разделенных запятыми. Методы «patch» гарантируют, что другие значения, например, добавленные посредством middleware, не будут удалены.

Поля заголовков HTTP не могут содержать символы новой строки. Попытка установить поле заголовка, содержащее символ новой строки (CR или LF), вызовет BadHeaderError

Инструктирование браузера обрабатывать ответ как прикрепленный файл

Чтобы указать браузеру обрабатывать ответ как прикрепленный файл, используйте аргумент content_type и установите заголовок Content-Disposition. Например, вот как можно вернуть электронную таблицу Microsoft Excel:

>>> response = HttpResponse(my_data, content_type='application/vnd.ms-excel')
>>> response['Content-Disposition'] = 'attachment; filename="foo.xls"'

Заголовок Content-Disposition не специфичен для Django, но его синтаксис легко забыть, поэтому мы включили его сюда.

Атрибуты

HttpResponse.content

Строка байтов, представляющая содержимое, закодированная из строки, если необходимо.

HttpResponse.charset

Строка, обозначающая кодировку символов, в которой будет закодирован ответ. Если она не задана во время создания HttpResponse, она будет извлечена из content_type и, если это не удастся, будет использовано значение настройки DEFAULT_CHARSET.

HttpResponse.status_code

Код состояния HTTP для ответа.

Если reason_phrase не указан явно, изменение значения status_code вне конструктора также изменит значение reason_phrase.

HttpResponse.reason_phrase

Фраза причины ответа HTTP. Она использует стандартные фразы причин HTTP.

Если не указан явно, reason_phrase определяется по значению status_code.

HttpResponse.streaming

Это всегда False.

Этот атрибут нужен, чтобы middleware мог различать ответы, передаваемые по частям, и обычные ответы.

HttpResponse.closed

True если ответ был закрыт.

Методы

HttpResponse.__init__(content=b'', content_type=None, status=200, reason=None, charset=None)

Инициализирует объект HttpResponse с заданным содержимым страницы и типом содержимого.

content чаще всего является итератором, байтовой строкой, memoryview или строкой. Другие типы будут преобразованы в байтовую строку путем кодирования их строкового представления. Итераторы должны возвращать строки или байтовые строки, которые будут объединены для формирования содержимого ответа.

content_type — это тип MIME, который дополнительно может содержать кодировку символов и используется для заполнения заголовка HTTP Content-Type. Если он не указан, он формируется из 'text/html' и настроек DEFAULT_CHARSET, по умолчанию: "text/html; charset=utf-8".

status — это код состояния HTTP для ответа. Для наглядности можно использовать алиасы из Python’s http.HTTPStatus, такие как HTTPStatus.NO_CONTENT.

reason — это фраза ответа HTTP. Если она не указана, используется фраза по умолчанию.

charset — это кодировка символов, в которой будет закодирован ответ. Если она не задана, она будет извлечена из content_type, и если это не удастся, будет использовано значение настройки DEFAULT_CHARSET.

Изменено в Django 3.0:

Была добавлена поддержка memoryview content.

HttpResponse.__setitem__(header, value)

Устанавливает заданное имя заголовка в заданное значение. Оба header и value должны быть строками.

HttpResponse.__delitem__(header)

Удаляет заголовок с указанным именем. Не вызывает ошибок, если заголовок не существует. Нечувствительно к регистру.

HttpResponse.__getitem__(header)

Возвращает значение для заданного имени заголовка. Нечувствительно к регистру.

HttpResponse.has_header(header)

Возвращает True или False в зависимости от проверки имени заголовка без учета регистра.

HttpResponse.setdefault(header, value)

Устанавливает заголовок, если он еще не установлен.

HttpResponse.set_cookie(key, value='', max_age=None, expires=None, path='/', domain=None, secure=False, httponly=False, samesite=None)

Устанавливает cookie. Параметры совпадают с параметрами объекта cookie Morsel в стандартной библиотеке Python.

• max_age должен быть числом секунд или None (по умолчанию), если cookie должен действовать только в течение сессии браузера клиента. Если expires не указан, он будет рассчитан.
• expires должен быть либо строкой в формате "Wdy, DD-Mon-YY HH:MM:SS GMT", либо объектом datetime.datetime в формате UTC. Если expires — это объект datetime, значение max_age будет рассчитано.
• Используйте domain, если вы хотите установить cookie для нескольких доменов. Например, domain="example.com" установит cookie, который доступен для доменов www.example.com, blog.example.com и т. д. В противном случае cookie будет доступен только для домена, который его установил.
• Используйте secure=True, если вы хотите, чтобы cookie передавался только на сервер при запросе с использованием схемы https.

• Используйте httponly=True, чтобы предотвратить доступ к cookie со стороны JavaScript на стороне клиента.

  HttpOnly — это флаг, включенный в заголовок ответа HTTP Set-Cookie. Он является частью стандарта RFC 6265 для cookies и может быть полезным способом снижения риска доступа защищенных данных cookie со стороны скрипта на стороне клиента.

• Используйте samesite='Strict' или samesite='Lax' для предотвращения отправки cookie браузером при выполнении запроса с другого домена. SameSite не поддерживается всеми браузерами, поэтому это не замена защиты от CSRF Django, а мера защиты на несколько уровней.

Предупреждение

RFC 6265 гласит, что пользовательские агенты должны поддерживать cookies размером не менее 4096 байтов. Для многих браузеров это также максимальный размер. Django не вызовет исключение, если будет попытка сохранить cookie размером более 4096 байтов, но многие браузеры не установят cookie правильно.

HttpResponse.set_signed_cookie(key, value, salt='', max_age=None, expires=None, path='/', domain=None, secure=False, httponly=False, samesite=None)

Аналогично set_cookie(), но с криптографическим подписанием куки перед установкой. Используйте в сочетании с HttpRequest.get_signed_cookie(). Дополнительную силу ключа можно получить, используя необязательный аргумент salt, но вам необходимо передать его соответствующему вызову HttpRequest.get_signed_cookie().

HttpResponse.delete_cookie(key, path='/', domain=None, samesite=None)

Удаляет куки с заданным ключом. Если ключ не существует, то выполняется без ошибок.

Из-за особенностей работы куки, значения path и domain должны быть идентичны тем, которые использовались в set_cookie(), иначе куки может не удалиться.

Изменено в Django 2.2.15:

Добавлен аргумент samesite.

HttpResponse.close()

Этот метод вызывается в конце запроса непосредственно сервером WSGI.

HttpResponse.write(content)

Этот метод делает экземпляр HttpResponse объектом типа «файл».

HttpResponse.flush()

Этот метод делает экземпляр HttpResponse объектом типа «файл».

HttpResponse.tell()

Этот метод делает экземпляр HttpResponse объектом типа «файл».

HttpResponse.getvalue()

Возвращает значение HttpResponse.content. Этот метод делает экземпляр HttpResponse объектом типа «поток».

HttpResponse.readable()

Всегда False. Этот метод делает экземпляр HttpResponse объектом типа «поток».

HttpResponse.seekable()

Всегда False. Этот метод делает экземпляр HttpResponse объектом типа «поток».

HttpResponse.writable()

Всегда True. Этот метод делает экземпляр HttpResponse объектом типа «поток».

HttpResponse.writelines(lines)

Записывает список строк в ответ. Разделители строк не добавляются. Этот метод делает экземпляр HttpResponse объектом типа «поток».

HttpResponse подклассы

Django включает несколько HttpResponse подклассов, обрабатывающих различные типы HTTP-ответов. Как и HttpResponse, эти подклассы находятся в django.http.

class HttpResponseRedirect

Первый аргумент конструктора обязателен – путь для перенаправления. Это может быть полная URL-адреса (например, 'https://www.yahoo.com/search/'), абсолютный путь без домена (например, '/search/'), или даже относительный путь (например, 'search/'). В последнем случае браузер клиента сам восстановит полную URL-адресу в соответствии с текущим путем. Смотрите HttpResponse для других необязательных аргументов конструктора. Обратите внимание, что возвращается код HTTP 302.

url

Это только для чтения атрибут, представляющий URL, на который будет перенаправлен ответ (эквивалентен заголовку ответа Location).

class HttpResponsePermanentRedirect

Аналогично HttpResponseRedirect, но возвращает постоянное перенаправление (код HTTP 301), а не перенаправление «найдено» (код 302).

class HttpResponseNotModified

Конструктор не принимает никаких аргументов, и к этому ответу не должно добавляться никакого контента. Используйте для обозначения того, что страница не изменялась с момента последнего запроса пользователя (код 304).

class HttpResponseBadRequest

Ведет себя точно так же, как HttpResponse, но использует код состояния 400.

class HttpResponseNotFound

Ведет себя точно так же, как HttpResponse, но использует код состояния 404.

class HttpResponseForbidden

Ведет себя точно так же, как HttpResponse, но использует код состояния 403.

class HttpResponseNotAllowed

Аналогично HttpResponse, но использует код состояния 405. Первый аргумент конструктора обязателен: список разрешенных методов (например, ['GET', 'POST']).

class HttpResponseGone

Ведет себя точно так же, как HttpResponse, но использует код состояния 410.

class HttpResponseServerError

Ведет себя точно так же, как HttpResponse, но использует код состояния 500.

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

Если вам нужен класс ответа, которого нет в Django, вы можете создать его с помощью http.HTTPStatus. Например:

from http import HTTPStatus
from django.http import HttpResponse

class HttpResponseNoContent(HttpResponse):
    status_code = HTTPStatus.NO_CONTENT

JsonResponse объекты

class JsonResponse(data, encoder=DjangoJSONEncoder, safe=True, json_dumps_params=None, **kwargs)

Подкласс HttpResponse, который помогает создавать JSON-кодированный ответ. Он наследует большинство свойств от своего суперкласса с некоторыми отличиями:

Его значение по умолчанию для заголовка Content-Type установлено на application/json.

Первый параметр, data, должен быть экземпляром dict. Если параметр safe установлен в False (см. ниже), он может быть любым сериализуемым в JSON объектом.

encoder, по умолчанию django.core.serializers.json.DjangoJSONEncoder, будет использоваться для сериализации данных. См. Сериализация JSON для получения более подробной информации об этом сериализаторе.

Булевый параметр safe по умолчанию True. Если он установлен в False, для сериализации можно передать любой объект (в противном случае допускаются только экземпляры dict). Если safe установлен в True, и в качестве первого аргумента передан не объект dict, будет выброшено исключение TypeError.

Параметр json_dumps_params — это словарь ключевых аргументов, которые нужно передать в вызов json.dumps() для генерации ответа.

Использование

Типичное использование может выглядеть так:

>>> from django.http import JsonResponse
>>> response = JsonResponse({'foo': 'bar'})
>>> response.content
b'{"foo": "bar"}'

Сериализация объектов, отличных от словарей

Для сериализации объектов, отличных от dict, необходимо установить параметр safe в False.

>>> response = JsonResponse([1, 2, 3], safe=False)

Без передачи safe=False, будет выброшено исключение TypeError.

Изменение стандартного кодировщика JSON

Если вам необходимо использовать другой класс кодировщика JSON, вы можете передать параметр encoder в метод конструктора:

>>> response = JsonResponse(data, encoder=MyJSONEncoder)

StreamingHttpResponse объекты

class StreamingHttpResponse

Класс StreamingHttpResponse используется для потоковой передачи ответа от Django в браузер. Это может потребоваться, если генерация ответа занимает слишком много времени или использует слишком много памяти. Например, это полезно для генерации больших CSV-файлов.

Класс StreamingHttpResponse не является подклассом HttpResponse, так как он имеет немного другой API. Однако он почти идентичен, с следующими заметными отличиями:

• Ему должен быть передан итератор, который возвращает байтовые строки в качестве содержимого.
• Вы не можете получить доступ к его содержимому, кроме как итерируя сам объект ответа. Это должно происходить только тогда, когда ответ возвращается клиенту.
• У него нет атрибута content. Вместо этого у него есть атрибут streaming_content.
• Вы не можете использовать объект типа файла tell() или методы write(). Это вызовет исключение.

StreamingHttpResponse следует использовать только в тех случаях, когда совершенно необходимо, чтобы все содержимое не было обработано до передачи данных клиенту. Поскольку к содержимому нельзя получить доступ, многие модули не могут нормально функционировать. Например, заголовки ETag и Content-Length не могут быть сгенерированы для потоковых ответов.

Атрибуты

StreamingHttpResponse.streaming_content

Итератор содержимого ответа, закодированный в байтах в соответствии с HttpResponse.charset.

StreamingHttpResponse.status_code

Код состояния HTTP для ответа.

Если reason_phrase не задан явно, изменение значения status_code вне конструктора также изменит значение reason_phrase.

StreamingHttpResponse.reason_phrase

Фраза причины HTTP для ответа. Она использует стандартные фразы причины HTTP.

Если не задано явно, reason_phrase определяется значением status_code.

StreamingHttpResponse.streaming

Это всегда True.

FileResponse объекты

class FileResponse(open_file, as_attachment=False, filename='', **kwargs)

FileResponse — подкласс StreamingHttpResponse, оптимизированный для бинарных файлов. Он использует wsgi.file_wrapper, если это предоставляется сервером WSGI, в противном случае он передает файл по частям.

Если as_attachment=True, заголовок Content-Disposition устанавливается в attachment, что предлагает браузеру предложить пользователю файл для скачивания. В противном случае заголовок Content-Disposition со значением inline (стандартное значение браузера) будет задан только при наличии имени файла.

Если у open_file нет имени или имя open_file не подходит, укажите пользовательское имя файла с помощью параметра filename. Обратите внимание, что если вы передаёте объект типа файла, например, io.BytesIO, вам необходимо seek() его перед передачей в FileResponse.

Заголовки Content-Length и Content-Type автоматически устанавливаются, когда их можно определить из содержимого open_file.

FileResponse принимает любой объект типа файла с бинарным содержимым, например, файл, открытый в бинарном режиме, как показано ниже:

>>> from django.http import FileResponse
>>> response = FileResponse(open('myfile.png', 'rb'))

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

Методы

FileResponse.set_headers(open_file)

Этот метод автоматически вызывается во время инициализации ответа и устанавливает различные заголовки (Content-Length, Content-Type, и Content-Disposition) в зависимости от open_file.