Модуль 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), в том числе учитывает атрибуты файлов cookie max-age и port, введённые в RFC 2965.
Примечание
Различные именованные параметры в заголовках Set-Cookie и Set-Cookie2 (например, domain и expires) обычно называются атрибутами. Чтобы отличать их от атрибутов Python, в документации этого модуля для них используется термин атрибут файла cookie.
Модуль определяет следующее исключение:
exception http.cookiejar.LoadError
Экземпляры FileCookieJar вызывают это исключение, если не удаётся загрузить файлы cookie из файла. LoadError является подклассом OSError.
Изменено в версии 3.3: Ранее LoadError был подтипом IOError, который теперь является псевдонимом OSError.
Предоставляются следующие классы:
class http.cookiejar.CookieJar(policy=None)
policy — это объект, реализующий интерфейс CookiePolicy.
Класс CookieJar хранит файлы cookie HTTP. Он извлекает файлы cookie из HTTP-запросов и возвращает их в HTTP-ответах. Экземпляры CookieJar автоматически удаляют содержащиеся в них файлы cookie по истечении срока действия. Подклассы также отвечают за сохранение и извлечение файлов cookie из файла или базы данных.
class http.cookiejar.FileCookieJar(filename=None, delayload=None, policy=None)
policy — это объект, реализующий интерфейс CookiePolicy. Сведения об остальных аргументах см. в документации соответствующих атрибутов.
Аргументы конструктора следует передавать только в виде именованных аргументов. blocked_domains — это последовательность доменных имён, от которых мы никогда не принимаем файлы cookie и которым никогда не отправляем их. Если allowed_domains не равен None, он представляет собой последовательность доменов, для которых мы принимаем и отправляем файлы cookie. secure_protocols — это последовательность протоколов, для которых можно добавлять защищённые файлы cookie. По умолчанию защищёнными считаются протоколы https и wss (защищённый websocket). Сведения об остальных аргументах см. в документации объектов CookiePolicy и DefaultCookiePolicy.
DefaultCookiePolicy реализует стандартные правила принятия и отклонения файлов cookie Netscape и RFC 2965. По умолчанию файлы cookie RFC 2109 (то есть файлы cookie, полученные в заголовке Set-Cookie с атрибутом файла cookie version со значением 1) обрабатываются по правилам RFC 2965. Однако, если обработка RFC 2965 отключена или rfc2109_as_netscape равно True, экземпляр CookieJar «понижает» файлы cookie RFC 2109 до файлов 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.
Добавить в request соответствующий заголовок Cookie.
Если это разрешено политикой (то есть атрибуты rfc2965 и hide_cookie2 экземпляра CookiePolicy объекта 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)
Извлечь файлы cookie из HTTP-response и сохранить их в CookieJar, если это разрешено политикой.
CookieJar будет искать в аргументе response допустимые заголовки Set-Cookie и Set-Cookie2 и сохранять файлы cookie соответствующим образом (с учётом решения метода CookiePolicy.set_ok()).
Объект 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() удалена.
Установить Cookie, не проверяя по политике, следует ли его устанавливать.
CookieJar.clear([domain[, path[, name]]])
Удалить некоторые файлы cookie.
Если метод вызван без аргументов, удаляются все файлы cookie. Если указан один аргумент, удаляются только файлы cookie, принадлежащие этому domain. Если указаны два аргумента, удаляются файлы cookie, принадлежащие указанным domain и URL-path. Если указаны три аргумента, удаляется файл cookie с указанными domain, path и name.
Вызывает KeyError, если подходящий файл cookie не найден.
CookieJar.clear_session_cookies()
Удалить все сеансовые файлы cookie.
Удаляет все содержащиеся файлы cookie, у которых атрибут discard имеет значение true (обычно потому, что у них отсутствовал атрибут max-age или expires либо был явно задан атрибут discard). В интерактивных браузерах завершение сеанса обычно соответствует закрытию окна браузера.
Обратите внимание, что метод save() в любом случае не сохраняет сеансовые файлы cookie, если явно не запросить это, передав аргумент ignore_discard со значением true.
FileCookieJar реализует следующие дополнительные методы:
Этот базовый класс вызывает NotImplementedError. Подклассы могут не реализовывать этот метод.
filename — имя файла, в который нужно сохранить файлы cookie. Если filename не указан, используется self.filename (значение по умолчанию — значение, переданное конструктору, если оно есть); если self.filename равен None, вызывается ValueError.
ignore_discard: сохранять даже файлы cookie, помеченные для удаления. ignore_expires: сохранять даже файлы cookie с истёкшим сроком действия.
Если файл уже существует, он перезаписывается, удаляя все содержащиеся в нём файлы cookie. Сохранённые файлы cookie можно восстановить позже с помощью методов load() или revert().
Указанный файл должен иметь формат, поддерживаемый классом, иначе будет вызвано исключение LoadError. Также может быть вызвано исключение OSError, например, если файл не существует.
Изменено в версии 3.3: Ранее вызывалось исключение IOError; теперь оно является псевдонимом OSError.
Удалить все файлы cookie и повторно загрузить их из сохранённого файла.
revert() может вызывать те же исключения, что и load(). В случае сбоя состояние объекта не изменяется.
Экземпляры FileCookieJar имеют следующие общедоступные атрибуты:
FileCookieJar.filename
Имя файла по умолчанию для хранения файлов cookie. Этому атрибуту можно присваивать значение.
FileCookieJar.delayload
Если значение истинно, файлы cookie загружаются с диска по запросу. Этому атрибуту не следует присваивать значение. Это лишь подсказка, поскольку она влияет только на производительность, но не на поведение (если только файлы cookie на диске не меняются). Объект CookieJar может её игнорировать. Ни один из классов FileCookieJar, входящих в стандартную библиотеку, не загружает файлы cookie по запросу.
Подклассы FileCookieJar и взаимодействие с веб-браузерами
Для чтения и записи предоставляются следующие подклассы CookieJar.
class http.cookiejar.MozillaCookieJar(filename=None, delayload=None, policy=None)
FileCookieJar, который может загружать файлы cookie с диска и сохранять их на диск в формате файла cookies.txt Mozilla (который также используют curl и браузеры Lynx и Netscape).
Примечание
При этом теряется информация о файлах cookie RFC 2965, а также о новых или нестандартных атрибутах файлов cookie, таких как port.
Предупреждение
Перед сохранением сделайте резервную копию файлов cookie, если их потеря или повреждение доставят неудобства (есть некоторые нюансы, из-за которых файл может немного измениться после цикла загрузки и сохранения).
Также обратите внимание, что файлы cookie, сохранённые во время работы Mozilla, будут перезаписаны Mozilla.
class http.cookiejar.LWPCookieJar(filename=None, delayload=None, policy=None)
FileCookieJar, который может загружать файлы cookie с диска и сохранять их на диск в формате файла Set-Cookie3, совместимом с библиотекой libwww-perl. Это удобно, если вы хотите хранить файлы cookie в файле, доступном для чтения человеком.
Возвращает False, если cookie не следует отправлять с учётом домена cookie.
Этот метод служит для оптимизации. Он избавляет от необходимости проверять каждую cookie с определённым доменом (что может потребовать чтения множества файлов). Если методы domain_return_ok() и path_return_ok() возвращают true, всю работу выполняет return_ok().
Обратите внимание: domain_return_ok() вызывается для каждого домена cookie, а не только для домена request. Например, если домен запроса — "www.example.com", функция может быть вызвана как с ".example.com", так и с "www.example.com". То же относится к path_return_ok().
Аргумент request описан в документации для return_ok().
CookiePolicy.path_return_ok(path, request)
Возвращает False, если cookie не следует отправлять с учётом пути cookie.
Помимо реализации перечисленных выше методов, реализации интерфейса CookiePolicy должны также предоставлять следующие атрибуты, указывающие, какие протоколы следует использовать и как. Всем этим атрибутам можно присваивать значения.
Не добавляет заголовок Cookie2 к запросам (наличие этого заголовка сообщает серверу, что мы поддерживаем cookies RFC 2965).
Наиболее полезный способ определить класс CookiePolicy — создать подкласс DefaultCookiePolicy и переопределить некоторые или все перечисленные выше методы. Сам CookiePolicy можно использовать как «нулевую политику», разрешающую устанавливать и принимать любые cookies (это вряд ли будет полезно).
Объекты DefaultCookiePolicy
Реализует стандартные правила принятия и отправки cookies.
Поддерживаются и cookies RFC 2965, и cookies 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).
Предусмотрены списки запрещённых и разрешённых доменов (по умолчанию оба отключены). В установке и отправке cookies участвуют только домены, отсутствующие в списке запрещённых и присутствующие в списке разрешённых (если он включён). Используйте аргумент конструктора 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)
Возвращает True, если domain отсутствует в списке разрешённых доменов для установки или получения cookies.
Экземпляры DefaultCookiePolicy имеют следующие атрибуты. Все они инициализируются аргументами конструктора с такими же именами, и всем им можно присваивать значения.
DefaultCookiePolicy.rfc2109_as_netscape
Если значение истинно, указывает экземпляру CookieJar понизить cookies RFC 2109 (то есть cookies, полученные в заголовке Set-Cookie с атрибутом cookie version, равным 1) до cookies Netscape, установив атрибут version экземпляра Cookie в 0. Значение по умолчанию — None; в этом случае cookies RFC 2109 понижаются только при отключённой обработке RFC 2965. Поэтому по умолчанию cookies RFC 2109 понижаются.
Общие переключатели строгости:
DefaultCookiePolicy.strict_domain
Запрещает сайтам задавать двухкомпонентные домены с доменами верхнего уровня — кодами стран, например .co.uk, .gov.uk, .co.nz и т. д. Это далеко не идеальное решение, и его работа не гарантируется!
Применяет правила RFC 2965 к непроверяемым транзакциям (обычно непроверяемая транзакция возникает в результате перенаправления или запроса изображения, размещённого на другом сайте). Если значение ложно, cookies никогда не блокируются на основании возможности проверки.
Переключатели строгости протокола Netscape:
DefaultCookiePolicy.strict_ns_unverifiable
Применяет правила RFC 2965 для непроверяемых транзакций также к cookies Netscape.
DefaultCookiePolicy.strict_ns_domain
Флаги, определяющие строгость правил сопоставления доменов для cookies Netscape. Допустимые значения приведены ниже.
DefaultCookiePolicy.strict_ns_set_initial_dollar
Игнорирует cookies в заголовках Set-Cookie:, имена которых начинаются с '$'.
DefaultCookiePolicy.strict_ns_set_path
Запрещает устанавливать cookies, путь которых не соответствует пути URI запроса.
strict_ns_domain — это набор флагов. Его значение формируется побитовым ИЛИ соответствующих флагов (например, DomainStrictNoDots|DomainStrictNonDomain означает, что установлены оба флага).
DefaultCookiePolicy.DomainStrictNoDots
При установке cookies «префикс хоста» не должен содержать точку (например, 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
При установке cookies требует полного соответствия домена правилам RFC 2965.
Для удобства предоставлены следующие атрибуты — наиболее полезные комбинации перечисленных выше флагов:
DefaultCookiePolicy.DomainLiberal
Эквивалентно 0 (то есть все перечисленные выше флаги строгости доменов Netscape отключены).
Экземпляры Cookie имеют атрибуты Python, примерно соответствующие стандартным атрибутам cookie, определённым в различных стандартах cookie. Это соответствие не является взаимно однозначным: правила назначения значений по умолчанию сложны, атрибуты cookie max-age и expires содержат эквивалентную информацию, а cookies RFC 2109 модуль http.cookiejar может «понизить» с версии 1 до версии 0 (Netscape).
Присваивать значения этим атрибутам обычно не требуется, за исключением редких случаев в методе CookiePolicy. Класс не обеспечивает внутреннюю согласованность, поэтому при изменении атрибутов необходимо понимать, что вы делаете.
Cookie.version
Целое число или None. Для cookies Netscape значение version равно 0. Для cookies RFC 2965 и RFC 2109 значение атрибута cookie version равно 1. Однако учтите, что http.cookiejar может «понизить» cookies RFC 2109 до cookies Netscape; в этом случае значение version равно 0.
Строка, представляющая порт или набор портов (например, ‘80’ или ‘80,8080’), либо None.
Cookie.domain
Домен cookie (строка).
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 может «понизить» cookies RFC 2109 до cookies Netscape; в этом случае значение version равно 0.
Cookie.port_specified
True, если сервер явно указал порт или набор портов (в заголовке Set-Cookie / Set-Cookie2).
Cookie.domain_specified
True, если сервер явно указал домен.
Cookie.domain_initial_dot
True, если домен, явно указанный сервером, начинался с точки ('.').
Cookies могут иметь дополнительные нестандартные атрибуты. Доступ к ним можно получить с помощью следующих методов:
Cookie.has_nonstandard_attr(name)
Возвращает True, если cookie имеет указанный атрибут.
Cookie.get_nonstandard_attr(name, default=None)
Если cookie имеет указанный атрибут, возвращает его значение. В противном случае возвращает default.
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-адрес, используя cookies из Netscape, Mozilla или Lynx (предполагается, что для расположения файла cookies используется соглашение Unix/Netscape):
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/")
