Модуль http.cookiejar определяет классы для автоматической обработки файлов cookie HTTP. Он полезен для доступа к веб-сайтам, которые требуют установки небольших фрагментов данных — файлов cookie — на клиенте HTTP-ответом веб-сервера и последующего возвращения их серверу в последующих HTTP-запросах.
Обрабатываются как обычный протокол файлов cookie Netscape, так и протокол, определённый в RFC 2965. Обработка RFC 2965 по умолчанию выключена. Файлы cookie RFC 2109 парсятся как файлы cookie Netscape и впоследствии обрабатываются как файлы cookie Netscape или RFC 2965 в зависимости от применяемой «политики». Обратите внимание, что подавляющее большинство файлов cookie в Интернете — это файлы cookie Netscape. http.cookiejar пытается следовать фактическому протоколу файлов cookie Netscape (который существенно отличается от того, что указано в первоначальной спецификации Netscape), включая учёт max-age и port атрибутов файлов cookie, введённых в RFC 2965.
Примечание
Различные именованные параметры, встречающиеся в заголовках Set-Cookie и Set-Cookie2 (например, domain и expires) обычно называются атрибутами. Чтобы отличать их от атрибутов Python, в документации этого модуля используется термин атрибут файла cookie вместо.
Модуль определяет следующую ошибку:
exception http.cookiejar.LoadError
Экземпляры FileCookieJar генерируют эту ошибку при неудачной загрузке файлов cookie из файла. LoadError является подклассом OSError.
Изменено в версии 3.3: LoadError был переведён в подкласс OSError вместо IOError.
Класс CookieJar хранит файлы cookie HTTP. Он извлекает файлы cookie из HTTP-запросов и возвращает их в HTTP-ответах. Экземпляры CookieJar автоматически удаляют устаревшие файлы cookie при необходимости. Подклассы также отвечают за хранение и извлечение файлов cookie из файла или базы данных.
class http.cookiejar.FileCookieJar(filename, delayload=None, policy=None)
policy — объект, реализующий интерфейс CookiePolicy. Для других аргументов см. документацию по соответствующим атрибутам.
Аргументы конструктора должны передаваться только как именованные аргументы. blocked_domains — последовательность доменных имён, файлы cookie от которых никогда не принимаются и не возвращаются. allowed_domains, если не None, — последовательность доменных имён, для которых принимаются и возвращаются файлы cookie. secure_protocols — последовательность протоколов, для которых можно добавлять защищённые файлы cookie. По умолчанию https и wss (защищённый веб-сокет) считаются защищёнными протоколами. Для всех остальных аргументов см. документацию по объектам CookiePolicy и DefaultCookiePolicy.
DefaultCookiePolicy реализует стандартные правила принятия/отклонения файлов cookie Netscape и RFC 2965. По умолчанию файлы cookie RFC 2109 (т. е. файлы cookie, полученные в заголовке Set-Cookie с атрибутом файла cookie версии 1) обрабатываются согласно правилам RFC 2965. Однако, если обработка RFC 2965 отключена или rfc2109_as_netscape имеет значение True, файлы cookie RFC 2109 «снижаются» экземпляром CookieJar до файлов cookie Netscape, установив атрибут version экземпляра Cookie в 0. DefaultCookiePolicy также предоставляет некоторые параметры для тонкой настройки политики.
class http.cookiejar.Cookie
Этот класс представляет файлы cookie Netscape, RFC 2109 и RFC 2965. Не ожидается, что пользователи http.cookiejar будут создавать свои экземпляры Cookie. Вместо этого, при необходимости, вызовите make_cookies() для экземпляра CookieJar.
Спецификация исходного протокола файлов cookie Netscape. Хотя это по-прежнему преобладающий протокол, «протокол файлов cookie Netscape», реализованный всеми основными браузерами (и http.cookiejar) лишь отдаленно напоминает тот, что набросан в cookie_spec.html.
Если политика разрешает (т.е. атрибуты rfc2965 и hide_cookie2 экземпляра CookieJar’s CookiePolicy соответственно равны true и false), то заголовок Cookie2 также добавляется при необходимости.
Объект запрос (обычно экземпляр urllib.request.Request) должен поддерживать методы get_full_url(), get_host(), get_type(), unverifiable(), has_header(), get_header(), header_items(), add_unredirected_header() и атрибут origin_req_host, как описано в urllib.request.
Изменено в версии 3.3: Объект запрос требует атрибута origin_req_host. Зависимость от устаревшего метода get_origin_req_host() была удалена.
CookieJar.extract_cookies(response, request)
Извлечь куки из HTTP ответа и сохранить их в CookieJar, если это разрешено политикой.
CookieJar будет искать допустимые заголовки Set-Cookie и Set-Cookie2 в аргументе ответ и сохранять куки соответственно (в соответствии с одобрением метода CookiePolicy.set_ok()).
Объект запрос (обычно экземпляр urllib.request.Request) должен поддерживать методы get_full_url(), get_host(), unverifiable() и атрибут origin_req_host, как описано в urllib.request. Запрос используется для установки значений по умолчанию для атрибутов куки, а также для проверки того, разрешено ли установить куки.
Изменено в версии 3.3: Объект запрос требует атрибута origin_req_host. Зависимость от устаревшего метода get_origin_req_host() была удалена.
Возвращает последовательность объектов Cookie, извлечённых из объекта ответ.
См. документацию для extract_cookies() для интерфейсов, требуемых для аргументов ответ и запрос.
CookieJar.set_cookie_if_ok(cookie, request)
Установить Cookie, если политика разрешает это сделать.
CookieJar.set_cookie(cookie)
Установить Cookie без проверки с политикой, чтобы определить, должно ли оно быть установлено.
CookieJar.clear([domain[, path[, name]]])
Очистить некоторые куки.
Если вызвана без аргументов, очищает все куки. Если задан один аргумент, удаляются только куки, принадлежащие этому домену. Если заданы два аргумента, удаляются куки, принадлежащие указанному домену и пути URL. Если заданы три аргумента, удаляется куки с указанным доменом, путем и именем.
Возбуждает KeyError, если соответствующий куки не существует.
CookieJar.clear_session_cookies()
Удалить все куки сеанса.
Удаляет все содержащиеся куки, у которых атрибут discard имеет значение true (обычно потому, что у них либо отсутствовал атрибут куки max-age или expires, либо был явно задан атрибут куки discard). Для интерактивных браузеров конец сеанса обычно соответствует закрытию окна браузера.
Обратите внимание, что метод save() не сохранит куки сеанса в любом случае, если вы не попросите об этом, передав аргумент ignore_discard со значением true.
FileCookieJar реализует следующие дополнительные методы:
Этот базовый класс возбуждает NotImplementedError. Подклассы могут оставить этот метод нереализованным.
filename — имя файла, в который нужно сохранить куки. Если filename не указан, используется self.filename (по умолчанию значение, переданное в конструктор, если таковой имеется); если self.filename равен None, возбуждается ValueError.
ignore_discard: сохранить даже куки, установленные на удаление. ignore_expires: сохранить даже куки, срок действия которых истек.
Файл перезаписывается, если он уже существует, удаляя все содержащиеся в нем куки. Сохраненные куки можно восстановить позже, используя методы load() или revert().
Указанный файл должен быть в формате, понимаемом классом, иначе будет возбуждено LoadError. Также может быть возбуждено OSError, например, если файл не существует.
Изменено в версии 3.3: IOError ранее возбуждалось, теперь это псевдоним OSError.
Очистить все куки и перезагрузить куки из сохраненного файла.
revert() может возбуждать те же исключения, что и load(). При ошибке состояние объекта не изменяется.
FileCookieJar экземпляры имеют следующие публичные атрибуты:
FileCookieJar.filename
Имя файла по умолчанию, в котором хранятся куки. Этот атрибут может быть присвоен.
FileCookieJar.delayload
Если true, куки загружаются лениво из диска. Этот атрибут не должен быть присвоен. Это лишь подсказка, поскольку это влияет только на производительность, а не на поведение (если куки на диске изменяются). Объект CookieJar может игнорировать его. Ни один из FileCookieJar классов, включенных в стандартную библиотеку, лениво не загружает куки.
Подклассы FileCookieJar и взаимодействие с веб-браузерами
Предоставлены следующие подклассы CookieJar для чтения и записи.
class http.cookiejar.MozillaCookieJar(filename, delayload=None, policy=None)
Класс FileCookieJar, который может загружать и сохранять куки на диск в формате файлов Mozilla cookies.txt (который также используется браузерами Lynx и Netscape).
Примечание
При этом теряется информация о куках **RFC 2965**, а также о более новых или нестандартных атрибутах куки, таких как port.
Предупреждение
Сделайте резервную копию своих куки перед сохранением, если потеря/повреждение куки будет неудобной (есть некоторые нюансы, которые могут привести к небольшим изменениям в файле при обратном переходе «загрузка-сохранение»).
Также обратите внимание, что куки, сохраненные во время работы Mozilla, будут перезаписаны Mozilla.
class http.cookiejar.LWPCookieJar(filename, delayload=None, policy=None)
Класс FileCookieJar, который может загружать и сохранять куки на диск в формате, совместимом с форматом файлов Set-Cookie3 библиотеки libwww-perl. Это удобно, если вы хотите сохранить куки в читаемом файле.
Изменено в версии 3.8: Параметр filename поддерживает объекты-пути.
Объекты CookiePolicy
Объекты, реализующие интерфейс CookiePolicy, имеют следующие методы:
CookiePolicy.set_ok(cookie, request)
Возвращает булево значение, указывающее, должна ли кука приниматься от сервера.
Возвращает False если куки не должны возвращаться, учитывая домен куки.
Этот метод является оптимизацией. Он исключает необходимость проверки каждой куки с определенным доменом (что может включать чтение многих файлов). Возвращение значения True из domain_return_ok() и path_return_ok() оставляет всю работу методу return_ok().
Обратите внимание, что 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 если куки не должны возвращаться, учитывая путь куки.
Помимо реализации перечисленных выше методов, реализации интерфейса CookiePolicy также должны предоставить следующие атрибуты, указывающие, какие протоколы следует использовать и как. Все эти атрибуты могут быть назначены.
Не добавлять заголовок Cookie2 в запросы (наличие этого заголовка указывает серверу, что мы понимаем куки **RFC 2965**).
Наиболее полезный способ определения класса CookiePolicy — наследование от DefaultCookiePolicy и переопределение некоторых или всех методов выше. Сам CookiePolicy может использоваться как «нулевая политика», позволяющая устанавливать и получать любые куки (это вряд ли будет полезно).
END_OF_DOCUMENT_MARKER
Объекты 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, этот класс позволяет блокировать и разрешать домены для установки и получения файлов cookie. Также есть несколько переключателей строгости, которые позволяют немного ужесточить довольно свободные правила протокола Netscape (за счёт блокировки некоторых безобидных файлов cookie).
Предоставляется чёрный и белый список доменов (оба отключены по умолчанию). Участие в установке и возврате файлов 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 нет.
Устанавливает последовательность разрешённых доменов или None.
DefaultCookiePolicy.is_not_allowed(domain)
Возвращает значение, указывающее, не находится ли domain в белом списке для установки или получения файлов cookie.
DefaultCookiePolicy экземпляры имеют следующие атрибуты, которые все инициализируются из аргументов конструктора с тем же именем и которые могут быть все назначены.
DefaultCookiePolicy.rfc2109_as_netscape
Если значение истинно, запрашивается, чтобы экземпляр CookieJar понижал RFC 2109 файлы cookie (т.е. файлы cookie, полученные в заголовке Set-Cookie с атрибутом версии cookie равным 1) до файлов cookie Netscape, установив атрибут версии экземпляра Cookie в 0. Значение по умолчанию — None, в этом случае RFC 2109 файлы cookie понижаются, только если обработка RFC 2965 отключена. Поэтому RFC 2109 файлы cookie понижаются по умолчанию.
Общие переключатели строгости:
DefaultCookiePolicy.strict_domain
Не разрешать сайтам устанавливать домены из двух компонентов с доменами верхнего уровня страны, такими как .co.uk, .gov.uk, .co.nz. И т.д. Это далеко не идеально и не гарантирует работу!
Следовать правилам RFC 2965 по неподтверждаемым транзакциям (обычно неподтверждаемая транзакция — это транзакция, возникшая в результате перенаправления или запроса изображения, размещённого на другом сайте). Если это значение ложь, файлы cookie никогда не блокируются на основе проверяемости
Переключатели строгости протокола Netscape:
DefaultCookiePolicy.strict_ns_unverifiable
Применять правила RFC 2965 по неподтверждаемым транзакциям даже для файлов cookie Netscape.
DefaultCookiePolicy.strict_ns_domain
Флаги, указывающие, насколько строго следует соблюдать правила сопоставления доменов для файлов cookie Netscape. См. допустимые значения ниже.
DefaultCookiePolicy.strict_ns_set_initial_dollar
Игнорировать файлы cookie в заголовках Set-Cookie:, у которых имена начинаются с '$'.
DefaultCookiePolicy.strict_ns_set_path
Не разрешать установку файлов cookie, путь которых не соответствует пути URI запроса.
strict_ns_domain — это набор флагов. Его значение строится путём побитового ИЛИ (например, DomainStrictNoDots|DomainStrictNonDomain означает, что оба флага установлены).
DefaultCookiePolicy.DomainStrictNoDots
При установке файлов cookie «префикс хоста» не должен содержать точку (например, www.foo.bar.com не может устанавливать файл cookie для .bar.com, потому что www.foo содержит точку).
DefaultCookiePolicy.DomainStrictNonDomain
Файлы cookie, которые явно не указали атрибут cookie «domain», могут быть возвращены только в домен, равный домену, который установил файл cookie (например, spam.example.com не получит файлы cookie от example.com, у которых не было атрибута cookie domain).
DefaultCookiePolicy.DomainRFC2965Match
При установке файлов cookie требуется полное соответствие домена RFC 2965.
Следующие атрибуты предоставлены для удобства и представляют собой наиболее полезные комбинации вышеуказанных флагов:
DefaultCookiePolicy.DomainLiberal
Эквивалентно 0 (т.е. все вышеуказанные флаги строгости домена Netscape выключены).
Cookie экземпляры имеют атрибуты Python, примерно соответствующие стандартным атрибутам cookie, указанным в различных стандартах cookie. Соответствие не является взаимно однозначным, потому что существуют сложные правила для назначения значений по умолчанию, потому что атрибуты cookie max-age и expires содержат эквивалентную информацию, и потому что cookie RFC 2109 могут быть «снижены» http.cookiejar с версии 1 до версии 0 (cookie Netscape).
Присваивание этим атрибутам не требуется, за исключением редких случаев в методе CookiePolicy. Класс не обеспечивает внутреннюю согласованность, поэтому вы должны знать, что делаете, если это делаете.
Cookie.version
Целое число или None. Cookie Netscape имеют version 0. Cookie RFC 2965 и RFC 2109 имеют атрибут cookie version 1. Однако обратите внимание, что http.cookiejar может «снизить» cookie RFC 2109 до cookie Netscape, в этом случае version равно 0.
Строка, представляющая порт или набор портов (например, «80» или «80,8080»), или None.
Cookie.path
Путь cookie (строка, например, '/acme/rocket_launchers').
Cookie.secure
True если cookie должен возвращаться только по защищенному соединению.
Cookie.expires
Дата истечения срока действия в секундах с начала эпохи, или None. См. также метод is_expired().
Cookie.discard
True если это cookie сеанса.
Cookie.comment
Строковый комментарий от сервера, объясняющий функцию этого cookie, или None.
Cookie.comment_url
URL, который ссылается на комментарий сервера, объясняющий функцию этого cookie, или None.
Cookie.rfc2109
True если этот cookie был получен как cookie RFC 2109 (т. е. cookie пришел в заголовке Set-Cookie, а значение атрибута cookie Version в этом заголовке было 1). Этот атрибут предоставляется, потому что http.cookiejar может «снизить» cookie RFC 2109 до cookie Netscape, в этом случае version равно 0.
Cookie.port_specified
True если порт или набор портов был явно указан сервером (в заголовке Set-Cookie / Set-Cookie2).
Cookie.domain_specified
True если домен был явно указан сервером.
Cookie.domain_initial_dot
True если домен, явно указанный сервером, начинался с точки ('.').
Cookie могут иметь дополнительные нестандартные атрибуты cookie. К ним можно получить доступ с помощью следующих методов:
Cookie.has_nonstandard_attr(name)
Возвращает True если cookie имеет указанный атрибут cookie.
Cookie.get_nonstandard_attr(name, default=None)
Если cookie имеет указанный атрибут cookie, возвращает его значение. В противном случае возвращает default.
Cookie.set_nonstandard_attr(name, value)
Устанавливает значение указанного атрибута cookie.
True если cookie истек по времени, когда сервер запросил его срок действия. Если указано now (в секундах с начала эпохи), возвращает, истек ли cookie в указанное время.
Примеры
Первый пример демонстрирует наиболее распространенное использование 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. Включите cookie RFC 2965, будьте более строгими по отношению к доменам при установке и возврате cookie Netscape и заблокируйте некоторые домены от установки cookie или их возврата:
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/")
