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

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

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 может упростить перемещение кода между тестовыми и производственными серверами.

Например, если префикс скрипта приложения установлен как "/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, например, когда форма запрошена методом 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

Объект типа «словарь», не чувствительный к регистру, предоставляющий доступ ко всем заголовкам 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. Если местоположение не указано, местоположение будет установлено в 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.accepts(mime_type)

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

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

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

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

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)

Принимает словарь или словарь-подобный объект. Подобно 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()

Возвращает представление 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, поскольку эти поля могут иметь несколько значений, разделенных запятыми. Методы «patch» гарантируют, что другие значения, например, добавленные middleware, не будут удалены.

Поля 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

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

HttpResponse.charset

Строка, обозначающая кодировку символов, в которой будет закодирован ответ. Если не указано при создании, она извлекается из 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, headers=None)

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

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

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

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

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

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

headers — словарь HTTP-заголовков для ответа.

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)

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

• max_age должен быть объектом timedelta, целым числом, представляющим количество секунд, или None (по умолчанию), если cookie должен действовать только во время сессии браузера клиента. Если expires не указан, он будет вычислен.

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

  Добавлена поддержка объектов timedelta.

• 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, а мера дополнительной защиты.

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

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

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(), но использует криптографическое шифрование cookie перед его установкой. Используется вместе с HttpRequest.get_signed_cookie(). Можно использовать необязательный параметр salt для повышения стойкости ключа, но нужно помнить о передаче его в соответствующий вызов HttpRequest.get_signed_cookie().

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

Удаляет cookie с заданным ключом. Безмолвно завершается, если ключ не найден.

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

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.

Обратите внимание, что API на основе объектов dict более расширяемый, гибкий и упрощает поддержание обратной совместимости. Поэтому следует избегать использования объектов, отличных от словарей, в JSON-кодированных ответах.

Изменение кодировщика JSON по умолчанию

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

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

StreamingHttpResponse объекты

class StreamingHttpResponse

Класс StreamingHttpResponse используется для потоковой передачи ответа из Django в браузер.

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

Однако при этом есть соображения по производительности. Django в WSGI предназначен для кратковременных запросов. Потоковые ответы связывают рабочий процесс на все время ответа. Это может привести к плохой производительности.

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

Однако при работе в ASGI StreamingHttpResponse не мешает обслуживать другие запросы во время ожидания ввода-вывода. Это открывает возможность для долговременных запросов для потоковой передачи содержимого и реализации таких шаблонов, как длинный опрос и события, отправляемые сервером.

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

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

• Ему должен быть передан итератор, который возвращает байтовые строки в качестве содержимого. При работе в WSGI это должен быть синхронный итератор. При работе в ASGI это должен быть асинхронный итератор.

• К его содержимому нельзя получить доступ, кроме как перебирая сам объект ответа. Это должно происходить только при возврате ответа клиенту: вы не должны перебирать ответ самостоятельно.

  В WSGI ответ будет перебираться синхронно. В ASGI ответ будет перебираться асинхронно. (Поэтому тип итератора должен соответствовать используемому протоколу.)

  Чтобы избежать сбоя, неправильный тип итератора будет сопоставлен с правильным типом при итерации, и будет выведено предупреждение, но для этого итератор должен быть полностью использован, что сводит на нет смысл использования StreamingHttpResponse.

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

Базовый класс HttpResponseBase общий для HttpResponse и StreamingHttpResponse.

Атрибуты

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.

StreamingHttpResponse.is_async

Новое в Django 4.2.

Булево значение, указывающее, является ли StreamingHttpResponse.streaming_content асинхронным итератором или нет.

Это полезно для middleware, которым нужно обернуть StreamingHttpResponse.streaming_content.

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 автоматически устанавливается, когда его можно определить из содержимого open_file.

Заголовок Content-Type автоматически устанавливается, когда его можно определить из filename, или имени 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.

HttpResponseBase класс

class HttpResponseBase

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