http.cookiejar — Обработка куки для HTTP-клиентов

Источник: Lib/http/cookiejar.py

Модуль http.cookiejar определяет классы для автоматической обработки HTTP-куки. Он полезен для доступа к веб-сайтам, которые требуют небольших фрагментов данных - cookies – должны быть установлены на клиентской машине в HTTP-ответе веб-сервера, а затем возвращены серверу в последующих HTTP-запросах.

Поддерживается как обычный протокол Netscape cookie, так и протокол, определенный RFC 2965. Обработка RFC 2965 по умолчанию отключена. Куки RFC 2109 анализируются как куки Netscape и в дальнейшем обрабатываются либо как куки Netscape, либо как куки RFC 2965 в соответствии с действующей «политикой». Обратите внимание, что подавляющее большинство файлов cookie в Интернете - это файлы cookie Netscape. http.cookiejar пытается следовать де-факто протоколу куки-файлов Netscape (который существенно отличается от протокола, изложенного в оригинальной спецификации Netscape), включая учет max-age и port атрибутов куки-файлов, введенных в RFC 2965.

Примечание

Различные именованные параметры, встречающиеся в заголовках Set-Cookie и Set-Cookie2 (например, domain и expires), условно обозначаются как attributes. Чтобы отличить их от атрибутов Python, в документации к этому модулю вместо них используется термин cookie-attribute.

Модуль определяет следующее исключение:

exception http.cookiejar.LoadError

Экземпляры FileCookieJar вызывают это исключение при неудачной загрузке cookies из файла. LoadError является подклассом OSError.

Изменено в версии 3.3: LoadError раньше был подтипом IOError, который теперь является псевдонимом OSError.

Предусмотрены следующие занятия:

class http.cookiejar.CookieJar(policy=None)

Политика - это объект, реализующий интерфейс CookiePolicy.

Класс CookieJar хранит HTTP-куки. Он извлекает куки из HTTP-запросов и возвращает их в HTTP-ответах. Экземпляры CookieJar при необходимости автоматически уничтожают содержащиеся файлы cookie. Подклассы также отвечают за хранение и извлечение файлов cookie из файла или базы данных.

class http.cookiejar.FileCookieJar(filename=None, delayload=None, policy=None)

policy - это объект, реализующий интерфейс CookiePolicy. Остальные аргументы см. в документации к соответствующим атрибутам.

Метод CookieJar, который может загружать файлы cookie из файла на диске и, возможно, сохранять их в нем. Cookies НЕ загружаются из именованного файла до тех пор, пока не будет вызван метод load() или revert(). Подклассы этого класса документированы в разделе Подклассы FileCookieJar и сотрудничество с веб-браузерами.

Его не следует инициализировать напрямую - вместо этого используйте его подклассы, приведенные ниже.

Изменено в версии 3.8: Параметр filename поддерживает значение path-like object.

class http.cookiejar.CookiePolicy

Этот класс отвечает за принятие решения о том, должен ли каждый cookie быть принят от сервера или возвращен ему.

class http.cookiejar.DefaultCookiePolicy(blocked_domains=None, allowed_domains=None, netscape=True, rfc2965=False, rfc2109_as_netscape=None, hide_cookie2=False, strict_domain=False, strict_rfc2965_unverifiable=True, strict_ns_unverifiable=False, strict_ns_domain=DefaultCookiePolicy.DomainLiberal, strict_ns_set_initial_dollar=False, strict_ns_set_path=False, secure_protocols=('https', 'wss'))

Аргументы конструктора должны передаваться только как аргументы ключевого слова. blocked_domains - последовательность имен доменов, от которых мы не принимаем и не возвращаем куки. разрешенные_домены, если не None, то это последовательность единственных доменов, для которых мы принимаем и возвращаем cookies. secure_protocols - последовательность протоколов, для которых могут быть добавлены безопасные куки. По умолчанию безопасными протоколами считаются https и wss (безопасные веб-сокеты). Все остальные аргументы см. в документации к объектам CookiePolicy и DefaultCookiePolicy.

DefaultCookiePolicy реализует стандартные правила принятия/отклонения для куки-файлов Netscape и RFC 2965. По умолчанию файлы RFC 2109 cookie (т. е. файлы cookie, полученные в заголовке Set-Cookie с атрибутом cookie-версии, равным 1) обрабатываются в соответствии с правилами RFC 2965. Однако если обработка RFC 2965 отключена или rfc2109_as_netscape является True, куки RFC 2109 «понижаются» экземпляром CookieJar до куки Netscape, устанавливая атрибут version экземпляра Cookie в 0. DefaultCookiePolicy также предоставляет некоторые параметры, позволяющие тонко настраивать политику.

