Содержание страницы
20.22. Cookie – управление состоянием HTTP¶Cookie – HTTP state management
Примечание
Модуль Cookie переименован в http.cookies в Python
3. Инструмент 2to3 автоматически адаптирует импорты при преобразовании
исходных кодов в Python 3.
Исходный код: Lib/Cookie.py
Модуль Cookie определяет классы для абстрагирования концепции куки – механизма управления состоянием HTTP. Он поддерживает как простые куки, состоящие только из строк, так и абстракцию для использования любого сериализуемого типа данных в качестве значения куки.
Раньше модуль строго применял правила разбора, описанные в спецификациях RFC 2109 и RFC 2068. Но с тех пор выяснилось, что MSIE 3.0x не соблюдает описанные в этих спецификациях правила набора символов, и к тому же многие современные браузеры и серверы при работе с Cookie придерживаются менее строгих правил разбора. В результате используемые правила разбора стали несколько менее строгими.
Набор символов string.ascii_letters, string.digits и !#$%&'*+-.^_`|~ обозначает множество допустимых символов, которые разрешены этим модулем в имени Cookie (как key).
Примечание
При обнаружении недопустимой куки возбуждается исключение CookieError, поэтому, если данные куки поступают из браузера, всегда следует быть готовым к недопустимым данным и перехватывать CookieError при разборе.
-
exception
Cookie.CookieError¶ Исключение, возникающее из-за недействительности RFC 2109: неверные атрибуты, неверный заголовок Set-Cookie и т.д.
-
class
Cookie.BaseCookie([input])¶ Этот класс является объектом, подобным словарю, ключи которого – строки, а значения – экземпляры
Morsel. Обратите внимание, что при установке ключа в значение, это значение сначала преобразуется в объектMorsel, содержащий ключ и значение.Если передан параметр input, он передаётся методу
load().
-
class
Cookie.SimpleCookie([input])¶ Этот класс наследуется от
BaseCookieи переопределяетvalue_decode()иvalue_encode(), превращая их в identity иstr()соответственно.
-
class
Cookie.SerialCookie([input])¶ Этот класс наследуется от
BaseCookieи переопределяетvalue_decode()иvalue_encode(), чтобы они сталиpickle.loads()иpickle.dumps().Устарело с версии 2.3: Чтение значений pickle из ненадёжных данных cookie – серьёзная уязвимость, так как строки pickle могут быть специально созданы для выполнения произвольного кода на вашем сервере. Она поддерживается только для обратной совместимости и может быть удалена в будущем.
-
class
Cookie.SmartCookie([input])¶ Этот класс наследуется от
BaseCookie. Он переопределяетvalue_decode()так, чтобы он возвращалpickle.loads(), если это допустимый pickle, иначе само значение. Он переопределяетvalue_encode()так, чтобы он возвращалpickle.dumps(), если это не строка, в противном случае возвращает само значение.Устарело с версии 2.3: Те же предупреждения безопасности, что и в
SerialCookie, применимы и здесь.
Стоит сделать ещё одно замечание по безопасности. Для обратной совместимости модуль
Cookie экспортирует класс с именем Cookie, который является
просто псевдонимом для SmartCookie. Вероятно, это ошибка, и он будет
удалён в одной из будущих версий. Не следует использовать класс
Cookie в своих приложениях по той же причине, по которой не следует использовать класс SerialCookie.
См. также
20.22.1. Объекты Cookie¶Cookie Objects
-
BaseCookie.value_decode(val)¶ Возвращает декодированное значение из строкового представления. Возвращаемое значение может быть любого tипа. Этот метод ничего не делает в
BaseCookie– он существует, чтобы его можно было переопределить.
-
BaseCookie.value_encode(val)¶ Возвращает закодированное значение. val может быть любого типа, но возвращаемое значение должно быть строкой. Этот метод ничего не делает в
BaseCookie– он существует, чтобы его можно было переопределить.В общем случае должно выполняться условие, что
value_encode()иvalue_decode()являются взаимно обратными на области значений value_decode.
-
BaseCookie.output([attrs[, header[, sep]]])¶ Возвращает строковое представление, пригодное для отправки в качестве HTTP-заголовков. attrs и header передаются каждому методу
output()объектаMorsel. sep используется для объединения заголовков, и по умолчанию имеет значение'\r\n'(CRLF).Изменено в версии 2.5: Разделитель по умолчанию изменён с
'\n'в соответствии со спецификацией cookie.
20.22.2. Объекты Morsel¶Morsel Objects
-
class
Cookie.Morsel¶ Абстрагирует пару ключ/значение с атрибутами RFC 2109.
Объекты Morsel похожи на словари, и их набор ключей постоянен: это допустимые атрибуты RFC 2109, которые
expirespathcommentdomainmax-agesecureversionhttponly
Атрибут
httponlyуказывает, что cookie передаётся только в HTTP-запросах и недоступен через JavaScript. Это предназначено для снижения риска некоторых форм межсайтового скриптинга.Ключи нечувствительны к регистру.
Новое в версии 2.6: Был добавлен атрибут
httponly.
-
Morsel.value¶ Значение cookie.
-
Morsel.coded_value¶ Закодированное значение cookie – именно его следует отправлять.
-
Morsel.key¶ Имя cookie.
-
Morsel.set(key, value, coded_value)¶ Устанавливает атрибуты key, value и coded_value.
-
Morsel.output([attrs[, header]])¶ Возвращает строковое представление Morsel, пригодное для отправки в качестве HTTP-заголовка. По умолчанию включаются все атрибуты, если не указан attrs – в этом случае это должен быть список используемых атрибутов. header по умолчанию равен
"Set-Cookie:".
20.22.3. Пример¶Example
Следующий пример демонстрирует, как использовать модуль Cookie.
>>> import Cookie
>>> C = Cookie.SimpleCookie()
>>> C["fig"] = "newton"
>>> C["sugar"] = "wafer"
>>> print C # сгенерировать HTTP-заголовки
Set-Cookie: fig=newton
Set-Cookie: sugar=wafer
>>> print C.output() # то же самое
Set-Cookie: fig=newton
Set-Cookie: sugar=wafer
>>> C = Cookie.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 = Cookie.SimpleCookie()
>>> C.load("chips=ahoy; vienna=finger") # загрузить из строки (HTTP-заголовок)
>>> print C
Set-Cookie: chips=ahoy
Set-Cookie: vienna=finger
>>> C = Cookie.SimpleCookie()
>>> C.load('keebler="E=everybody; L=\\"Loves\\"; fudge=\\012;";')
>>> print C
Set-Cookie: keebler="E=everybody; L=\"Loves\"; fudge=\012;"
>>> C = Cookie.SimpleCookie()
>>> C["oreo"] = "doublestuff"
>>> C["oreo"]["path"] = "/"
>>> print C
Set-Cookie: oreo=doublestuff; Path=/
>>> C["twix"] = "none for you"
>>> C["twix"].value
'none for you'
>>> C = Cookie.SimpleCookie()
>>> C["number"] = 7 # эквивалентно 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
>>> # SerialCookie и SmartCookie устарели
>>> # его использование может привести к появлению уязвимостей безопасности в вашем коде.
>>> C = Cookie.SerialCookie()
>>> C["number"] = 7
>>> C["string"] = "seven"
>>> C["number"].value
7
>>> C["string"].value
'seven'
>>> print C
Set-Cookie: number="I7\012."
Set-Cookie: string="S'seven'\012p1\012."
>>> C = Cookie.SmartCookie()
>>> C["number"] = 7
>>> C["string"] = "seven"
>>> C["number"].value
7
>>> C["string"].value
'seven'
>>> print C
Set-Cookie: number="I7\012."
Set-Cookie: string=seven