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

Исходный код: Lib/http/cookies.py

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

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

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

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() на идентичность и str() соответственно.

21.23.1. Объекты Cookie

BaseCookie.value_decode(val)

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

BaseCookie.value_encode(val)

Возвращает закодированное значение. val может быть любого типа, но возвращаемое значение должно быть строкой. Этот метод ничего не делает в BaseCookie — он существует, чтобы его можно было переопределить.

В целом, должно быть так, что value_encode() и value_decode() являются обратными на диапазоне value_decode.

BaseCookie.output(attrs=None, header='Set-Cookie:', sep='\r\n')

Возвращает строковое представление, подходящее для отправки в виде заголовков HTTP. attrs и header передаются каждому Morsel’s методу output(). sep используется для объединения заголовков, и по умолчанию это сочетание '\r\n' (CRLF).

BaseCookie.js_output(attrs=None)

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

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

BaseCookie.load(rawdata)

Если rawdata — строка, разобрать её как HTTP_COOKIE и добавить найденные значения в качестве Morsels. Если это словарь, это эквивалентно:

for k, v in rawdata.items():
    cookie[k] = v

21.23.2. Объекты Morsel

class http.cookies.Morsel

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

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

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

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

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

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

Morsel.value

Значение куки.

Устаревшее начиная с версии 3.5: присваивание value; используйте set() вместо этого.

Morsel.coded_value

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

Устаревшее начиная с версии 3.5: присваивание coded_value; используйте set() вместо этого.

Morsel.key

Имя куки.

Устаревшее начиная с версии 3.5: присваивание key; используйте set() вместо этого.

Morsel.set(key, value, coded_value)

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

Устаревшее начиная с версии 3.5: Недокументированный параметр LegalChars игнорируется и будет удалён в будущей версии.

Morsel.isReservedKey(K)

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

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

Возвращает строковое представление Morsel, подходящее для отправки в качестве заголовка 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. Вызывает ошибку, если какой-либо ключ в словаре values не является допустимым атрибутом RFC 2109.

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

Morsel.copy(value)

Возвращает неглубокую копию объекта куки.

Изменено в версии 3.5: возвращается объект Morsel вместо словаря.

Morsel.setdefault(key, value=None)

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

21.23.3. Пример

Следующий пример демонстрирует, как использовать модуль http.cookies.

>>> from http import cookies
>>> C = cookies.SimpleCookie()
>>> C["fig"] = "newton"
>>> C["sugar"] = "wafer"
>>> print(C) # generate HTTP headers
Set-Cookie: fig=newton
Set-Cookie: sugar=wafer
>>> print(C.output()) # same thing
Set-Cookie: fig=newton
Set-Cookie: sugar=wafer
>>> C = cookies.SimpleCookie()
>>> C["rocky"] = "road"
>>> C["rocky"]["path"] = "/cookie"
>>> print(C.output(header="Cookie:"))
Cookie: rocky=road; Path=/cookie
>>> print(C.output(attrs=[], header="Cookie:"))
Cookie: rocky=road
>>> C = cookies.SimpleCookie()
>>> C.load("chips=ahoy; vienna=finger") # load from a string (HTTP header)
>>> print(C)
Set-Cookie: chips=ahoy
Set-Cookie: vienna=finger
>>> C = cookies.SimpleCookie()
>>> C.load('keebler="E=everybody; L=\\"Loves\\"; fudge=\\012;";')
>>> print(C)
Set-Cookie: keebler="E=everybody; L=\"Loves\"; fudge=\012;"
>>> C = cookies.SimpleCookie()
>>> C["oreo"] = "doublestuff"
>>> C["oreo"]["path"] = "/"
>>> print(C)
Set-Cookie: oreo=doublestuff; Path=/
>>> C = cookies.SimpleCookie()
>>> C["twix"] = "none for you"
>>> C["twix"].value
'none for you'
>>> C = cookies.SimpleCookie()
>>> C["number"] = 7 # equivalent to C["number"] = str(7)
>>> C["string"] = "seven"
>>> C["number"].value
'7'
>>> C["string"].value
'seven'
>>> print(C)
Set-Cookie: number=7
Set-Cookie: string=seven