`http.cookies.md`

213 строк · 15.4 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.10/library/http.cookies.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# [`http.cookies`](https://python-all.ru/3.10/library/http.cookies.html#module-http.cookies) – Управление состоянием HTTP89**Исходный код:** [Lib/http/cookies.py](https://python-all.ru/src/3.10/Lib/http/cookies.py)1011---1213Модуль [`http.cookies`](https://python-all.ru/3.10/library/http.cookies.html#module-http.cookies) определяет классы для абстрагирования концепции куки – механизма управления состоянием HTTP. Он поддерживает как простые куки, состоящие только из строк, так и абстракцию для использования любого сериализуемого типа данных в качестве значения куки.1415Раньше модуль строго применял правила разбора, описанные в спецификациях [**RFC 2109**](https://python-all.ru/3.10/library/http.cookies.html) и [**RFC 2068**](https://python-all.ru/3.10/library/http.cookies.html). Но с тех пор выяснилось, что MSIE 3.0x не соблюдает описанные в этих спецификациях правила набора символов, и к тому же многие современные браузеры и серверы при работе с Cookie придерживаются менее строгих правил разбора. В результате используемые правила разбора стали несколько менее строгими.1617Набор символов [`string.ascii_letters`](https://python-all.ru/3.10/library/string.html#string.ascii_letters), [`string.digits`](https://python-all.ru/3.10/library/string.html#string.digits) и `` !#$%&'*+-.^_`|~: `` обозначает множество допустимых символов, которые разрешены этим модулем в имени Cookie (как [`key`](https://python-all.ru/3.10/library/http.cookies.html#http.cookies.Morsel.key)).1819Изменено в версии 3.3: Разрешён символ ‘:’ в качестве допустимого символа имени Cookie.2021> **Примечание**22>23> При обнаружении недопустимой куки возбуждается исключение [`CookieError`](https://python-all.ru/3.10/library/http.cookies.html#http.cookies.CookieError), поэтому, если данные куки поступают из браузера, всегда следует быть готовым к недопустимым данным и перехватывать [`CookieError`](https://python-all.ru/3.10/library/http.cookies.html#http.cookies.CookieError) при разборе.2425#### `exception http.cookies.CookieError`2627Исключение, возникающее из-за недействительности [**RFC 2109**](https://python-all.ru/3.10/library/http.cookies.html): неверные атрибуты, неверный заголовок *Set-Cookie* и т.д.2829#### `class http.cookies.BaseCookie([input])`3031Этот класс является объектом, подобным словарю, ключи которого – строки, а значения – экземпляры [`Morsel`](https://python-all.ru/3.10/library/http.cookies.html#http.cookies.Morsel). Обратите внимание, что при установке ключа в значение, это значение сначала преобразуется в объект [`Morsel`](https://python-all.ru/3.10/library/http.cookies.html#http.cookies.Morsel), содержащий ключ и значение.3233Если передан параметр *input*, он передаётся методу [`load()`](https://python-all.ru/3.10/library/http.cookies.html#http.cookies.BaseCookie.load).3435#### `class http.cookies.SimpleCookie([input])`3637Этот класс наследуется от [`BaseCookie`](https://python-all.ru/3.10/library/http.cookies.html#http.cookies.BaseCookie) и переопределяет `value_decode()` и `value_encode()`. SimpleCookie поддерживает строки в качестве значений cookie. При установке значения SimpleCookie вызывает встроенную функцию [`str()`](https://python-all.ru/3.10/library/stdtypes.html#str) для преобразования значения в строку. Значения, полученные из HTTP, сохраняются как строки.3839> **См. также**40>41> **Модуль [`http.cookiejar`](https://python-all.ru/3.10/library/http.cookiejar.html#module-http.cookiejar)**42>43> Обработка HTTP-куки для веб-*клиентов*. Модули [`http.cookiejar`](https://python-all.ru/3.10/library/http.cookiejar.html#module-http.cookiejar) и [`http.cookies`](https://python-all.ru/3.10/library/http.cookies.html#module-http.cookies) не зависят друг от друга.44>45> **[**RFC 2109**](https://python-all.ru/3.10/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.10/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.10/library/http.cookies.html#http.cookies.BaseCookie) – он существует, чтобы его можно было переопределить.5859В общем случае должно выполняться условие, что [`value_encode()`](https://python-all.ru/3.10/library/http.cookies.html#http.cookies.BaseCookie.value_encode) и [`value_decode()`](https://python-all.ru/3.10/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.10/library/http.cookies.html#http.cookies.BaseCookie.output) объекта [`Morsel`](https://python-all.ru/3.10/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.10/library/http.cookies.html#http.cookies.BaseCookie.output).7071#### `BaseCookie.load(rawdata)`7273Если *rawdata* является строкой, разобрать её как `HTTP_COOKIE` и добавить найденные значения как объекты [`Morsel`](https://python-all.ru/3.10/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.10/library/http.cookies.html).8586Объекты Morsel похожи на словари, и их набор ключей постоянен: это допустимые атрибуты [**RFC 2109**](https://python-all.ru/3.10/library/http.cookies.html), которые8788- `expires`89- `path`90- `comment`91- `domain`92- `max-age`93- `secure`94- `version`95- `httponly`96- `samesite`9798Атрибут `httponly` указывает, что cookie передаётся только в HTTP-запросах и недоступен через JavaScript. Это предназначено для снижения риска некоторых форм межсайтового скриптинга.99100Атрибут `samesite` указывает, что браузеру не разрешается отправлять cookie вместе с межсайтовыми запросами. Это помогает снизить риск CSRF-атак. Допустимые значения этого атрибута – “Strict” и “Lax”.101102Ключи нечувствительны к регистру, и их значение по умолчанию – `''`.103104Изменено в версии 3.5: `__eq__()` теперь учитывает [`key`](https://python-all.ru/3.10/library/http.cookies.html#http.cookies.Morsel.key) и [`value`](https://python-all.ru/3.10/library/http.cookies.html#http.cookies.Morsel.value).105106Изменено в версии 3.7: Атрибуты [`key`](https://python-all.ru/3.10/library/http.cookies.html#http.cookies.Morsel.key), [`value`](https://python-all.ru/3.10/library/http.cookies.html#http.cookies.Morsel.value) и [`coded_value`](https://python-all.ru/3.10/library/http.cookies.html#http.cookies.Morsel.coded_value) теперь доступны только для чтения. Для их установки используйте [`set()`](https://python-all.ru/3.10/library/http.cookies.html#http.cookies.Morsel.set).107108Изменено в версии 3.8: Добавлена поддержка атрибута `samesite`.109110#### `Morsel.value`111112Значение cookie.113114#### `Morsel.coded_value`115116Закодированное значение cookie – именно его следует отправлять.117118#### `Morsel.key`119120Имя cookie.121122#### `Morsel.set(key, value, coded_value)`123124Устанавливает атрибуты *key*, *value* и *coded\_value*.125126#### `Morsel.isReservedKey(K)`127128Проверяет, входит ли *K* в набор ключей [`Morsel`](https://python-all.ru/3.10/library/http.cookies.html#http.cookies.Morsel).129130#### `Morsel.output(attrs=None, header='Set-Cookie:')`131132Возвращает строковое представление Morsel, пригодное для отправки в качестве HTTP-заголовка. По умолчанию включаются все атрибуты, если не указан *attrs* – в этом случае это должен быть список используемых атрибутов. *header* по умолчанию равен `"Set-Cookie:"`.133134#### `Morsel.js_output(attrs=None)`135136Возвращает встраиваемый фрагмент JavaScript, который при выполнении в браузере, поддерживающем JavaScript, будет действовать так же, как если бы был отправлен HTTP-заголовок.137138Значение *attrs* такое же, как в [`output()`](https://python-all.ru/3.10/library/http.cookies.html#http.cookies.Morsel.output).139140#### `Morsel.OutputString(attrs=None)`141142Возвращает строку, представляющую Morsel, без какого-либо окружающего HTTP или JavaScript.143144Значение *attrs* такое же, как в [`output()`](https://python-all.ru/3.10/library/http.cookies.html#http.cookies.Morsel.output).145146#### `Morsel.update(values)`147148Обновляет значения в словаре Morsel значениями из словаря *values*. Вызывает ошибку, если какой-либо из ключей в словаре *values* не является допустимым атрибутом [**RFC 2109**](https://python-all.ru/3.10/library/http.cookies.html).149150Изменено в версии 3.5: возникает ошибка для недопустимых ключей.151152#### `Morsel.copy(value)`153154Возвращает поверхностную копию объекта Morsel.155156Изменено в версии 3.5: возвращает объект Morsel вместо словаря.157158#### `Morsel.setdefault(key, value=None)`159160Вызывает ошибку, если ключ не является допустимым атрибутом [**RFC 2109**](https://python-all.ru/3.10/library/http.cookies.html), в противном случае ведёт себя так же, как [`dict.setdefault()`](https://python-all.ru/3.10/library/stdtypes.html#dict.setdefault).161162## Пример163164Следующий пример демонстрирует, как использовать модуль [`http.cookies`](https://python-all.ru/3.10/library/http.cookies.html#module-http.cookies).165166```pycon167>>> from http import cookies168>>> C = cookies.SimpleCookie()169>>> C["fig"] = "newton"170>>> C["sugar"] = "wafer"171>>> print(C) # сгенерировать HTTP-заголовки172Set-Cookie: fig=newton173Set-Cookie: sugar=wafer174>>> print(C.output()) # то же самое175Set-Cookie: fig=newton176Set-Cookie: sugar=wafer177>>> C = cookies.SimpleCookie()178>>> C["rocky"] = "road"179>>> C["rocky"]["path"] = "/cookie"180>>> print(C.output(header="Cookie:"))181Cookie: rocky=road; Path=/cookie182>>> print(C.output(attrs=[], header="Cookie:"))183Cookie: rocky=road184>>> C = cookies.SimpleCookie()185>>> C.load("chips=ahoy; vienna=finger") # загрузить из строки (HTTP-заголовок)186>>> print(C)187Set-Cookie: chips=ahoy188Set-Cookie: vienna=finger189>>> C = cookies.SimpleCookie()190>>> C.load('keebler="E=everybody; L=\\"Loves\\"; fudge=;";')191>>> print(C)192Set-Cookie: keebler="E=everybody; L=\"Loves\"; fudge=;"193>>> C = cookies.SimpleCookie()194>>> C["oreo"] = "doublestuff"195>>> C["oreo"]["path"] = "/"196>>> print(C)197Set-Cookie: oreo=doublestuff; Path=/198>>> C = cookies.SimpleCookie()199>>> C["twix"] = "none for you"200>>> C["twix"].value201'none for you'202>>> C = cookies.SimpleCookie()203>>> C["number"] = 7 # эквивалентно C["number"] = str(7)204>>> C["string"] = "seven"205>>> C["number"].value206'7'207>>> C["string"].value208'seven'209>>> print(C)210Set-Cookie: number=7211Set-Cookie: string=seven212```213