Модуль 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()
объект подобный словарю,http.cookies.SimpleCookie()
является производным BaseCookie
,http.cookies.CookieError
исключение модуля.BaseCookie.value_decode()
ничего не декодирует, существует для переопределения,BaseCookie.value_encode()
ничего не кодирует, существует для переопределения,BaseCookie.output()
вернет строку заголовков cookie,BaseCookie.js_output()
вернет фрагмент кода JavaScript,BaseCookie.load()
анализирует строку как HTTP_COOKIE
.Morsel
:Morsel.value
значение cookie,Morsel.coded_value
закодированное значение cookie,Morsel.key
имя cookie,Morsel.set()
устанавливает атрибуты key
, value
и coded_value
,Morsel.isReservedKey()
проверка членства ключа,Morsel.output()
строковое представление Morsel
,Morsel.js_output()
фрагмент кода JavaScript,Morsel.OutputString()
объект Morsel
в строку,Morsel.update()
обновляет словарь объекта Morsel
,Morsel.copy()
неглубокая копия Morsel
,Morsel.setdefault()
ведет себя так же, как dict.setdefault()
,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
не зависят друг от друга.
BaseCookie.value_decode()
ничего не декодирует, существует для переопределения,BaseCookie.value_encode()
ничего не кодирует, существует для переопределения,BaseCookie.output()
вернет строку заголовков cookie,BaseCookie.js_output()
вернет фрагмент кода JavaScript,BaseCookie.load()
анализирует строку как HTTP_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
значение cookie,Morsel.coded_value
закодированное значение cookie,Morsel.key
имя cookie,Morsel.set()
устанавливает атрибуты key
, value
и coded_value
,Morsel.isReservedKey()
проверка членства ключа,Morsel.output()
строковое представление Morsel
,Morsel.js_output()
фрагмент кода JavaScript,Morsel.OutputString()
объект Morsel
в строку,Morsel.update()
обновляет словарь объекта Morsel
,Morsel.copy()
неглубокая копия Morsel
,Morsel.setdefault()
ведет себя так же, как dict.setdefault()
,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()
.
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