21.24. http.cookiejar – Обработка cookie для HTTP-клиентов¶http.cookiejar – Cookie handling for HTTP clients

21.24.1. Объекты CookieJar и FileCookieJar¶CookieJar and FileCookieJar Objects

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

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

CookieJar.add_cookie_header(request)¶

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

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

Объект request (обычно экземпляр 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: объекту request требуется атрибут origin_req_host. Зависимость от устаревшего метода get_origin_req_host() удалена.

CookieJar.extract_cookies(response, request)¶

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

CookieJar будет искать допустимые заголовки Set-Cookie и Set-Cookie2 в аргументе ответа, и сохранять cookie соответствующим образом (с учётом одобрения метода CookiePolicy.set_ok()).

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

Объект request (обычно экземпляр urllib.request.Request) должен поддерживать методы get_full_url(), get_host(), unverifiable() и атрибут origin_req_host, как описано в urllib.request. 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() для описания интерфейсов, требуемых от аргументов ответа и запроса.

CookieJar.set_cookie_if_ok(cookie, request)¶

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

CookieJar.set_cookie(cookie)¶

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

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

Очищает некоторые куки.

Если вызван без аргументов, очищает все cookie. Если передан один аргумент, удаляются только cookie, принадлежащие этому домену. Если передано два аргумента, удаляются cookie, принадлежащие указанному домену и URL-пути. Если передано три аргумента, то удаляется cookie с указанными доменом, путём и именем.

Возбуждает KeyError, если соответствующая cookie не найдена.

CookieJar.clear_session_cookies()¶

Удалить все сессионные куки.

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

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

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

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

Сохраняет куки в файл.

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

filename is the name of file in which to save cookies. If filename is not specified, self.filename is used (whose default is the value passed to the constructor, if any); if self.filename is None, ValueError is raised.

ignore_discard: сохранять даже те куки, которые помечены к удалению. ignore_expires: сохранять даже куки с истекшим сроком действия.

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

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

Загружает куки из файла.

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

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

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

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

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

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

revert() может возбуждать те же исключения, что и load(). В случае неудачи состояние объекта не изменится.

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

FileCookieJar.filename¶

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

FileCookieJar.delayload¶

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

21.24.2. Подклассы FileCookieJar и взаимодействие с веб-браузерами¶FileCookieJar subclasses and co-operation with web browsers

Следующие подклассы 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. Это удобно, если нужно хранить куки в файле, читаемом человеком.

21.24.3. Объекты CookiePolicy¶CookiePolicy Objects

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

CookiePolicy.set_ok(cookie, request)¶

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

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

CookiePolicy.return_ok(cookie, request)¶

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

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

CookiePolicy.domain_return_ok(domain, request)¶

Возвращает false, если cookie не должны быть возвращены для данного домена cookie.

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

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

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

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

CookiePolicy.path_return_ok(path, request)¶

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

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

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

CookiePolicy.netscape¶

Реализация протокола Netscape.

CookiePolicy.rfc2965¶

Реализует протокол RFC 2965.

CookiePolicy.hide_cookie2¶

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

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

21.24.4. Объекты DefaultCookiePolicy¶DefaultCookiePolicy Objects

Реализует стандартные правила принятия и возврата куки.

Охватываются как куки 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, этот класс позволяет блокировать и разрешать домены при установке и получении куки. Также есть несколько переключателей строгости, которые позволяют немного ужесточить довольно свободные правила протокола Netscape (ценой блокировки некоторых безвредных куки).

Предоставляются чёрный и белый списки доменов (оба отключены по умолчанию). В установке и возврате 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)¶

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

DefaultCookiePolicy.allowed_domains()¶

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

DefaultCookiePolicy.set_allowed_domains(allowed_domains)¶

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

DefaultCookiePolicy.is_not_allowed(domain)¶

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

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

DefaultCookiePolicy.rfc2109_as_netscape¶

Если true, запросить, чтобы экземпляр CookieJar понижал cookie RFC 2109 (то есть cookie, полученные в заголовке Set-Cookie с атрибутом version cookie-attribute равным 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:

DefaultCookiePolicy.strict_rfc2965_unverifiable¶

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

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

DefaultCookiePolicy.strict_ns_unverifiable¶

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

DefaultCookiePolicy.strict_ns_domain¶

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

DefaultCookiePolicy.strict_ns_set_initial_dollar¶

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

DefaultCookiePolicy.strict_ns_set_path¶

Не разрешать установку куки, путь которых не соответствует 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¶

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

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

DefaultCookiePolicy.DomainLiberal¶

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

DefaultCookiePolicy.DomainStrict¶

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

21.24.5. Объекты Cookie¶Cookie Objects

Экземпляры 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.

Cookie.name¶

Имя cookie (строка).

Cookie.value¶

Значение cookie (строка) или None.

Cookie.port¶

Строка, представляющая порт или набор портов (например, ‘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, и значение атрибута 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.get_nonstandard_attr(name, default=None)¶

Если cookie имеет указанный атрибут cookie, возвращает его значение. В противном случае возвращает default.

Cookie.set_nonstandard_attr(name, value)¶

Устанавливает значение указанного атрибута cookie.

Класс Cookie также определяет следующий метод:

Cookie.is_expired(now=None)¶

True, если срок действия cookie истёк (прошло время, указанное сервером для истечения). Если передан now (в секундах с начала эпохи), возвращается, истёк ли срок действия cookie на указанный момент времени.

21.24.6. Примеры¶Examples

Первый пример показывает наиболее распространённое использование 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 с использованием ваших куки Netscape, Mozilla или Lynx (предполагается соглашение 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/")

The next example illustrates the use of DefaultCookiePolicy. Turn on RFC 2965 cookies, be more strict about domains when setting and returning Netscape cookies, and block some domains from setting cookies or having them returned:

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/")