`http.cookies.md`

221 строк · 15.8 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.13/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.13/Lib/http/cookies.py)1011---1213Модуль `http.cookies` определяет классы для абстрагирования концепции куки – механизма управления состоянием HTTP. Он поддерживает как простые куки, состоящие только из строк, так и абстракцию для использования любого сериализуемого типа данных в качестве значения куки.1415Ранее модуль строго применял правила разбора, описанные в спецификациях [**RFC 2109**](https://python-all.ru/3.13/library/http.cookies.html) и [**RFC 2068**](https://python-all.ru/3.13/library/http.cookies.html). С тех пор было обнаружено, что MSIE 3.0x не следовал правилам символов, изложенным в этих спецификациях; многие современные браузеры и серверы также ослабили правила разбора при работе с куки. В результате этот модуль теперь использует правила разбора, которые стали несколько менее строгими, чем раньше.1617Наборы символов [`string.ascii_letters`](https://python-all.ru/3.13/library/string.html#string.ascii_letters), [`string.digits`](https://python-all.ru/3.13/library/string.html#string.digits) и `` !#$%&'*+-.^_`|~: `` обозначают множество допустимых символов, разрешённых этим модулем в имени куки (как [`key`](https://python-all.ru/3.13/library/http.cookies.html#http.cookies.Morsel.key)).1819Изменено в версии 3.3: Разрешён символ ‘:’ в качестве допустимого символа в имени куки.2021> **Примечание**22>23> При обнаружении недопустимой куки возбуждается исключение [`CookieError`](https://python-all.ru/3.13/library/http.cookies.html#http.cookies.CookieError), поэтому, если данные куки поступают из браузера, всегда следует быть готовым к недопустимым данным и перехватывать `CookieError` при разборе.2425#### `exception http.cookies.CookieError`2627Исключение, возникающее из-за недействительности [**RFC 2109**](https://python-all.ru/3.13/library/http.cookies.html): неверные атрибуты, неверный заголовок *Set-Cookie* и т.д.2829#### `class http.cookies.BaseCookie([input])`3031Этот класс является объектом, подобным словарю, ключи которого – строки, а значения – экземпляры [`Morsel`](https://python-all.ru/3.13/library/http.cookies.html#http.cookies.Morsel). Обратите внимание, что при установке ключа в значение, это значение сначала преобразуется в объект `Morsel`, содержащий ключ и значение.3233Если передан параметр *input*, он передаётся методу [`load()`](https://python-all.ru/3.13/library/http.cookies.html#http.cookies.BaseCookie.load).3435#### `class http.cookies.SimpleCookie([input])`3637Этот класс происходит от [`BaseCookie`](https://python-all.ru/3.13/library/http.cookies.html#http.cookies.BaseCookie) и переопределяет [`value_decode()`](https://python-all.ru/3.13/library/http.cookies.html#http.cookies.BaseCookie.value_decode) и [`value_encode()`](https://python-all.ru/3.13/library/http.cookies.html#http.cookies.BaseCookie.value_encode). `SimpleCookie` поддерживает строки в качестве значений куки. При установке значения `SimpleCookie` вызывает встроенную функцию [`str()`](https://python-all.ru/3.13/library/stdtypes.html#str) для преобразования значения в строку. Значения, полученные из HTTP, сохраняются как строки.3839> **См. также**40>41> **Модуль [`http.cookiejar`](https://python-all.ru/3.13/library/http.cookiejar.html#module-http.cookiejar)**42>43> Обработка HTTP-куки для веб-*клиентов*. Модули [`http.cookiejar`](https://python-all.ru/3.13/library/http.cookiejar.html#module-http.cookiejar) и `http.cookies` не зависят друг от друга.44>45> **[**RFC 2109**](https://python-all.ru/3.13/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.13/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.13/library/http.cookies.html#http.cookies.BaseCookie) – он существует, чтобы его можно было переопределить.5859В общем случае должно выполняться условие, что `value_encode()` и [`value_decode()`](https://python-all.ru/3.13/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.13/library/http.cookies.html#http.cookies.Morsel.output) объекта [`Morsel`](https://python-all.ru/3.13/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.13/library/http.cookies.html#http.cookies.BaseCookie.output).7071#### `BaseCookie.load(rawdata)`7273Если *rawdata* является строкой, разобрать её как `HTTP_COOKIE` и добавить найденные значения как объекты [`Morsel`](https://python-all.ru/3.13/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.13/library/http.cookies.html).8586Объекты Morsel похожи на словари, их набор ключей постоянен – это атрибуты [**RFC 2109**](https://python-all.ru/3.13/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`105106Атрибут [`httponly`](https://python-all.ru/3.13/library/http.cookies.html#http.cookies.Morsel.httponly) указывает, что cookie передаётся только в HTTP-запросах и недоступен через JavaScript. Это предназначено для снижения риска некоторых форм межсайтового скриптинга.107108Атрибут [`samesite`](https://python-all.ru/3.13/library/http.cookies.html#http.cookies.Morsel.samesite) управляет тем, когда браузер отправляет cookie с межсайтовыми запросами. Это помогает снизить риск CSRF-атак. Допустимые значения: “Strict” (отправляется только с запросами того же сайта), “Lax” (отправляется с запросами того же сайта и навигациями верхнего уровня) и “None” (отправляется с запросами того же сайта и межсайтовыми запросами). При использовании “None” также должен быть установлен атрибут “secure”, как того требуют современные браузеры.109110Ключи нечувствительны к регистру, и их значение по умолчанию – `''`.111112Изменено в версии 3.5: `__eq__()` теперь учитывает [`key`](https://python-all.ru/3.13/library/http.cookies.html#http.cookies.Morsel.key) и [`value`](https://python-all.ru/3.13/library/http.cookies.html#http.cookies.Morsel.value).113114Изменено в версии 3.7: Атрибуты [`key`](https://python-all.ru/3.13/library/http.cookies.html#http.cookies.Morsel.key), [`value`](https://python-all.ru/3.13/library/http.cookies.html#http.cookies.Morsel.value) и [`coded_value`](https://python-all.ru/3.13/library/http.cookies.html#http.cookies.Morsel.coded_value) теперь доступны только для чтения. Для их установки используйте [`set()`](https://python-all.ru/3.13/library/http.cookies.html#http.cookies.Morsel.set).115116Изменено в версии 3.8: Добавлена поддержка атрибута [`samesite`](https://python-all.ru/3.13/library/http.cookies.html#http.cookies.Morsel.samesite).117118#### `Morsel.value`119120Значение cookie.121122#### `Morsel.coded_value`123124Закодированное значение cookie – именно его следует отправлять.125126#### `Morsel.key`127128Имя cookie.129130#### `Morsel.set(key, value, coded_value)`131132Устанавливает атрибуты *key*, *value* и *coded\_value*.133134#### `Morsel.isReservedKey(K)`135136Проверяет, входит ли *K* в набор ключей [`Morsel`](https://python-all.ru/3.13/library/http.cookies.html#http.cookies.Morsel).137138#### `Morsel.output(attrs=None, header='Set-Cookie:')`139140Возвращает строковое представление Morsel, пригодное для отправки в качестве HTTP-заголовка. По умолчанию включаются все атрибуты, если не указан *attrs* – в этом случае это должен быть список используемых атрибутов. *header* по умолчанию равен `"Set-Cookie:"`.141142#### `Morsel.js_output(attrs=None)`143144Возвращает встраиваемый фрагмент JavaScript, который при выполнении в браузере, поддерживающем JavaScript, будет действовать так же, как если бы был отправлен HTTP-заголовок.145146Значение *attrs* такое же, как в [`output()`](https://python-all.ru/3.13/library/http.cookies.html#http.cookies.Morsel.output).147148#### `Morsel.OutputString(attrs=None)`149150Возвращает строку, представляющую Morsel, без какого-либо окружающего HTTP или JavaScript.151152Значение *attrs* такое же, как в [`output()`](https://python-all.ru/3.13/library/http.cookies.html#http.cookies.Morsel.output).153154#### `Morsel.update(values)`155156Обновляет значения в словаре Morsel значениями из словаря *values*. Вызывает ошибку, если какой-либо из ключей в словаре *values* не является допустимым атрибутом [**RFC 2109**](https://python-all.ru/3.13/library/http.cookies.html).157158Изменено в версии 3.5: возникает ошибка для недопустимых ключей.159160#### `Morsel.copy(value)`161162Возвращает поверхностную копию объекта Morsel.163164Изменено в версии 3.5: возвращает объект Morsel вместо словаря.165166#### `Morsel.setdefault(key, value=None)`167168Вызывает ошибку, если ключ не является допустимым атрибутом [**RFC 2109**](https://python-all.ru/3.13/library/http.cookies.html), в противном случае ведёт себя так же, как [`dict.setdefault()`](https://python-all.ru/3.13/library/stdtypes.html#dict.setdefault).169170## Пример171172Следующий пример демонстрирует, как использовать модуль `http.cookies`.173174```pycon175>>> from http import cookies176>>> C = cookies.SimpleCookie()177>>> C["fig"] = "newton"178>>> C["sugar"] = "wafer"179>>> print(C) # сгенерировать HTTP-заголовки180Set-Cookie: fig=newton181Set-Cookie: sugar=wafer182>>> print(C.output()) # то же самое183Set-Cookie: fig=newton184Set-Cookie: sugar=wafer185>>> C = cookies.SimpleCookie()186>>> C["rocky"] = "road"187>>> C["rocky"]["path"] = "/cookie"188>>> print(C.output(header="Cookie:"))189Cookie: rocky=road; Path=/cookie190>>> print(C.output(attrs=[], header="Cookie:"))191Cookie: rocky=road192>>> C = cookies.SimpleCookie()193>>> C.load("chips=ahoy; vienna=finger") # загрузить из строки (HTTP-заголовок)194>>> print(C)195Set-Cookie: chips=ahoy196Set-Cookie: vienna=finger197>>> C = cookies.SimpleCookie()198>>> C.load('keebler="E=everybody; L=\\"Loves\\"; fudge=;";')199>>> print(C)200Set-Cookie: keebler="E=everybody; L=\"Loves\"; fudge=;"201>>> C = cookies.SimpleCookie()202>>> C["oreo"] = "doublestuff"203>>> C["oreo"]["path"] = "/"204>>> print(C)205Set-Cookie: oreo=doublestuff; Path=/206>>> C = cookies.SimpleCookie()207>>> C["twix"] = "none for you"208>>> C["twix"].value209'none for you'210>>> C = cookies.SimpleCookie()211>>> C["number"] = 7 # эквивалентно C["number"] = str(7)212>>> C["string"] = "seven"213>>> C["number"].value214'7'215>>> C["string"].value216'seven'217>>> print(C)218Set-Cookie: number=7219Set-Cookie: string=seven220```221