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

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

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

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

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

HttpRequest объекты

class HttpRequest

Атрибуты

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

HttpRequest.scheme

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

HttpRequest.body

Необработанное тело HTTP-запроса в виде байтовой строки. Это полезно для обработки данных нестандартными способами, отличными от обычных HTML-форм: бинарные изображения, XML-payload и т. д. Для обработки обычных данных формы используйте 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 – Строка пользовательского агента клиента.
• 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 }}

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

Добавлена поддержка поиска с использованием подчёркиваний.

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, включенные в модули 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"

Примечание

Метод 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)

Новое в Django 3.1.

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

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

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

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

HttpRequest.is_ajax()

Устарело начиная с версии 3.1.

Возвращает True если запрос был выполнен через XMLHttpRequest, проверяя заголовок HTTP_X_REQUESTED_WITH на наличие строки 'XMLHttpRequest'. Большинство современных библиотек JavaScript отправляют этот заголовок. Если вы пишете свой собственный XMLHttpRequest вызов (на стороне браузера), вам нужно будет установить этот заголовок вручную, если вы хотите, чтобы is_ajax() работал.

Если ответ зависит от того, запрашивается ли он через AJAX, и вы используете какую-либо форму кэширования, например, кэширование Django cache middleware, вы должны декорировать представление с помощью vary_on_headers('X-Requested-With'), чтобы ответы были должным образом кэшированы.

HttpRequest.read(size=None)

HttpRequest.readline()

HttpRequest.readlines()

HttpRequest.__iter__()

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

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

import xml.etree.ElementTree as ET
for element in ET.iterparse(request):
    process(element)

QueryDict объекты

class QueryDict

В объекте HttpRequest атрибуты GET и POST являются экземплярами django.http.QueryDict, словарем-подобным классом, настроенным для обработки нескольких значений для одного ключа. Это необходимо, так как некоторые элементы HTML-форм, в частности <select multiple>, передают несколько значений для одного ключа.

Экземпляры QueryDict в request.POST и request.GET будут неизменяемыми при доступе в обычном цикле запрос/ответ. Для получения изменяемой версии необходимо использовать QueryDict.copy().

Методы

QueryDict реализует все стандартные методы словаря, так как является подклассом словаря. Исключение описаны здесь:

QueryDict.__init__(query_string=None, mutable=False, encoding=None)

Инициализирует объект QueryDict на основе query_string.

>>> QueryDict('a=1&a=2&c=3')
<QueryDict: {'a': ['1', '2'], 'c': ['3']}>

Если query_string не передан, полученный QueryDict будет пустым (у него не будет ключей или значений).

Большинство QueryDict с которыми вы столкнётесь, в частности те, что в request.POST и request.GET, будут неизменяемыми. Если вы инициализируете экземпляр самостоятельно, вы можете сделать его изменяемым, передав mutable=True в его __init__().

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

classmethod QueryDict.fromkeys(iterable, value='', mutable=False, encoding=None)

Создаёт новый QueryDict с ключами из iterable и каждым значением равным value Например:

>>> QueryDict.fromkeys(['a', 'a', 'b'], value='val')
<QueryDict: {'a': ['val', 'val'], 'b': ['val']}>

QueryDict.__getitem__(key)

Возвращает значение для заданного ключа. Если ключ имеет более одного значения, возвращает последнее значение. Вызывает django.utils.datastructures.MultiValueDictKeyError если ключ не существует. (Это подкласс стандартного исключения Python KeyError, поэтому вы можете ограничиться перехватом KeyError.)

QueryDict.__setitem__(key, value)

Устанавливает указанный ключ в [value] (список, содержащий единственный элемент value). Обратите внимание, что это, как и другие функции словаря, которые имеют побочные эффекты, может быть вызвано только для изменяемого QueryDict (такого, который был создан с помощью QueryDict.copy()).

QueryDict.__contains__(key)

Возвращает True если заданный ключ установлен. Это позволяет, например, выполнить if "foo" in request.GET.

QueryDict.get(key, default=None)

Использует ту же логику, что и __getitem__(), с возможностью возвращать значение по умолчанию, если ключ не существует.

QueryDict.setdefault(key, default=None)

Аналогично dict.setdefault(), но использует __setitem__() внутри.

QueryDict.update(other_dict)

Принимает словарь или словарь-подобный объект. Подобно dict.update(), но добавляет к текущим элементам словаря, а не заменяет их. Например:

>>> q = QueryDict('a=1', mutable=True)
>>> q.update({'a': '2'})
>>> q.getlist('a')
['1', '2']
>>> q['a'] # returns the last
'2'

QueryDict.items()

Подобно dict.items(), но использует ту же логику последнего значения, что и __getitem__() и возвращает объект-итератор вместо объекта-представления. Например:

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

QueryDict.values()

Подобно dict.values(), но использует ту же логику последнего значения, что и __getitem__() и возвращает итератор вместо объекта-представления. Например:

>>> q = QueryDict('a=1&a=2&a=3')
>>> list(q.values())
['3']

В дополнение к этому, QueryDict имеет следующие методы:

QueryDict.copy()

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

QueryDict.getlist(key, default=None)

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

QueryDict.setlist(key, list_)

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

QueryDict.appendlist(key, item)

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

QueryDict.setlistdefault(key, default_list=None)

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

QueryDict.lists()

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

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

QueryDict.pop(key)

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

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

QueryDict.popitem()

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

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

QueryDict.dict()

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

safe

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 вместо него.

Установка полей заголовков

Чтобы установить или удалить поле заголовка в ответе, обратитесь к нему как к словарю:

>>> response = HttpResponse()
>>> response['Age'] = 120
>>> del response['Age']

Обратите внимание, что в отличие от словаря, del не вызывает KeyError , если поле заголовка не существует.

Для установки полей заголовков 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, content_type='application/vnd.ms-excel')
>>> response['Content-Disposition'] = 'attachment; filename="foo.xls"'

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

Атрибуты

HttpResponse.content

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

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.

Этот атрибут существует, чтобы промежуточное ПО могло обращаться с потоковыми ответами по-разному от обычных ответов.

HttpResponse.closed

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

Методы

HttpResponse.__init__(content=b'', content_type=None, status=200, reason=None, charset=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.

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

Добавлена поддержка memoryview content.

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

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

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

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

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

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

Разрешено использование samesite='None' (строка).

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

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().

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

Разрешено использование samesite='None' (строка).

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

Удаляет cookie с заданным ключом. Проходит без ошибок, если ключ не существует.

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

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

Добавлен аргумент samesite.

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.

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

Атрибуты

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.