Модуль http.cookiejar определяет классы для автоматической обработки файлов cookie HTTP. Он полезен для доступа к веб-сайтам, которым требуются небольшие фрагменты данных — файлы cookie, — сохраняемые на компьютере клиента в ответе HTTP от веб-сервера и отправляемые серверу в последующих HTTP-запросах.
Поддерживаются как обычный протокол файлов cookie Netscape, так и протокол, определённый в RFC 2965. Обработка RFC 2965 по умолчанию отключена. Файлы cookie RFC 2109 разбираются как файлы cookie Netscape, а затем обрабатываются либо как файлы cookie Netscape, либо как файлы cookie 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.
Класс 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 (защищённый веб-сокет). Описание остальных аргументов см. в документации объектов 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.
Если это разрешено политикой (то есть атрибуты 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, принадлежащие этому домену. Если переданы два аргумента, будут удалены файлы cookie, принадлежащие указанным домену и пути URL. Если переданы три аргумента, будет удалён файл cookie с указанными доменом, путём и именем.
Если подходящего файла cookie нет, вызывается исключение KeyError.
CookieJar.clear_session_cookies()
Удалить все сеансовые файлы cookie.
Удаляет все содержащиеся файлы cookie, у которых атрибут discard имеет значение true (обычно потому, что у них отсутствовал атрибут файла cookie max-age или expires либо был явно задан атрибут файла cookie 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. Например, функция может быть вызвана как с ".example.com", так и с "www.example.com", если домен запроса — "www.example.com". То же относится к path_return_ok().
Аргумент request описан в документации для return_ok().
CookiePolicy.path_return_ok(path, request)
Возвращает False, если cookie не следует отправлять с учётом пути cookie.
Помимо реализации перечисленных выше методов, реализации интерфейса CookiePolicy должны также предоставлять следующие атрибуты, указывающие, какие протоколы следует использовать и каким образом. Всем этим атрибутам можно присваивать значения.
Не добавлять заголовок Cookie2 к запросам (наличие этого заголовка сообщает серверу, что мы понимаем cookie RFC 2965).
Наиболее полезный способ определить класс CookiePolicy — создать подкласс DefaultCookiePolicy и переопределить некоторые или все перечисленные выше методы. Сам CookiePolicy можно использовать как «нулевую политику», разрешающую устанавливать и получать любые cookie (это вряд ли будет полезно).
Объекты DefaultCookiePolicy
Реализует стандартные правила приёма и отправки cookie.
Поддерживаются как cookie RFC 2965, так и cookie 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)
Возвращает True, если domain отсутствует в списке разрешённых доменов для установки или получения cookie.
Экземпляры DefaultCookiePolicy имеют следующие атрибуты. Все они инициализируются одноимёнными аргументами конструктора, и всем им можно присваивать значения.
DefaultCookiePolicy.rfc2109_as_netscape
Если значение истинно, предписывает экземпляру CookieJar понижать версию cookie RFC 2109 (то есть cookie, полученных в заголовке Set-Cookie с атрибутом cookie-версии со значением 1) до cookie Netscape, устанавливая для атрибута версии экземпляра Cookie значение 0. Значение по умолчанию — None; в этом случае версия cookie RFC 2109 понижается только при отключённой обработке RFC 2965. Поэтому по умолчанию версия cookie RFC 2109 понижается.
Переключатели общей строгости:
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 (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.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 может «понизить» версию 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.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/")
