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

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

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

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

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

exception Cookie.CookieError

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

class Cookie.BaseCookie([input])

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

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

class Cookie.SimpleCookie([input])

Этот класс наследуется от BaseCookie и переопределяет value_decode() и value_encode() как идентичность и str() соответственно.

class Cookie.SerialCookie([input])

Этот класс наследуется от BaseCookie и переопределяет value_decode() и value_encode() на pickle.loads() и pickle.dumps().

Устарело начиная с версии 2.3: Чтение закодированных значений из ненадежных данных куки — серьёзная уязвимость безопасности, так как строки pickle могут быть сформированы для выполнения произвольного кода на вашем сервере. Он поддерживается только для обратной совместимости и, возможно, в будущем будет удален.

class Cookie.SmartCookie([input])

Этот класс наследуется от BaseCookie. Он переопределяет value_decode() на pickle.loads(), если это корректный pickle, в противном случае само значение. Он переопределяет value_encode() на pickle.dumps(), за исключением случаев, когда это строка, в этом случае он возвращает само значение.

Устарело начиная с версии 2.3: Здесь также действует то же предупреждение о безопасности, что и для SerialCookie.

Необходимо сделать дополнительное примечание о безопасности. Для обратной совместимости модуль Cookie экспортирует класс с именем Cookie, который просто является псевдонимом для SmartCookie. Скорее всего, это ошибка, и она, вероятно, будет удалена в будущей версии. Вы не должны использовать класс Cookie в своих приложениях по той же причине, по которой не следует использовать класс SerialCookie.

1. Объекты Cookie

BaseCookie.value_decode(val)

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

BaseCookie.value_encode(val)

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

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

BaseCookie.output([attrs[, header[, sep]]])

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

Изменено в версии 2.5: Разделитель по умолчанию изменен с '\n' для соответствия спецификации куки.

BaseCookie.js_output([attrs])

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

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

BaseCookie.load(rawdata)

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

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

2. Объекты Morsel

class Cookie.Morsel

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

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

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

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

Ключи регистронезависимы.

Добавлена в версии 2.6: Атрибут httponly был добавлен.

Morsel.value

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

Morsel.coded_value

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

Morsel.key

Имя куки.

Morsel.set(key, value, coded_value)

Устанавливает атрибуты ключ, значение и coded_value.

Morsel.isReservedKey(K)

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

Morsel.output([attrs[, header]])

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

Morsel.js_output([attrs])

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

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

Morsel.OutputString([attrs])

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

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

3. Пример

Следующий пример демонстрирует использование модуля Cookie.

>>> import Cookie
>>> C = Cookie.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 = 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") # load from a string (HTTP header)
>>> 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 # 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
>>> # SerialCookie and SmartCookie are deprecated
>>> # using it can cause security loopholes in your code.
>>> 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