`http.cookies.md`

229 строк · 17.1 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.14/library/http.cookies.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `http.cookies` – Управление состоянием HTTP89**Исходный код:** [Lib/http/cookies.py](https://python-all.ru/src/3.14/Lib/http/cookies.py)1011---1213Модуль `http.cookies` определяет классы для абстрагирования концепции куки – механизма управления состоянием HTTP. Он поддерживает как простые куки, состоящие только из строк, так и абстракцию для использования любого сериализуемого типа данных в качестве значения куки.1415Ранее модуль строго применял правила разбора, описанные в спецификациях [**RFC 2109**](https://python-all.ru/3.14/library/http.cookies.html) и [**RFC 2068**](https://python-all.ru/3.14/library/http.cookies.html). С тех пор было обнаружено, что MSIE 3.0x не следовал правилам символов, изложенным в этих спецификациях; многие современные браузеры и серверы также ослабили правила разбора при работе с куки. В результате этот модуль теперь использует правила разбора, которые стали несколько менее строгими, чем раньше.1617Наборы символов [`string.ascii_letters`](https://python-all.ru/3.14/library/string.html#string.ascii_letters), [`string.digits`](https://python-all.ru/3.14/library/string.html#string.digits) и `` !#$%&'*+-.^_`|~: `` обозначают множество допустимых символов, разрешённых этим модулем в имени куки (как [`key`](https://python-all.ru/3.14/library/http.cookies.html#http.cookies.Morsel.key)).1819Изменено в версии 3.3: Разрешён символ ‘:’ в качестве допустимого символа в имени куки.2021> **Примечание**22>23> При обнаружении недопустимой куки возбуждается исключение [`CookieError`](https://python-all.ru/3.14/library/http.cookies.html#http.cookies.CookieError), поэтому, если данные куки поступают из браузера, всегда следует быть готовым к недопустимым данным и перехватывать `CookieError` при разборе.2425#### `exception http.cookies.CookieError`2627Исключение, возникающее из-за недействительности [**RFC 2109**](https://python-all.ru/3.14/library/http.cookies.html): неверные атрибуты, неверный заголовок *Set-Cookie* и т.д.2829#### `class http.cookies.BaseCookie([input])`3031Этот класс является объектом, подобным словарю, ключи которого – строки, а значения – экземпляры [`Morsel`](https://python-all.ru/3.14/library/http.cookies.html#http.cookies.Morsel). Обратите внимание, что при установке ключа в значение, это значение сначала преобразуется в объект `Morsel`, содержащий ключ и значение.3233Если передан параметр *input*, он передаётся методу [`load()`](https://python-all.ru/3.14/library/http.cookies.html#http.cookies.BaseCookie.load).3435#### `class http.cookies.SimpleCookie([input])`3637Этот класс происходит от [`BaseCookie`](https://python-all.ru/3.14/library/http.cookies.html#http.cookies.BaseCookie) и переопределяет [`value_decode()`](https://python-all.ru/3.14/library/http.cookies.html#http.cookies.BaseCookie.value_decode) и [`value_encode()`](https://python-all.ru/3.14/library/http.cookies.html#http.cookies.BaseCookie.value_encode). `SimpleCookie` поддерживает строки в качестве значений куки. При установке значения `SimpleCookie` вызывает встроенную функцию [`str()`](https://python-all.ru/3.14/library/stdtypes.html#str) для преобразования значения в строку. Значения, полученные из HTTP, сохраняются как строки.3839> **См. также**40>41> **Модуль [`http.cookiejar`](https://python-all.ru/3.14/library/http.cookiejar.html#module-http.cookiejar)**42>43> Обработка HTTP-куки для веб-*клиентов*. Модули [`http.cookiejar`](https://python-all.ru/3.14/library/http.cookiejar.html#module-http.cookiejar) и `http.cookies` не зависят друг от друга.44>45> **[**RFC 2109**](https://python-all.ru/3.14/library/http.cookies.html) – Механизм управления состоянием HTTP**46>47> Это спецификация управления состоянием, реализованная этим модулем.4849## Объекты Cookie5051#### `BaseCookie.value_decode(val)`5253Возвращает кортеж `(real_value, coded_value)` из строкового представления. `real_value` может быть любого типа. Этот метод не выполняет декодирование в [`BaseCookie`](https://python-all.ru/3.14/library/http.cookies.html#http.cookies.BaseCookie) – он существует, чтобы его можно было переопределить.5455#### `BaseCookie.value_encode(val)`5657Возвращает кортеж `(real_value, coded_value)`. *val* может быть любого типа, но `coded_value` всегда будет преобразован в строку. Этот метод не выполняет кодирование в [`BaseCookie`](https://python-all.ru/3.14/library/http.cookies.html#http.cookies.BaseCookie) – он существует, чтобы его можно было переопределить.5859В общем случае должно выполняться условие, что `value_encode()` и [`value_decode()`](https://python-all.ru/3.14/library/http.cookies.html#http.cookies.BaseCookie.value_decode) являются взаимно обратными на области значений *value\_decode*.6061#### `BaseCookie.output(attrs=None, header='Set-Cookie:', sep='\r\n')`6263Возвращает строковое представление, пригодное для отправки в качестве HTTP-заголовков. *attrs* и *header* передаются каждому методу [`output()`](https://python-all.ru/3.14/library/http.cookies.html#http.cookies.Morsel.output) объекта [`Morsel`](https://python-all.ru/3.14/library/http.cookies.html#http.cookies.Morsel). *sep* используется для объединения заголовков, и по умолчанию имеет значение `'\r\n'` (CRLF).6465#### `BaseCookie.js_output(attrs=None)`6667Возвращает встраиваемый фрагмент JavaScript, который при выполнении в браузере, поддерживающем JavaScript, будет действовать так же, как если бы были отправлены HTTP-заголовки.6869Значение *attrs* такое же, как в [`output()`](https://python-all.ru/3.14/library/http.cookies.html#http.cookies.BaseCookie.output).7071#### `BaseCookie.load(rawdata)`7273Если *rawdata* является строкой, разобрать её как `HTTP_COOKIE` и добавить найденные значения как объекты [`Morsel`](https://python-all.ru/3.14/library/http.cookies.html#http.cookies.Morsel). Если это словарь, это эквивалентно:7475```python76for k, v in rawdata.items():77    cookie[k] = v78```7980## Объекты Morsel8182#### `class http.cookies.Morsel`8384Абстрагирует пару ключ/значение с атрибутами [**RFC 2109**](https://python-all.ru/3.14/library/http.cookies.html).8586Объекты Morsel похожи на словари, их набор ключей постоянен – это атрибуты [**RFC 2109**](https://python-all.ru/3.14/library/http.cookies.html), а именно:8788> #### `expires`89>90> #### `path`91>92> #### `comment`93>94> #### `domain`95>96> #### `max-age`97>98> #### `secure`99>100> #### `version`101>102> #### `httponly`103>104> #### `samesite`105>106> #### `partitioned`107108Атрибут [`httponly`](https://python-all.ru/3.14/library/http.cookies.html#http.cookies.Morsel.httponly) указывает, что cookie передаётся только в HTTP-запросах и недоступен через JavaScript. Это предназначено для снижения риска некоторых форм межсайтового скриптинга.109110Атрибут [`samesite`](https://python-all.ru/3.14/library/http.cookies.html#http.cookies.Morsel.samesite) управляет тем, когда браузер отправляет cookie с межсайтовыми запросами. Это помогает снизить риск CSRF-атак. Допустимые значения: “Strict” (отправляется только с запросами того же сайта), “Lax” (отправляется с запросами того же сайта и навигациями верхнего уровня) и “None” (отправляется с запросами того же сайта и межсайтовыми запросами). При использовании “None” также должен быть установлен атрибут “secure”, как того требуют современные браузеры.111112Атрибут [`partitioned`](https://python-all.ru/3.14/library/http.cookies.html#http.cookies.Morsel.partitioned) сообщает пользовательским агентам, что эти межсайтовые cookie *должны* быть доступны только в том же контексте верхнего уровня, в котором cookie был первоначально установлен. Чтобы это было принято пользовательским агентом, **необходимо** также установить `Secure`.113114Кроме того, рекомендуется использовать префикс `__Host` при установке разделённых cookie, чтобы они были привязаны к имени хоста, а не к регистрируемому домену. Полные сведения и примеры см. в [CHIPS (файлы cookie с независимым разделённым состоянием)](https://python-all.ru/3.14/library/http.cookies.html).115116Ключи нечувствительны к регистру, и их значение по умолчанию – `''`.117118Изменено в версии 3.5: `__eq__()` теперь учитывает [`key`](https://python-all.ru/3.14/library/http.cookies.html#http.cookies.Morsel.key) и [`value`](https://python-all.ru/3.14/library/http.cookies.html#http.cookies.Morsel.value).119120Изменено в версии 3.7: Атрибуты [`key`](https://python-all.ru/3.14/library/http.cookies.html#http.cookies.Morsel.key), [`value`](https://python-all.ru/3.14/library/http.cookies.html#http.cookies.Morsel.value) и [`coded_value`](https://python-all.ru/3.14/library/http.cookies.html#http.cookies.Morsel.coded_value) теперь доступны только для чтения. Для их установки используйте [`set()`](https://python-all.ru/3.14/library/http.cookies.html#http.cookies.Morsel.set).121122Изменено в версии 3.8: Добавлена поддержка атрибута [`samesite`](https://python-all.ru/3.14/library/http.cookies.html#http.cookies.Morsel.samesite).123124Изменено в версии 3.14: Добавлена поддержка атрибута [`partitioned`](https://python-all.ru/3.14/library/http.cookies.html#http.cookies.Morsel.partitioned).125126#### `Morsel.value`127128Значение cookie.129130#### `Morsel.coded_value`131132Закодированное значение cookie – именно его следует отправлять.133134#### `Morsel.key`135136Имя cookie.137138#### `Morsel.set(key, value, coded_value)`139140Устанавливает атрибуты *key*, *value* и *coded\_value*.141142#### `Morsel.isReservedKey(K)`143144Проверяет, входит ли *K* в набор ключей [`Morsel`](https://python-all.ru/3.14/library/http.cookies.html#http.cookies.Morsel).145146#### `Morsel.output(attrs=None, header='Set-Cookie:')`147148Возвращает строковое представление Morsel, пригодное для отправки в качестве HTTP-заголовка. По умолчанию включаются все атрибуты, если не указан *attrs* – в этом случае это должен быть список используемых атрибутов. *header* по умолчанию равен `"Set-Cookie:"`.149150#### `Morsel.js_output(attrs=None)`151152Возвращает встраиваемый фрагмент JavaScript, который при выполнении в браузере, поддерживающем JavaScript, будет действовать так же, как если бы был отправлен HTTP-заголовок.153154Значение *attrs* такое же, как в [`output()`](https://python-all.ru/3.14/library/http.cookies.html#http.cookies.Morsel.output).155156#### `Morsel.OutputString(attrs=None)`157158Возвращает строку, представляющую Morsel, без какого-либо окружающего HTTP или JavaScript.159160Значение *attrs* такое же, как в [`output()`](https://python-all.ru/3.14/library/http.cookies.html#http.cookies.Morsel.output).161162#### `Morsel.update(values)`163164Обновляет значения в словаре Morsel значениями из словаря *values*. Вызывает ошибку, если какой-либо из ключей в словаре *values* не является допустимым атрибутом [**RFC 2109**](https://python-all.ru/3.14/library/http.cookies.html).165166Изменено в версии 3.5: возникает ошибка для недопустимых ключей.167168#### `Morsel.copy(value)`169170Возвращает поверхностную копию объекта Morsel.171172Изменено в версии 3.5: возвращает объект Morsel вместо словаря.173174#### `Morsel.setdefault(key, value=None)`175176Вызывает ошибку, если ключ не является допустимым атрибутом [**RFC 2109**](https://python-all.ru/3.14/library/http.cookies.html), в противном случае ведёт себя так же, как [`dict.setdefault()`](https://python-all.ru/3.14/library/stdtypes.html#dict.setdefault).177178## Пример179180Следующий пример демонстрирует, как использовать модуль `http.cookies`.181182```pycon183>>> from http import cookies184>>> C = cookies.SimpleCookie()185>>> C["fig"] = "newton"186>>> C["sugar"] = "wafer"187>>> print(C) # сгенерировать HTTP-заголовки188Set-Cookie: fig=newton189Set-Cookie: sugar=wafer190>>> print(C.output()) # то же самое191Set-Cookie: fig=newton192Set-Cookie: sugar=wafer193>>> C = cookies.SimpleCookie()194>>> C["rocky"] = "road"195>>> C["rocky"]["path"] = "/cookie"196>>> print(C.output(header="Cookie:"))197Cookie: rocky=road; Path=/cookie198>>> print(C.output(attrs=[], header="Cookie:"))199Cookie: rocky=road200>>> C = cookies.SimpleCookie()201>>> C.load("chips=ahoy; vienna=finger") # загрузить из строки (HTTP-заголовок)202>>> print(C)203Set-Cookie: chips=ahoy204Set-Cookie: vienna=finger205>>> C = cookies.SimpleCookie()206>>> C.load('keebler="E=everybody; L=\\"Loves\\"; fudge=;";')207>>> print(C)208Set-Cookie: keebler="E=everybody; L=\"Loves\"; fudge=;"209>>> C = cookies.SimpleCookie()210>>> C["oreo"] = "doublestuff"211>>> C["oreo"]["path"] = "/"212>>> print(C)213Set-Cookie: oreo=doublestuff; Path=/214>>> C = cookies.SimpleCookie()215>>> C["twix"] = "none for you"216>>> C["twix"].value217'none for you'218>>> C = cookies.SimpleCookie()219>>> C["number"] = 7 # эквивалентно C["number"] = str(7)220>>> C["string"] = "seven"221>>> C["number"].value222'7'223>>> C["string"].value224'seven'225>>> print(C)226Set-Cookie: number=7227Set-Cookie: string=seven228```229