Cookies
Библиотека автоматически сохраняет подходящие Set-Cookie из ответов и подставляет cookies в следующие запросы. Для ручного управления используйте client.cookies. Это то же хранилище, которым пользуются запросы, поэтому отдельный контейнер в Python собирать не нужно.
Cookies живут в памяти открытого клиента. Маршруты одного HttpClient используют общее хранилище; разные клиенты изолированы, даже если используют один state_dir. На низком уровне оно доступно как Session.cookies или AsyncSession.cookies. Объект Cookie — неизменяемая копия записи на момент чтения.
Чтение и сохранение
Методы чтения и экспорта предоставляют доступ в том числе к значениям HttpOnly. Этот признак ограничивает браузерные скрипты, но не явно вызванный SDK-метод. repr() скрывает значения; value и export_data() возвращают их полностью.
Хранилище не сохраняется на диск при запуске или закрытии клиента. Для переноса между запусками экспортируйте данные до закрытия клиента, сохраните их средствами приложения и импортируйте в новый открытый клиент. Импорт проверяет правила cookies и не расширяет разрешённые области.
Добавление и перенос cookies
В следующем примере client уже открыт через with HttpClient(...) или async with AsyncHttpClient(...). Методы хранилища синхронные в обоих случаях.
client.cookies.set(
'language', 'ru', url='https://example.com/',
path='/', secure=True, same_site='lax',
)
language = client.cookies.get(
'language', domain='example.com', path='/', host_only=True,
)
saved_cookies = client.cookies.export_data()saved_cookies — обычный словарь. Для сохранения между запусками запишите его в своё защищённое хранилище, например в формате JSON. В следующем открытом клиенте восстановите данные:
client.cookies.import_data(saved_cookies)Импорт добавляет и заменяет записи. Если нужна полная замена, сначала вызовите clear(), затем import_data(). Это два отдельных действия: ошибка импорта не вернёт ранее очищенное содержимое.
Cookies
| Метод | Поведение |
|---|---|
| all() | Возвращает кортеж неизменяемых записей Cookie из одного снимка хранилища. Последующие изменения не меняют полученные записи. Итерация и len() также используют снимок. |
| get(name, default=None, *, domain=None, path=None, partition_site=None, host_only=None) | Возвращает value/default. Фильтр None не ограничивает область. Более одного совпадения — ValueError; нужна точная область. Если записи отличаются только cross_site_ancestor, у get нет такого фильтра: используйте all и выберите запись явно. |
| set(name, value, *, url, domain=None, path=None, secure=False, http_only=False, same_site=None, expires=None, partition_url=None) | Добавляет или заменяет cookie по правилам Set-Cookie. Обязательный url задаёт источник записи. domain=None ограничивает cookie этим хостом, path=None выбирает путь от URL. expires — конечное число секунд Unix, округляется вверх. Атрибуты проверяются до изменения. |
| update(values, *, url, **attributes) | Записывает словарь или пары одним действием; общие атрибуты применяются ко всем записям. При ошибке частичного обновления нет. Допустимы domain, path, secure, http_only, same_site, expires, partition_url, partitioned. partition_url задаёт сайт раздела и несовместим с явно переданным partitioned. При partitioned=True без partition_url верхний сайт берётся из url. |
| delete(name, *, domain=None, path=None, partition_site=None, host_only=None, cross_site_ancestor=None) | False если нет совпадений, True при удалении; больше одного совпадения — ValueError. |
| clear() | Удаляет все cookies из хранилища этого клиента. |
| export_data() | Словарь с schema=1 и списком cookies, содержащим полные поля Cookie в порядке creation_order. Сам файл не сохраняет. |
| import_data(data) | Добавляет или заменяет записи из экспорта, не очищая хранилище. Принимает словарь только с schema=1 и cookies: до 10000 полных записей Cookie. Проверяет все данные и применяет их одной транзакцией. |
secure, http_only и partitioned принимают строго bool. same_site — None, none, lax или strict. Имя, значение, домен и путь проверяются на допустимые ASCII-символы, управляющие символы и ;; путь должен начинаться с /. Хранилище проверяет область домена, публичные суффиксы, Secure, префиксы, SameSite, срок и раздел. Например, domain не позволяет установить cookie для постороннего домена.
URL и область нужно передать явно: они не берутся из последнего запроса. Для разделённой cookie partition_url задаёт сайт верхнего уровня, url — источник записи. set() и update() записывают cookies с CookieContext(kind='navigation', credentials='include'); это привилегированная операция SDK, а не браузерный Fetch.
Запись Cookie и формат экспорта
У записи Cookie следующие поля:
| Поля | Тип | Значение конструктора по умолчанию |
|---|---|---|
| name, value | str | Обязательные |
| domain, path | str | Пустая строка и / |
| host_only | bool | True |
| secure, http_only | bool | False |
| same_site | str или None | None |
| partition_site | str | Пустая строка |
| partitioned, cross_site_ancestor, persistent | bool | False |
| creation_ms, updated_ms, expiry_ms, creation_order | int | 0 |
value скрыто в repr(), но доступно как свойство записи. host_only=True ограничивает cookie исходным хостом; False допускает подходящие поддомены. persistent означает наличие срока действия, а не сохранение на диск. creation_order задаёт порядок создания.
В снимке и экспорте время задаётся в миллисекундах Unix; аргумент expires у set() принимает секунды. expiry_ms=0 без признака persistent не означает бессрочное сохранение на диск.
Импорт требует все поля записи, строгие bool, неотрицательные целые значения времени и положительный creation_order. Одна транзакция восстанавливает время создания, изменения и истечения, порядок, host-only, раздел и признак предка. Неполные или отклонённые записи не пропускаются молча. Экспорт содержит значения cookies: сохраняйте его как данные авторизации, не как обычный журнал.
Cookies одного запроса
Параметр cookies конструктора задаёт добавочные cookies для каждого запроса, но не наполняет хранилище клиента. request(cookies=...) целиком заменяет этот набор для одного вызова; None или пустой набор убирает добавку, оставляя автоматический выбор из хранилища.
Сначала выбираются cookies для URL. Затем значения с именами из одноразового набора заменяются его значениями. Само хранилище не меняется. Дубли имён в добавочном наборе запрещены; имя должно быть допустимым HTTP-именем, значение — безопасным ASCII без пробелов, кавычек, запятой, ; и обратной косой черты. Добавка не обходит правила omit, сторонних cookies или SameSite.
Заголовок Cookie преобразуется в такой же одноразовый набор. Его нельзя сочетать с непустым набором по умолчанию или явно переданным cookies, даже cookies=None. Неверные и повторные пары отклоняются.
cookies_enabled=False запрещает отправку cookies и несовместим с непустым cookies или явным Cookie. Если задан собственный контекст, его credentials должен быть omit. persist_cookies=False запрещает только сохранение Set-Cookie из ответа. При переходе на другой origin (схему, хост или порт) одноразовый набор удаляется, при прежнем — сохраняется. Cookies из каждого ответа проходят проверку политики.
Политика и контекст
Передайте cookie_policy=CookiePolicyOptions(...) в конструктор клиента, если нужно изменить правила хранилища. Класс импортируется из duckonet.
| Параметр | По умолчанию | Назначение и диапазон |
|---|---|---|
| maximum_cookies | 1000 | Число записей; от 1 до 10000. |
| maximum_header_bytes | 65536 | Размер формируемого заголовка Cookie, в байтах; от 4096 до 65536. |
| unspecified_lax_grace_ms | 120000 | Льготный период для cookies без явно заданного SameSite, в миллисекундах; от 0 до 120000. |
| maximum_lifetime_ms | 400*86400000 | Верхний предел срока действия, в миллисекундах; от 1 мс до 400 суток. |
| allow_third_party | True | Разрешать сторонние cookies с учётом остальных правил. Принимает только bool. |
CookieContext описывает условия, в которых выбираются cookies:
top_level_url— адрес страницы верхнего уровня.initiator_url— адрес инициатора запроса.kind—navigation,fetchилиsubresource; по умолчаниюfetch.credentials—omit(не отправлять),same_origin(тот же origin) илиinclude(разрешить с учётом политики); по умолчаниюsame_origin.ancestors— кортеж URL страниц-предков, до 32 записей.redirect_history— кортеж предыдущих URL перенаправлений.
Полные URL передаются ASCII-строками длиной не более 16384 символов.
По умолчанию HttpClient создаёт контекст fetch для заданного URL с credentials=include или omit при отключённых cookies. Списки предков и переходов пусты, document_url равен URL, признаки initial_navigation, user_activation и storage_access выключены. Для стороннего сайта или разделённого хранилища передайте BrowserHopContext с нужными BrowserContext и CookieContext. body_present должен соответствовать телу; режим — cors, preflight=False.
При самостоятельном создании CookieContext список redirect_history содержит не более 20 URL. Во время выполнения HTTP-запроса клиент может расширить его до 100 записей.
Область разделённых cookies
При выборе разделённой cookie учитываются сайт верхнего уровня (схема и регистрируемый домен) и cross_site_ancestor — наличие сторонней страницы в цепочке предков. Поддомены a.example.test и b.example.test сами по себе не образуют разные сайты раздела.
set(partition_url=...) создаёт запись с навигационным контекстом и cross_site_ancestor=False. Запрос из стороннего iframe может иметь True и поэтому не выберет эту запись. Импорт и экспорт сохраняют оба признака. Неизвестная область раздела или несовпадение признака предка исключают cookie из отправки.