class http.cookiejar.Cookie

Этот класс представляет файлы cookie Netscape, RFC 2109 и RFC 2965. Не предполагается, что пользователи http.cookiejar будут создавать свои собственные экземпляры Cookie. Вместо этого, при необходимости, вызывайте make_cookies() на экземпляре CookieJar.

См.также

Модуль urllib.request

Открытие URL-адресов с автоматической обработкой файлов cookie.

Модуль http.cookies

Классы HTTP-куки, в основном полезные для кода на стороне сервера. Модули http.cookiejar и http.cookies не зависят друг от друга.

https://curl.se/rfc/cookie_spec.html

Спецификация оригинального протокола cookie от Netscape. Хотя этот протокол до сих пор является доминирующим, «протокол куки Netscape», реализованный во всех основных браузерах (и http.cookiejar), лишь отдаленно похож на протокол, описанный в cookie_spec.html.

RFC 2109 - Механизм управления состоянием HTTP

Устаревшая версия RFC 2965. Используется Set-Cookie с версией=1.

RFC 2965 - Механизм управления состоянием HTTP

Протокол Netscape с исправленными ошибками. Использует Set-Cookie2 вместо Set-Cookie. Широко не используется.

http://kristol.org/cookie/errata.html

Незаконченные исправления к RFC 2965.

RFC 2964 - Использование управления состоянием HTTP

Объекты CookieJar и FileCookieJar

Объекты CookieJar поддерживают протокол iterator для итерации по содержащимся объектам Cookie.

CookieJar имеет следующие методы:

Добавьте правильный заголовок Cookie в запрос.

Если политика позволяет (т. е. атрибуты rfc2965 и hide_cookie2 экземпляра CookieJar равны true и false соответственно), заголовок Cookie2 также добавляется при необходимости.

Объект request (обычно экземпляр urllib.request.Request) должен поддерживать методы get_full_url(), has_header(), get_header(), header_items(), add_unredirected_header() и атрибуты host, type, unverifiable и origin_req_host в соответствии с документацией urllib.request.

Изменено в версии 3.3: Объекту request необходим атрибут origin_req_host. Зависимость от устаревшего метода get_origin_req_host() была удалена.

CookieJar.extract_cookies(response, request)

Извлекает куки из HTTP ответов и сохраняет их в CookieJar, если это разрешено политикой.

Метод CookieJar будет искать допустимые заголовки Set-Cookie и Set-Cookie2 в аргументе response и сохранять cookies, если это необходимо (при условии одобрения метода CookiePolicy.set_ok()).

Объект ответ (обычно результат вызова urllib.request.urlopen() или аналогичного) должен поддерживать метод info(), который возвращает экземпляр email.message.Message.

Объект request (обычно экземпляр urllib.request.Request) должен поддерживать метод get_full_url() и атрибуты host, unverifiable и origin_req_host, как описано в urllib.request. Запрос используется для установки значений по умолчанию для атрибутов cookie, а также для проверки того, что cookie разрешено устанавливать.

Изменено в версии 3.3: Объекту request необходим атрибут origin_req_host. Зависимость от устаревшего метода get_origin_req_host() была удалена.

CookieJar.set_policy(policy)

Установите экземпляр CookiePolicy, который будет использоваться.

CookieJar.make_cookies(response, request)

Возвращает последовательность объектов Cookie, извлеченных из объекта ответ.

См. документацию для extract_cookies(), чтобы узнать, какие интерфейсы требуются для аргументов ответ и запрос.

Установите значение Cookie, если политика разрешает это сделать.

Устанавливает значение Cookie, не проверяя политику на предмет того, следует ли его устанавливать.

CookieJar.clear([domain[, path[, name]]])

Очистите некоторые файлы cookie.

При вызове без аргументов очищает все файлы cookie. Если указан один аргумент, будут удалены только куки, принадлежащие данному домену. Если указано два аргумента, то будут удалены куки, принадлежащие указанному домену и URL path. Если указано три аргумента, то будут удалены cookie с указанными домен, путь и имя.

Вызывает KeyError, если не существует подходящего cookie.

CookieJar.clear_session_cookies()

Удалите все файлы cookie сеанса.

Удаляет все содержащиеся файлы cookie, которые имеют истинный атрибут discard (обычно потому, что у них не было атрибутов max-age или expires, либо был явный атрибут discard). Для интерактивных браузеров завершение сеанса обычно соответствует закрытию окна браузера.

Обратите внимание, что метод save() в любом случае не будет сохранять куки сессии, если вы не попросите об обратном, передав аргумент true ignore_discard.

