http.cookies — HTTP state management

Вихідний код: Lib/http/cookies.py

Модуль http.cookies визначає класи для абстрагування концепції файлів cookie, механізму керування станом HTTP. Він підтримує як прості файли cookie лише з рядками, так і надає абстракцію для будь-якого серіалізованого типу даних як значення cookie.

The module formerly strictly applied the parsing rules described in the RFC 2109 and RFC 2068 specifications. It has since been discovered that MSIE 3.0x didn’t follow the character rules outlined in those specs; many current-day browsers and servers have also relaxed parsing rules when it comes to cookie handling. As a result, this module now uses parsing rules that are a bit less strict than they once were.

The character set, string.ascii_letters, string.digits and !#$%&'*+-.^_`|~: denote the set of valid characters allowed by this module in a cookie name (as key).

Змінено в версії 3.3: Allowed „:“ as a valid cookie name character.

Примітка

У разі виявлення недійсних файлів cookie виникає помилка CookieError, тому, якщо ваші дані файлів cookie надходять із браузера, ви повинні завжди бути готовими до недійсних даних і виявляти помилку CookieError під час синтаксичного аналізу.

exception http.cookies.CookieError

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

class http.cookies.BaseCookie([input])

Цей клас є словниковим об’єктом, ключі якого є рядками, а значення – екземплярами Morsel. Зауважте, що після встановлення ключа значення, значення спочатку перетворюється на Morsel, що містить ключ і значення.

Якщо задано input, воно передається в метод load().

class http.cookies.SimpleCookie([input])

This class derives from BaseCookie and overrides value_decode() and value_encode(). SimpleCookie supports strings as cookie values. When setting the value, SimpleCookie calls the builtin str() to convert the value to a string. Values received from HTTP are kept as strings.

Дивись також

Модуль http.cookiejar

Обробка файлів cookie HTTP для веб-клієнтів. Модулі http.cookiejar і http.cookies не залежать один від одного.

RFC 2109 - механізм керування станом HTTP

Це специфікація управління станом, реалізована цим модулем.

Шматок об’єктів

class http.cookies.Morsel

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

Morsels are dictionary-like objects, whose set of keys is constant — the valid RFC 2109 attributes, which are:

expires
path
comment
domain
max-age
secure
version
httponly
samesite

Атрибут httponly вказує, що файл cookie передається лише в HTTP-запитах і не доступний через JavaScript. Це призначено для пом’якшення деяких форм міжсайтових сценаріїв.

Атрибут samesite вказує, що браузеру заборонено надсилати файли cookie разом із міжсайтовими запитами. Це допомагає пом’якшити атаки CSRF. Дійсні значення для цього атрибута: «Strict» і «Lax».

Ключі нечутливі до регістру, а їхнє значення за замовчуванням – ''.

Змінено в версії 3.5: __eq__() now takes key and value into account.

Змінено в версії 3.7: Атрибути key, value і coded_value доступні лише для читання. Використовуйте set() для їх налаштування.

Змінено в версії 3.8: Додано підтримку атрибута samesite.

Morsel.value

Значення файлу cookie.

Morsel.coded_value

Закодоване значення файлу cookie — це те, що потрібно надіслати.

Morsel.key

Назва файлу cookie.

Morsel.set(key, value, coded_value)

Установіть атрибути key, value і coded_value.

Morsel.isReservedKey(K)

Чи є K членом набору ключів Morsel.

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

Повертає рядкове представлення Morsel, придатне для надсилання як заголовок HTTP. За замовчуванням включено всі атрибути, якщо не вказано attrs, у цьому випадку це має бути список атрибутів для використання. заголовок за замовчуванням "Set-Cookie:".

Morsel.js_output(attrs=None)

Повертає вбудований фрагмент JavaScript, який, якщо запустити в браузері, який підтримує JavaScript, діятиме так само, як якщо б було надіслано заголовок HTTP.

Значення attrs таке ж, як і в output().

Morsel.OutputString(attrs=None)

Повертає рядок, що представляє Morsel, без будь-якого оточуючого HTTP або JavaScript.

Значення attrs таке ж, як і в output().

Morsel.update(values)

Оновіть значення в словнику Morsel значеннями в словнику values. Викликає помилку, якщо будь-який із ключів у values dict не є дійсним атрибутом RFC 2109.

Змінено в версії 3.5: виникає помилка для недійсних ключів.

Morsel.copy(value)

Поверніть дрібну копію об’єкта Morsel.

Змінено в версії 3.5: повертає об’єкт Morsel замість dict.

Morsel.setdefault(key, value=None)

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

приклад

У наступному прикладі показано, як використовувати модуль 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