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

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

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, например, если форма запрошена с помощью метода POST HTTP, но не содержит данных формы. Поэтому не следует использовать 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 – Заголовок Host HTTP, отправленный клиентом.
• HTTP_REFERER – Ссылка на предыдущую страницу (если есть).
• HTTP_USER_AGENT – Строка пользователя-агента клиента.
• QUERY_STRING – Строка запроса как единая (необработанная) строка.
• REMOTE_ADDR – IP-адрес клиента.
• REMOTE_HOST – Имя хоста клиента.
• REMOTE_USER – Пользователь, авторизованный веб-сервером (если есть).
• REQUEST_METHOD – Строка типа "GET" или "POST".
• SERVER_NAME – Имя хоста сервера.
• SERVER_PORT – Порт сервера (в виде строки).

За исключением CONTENT_LENGTH и CONTENT_TYPE, как указано выше, все HTTP-заголовки в запросе преобразуются в ключи META путем преобразования всех символов в верхний регистр, замены всех тире на нижние подчеркивания и добавления префикса HTTP_ к имени. Например, заголовок X-Bender будет сопоставлен с ключом META HTTP_X_BENDER.

Обратите внимание, что runserver удаляет все заголовки с нижними подчеркиваниями в имени, поэтому вы их не увидите в META. Это предотвращает подделку заголовков, основанную на неоднозначности между тире и нижними подчеркиваниями, которые нормализуются до нижних подчеркиваний в переменных среды WSGI. Это соответствует поведению веб-серверов, таких как Nginx и Apache 2.4+.

HttpRequest.headers — более простой способ получить доступ ко всем HTTP-заголовкам, а также к CONTENT_LENGTH и CONTENT_TYPE.

HttpRequest.headers

Объект типа словаря, не чувствительный к регистру, предоставляющий доступ ко всем HTTP-заголовкам (плюс Content-Length и Content-Type) запроса.

Название каждого заголовка форматируется с использованием прописных букв в начале (например, User-Agent) при отображении. Вы можете получать доступ к заголовкам, не учитывая регистр:

>>> request.headers
{'User-Agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6', ...}

>>> 'User-Agent' in request.headers
True
>>> 'user-agent' in request.headers
True

>>> request.headers['User-Agent']
Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6)
>>> request.headers['user-agent']
Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6)

>>> request.headers.get('User-Agent')
Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6)
>>> request.headers.get('user-agent')
Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6)

Для использования, например, в шаблонах Django, заголовки также можно искать, используя подчёркивания вместо дефисов:

{{ request.headers.user_agent }}

HttpRequest.resolver_match

Экземпляр ResolverMatch, представляющий решенный URL. Этот атрибут устанавливается только после разрешения URL, что означает, что он доступен во всех представлениях, но не в middleware, которые выполняются до разрешения URL (хотя вы можете использовать его в process_view()).

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

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

HttpRequest.current_app

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

HttpRequest.urlconf

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

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

HttpRequest.exception_reporter_filter

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

HttpRequest.exception_reporter_class

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

Атрибуты, установленные middleware

Некоторые middleware, включенные в contrib приложения Django, устанавливают атрибуты в запросе. Если вы не видите атрибут в запросе, убедитесь, что соответствующий класс middleware указан в MIDDLEWARE.

HttpRequest.session

Из SessionMiddleware: Чтение и запись, похожий на словарь объект, представляющий текущую сессию.

HttpRequest.site

Из CurrentSiteMiddleware: Экземпляр Site или RequestSite, как возвращается get_current_site(), представляющий текущий сайт.

HttpRequest.user

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

if request.user.is_authenticated:
    ... # Do something for logged-in users.
else:
    ... # Do something for anonymous users.

Методы

HttpRequest.get_host()

Возвращает исходный хост запроса, используя информацию из HTTP_X_FORWARDED_HOST (если включён USE_X_FORWARDED_HOST) и HTTP_HOST заголовков, в указанном порядке. Если они не предоставляют значение, метод использует комбинацию SERVER_NAME и SERVER_PORT, как подробно описано в PEP 3333.

Пример: "127.0.0.1:8000"

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

Примечание

Метод get_host() терпит неудачу, когда хост находится за несколькими прокси. Одним из решений является использование middleware для переписывания заголовков прокси, как в следующем примере:

class MultipleProxyMiddleware:
    FORWARDED_FOR_FIELDS = [
        'HTTP_X_FORWARDED_FOR',
        'HTTP_X_FORWARDED_HOST',
        'HTTP_X_FORWARDED_SERVER',
    ]

    def __init__(self, get_response):
        self.get_response = get_response

    def __call__(self, request):
        """
        Rewrites the proxy headers so that only the most
        recent proxy is used.
        """
        for field in self.FORWARDED_FOR_FIELDS:
            if field in request.META:
                if ',' in request.META[field]:
                    parts = request.META[field].split(',')
                    request.META[field] = parts[-1].strip()
        return self.get_response(request)

Этот middleware должен быть размещен перед любым другим middleware, который полагается на значение get_host() — например, CommonMiddleware или CsrfViewMiddleware.

HttpRequest.get_port()

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

HttpRequest.get_full_path()

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

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

HttpRequest.get_full_path_info()

Как get_full_path(), но использует path_info вместо path.

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

HttpRequest.build_absolute_uri(location=None)

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

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

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

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

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

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

Атрибуты

HttpResponse.content

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

HttpResponse.headers

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

HttpResponse.charset

Строка, обозначающая кодировку символов, в которой будет закодирован ответ. Если она не задана во время создания объекта, она будет извлечена из 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 для ответа. Для осмысленных псевдонимов можно использовать http.HTTPStatus Python, например 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. Параметры совпадают с параметрами объекта Morsel cookie в стандартной библиотеке Python.

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

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

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

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

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

  HttpOnly — флаг, включённый в HTTP-заголовок ответа Set-Cookie. Это часть стандарта RFC 6265 для 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 в браузер. Это может быть полезно, если генерация ответа занимает слишком много времени или использует слишком много памяти. Например, он полезен для генерации больших CSV-файлов.

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

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

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

Базовый класс 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.

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.

HttpResponseBase класс

class HttpResponseBase

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