FileCookieJar реализует следующие дополнительные методы:

FileCookieJar.save(filename=None, ignore_discard=False, ignore_expires=False)

Сохраните файлы cookie в файл.

Этот базовый класс поднимает значение NotImplementedError. Подклассы могут оставить этот метод нереализованным.

filename - имя файла, в котором будут сохраняться cookies. Если filename не указано, используется self.filename (по умолчанию это значение, переданное в конструктор, если таковое имеется); если self.filename - None, используется ValueError.

ignore_discard: сохранять даже те файлы cookie, которые будут отброшены. ignore_expires: сохранять даже те файлы cookie, срок действия которых истек.

Файл перезаписывается, если он уже существует, тем самым удаляя все содержащиеся в нем куки. Сохраненные файлы cookie можно восстановить позже с помощью методов load() или revert().

FileCookieJar.load(filename=None, ignore_discard=False, ignore_expires=False)

Загрузка файлов cookie из файла.

Старые файлы cookie сохраняются до тех пор, пока не будут перезаписаны вновь загруженными.

Аргументы указаны как для save().

Именованный файл должен быть в формате, понятном классу, иначе будет вызвана ошибка LoadError. Также может быть вызвана ошибка OSError, например, если файл не существует.

Изменено в версии 3.3: Раньше поднимался IOError, теперь это псевдоним OSError.

FileCookieJar.revert(filename=None, ignore_discard=False, ignore_expires=False)

Очистка всех файлов cookie и повторная загрузка файлов cookie из сохраненного файла.

revert() может вызывать те же исключения, что и load(). Если произойдет сбой, состояние объекта не изменится.

Экземпляры FileCookieJar имеют следующие публичные атрибуты:

FileCookieJar.filename

Имя файла по умолчанию, в котором будут храниться файлы cookie. Этот атрибут может быть присвоен.

FileCookieJar.delayload

Если true, то печенье будет загружаться с диска лениво. Этот атрибут не должен быть назначен. Это только подсказка, так как это влияет только на производительность, а не на поведение (если только куки на диске не меняются). Объект CookieJar может игнорировать его. Ни один из классов FileCookieJar, включенных в стандартную библиотеку, не загружает куки лениво.

Подклассы FileCookieJar и сотрудничество с веб-браузерами

Для чтения и записи предусмотрены следующие подклассы CookieJar.

class http.cookiejar.MozillaCookieJar(filename=None, delayload=None, policy=None)

Программа FileCookieJar, которая может загружать и сохранять куки на диск в формате файлов Mozilla cookies.txt (который также используется в curl и браузерах Lynx и Netscape).

Примечание

При этом теряется информация о файлах cookie RFC 2965, а также о более новых или нестандартных атрибутах файлов cookie, таких как port.

Предупреждение

Создайте резервную копию файлов cookie перед сохранением, если у вас есть файлы cookie, потеря/повреждение которых будет неудобна (есть некоторые тонкости, которые могут привести к незначительным изменениям в файле во время загрузки/сохранения).

Также обратите внимание, что файлы cookie, сохраненные во время работы Mozilla, будут уничтожены Mozilla.

class http.cookiejar.LWPCookieJar(filename=None, delayload=None, policy=None)

Программа FileCookieJar, которая может загружать и сохранять куки на диск в формате, совместимом с форматом файлов Set-Cookie3 библиотеки libwww-perl. Это удобно, если вы хотите хранить куки в человекочитаемом файле.

Изменено в версии 3.8: Параметр filename поддерживает значение path-like object.

Объекты политики cookiePolicy

Объекты, реализующие интерфейс CookiePolicy, имеют следующие методы:

CookiePolicy.set_ok(cookie, request)

Возвращает булево значение, указывающее, следует ли принимать cookie от сервера.

cookie - это экземпляр Cookie. request - объект, реализующий интерфейс, определенный в документации для CookieJar.extract_cookies().

CookiePolicy.return_ok(cookie, request)

Возвращает булево значение, указывающее, следует ли возвращать cookie серверу.

cookie - это экземпляр Cookie. request - объект, реализующий интерфейс, определенный в документации для CookieJar.add_cookie_header().

CookiePolicy.domain_return_ok(domain, request)

Возвращает False, если файлы cookie не должны быть возвращены, учитывая домен cookie.

Этот метод является оптимизацией. Он избавляет от необходимости проверять каждую cookie с определенным доменом (что может потребовать чтения многих файлов). Возврат true из domain_return_ok() и path_return_ok() оставляет всю работу return_ok().

