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

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

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, что означает, что он доступен во всех представлениях, но не в 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)

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

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

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

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

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

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

Атрибуты

HttpResponse.content

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

HttpResponse.headers

Новое в Django 3.2.

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

HttpResponse.charset

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

HttpResponse.status_code

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

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

HttpResponse.reason_phrase

Фраза причины HTTP-ответа. Использует фразы причин по умолчанию стандартного HTTP.

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

HttpResponse.streaming

Это всегда False.

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

HttpResponse.closed

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

Методы

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

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

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

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

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

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

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

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

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

Добавлен параметр headers.

HttpResponse.__setitem__(header, value)

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

HttpResponse.__delitem__(header)

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

HttpResponse.__getitem__(header)

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

HttpResponse.get(header, alternate=None)

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

HttpResponse.has_header(header)

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

HttpResponse.items()

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

HttpResponse.setdefault(header, value)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Из-за работы куки path и domain должны быть такими же, как вы использовали в set_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 в браузер. Это может потребоваться, если генерация ответа занимает слишком много времени или использует слишком много памяти. Например, это полезно для генерации больших CSV-файлов.

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

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

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

Атрибуты

StreamingHttpResponse.streaming_content

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

StreamingHttpResponse.status_code

Код HTTP-статуса ответа.

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

StreamingHttpResponse.reason_phrase

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

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

StreamingHttpResponse.streaming

Это всегда True.

FileResponse объекты

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

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

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

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

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

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

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

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

Методы

FileResponse.set_headers(open_file)

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