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

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

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 – Строка 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, что означает, что он доступен во всех представлениях, но не в среднем программном обеспечении, которое выполняется до разрешения URL (хотя вы можете использовать его в process_view()).

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

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

HttpRequest.current_app

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

HttpRequest.urlconf

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

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

HttpRequest.exception_reporter_filter

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

HttpRequest.exception_reporter_class

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

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

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

Возвращает исходный хост запроса, используя информацию из 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() не работает, когда хост находится за несколькими прокси. Одним из решений является использование средства разработки для перезаписи заголовков прокси, как показано в следующем примере:

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)

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

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

Необязательный аргумент salt может использоваться для дополнительной защиты от атак с перебором паролей на ваш секретный ключ. Если он передан, аргумент max_age будет проверен на соответствие подписанному временнному отметке, прикрепленному к значению куки, чтобы убедиться, что куки не старше 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)

Принимает словарь или 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, так как эти поля могут иметь несколько значений, разделённых запятыми. Методы «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.cookies

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

HttpResponse.headers

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

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 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, если вы хотите предотвратить доступ скриптов JavaScript на стороне клиента к cookie.

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

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

  Используйте samesite='None' (строка), чтобы явно указать, что этот cookie отправляется со всеми запросами same-site и 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)

Этот метод делает экземпляр 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. Однако он почти идентичен, с следующими важными отличиями:

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

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

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

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

• У него нет content атрибута. Вместо этого у него есть атрибут streaming_content. Его можно использовать в middleware для обертывания итерируемого объекта ответа, но не следует потреблять.
• Вы не можете использовать похожий на файл объект 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.

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

Если клиент прерывает соединение во время потокового ответа, 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)

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