Если domain_return_ok() возвращает true для домена cookie, то path_return_ok() вызывается для пути cookie. В противном случае path_return_ok() и return_ok() никогда не вызываются для этого домена cookie. Если path_return_ok() возвращает true, вызывается return_ok() с самим объектом Cookie для полной проверки. В противном случае return_ok() никогда не вызывается для этого пути cookie.

Обратите внимание, что domain_return_ok() вызывается для каждого домена cookie, а не только для домена request. Например, функция может быть вызвана с ".example.com" и "www.example.com", если доменом запроса является "www.example.com". То же самое относится и к path_return_ok().

Аргумент request соответствует документированному для return_ok().

CookiePolicy.path_return_ok(path, request)

Возвращает False, если куки не должны быть возвращены, учитывая путь к кукам.

См. документацию для domain_return_ok().

Помимо реализации вышеуказанных методов, реализации интерфейса CookiePolicy также должны предоставлять следующие атрибуты, указывающие, какие протоколы должны использоваться и каким образом. Все эти атрибуты могут быть присвоены.

CookiePolicy.netscape

Реализуйте протокол Netscape.

CookiePolicy.rfc2965

Внедрите протокол RFC 2965.

CookiePolicy.hide_cookie2

Не добавляйте в запросы заголовок Cookie2 (наличие этого заголовка указывает серверу, что мы понимаем куки RFC 2965).

Наиболее полезным способом определения класса CookiePolicy является подкласс от DefaultCookiePolicy и переопределение некоторых или всех методов, описанных выше. Сам CookiePolicy может быть использован в качестве «нулевой политики», позволяющей устанавливать и получать любые и все куки (это вряд ли будет полезно).

Объекты DefaultCookiePolicy

Реализует стандартные правила приема и возврата файлов cookie.

Поддерживаются куки RFC 2965 и Netscape. Обработка RFC 2965 по умолчанию отключена.

Самый простой способ обеспечить собственную политику - переопределить этот класс и вызывать его методы в своих переопределенных реализациях перед добавлением собственных дополнительных проверок:

import http.cookiejar
class MyCookiePolicy(http.cookiejar.DefaultCookiePolicy):
    def set_ok(self, cookie, request):
        if not http.cookiejar.DefaultCookiePolicy.set_ok(self, cookie, request):
            return False
        if i_dont_want_to_store_this_cookie(cookie):
            return False
        return True

В дополнение к функциям, необходимым для реализации интерфейса CookiePolicy, этот класс позволяет блокировать и разрешать доменам устанавливать и получать cookies. Также есть несколько переключателей строгости, которые позволяют немного ужесточить довольно свободные правила протокола Netscape (ценой блокировки некоторых доброкачественных cookies).

Предусмотрены блокирующий и разрешающий списки доменов (по умолчанию оба выключены). Только домены, не входящие в список блокировки и присутствующие в списке разрешения (если список разрешения активен), участвуют в установке и возврате cookie. Используйте аргумент конструктора blocked_domains, а также методы blocked_domains() и set_blocked_domains() (и соответствующие аргумент и методы для allowed_domains). Если вы установили список разрешенных доменов, вы можете отключить его снова, установив значение None.

Домены в списках блокировки или разрешения, которые не начинаются с точки, должны быть равны домену cookie, чтобы совпасть с ним. Например, "example.com" соответствует записи в списке блокировки "example.com", а "www.example.com" - нет. Домены, начинающиеся с точки, также совпадают с более конкретными доменами. Например, и "www.example.com", и "www.coyote.example.com" соответствуют ".example.com" (но сам "example.com" не соответствует). Исключением являются IP-адреса, которые должны совпадать в точности. Например, если blocked_domains содержит "192.168.1.2" и ".168.1.2", 192.168.1.2 будет заблокирован, а 193.168.1.2 - нет.

DefaultCookiePolicy реализует следующие дополнительные методы:

DefaultCookiePolicy.blocked_domains()

Возвращает последовательность заблокированных доменов (в виде кортежа).

DefaultCookiePolicy.set_blocked_domains(blocked_domains)

Установите последовательность блокируемых доменов.

DefaultCookiePolicy.is_blocked(domain)

Возвращает True, если домен находится в списке блокировки для установки или получения cookies.

DefaultCookiePolicy.allowed_domains()

Возвращает None или последовательность разрешенных доменов (в виде кортежа).

DefaultCookiePolicy.set_allowed_domains(allowed_domains)

Задайте последовательность разрешенных доменов, или None.

DefaultCookiePolicy.is_not_allowed(domain)

Возвращает True, если домен не находится в списке разрешенных для установки или получения cookies.

Экземпляры DefaultCookiePolicy имеют следующие атрибуты, которые инициализируются из одноименных аргументов конструктора и могут быть назначены.

