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

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

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

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

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

HttpRequest объекты

class HttpRequest [source]

Атрибуты

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

HttpRequest.scheme [source]

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

HttpRequest.body [source]

Необработанное тело 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 [source]

Строка, представляющая текущее кодирование, используемое для декодирования данных отправки формы (или 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

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

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 [source]

Объект, подобный словарю, который обеспечивает доступ ко всем 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.

Метод auser() делает то же самое, но может использоваться из асинхронных контекстов.

Методы

HttpRequest.auser()

Введено в Django 5.0.

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

HttpRequest.get_host() [source]

Возвращает исходный хост запроса, используя информацию из 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() [source]

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

HttpRequest.get_full_path() [source]

Возвращает path, а также добавленный строку запроса, если применимо.

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

HttpRequest.get_full_path_info() [source]

Подобно get_full_path(), но использует path_info вместо path.

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

HttpRequest.build_absolute_uri(location=None) [source]

Возвращает абсолютный 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) [source]

Возвращает значение 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() [source]

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

HttpRequest.accepts(mime_type) [source]

Возвращает 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) [source]

HttpRequest.readline() [source]

HttpRequest.readlines() [source]

HttpRequest.__iter__() [source]

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

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

import xml.etree.ElementTree as ET

for element in ET.iterparse(request):
    process(element)

QueryDict объекты

class QueryDict [source]

В объекте 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) [source]

Инициализирует объект 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) [source]

Создаёт новый 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) [source]

Устанавливает данный ключ в [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) [source]

Аналогично 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() [source]

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

QueryDict.getlist(key, default=None)

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

QueryDict.setlist(key, list_) [source]

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

QueryDict.appendlist(key, item) [source]

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

QueryDict.setlistdefault(key, default_list=None) [source]

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

QueryDict.lists()

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

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

QueryDict.pop(key) [source]

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

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

QueryDict.popitem() [source]

Удаляет произвольный элемент словаря (поскольку нет понятия порядка) и возвращает кортеж из двух значений, содержащий ключ и список всех значений для ключа. Вызывает исключение 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) [source]

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

>>> 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 [source]

В отличие от объектов 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» гарантируют, что другие значения, например, добавленные посредником, не будут удалены.

Поля заголовков 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 [source]

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

HttpResponse.cookies

Объект http.cookies.SimpleCookie, содержащий куки, включенные в ответ.

HttpResponse.headers

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

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) [source]

Создаёт объект 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-заголовков для ответа.

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. Параметры аналогичны параметрам объекта cookie Morsel в стандартной библиотеке Python.

• max_age должен быть объектом timedelta, целым числом в секундах или 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, а скорее является дополнительной мерой.

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

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

RFC 6265 устанавливает, что агенты пользователя должны поддерживать cookie размером как минимум 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 с заданным ключом. Без ошибок, если ключ не существует.

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

HttpResponse.close()

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

HttpResponse.write(content) [source]

Этот метод превращает экземпляр HttpResponse в похожий на файл объект.

HttpResponse.flush()

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

HttpResponse.tell() [source]

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

HttpResponse.getvalue() [source]

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

HttpResponse.readable()

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

HttpResponse.seekable()

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

HttpResponse.writable() [source]

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

HttpResponse.writelines(lines) [source]

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

HttpResponse подклассы

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

class HttpResponseRedirect [source]

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

url

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

class HttpResponsePermanentRedirect [source]

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

class HttpResponseNotModified [source]

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

class HttpResponseBadRequest [source]

Действует так же, как и HttpResponse, но использует код состояния 400.

class HttpResponseNotFound [source]

Действует так же, как и HttpResponse, но использует код состояния 404.

class HttpResponseForbidden [source]

Действует так же, как и HttpResponse, но использует код состояния 403.

class HttpResponseNotAllowed [source]

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

class HttpResponseGone [source]

Действует так же, как и HttpResponse, но использует код состояния 410.

class HttpResponseServerError [source]

Действует так же, как и 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) [source]

Подкласс 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 [source]

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

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

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

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

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

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

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

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

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

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

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

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

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

Атрибуты

StreamingHttpResponse.streaming_content [source]

Итератор содержимого ответа, закодированный в байты в соответствии с 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

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

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

Обработка разрывов соединения

Если клиент прерывает соединение во время потокового ответа, Django отменит сопрограмму, обрабатывающую ответ. Если вы хотите вручную очистить ресурсы, вы можете сделать это, перехватив asyncio.CancelledError:

async def streaming_response():
    try:
        # Do some work here
        async for chunk in my_streaming_iterator():
            yield chunk
    except asyncio.CancelledError:
        # Handle disconnect
        ...
        raise


async def my_streaming_view(request):
    return StreamingHttpResponse(streaming_response())

Этот пример показывает только как обработать разрыв соединения клиента во время потоковой передачи ответа. Если вы выполняете длительные операции в вашем представлении перед возвращением объекта StreamingHttpResponse , то, возможно, также захотите обработать разрывы соединения в самом представлении.

FileResponse объекты

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

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) [source]

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

HttpResponseBase класс

class HttpResponseBase [source]

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