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

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

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

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

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

HttpRequest объекты

class HttpRequest

Атрибуты

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

HttpRequest.scheme

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

HttpRequest.body

Необработанное тело HTTP-запроса в виде байтовой строки. Это полезно для обработки данных нестандартными способами, не связанными с обычными HTML-формами: бинарные изображения, XML-загрузка и т. п. Для обработки обычных данных форм используйте 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 – Строка пользователя-агента клиента.
• 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

Объект, похожий на словарь, не чувствительный к регистру, предоставляющий доступ ко всем 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 }}

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.

HttpRequest.exception_reporter_filter

Будет использоваться вместо DEFAULT_EXCEPTION_REPORTER_FILTER для текущего запроса. Подробности см. в Настройка сообщений об ошибках.

HttpRequest.exception_reporter_class

Будет использоваться вместо DEFAULT_EXCEPTION_REPORTER для текущего запроса. Подробности см. в Настройка сообщений об ошибках.

Атрибуты, заданные middleware

Некоторые middleware, включенные в приложения contrib Django, устанавливают атрибуты в запросе. Если вы не видите атрибут в запросе, убедитесь, что соответствующий класс 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"

Возбуждает django.core.exceptions.DisallowedHost если хост не входит в ALLOWED_HOSTS или имя домена недействительно в соответствии с RFC 1034/1035.

Примечание

Метод 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. Если не указан URL, URL будет установлен в request.get_full_path().

Если URL уже является абсолютным 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.accepts(mime_type)

Новое в Django 3.1.

Возвращает True если заголовок запроса Accept соответствует аргументу mime_type:

>>> request.accepts('text/html')
True

Большинство браузеров по умолчанию отправляют Accept: */*, поэтому это вернёт True для всех типов контента. Установка явного заголовка Accept в запросах API может быть полезна для возвращения другого типа контента только для этих потребителей. См. Пример переговорного определения контента использования accepts() для возвращения разного контента для потребителей API.

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

HttpRequest.is_ajax()

Устарело начиная с версии 3.1.

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

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

HttpRequest.read(size=None)

HttpRequest.readline()

HttpRequest.readlines()

HttpRequest.__iter__()

Методы, реализующие интерфейс типа файла для чтения из объекта HttpRequest. Это позволяет потреблять входящий запрос потоковым способом. Типичный пример использования – обработка большого XML-загруза итеративным анализатором без построения всего 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)

Возвращает список данных с запрошенным ключом. Возвращает пустой список, если ключ не существует и 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 вместо этого.

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

Чтобы установить или удалить заголовок поля в ответе, используйте HttpResponse.headers:

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

Вы также можете манипулировать заголовками, рассматривая ответ как словарь:

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

Это является проксированием для HttpResponse.headers, и это оригинальный интерфейс, предлагаемый HttpResponse.

При использовании этого интерфейса, в отличие от словаря, del не вызывает KeyError , если заголовок поля не существует.

Вы также можете задать заголовки при создании:

>>> response = HttpResponse(headers={'Age': 120})

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

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

Указание браузеру рассматривать ответ как файл-приложение

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

>>> response = HttpResponse(my_data, headers={
...     'Content-Type': 'application/vnd.ms-excel',
...     'Content-Disposition': 'attachment; filename="foo.xls"',
... })

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

Атрибуты

HttpResponse.content

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

HttpResponse.headers

Новое в Django 3.2.

Объект типа словаря, нечувствительный к регистру, предоставляющий интерфейс ко всем HTTP-заголовкам ответа. См. Указание заголовков полей.

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.

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

HttpResponse.closed

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

Методы

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

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

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

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

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

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

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

headers — это dict HTTP-заголовков для ответа.

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

Был добавлен параметр headers.

HttpResponse.__setitem__(header, value)

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

HttpResponse.__delitem__(header)

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

HttpResponse.__getitem__(header)

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

HttpResponse.get(header, alternate=None)

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

HttpResponse.has_header(header)

Возвращает True или False на основе регистронезависимой проверки наличия заголовка с заданным именем.

HttpResponse.items()

Действует как dict.items() для HTTP-заголовков ответа.

HttpResponse.setdefault(header, value)

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

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

Устанавливает куки. Параметры аналогичны объекту куки Morsel в стандартной библиотеке Python.

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

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

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

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

  Используйте samesite='None' (строка), чтобы явно указать, что этот куки отправляется со всеми запросами same-site и cross-site.

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

Использование samesite='None' (строка) было разрешено.

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

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

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().

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

Использование samesite='None' (строка) было разрешено.

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

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

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.