Сообщить об ошибке.

Модуль http.cookies в Python

Синтаксического анализа файлов cookies

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

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

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

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

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

Содержание:


http.cookies.BaseCookie([input]):

Класс http.cookies.BaseCookie() представляет собой объект подобный словарю, ключи которого являются строками, а значения - экземпляры класса http.cookies.Morsel.

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

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

http.cookies.SimpleCookie([input]):

Класс http.cookies.SimpleCookie() является производным от BaseCookie и переопределяет методы value_decode() и value_encode().

Класс SimpleCookie поддерживает строки как значения файлов cookie. При установке значения SimpleCookie вызывает встроенную функцию str() для преобразования значения в строку. Значения, полученные от HTTP, хранятся в виде строк.

Исключение модуля http.cookies:

http.cookies.CookieError:

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

Смотрите также модуль http.cookiejar, который представляет собой обработчик HTTP-файлов cookie для веб-клиентов . Модули http.cookiejar и http.cookies не зависят друг от друга.

Объект cookie.


BaseCookie.value_decode(val):

Метод BaseCookie.value_decode() возвращает кортеж (real_value, coded_value) из строкового представления.

Аргумент val может быть любого типа. Этот метод в BaseCookie не выполняет декодирование, он просто существует, поэтому его можно переопределить.

BaseCookie.value_encode(val):

Метод BaseCookie.value_encode() возвращает кортеж (real_value, coded_value).

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

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

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

Метод BaseCookie.output() возвращает строковое представление, подходящее для отправки в виде заголовков HTTP.

Аргументы attrs и header отправляются каждому методу объекта Morsel.output().

Аргумент sep используется для объединения заголовков и по умолчанию и представляет собой комбинацию '\r\n' (CRLF).

BaseCookie.js_output(attrs=None):

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

Значение аргумента attrs такое же, как и в BaseCookie.output().

BaseCookie.load(rawdata):

Метод BaseCookie.load() анализирует rawdata как HTTP_COOKIE.

Если rawdata является строкой, то она проанализируется как HTTP_COOKIE, и так же добавит найденные в ней значения как объект Morsel.

Если это словарь, он эквивалентен:

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

Объект Morsel.

http.cookies.Morsel([input]):

Класс http.cookies.Morsel представляет собой абстракцию пары ключ/значение, которая имеет некоторые атрибуты RFC 2109.

Morsel - это объекты, подобные словарю, набор ключей которых постоянен. Допустимые атрибуты этого объекта по RFC 2109: expires, path, comment, domain, max-age, secure, version, httponly, samesite.

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

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

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

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

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

Атрибуты и методы объекта Morsel.


Morsel.value:

Атрибут Morsel.value возвращает значение cookie.

Morsel.coded_value:

Атрибут Morsel.coded_value возвращает закодированное значение cookie - это то, что нужно отправить.

Morsel.key:

Атрибут Morsel.key возвращает имя cookie.

Morsel.set(key, value, coded_value):

Метод Morsel.set() устанавливает атрибуты key, value и coded_value.

Morsel.isReservedKey(K):

Метод Morsel.isReservedKey() проверяет, является ли аргумент K членом набора ключей объекта Morsel.

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

Метод Morsel.output() возвращает строковое представление объекта Morsel, подходящее для отправки в качестве заголовка HTTP.

По умолчанию для передачи в качестве заголовка HTTP включены все атрибуты. Если не указан аргумент attrs, то в этом случае это должен быть список атрибутов для передачи в качестве заголовка HTTP.

Генерируемый заголовок cookie по умолчанию - Set-Cookie:.

Morsel.js_output(attrs=None):

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

Значение аргумента attrs такое же, как и в Morsel.output().

Morsel.OutputString(attrs=None):

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

Значение аргумента attrs такое же, как и в Morsel.output().

Morsel.update(values):

Метод Morsel.update() обновляет значения в словаре объекта Morsel значениями из словарных значений. Вызывает ошибку, если какой-либо из ключей values не является допустимым атрибутом RFC 2109 (имена допустимых атрибутов смотрите выше).

Morsel.copy(value):

Метод Morsel.copy() возвращает неглубокую копию объекта Morsel.

Morsel.setdefault(key, value=None):

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


Примеры составления и генерации заголовков cookie модулем http.cookies:

В примере показано как собирать cookie HTTP заголовки из ключей и значений.

>>> from http import cookies
>>> cook = cookies.SimpleCookie()
>>> cook["fig"] = "newton"
>>> cook["sugar"] = "wafer"

# генерация HTTP заголовков
>>> print(cook)
# Set-Cookie: fig=newton
# Set-Cookie: sugar=wafer

# То же самое
>>> print(cook.output())
# Set-Cookie: fig=newton
# Set-Cookie: sugar=wafer

# генерация HTTP заголовков с 
# дополнительными параметрами
>>> cook = cookies.SimpleCookie()
>>> cook["rocky"] = "road"
>>> cook["rocky"]["path"] = "/cookie"
>>> print(cook.output(header="Cookie:"))
# Cookie: rocky=road; Path=/cookie
>>> print(cook.output(attrs=[], header="Cookie:"))
# Cookie: rocky=road

В следующем примере показано как генерировать cookie HTTP заголовки из строки.

>>> from http import cookies
>>> cook = cookies.SimpleCookie()
# Например надо установить такие куки
cookie = "chips=ahoy; vienna=finger"
# загрузка из строки
>>> cook.load(cookie)
>>> print(cook)
# Set-Cookie: chips=ahoy
# Set-Cookie: vienna=finger

# Обработка обратных слешей 
>>> cookie = 'keebler="E=everybody; L=\\"Loves\\"; fudge=\\012;";'
>>> cook = cookies.SimpleCookie()
>>> cook.load(cookie)
>>> print(cook)
# Set-Cookie: keebler="E=everybody; L=\"Loves\"; fudge=\012;"

Пример демонстрирующий некоторые особенности модуля.

>>> from http import cookies
>>> cook = cookies.SimpleCookie()
>>> cook["oreo"] = "doublestuff"
>>> cook["oreo"]["path"] = "/"
>>> print(cook)
# Set-Cookie: oreo=doublestuff; Path=/

>>> cook = cookies.SimpleCookie()
>>> cook["twix"] = "none for you"
>>> cook["twix"].value
# 'none for you'

>>> cook = cookies.SimpleCookie()
# Следующая операция эквивалентна C["number"] = str(7)
>>> cook["number"] = 7
>>> cook["number"].value
# '7'
>>> cook["string"] = "seven"
>>> cook["string"].value
# 'seven'
>>> print(cook)
# Set-Cookie: number=7
# Set-Cookie: string=seven