DefaultCookiePolicy.rfc2109_as_netscape

Если true, запросите, чтобы экземпляр CookieJar понизил версию RFC 2109 cookies (т.е. cookies, полученные в заголовке Set-Cookie с атрибутом cookie-версии, равным 1) до версии cookies Netscape, установив атрибут version экземпляра Cookie в 0. По умолчанию установлено значение None, и в этом случае cookies RFC 2109 понижаются тогда и только тогда, когда обработка RFC 2965 выключена. Поэтому файлы cookie RFC 2109 понижаются по умолчанию.

Переключатели общей строгости:

DefaultCookiePolicy.strict_domain

Не позволяйте сайтам устанавливать двухкомпонентные домены с кодом страны на верхнем уровне, например .co.uk, .gov.uk, .co.nz и т. д. Это далеко не идеальный вариант, и его работа не гарантирована!

RFC 2965 переключатели строгости протокола:

DefaultCookiePolicy.strict_rfc2965_unverifiable

Следуйте правилам RFC 2965 в отношении непроверяемых транзакций (обычно непроверяемая транзакция - это транзакция, возникающая в результате перенаправления или запроса изображения, размещенного на другом сайте). Если это неверно, файлы cookie никогда не блокируются на основании верифицируемости

Переключатели строгости протокола Netscape:

DefaultCookiePolicy.strict_ns_unverifiable

Применяйте правила RFC 2965 для непроверяемых операций даже к файлам cookie Netscape.

DefaultCookiePolicy.strict_ns_domain

Флаги, указывающие, насколько строгими должны быть правила подбора доменов для файлов cookie Netscape. Допустимые значения см. ниже.

DefaultCookiePolicy.strict_ns_set_initial_dollar

Игнорируйте куки в заголовках Set-Cookie:, имена которых начинаются с '$'.

DefaultCookiePolicy.strict_ns_set_path

Не разрешайте устанавливать cookies, путь к которым не совпадает с URI запроса.

strict_ns_domain - это набор флагов. Его значение строится путем перестановки букв «или» (например, DomainStrictNoDots|DomainStrictNonDomain означает, что оба флага установлены).

DefaultCookiePolicy.DomainStrictNoDots

При установке cookie-файлов «префикс хоста» не должен содержать точку (например, www.foo.bar.com не может установить cookie для .bar.com, потому что www.foo содержит точку).

DefaultCookiePolicy.DomainStrictNonDomain

Cookies, в которых явно не указан cookie-атрибут domain, могут быть возвращены только домену, равному домену, установившему cookie (например, spam.example.com не будет возвращать cookies от example.com, в которых не указан cookie-атрибут domain).

DefaultCookiePolicy.DomainRFC2965Match

При установке cookie-файлов требуйте полного совпадения с доменом RFC 2965.

Следующие атрибуты приведены для удобства и являются наиболее полезными комбинациями вышеуказанных флагов:

DefaultCookiePolicy.DomainLiberal

Эквивалентно 0 (т.е. все вышеперечисленные флаги строгости домена Netscape отключены).

DefaultCookiePolicy.DomainStrict

Эквивалент DomainStrictNoDots|DomainStrictNonDomain.

Примеры

В первом примере показано наиболее частое использование http.cookiejar:

import http.cookiejar, urllib.request
cj = http.cookiejar.CookieJar()
opener = urllib.request.build_opener(urllib.request.HTTPCookieProcessor(cj))
r = opener.open("http://example.com/")

В этом примере показано, как открыть URL-адрес, используя файлы cookie Netscape, Mozilla или Lynx (предполагается, что в Unix/Netscape принято указывать местоположение файла cookie):

import os, http.cookiejar, urllib.request
cj = http.cookiejar.MozillaCookieJar()
cj.load(os.path.join(os.path.expanduser("~"), ".netscape", "cookies.txt"))
opener = urllib.request.build_opener(urllib.request.HTTPCookieProcessor(cj))
r = opener.open("http://example.com/")

Следующий пример иллюстрирует использование DefaultCookiePolicy. Включите cookies RFC 2965, будьте более строги к доменам при установке и возврате cookies Netscape и заблокируйте некоторые домены от установки cookies или их возврата:

import urllib.request
from http.cookiejar import CookieJar, DefaultCookiePolicy
policy = DefaultCookiePolicy(
    rfc2965=True, strict_ns_domain=Policy.DomainStrict,
    blocked_domains=["ads.net", ".ads.net"])
cj = CookieJar(policy)
opener = urllib.request.build_opener(urllib.request.HTTPCookieProcessor(cj))
r = opener.open("http://example.com/")