http.cookies — Управление состоянием HTTP

Модуль http.cookies определяет классы для абстрагирования концепции cookie, механизма управления состоянием HTTP. Он поддерживает как простые строковые cookie, так и предоставляет абстракцию для использования любого сериализуемого типа данных в качестве значения cookie.

Ранее модуль строго применял правила синтаксического анализа, описанные в спецификациях RFC 2109 и RFC 2068. С тех пор было обнаружено, что MSIE 3.0x не следует правилам символов, изложенным в данных спецификациях, а также многие современные браузеры и серверы имеют ослабленные правила синтаксического анализа, когда дело доходит до обработки cookie. В результате используемые правила синтаксического анализа немного менее строги.

Множество символов string.ascii_letters, string.digits и !#$%&'*+-.^_`|~: обозначает множество допустимых символов, разрешенных этим модулем в имени файла cookie (как key).

Изменено в версии 3.3: Допускается «:» в качестве допустимого символа имени файла cookie.

Примечание

При обнаружении недействительного файла cookie возникает CookieError, поэтому, если ваши данные cookie поступают из браузера, вы всегда должны подготовиться к недопустимым данным и поймать CookieError при парсинге.

exception http.cookies.CookieError

Ошибка исключения из-за недействительности RFC 2109: неверные атрибуты, неправильный заголовок Set-Cookie и т. д.

class http.cookies.BaseCookie([input])

Данный класс — подобный словарю объект, ключи которого являются строками, а значения — экземплярами Morsel. Обратите внимание, что при установке значения ключа значение сначала преобразуется в Morsel, содержащее ключ и значение.

Если задан input, он передаётся методу load().

class http.cookies.SimpleCookie([input])

Данный класс является производным от BaseCookie и имеет приоритет над value_decode() и value_encode(). SimpleCookie поддерживает строки как значения cookie. При установке значения SimpleCookie вызывает встроенный str() для преобразования значения в строку. Значения, полученные от HTTP, хранятся в виде строк.

См.также

Модуль http.cookiejar
Обработка cookie HTTP для клиентов Интернета. http.cookiejar и Модули http.cookies не зависят друг от друга.
RFC 2109 — механизм управления состоянием HTTP
Это спецификация управления состоянием, реализованная этим модулем.

Объекты Морселя

class http.cookies.Morsel

Абстрагировать пару ключ/значение, у которой есть некоторые атрибуты RFC 2109.

Морсели — это подобные словарю объекты, множество ключей которых является постоянным — действительными атрибутами RFC 2109. Вот их перечень:

  • expires
  • path
  • comment
  • domain
  • max-age
  • secure
  • version
  • httponly
  • samesite

Атрибут httponly указывает, что cookie передаётся только в HTTP- запросах и недоступен через JavaScript. Это предназначено для смягчения некоторых форм межсайтового скриптинга.

Атрибут samesite указывает, что браузеру не разрешено отправлять cookie вместе с межсайтовыми запросами. Это помогает смягчить CSRF-атаки. Допустимые значения этого атрибута: «Strict» и «Lax».

Ключи не чувствительны к регистру, и их значение по умолчанию — ''.

Изменено в версии 3.5: __eq__() теперь принимает во внимание key и value.

Изменено в версии 3.7: Атрибуты key, value и coded_value доступны только для чтения. Для их настройки используйте set().

Изменено в версии 3.8: Добавлена поддержка атрибута samesite.

Morsel.value

Значение cookie.

Morsel.coded_value

Закодированное значение файла cookie — это то, что нужно отправить.

Morsel.key

Название куки.

Morsel.set(key, value, coded_value)

Устанавливает атрибуты key, value и coded_value.

Morsel.isReservedKey(K)

Является ли K членом набора ключей Morsel.

Morsel.output(attrs=None, header='Set-Cookie:')

Возвращает строковое представление Морселя, подходящее для отправки в качестве заголовка HTTP. По умолчанию включены все атрибуты, если не указан attrs, и в этом случае это должен быть список атрибутов для использования. header по умолчанию — "Set-Cookie:".

Morsel.js_output(attrs=None)

Возвращает встраиваемый фрагмент кода JavaScript, который при запуске в браузере, поддерживающем JavaScript, будет действовать так же, как если бы был отправлен заголовок HTTP.

Значение attrs такое же, как в output().

Morsel.OutputString(attrs=None)

Возвращает представляющую Морсель строку, без каких-либо окружающих HTTP или JavaScript.

Значение attrs такое же, как в output().

Morsel.update(values)

Обновляет значения в словаре Морселя значениями в словаре values. Вызвать ошибку, если какой-либо из ключей в dict values не является допустимым атрибутом RFC 2109.

Изменено в версии 3.5: Вызывается ошибка для недопустимых ключей.

Morsel.copy(value)

Возвращает поверхностную копию Морсель объекта.

Изменено в версии 3.5: Возвращает объект Морсель вместо dict.

Morsel.setdefault(key, value=None)

Вызывает ошибку, если ключ не является допустимым атрибутом RFC 2109, в противном случае ведёт себя так же, как dict.setdefault().